From 69d7bb3b317557240e3fbf491ebcaf844c9f7afc Mon Sep 17 00:00:00 2001
From: viragtripathi <virag.tripathi@gmail.com>
Date: Fri, 9 Oct 2026 03:24:56 -0400
Subject: [PATCH] fix: make the safety hooks and MCP servers work in Codex

The safety hooks never ran in Codex, for four separate reasons:

- Codex looks for plugin hooks in hooks/hooks.json, and the file sat at
  the plugin root, so it was never loaded. It now lives in
  plugins/cockroachdb/hooks/hooks.json.
- Codex replaces every character outside [A-Za-z0-9_] in MCP tool
  names, so the Toolbox SQL tool is
  mcp__cockroachdb_toolbox__cockroachdb_execute_sql. The hyphenated
  matcher never matched it.
- Codex runs hook commands in the session's working directory, so
  python3 ./scripts/... couldn't find the script, and Python's exit 2
  would have blocked every matched call. Commands now reference
  "${PLUGIN_ROOT}/scripts/...", which Codex substitutes, and end with
  "; exit 0" so a missing or crashing script fails open.
- Codex rejects unknown top-level keys in hook output and then ignores
  the whole output, so the scripts' Copilot CLI fields made a deny a
  no-op. The scripts take a --codex flag that emits only the keys Codex
  accepts; without it their output is unchanged.

check-sql-files.py also reads the edited paths out of apply_patch input,
which is how Codex edits files, so the lint now runs after Codex edits.

The localhost cockroachdb-toolbox-http server is gone: it failed unless
Toolbox was already serving HTTP on port 5000. The README no longer
says the cluster ID is required, documents turning off a backend
through config.toml, replaces the nonexistent codex plugin trust
command with /hooks, fixes the secure-cluster troubleshooting (Codex
never forwarded the SSL variables it described), and adds Toolbox
over HTTP and the first-party CockroachDB MCP Server as alternative
backends. The execute-sql description no longer promises DDL and DML,
since Toolbox runs read-only.

Related to cockroachdb/claude-plugin#27
---
 AGENTS.md                                     |   8 +-
 CONTRIBUTING.md                               |  16 ++-
 README.md                                     |  96 ++++++++++-----
 plugins/cockroachdb/.mcp.json                 |   5 -
 plugins/cockroachdb/hooks.json                |  28 -----
 plugins/cockroachdb/hooks/hooks.json          |  30 +++++
 .../cockroachdb/scripts/check-sql-files.py    | 109 ++++++++++++++----
 plugins/cockroachdb/scripts/validate-sql.py   |  51 ++++++--
 plugins/cockroachdb/tools.yaml                |   8 +-
 scripts/validate-marketplace-install.sh       |   2 +-
 tests/test_plugin_package.py                  |  81 ++++++++++++-
 11 files changed, 318 insertions(+), 116 deletions(-)
 delete mode 100644 plugins/cockroachdb/hooks.json
 create mode 100644 plugins/cockroachdb/hooks/hooks.json

diff --git a/AGENTS.md b/AGENTS.md
index 8984038..2a20bc5 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -19,21 +19,21 @@ codex plugin add cockroachdb@cockroachdb-codex-plugin
 
 - **Never edit `plugins/cockroachdb/skills/` by hand.** Skills are synced from the [cockroachdb-skills](https://github.com/cockroachlabs/cockroachdb-skills) submodule by `scripts/sync-skills.sh`. The sync uses `rsync -aL` on purpose: upstream uses symlinks for shared reference files, and symlinks break on Windows clones (`core.symlinks=false` checks them out as text files). Keep the `-L`.
 - **Skills keep the upstream domain-grouped layout** (unlike the copilot plugin, which flattens). Cross-skill relative links resolve on disk here, so no link rewriting is needed. If you change the layout, re-verify every `../` link still resolves.
-- **Hook commands use paths relative to the plugin payload** (`python3 ./scripts/...`), matching Codex conventions. The hook scripts emit both output contracts (top-level `permissionDecision`/`additionalContext` plus `hookSpecificOutput`/`systemMessage`) and are shared verbatim with the copilot plugin; if you change one, change both. Note that Codex runtime support for plugin hooks has version-dependent gaps; the scripts must always fail open (exit 0) so a runtime that does run them can never get stuck.
+- **Hooks live in `plugins/cockroachdb/hooks/hooks.json`** (Codex's default location) and their commands are `python3 "${PLUGIN_ROOT}/scripts/<script>.py" --codex; exit 0`. Codex runs hooks in the session's working directory, so a relative `./scripts` path fails, and `; exit 0` keeps a crashing script from blocking every call. Matchers use Codex's sanitized tool names (`mcp__cockroachdb_toolbox__cockroachdb_execute_sql`, `apply_patch`). `--codex` makes the scripts emit only the keys Codex accepts; without it they emit both the Copilot CLI and the VS Code/Claude Code contracts. The scripts are shared verbatim with the copilot plugin; if you change one, change both.
 - **Hook scripts are Python 3 stdlib only**, read JSON on stdin, write JSON on stdout.
 - **Never bump versions by hand.** Release Please owns `version` in `plugins/cockroachdb/.codex-plugin/plugin.json`, `.release-please-manifest.json`, and `CHANGELOG.md`. Conventional commits: `fix:`/`feat:` cut a release, `chore:`/`docs:` do not.
 - **No counts in descriptions.** Counts go stale; name the things instead.
 
 ## Testing
 
-Smoke-test hook scripts from the payload directory, the way `hooks.json` invokes them:
+Smoke-test hook scripts from the payload directory with the flag `hooks/hooks.json` passes:
 
 ```bash
 cd plugins/cockroachdb
-echo '{"tool_input":{"sql":"DROP DATABASE x"}}' | python3 ./scripts/validate-sql.py
+echo '{"tool_input":{"sql":"DROP DATABASE x"}}' | python3 ./scripts/validate-sql.py --codex
 ```
 
-To verify the full install path, add this repo as a marketplace with the Codex CLI (commands above) and confirm the cached payload contains the manifest, `.mcp.json`, `hooks.json`, and the skills tree.
+To verify the full install path, add this repo as a marketplace with the Codex CLI (commands above) and confirm the cached payload contains the manifest, `.mcp.json`, `hooks/hooks.json`, and the skills tree. `python3 -m unittest -v tests/test_plugin_package.py` checks the MCP and hook wiring, including the hook output shape Codex accepts.
 
 ## Writing style
 
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 6ac967e..14501fe 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -51,9 +51,10 @@ REPO_URL="file://$(pwd)" ./scripts/validate-marketplace-install.sh HEAD
 plugins/cockroachdb/       # Plugin payload (the directory Codex installs)
   .codex-plugin/
     plugin.json            # Plugin manifest (version managed by Release Please)
-  .mcp.json                # MCP server definitions (stdio, HTTP, Cloud)
+  .mcp.json                # MCP server definitions (Toolbox stdio, Cloud)
   tools.yaml               # MCP Toolbox source and tool definitions
-  hooks.json               # Hook triggers and matchers (Codex auto-discovers at plugin root)
+  hooks/
+    hooks.json             # Hook triggers and matchers (Codex's default hooks location)
   scripts/
     validate-sql.py        # PreToolUse: blocks dangerous SQL patterns
     check-sql-files.py     # PostToolUse: lints files for anti-patterns
@@ -134,12 +135,15 @@ This repo uses [Release Please](https://github.com/googleapis/release-please) fo
 
 - Hook scripts must be Python 3 with **no external dependencies** (stdlib only).
 - Read JSON from stdin, write JSON to stdout.
-- Exit code 0 = allow/continue; exit code 2 = block the tool call.
-- Place `hooks.json` at the plugin root (`plugins/cockroachdb/hooks.json`). Codex discovers it by convention.
-- Use paths relative to the plugin root in hook commands — Codex runs hook commands with the plugin directory as the working directory:
+- Always exit 0 and signal a block through JSON. Codex treats exit 2 with stderr text as a block, so a crashing script would block every matched call; the trailing `; exit 0` in each command keeps a missing or crashing script fail-open.
+- Keep hooks in `plugins/cockroachdb/hooks/hooks.json`, where Codex looks by default when the manifest declares no `hooks`.
+- Codex runs hook commands in the session's working directory, not the plugin root, so reference scripts through `${PLUGIN_ROOT}`, which Codex substitutes into the command, and quote it for paths with spaces:
   ```json
-  "command": "python3 ./scripts/your-script.py"
+  "command": "python3 \"${PLUGIN_ROOT}/scripts/your-script.py\" --codex; exit 0"
   ```
+- Pass `--codex` to the scripts. Codex rejects unknown top-level keys in hook output and then ignores the whole output, so the scripts emit only `systemMessage` and `hookSpecificOutput` in that mode.
+- Matchers see Codex's tool names: MCP tools become `mcp__<server>__<tool>` with every character outside `[A-Za-z0-9_]` replaced by `_` (so `mcp__cockroachdb_toolbox__cockroachdb_execute_sql`), and file edits are `apply_patch`, whose input is the patch text in `tool_input.command`.
+- Codex runs plugin hooks only after the user trusts them in `/hooks`, and asks again when a hook definition changes.
 
 ### MCP Configuration
 
diff --git a/README.md b/README.md
index c93a2a7..f5c15be 100644
--- a/README.md
+++ b/README.md
@@ -6,12 +6,11 @@ CockroachDB plugin for [OpenAI Codex CLI](https://developers.openai.com/codex/).
 
 ## What's inside
 
-- **3 MCP backends:**
+- **MCP backends:**
   - `cockroachdb-cloud` (HTTP) — managed CockroachDB Cloud MCP for Cloud clusters. Zero local install.
   - `cockroachdb-toolbox` (stdio) — self-hosted [MCP Toolbox](https://mcp-toolbox.dev/integrations/cockroachdb/source/) for any cluster (local dev, self-hosted, or Cloud). Codex spawns the Toolbox process.
-  - `cockroachdb-toolbox-http` (SSE) — remote/multi-user Toolbox over HTTP.
 - **Skills** sourced from [`cockroachlabs/cockroachdb-skills`](https://github.com/cockroachlabs/cockroachdb-skills) — covers query/schema design, observability, security, migrations (MOLT), and cluster lifecycle.
-- **Safety hooks** (ship as `hooks.json` + `scripts/`; activation depends on the Codex runtime version):
+- **Safety hooks** (`hooks/hooks.json` + `scripts/`), which run once you trust them in `/hooks`:
   - `validate-sql.py` (PreToolUse) — blocks `DROP DATABASE`/`TRUNCATE`, warns on `SERIAL`/multi-DDL.
   - `check-sql-files.py` (PostToolUse) — lints SQL/Go/Java/Python/Ruby/JS/TS files for CockroachDB anti-patterns.
 
@@ -20,8 +19,8 @@ CockroachDB plugin for [OpenAI Codex CLI](https://developers.openai.com/codex/).
 ### Prerequisites
 
 - [Codex CLI](https://developers.openai.com/codex/cli/install) installed.
-- [MCP Toolbox](https://mcp-toolbox.dev/documentation/introduction/#install-toolbox) installed (only needed for the Toolbox backends; supports Homebrew, binary download, or container).
-- Access to a CockroachDB cluster, or run `plugins/cockroachdb/scripts/setup-cockroachdb.sh` to spin up a local single-node cluster.
+- [MCP Toolbox](https://mcp-toolbox.dev/documentation/introduction/#install-toolbox) v1.0.0 or later on your `PATH`, for the `cockroachdb-toolbox` backend. Use `brew install mcp-toolbox` on macOS or Linux. On Windows, download `toolbox.exe` into a folder on your `PATH` as described in the [Toolbox install instructions](https://github.com/googleapis/mcp-toolbox#install-toolbox).
+- A running CockroachDB cluster for the `cockroachdb-toolbox` backend, or run `plugins/cockroachdb/scripts/setup-cockroachdb.sh` to spin up a local single-node cluster. Toolbox connects when Codex starts it, so without a reachable cluster the backend fails to start. If you don't run a cluster, [turn the backend off](#turn-off-a-backend-you-dont-use).
 
 ### Add the marketplace and install
 
@@ -34,22 +33,35 @@ The marketplace source accepts `owner/repo`, an HTTPS Git URL, an SSH Git URL, o
 
 ### Trust the safety hooks
 
-Codex does not auto-trust plugin-bundled hooks. On first run, Codex will prompt you to review and approve:
+Codex skips plugin hooks until you review and trust them. Run `/hooks` in a Codex session and trust the two CockroachDB hooks:
 
-- The PreToolUse hook on `mcp__cockroachdb-toolbox__cockroachdb-execute-sql`.
-- The PostToolUse hook on `Write|Edit|MultiEdit`.
+- The PreToolUse hook on `mcp__cockroachdb_toolbox__cockroachdb_execute_sql`, Codex's name for the Toolbox SQL tool.
+- The PostToolUse hook on file edits (`apply_patch`).
 
-Both run small Python scripts in `plugins/cockroachdb/scripts/` — review and approve to enable the safety checks.
+Both run small Python scripts bundled with the plugin. If a plugin update changes a hook, Codex asks you to review it again.
 
 ### Configure environment variables
 
-For the `cockroachdb-cloud` backend:
+All of these are optional. Set them in the environment you start Codex from.
+
+The `cockroachdb-cloud` backend works without configuration and can reach every cluster your CockroachDB Cloud role allows. To limit it to one cluster:
 
 ```bash
 export COCKROACHDB_CLUSTER_ID=<your-cloud-cluster-id>
 ```
 
-For the `cockroachdb-toolbox` (stdio) backend:
+The `cockroachdb-toolbox` (stdio) backend reads the variables below, and Codex forwards only these names to Toolbox. An unset variable falls back to its default in the bundled `tools.yaml`:
+
+| Variable               | Default     | Notes                                                                        |
+|------------------------|-------------|------------------------------------------------------------------------------|
+| `COCKROACHDB_HOST`     | `localhost` |                                                                              |
+| `COCKROACHDB_PORT`     | `26257`     |                                                                              |
+| `COCKROACHDB_USER`     | `root`      |                                                                              |
+| `COCKROACHDB_PASSWORD` | (empty)     |                                                                              |
+| `COCKROACHDB_DATABASE` | `defaultdb` |                                                                              |
+| `COCKROACHDB_SSLMODE`  | `require`   | Use `disable` for a local `--insecure` cluster, `verify-full` for production |
+
+For a local development cluster:
 
 ```bash
 export COCKROACHDB_HOST=localhost
@@ -78,25 +90,58 @@ The plugin's skills will be auto-loaded by Codex based on task context.
 
 | Backend | Transport | Use case |
 |---|---|---|
-| `cockroachdb-cloud` | HTTP | Managed CockroachDB Cloud MCP. Requires `COCKROACHDB_CLUSTER_ID`. Zero local install. |
-| `cockroachdb-toolbox` | stdio | Self-hosted Toolbox against any cluster (local dev, self-hosted, or Cloud). Codex spawns the process. Read-only by default; enable writes via `tools.yaml`. |
-| `cockroachdb-toolbox-http` | HTTP/SSE | Remote/multi-user Toolbox deployments. Client-only; start Toolbox separately. |
+| `cockroachdb-cloud` | HTTP | Managed CockroachDB Cloud MCP. Set `COCKROACHDB_CLUSTER_ID` to limit it to one cluster. Zero local install. |
+| `cockroachdb-toolbox` | stdio | Self-hosted Toolbox against any cluster (local dev, self-hosted, or Cloud). Codex spawns the process. Read-only: writes and schema changes need `enableWriteMode: true` in a Toolbox configuration of your own. |
+
+### Turn off a backend you don't use
+
+Codex starts both backends in every session. To turn one off, add this to `~/.codex/config.toml`:
+
+```toml
+[plugins."cockroachdb@cockroachdb-codex-plugin".mcp_servers.cockroachdb-toolbox]
+enabled = false
+```
+
+Use `cockroachdb-cloud` in place of `cockroachdb-toolbox` to turn off the Cloud backend. Don't put `enabled = false` under a bare `[mcp_servers.cockroachdb-toolbox]` table instead: Codex rejects a server table without a `command` or `url`, and every `codex` command fails until you remove it.
+
+### Alternative backends
+
+**MCP Toolbox over HTTP.** To use a Toolbox server you run yourself, for example a shared deployment, start it with `toolbox --config tools.yaml`, which listens on `http://127.0.0.1:5000/mcp` by default, and register it:
+
+```bash
+codex mcp add cockroachdb-toolbox-http --url http://127.0.0.1:5000/mcp
+```
 
-Enable/disable per-backend via Codex's MCP toggle UI.
+**CockroachDB MCP Server (first-party, self-hosted).** [CockroachDB MCP Server](https://github.com/cockroachdb/cockroachdb-mcp-server) is Cockroach Labs' own MCP server for clusters you run yourself. By default it registers only read-only tools, such as `list_databases`, `list_tables`, `get_table_schema`, `select_query`, `explain_query`, `show_statement`, and `show_running_queries`. Setting `CRDB_MCP_ENABLE_WRITE_QUERIES=true` adds `create_database`, `create_table`, `insert_rows`, `update_rows`, and `delete_rows`, and the server refuses an `UPDATE` or `DELETE` without a `WHERE` clause.
 
-The `cockroachdb-toolbox-http` entry only connects to
-`http://127.0.0.1:5000/mcp`; it does not start a server. Before enabling it,
-start Toolbox independently from a directory containing your Toolbox config:
+Install it with `go install github.com/cockroachdb/cockroachdb-mcp-server@latest` (Go 1.26+). Linux and Windows binaries and a Docker image are listed on the [releases page](https://github.com/cockroachdb/cockroachdb-mcp-server/releases). There are no prebuilt macOS binaries, so on macOS use `go install` or Docker. For a local `--insecure` development cluster:
 
 ```bash
-toolbox --config tools.yaml
+codex mcp add cockroachdb-mcp-server --env CRDB_DATABASE_URL="postgresql://root@localhost:26257/defaultdb?sslmode=disable" --env CRDB_MCP_ALLOW_INSECURE_DB=true -- cockroachdb-mcp-server
+```
+
+For certificate authentication (recommended), add it to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.cockroachdb-mcp-server]
+command = "cockroachdb-mcp-server"
+
+[mcp_servers.cockroachdb-mcp-server.env]
+CRDB_HOST = "your-cluster-host"
+CRDB_USERNAME = "ai_agent"
+CRDB_SSL_MODE = "verify-full"
+CRDB_SSL_CA_PATH = "/certs/ca.crt"
+CRDB_SSL_CERTFILE = "/certs/client.ai_agent.crt"
+CRDB_SSL_KEYFILE = "/certs/client.ai_agent.key"
 ```
 
+Password authentication is off unless you set `CRDB_MCP_ALLOW_PASSWORD_AUTH=true`. The plugin's SQL safety hook applies to the bundled Toolbox backend; this server enforces its own guardrails. See the [server's README](https://github.com/cockroachdb/cockroachdb-mcp-server#configuration) for every setting.
+
 ## Troubleshooting
 
 **`toolbox: command not found`** — install [MCP Toolbox](https://mcp-toolbox.dev/documentation/introduction/#install-toolbox) (Homebrew, binary download, or container image).
 
-**Hooks didn't run** — check Codex's hook trust review screen (`codex plugin trust cockroachdb`).
+**Hooks didn't run**: run `/hooks` in a Codex session and trust the CockroachDB hooks. Codex skips plugin hooks that haven't been trusted, or that changed since you trusted them.
 
 **Skills not appearing** — verify the installed plugin cache contains skills: `find ~/.codex/plugins/cache/cockroachdb-codex-plugin/cockroachdb/*/skills -name SKILL.md | wc -l`.
 
@@ -106,16 +151,7 @@ same name can shadow the plugin-provided server. The plugin itself uses its
 installed, bundled `tools.yaml`; it does not require an absolute checkout or
 versioned cache path.
 
-**`SSL error: certificate verify failed` or `node is running secure mode, SSL connection required`** — your cluster runs in secure mode. Set:
-
-```bash
-export COCKROACHDB_SSLMODE=verify-full   # or 'require' for less strict
-export COCKROACHDB_SSLROOTCERT=/path/to/ca.crt
-export COCKROACHDB_SSLCERT=/path/to/client.<user>.crt
-export COCKROACHDB_SSLKEY=/path/to/client.<user>.key
-```
-
-Then extend `tools.yaml` `queryParams:` block with `sslrootcert: ${COCKROACHDB_SSLROOTCERT}`, `sslcert: ${COCKROACHDB_SSLCERT}`, `sslkey: ${COCKROACHDB_SSLKEY}`.
+**`SSL error: certificate verify failed` or `node is running secure mode, SSL connection required`**: your cluster runs in secure mode, so set `COCKROACHDB_SSLMODE` to `require` or `verify-full`. The bundled `tools.yaml` passes only `sslmode` to the driver, and Codex forwards only the variables listed under [Configure environment variables](#configure-environment-variables). If you need a CA file or client certificates, run Toolbox with your own copy of `tools.yaml` that adds `sslrootcert`, `sslcert`, and `sslkey` under `queryParams`, register it as your own MCP server, and turn off the plugin's `cockroachdb-toolbox` backend.
 
 For a quick local dev cluster, start one in insecure mode: `cockroach start-single-node --insecure --listen-addr=localhost:26257 &` and use `COCKROACHDB_SSLMODE=disable`.
 
diff --git a/plugins/cockroachdb/.mcp.json b/plugins/cockroachdb/.mcp.json
index 0947956..78785ee 100644
--- a/plugins/cockroachdb/.mcp.json
+++ b/plugins/cockroachdb/.mcp.json
@@ -19,11 +19,6 @@
         "COCKROACHDB_DATABASE",
         "COCKROACHDB_SSLMODE"
       ]
-    },
-    "cockroachdb-toolbox-http": {
-      "type": "http",
-      "url": "http://127.0.0.1:5000/mcp",
-      "_comment": "SSE transport — run 'toolbox --config tools.yaml' first, then connect via this URL"
     }
   }
 }
diff --git a/plugins/cockroachdb/hooks.json b/plugins/cockroachdb/hooks.json
deleted file mode 100644
index 282f2d8..0000000
--- a/plugins/cockroachdb/hooks.json
+++ /dev/null
@@ -1,28 +0,0 @@
-{
-  "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": "mcp__cockroachdb-toolbox__cockroachdb-execute-sql",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "python3 ./scripts/validate-sql.py",
-            "timeout": 10
-          }
-        ]
-      }
-    ],
-    "PostToolUse": [
-      {
-        "matcher": "Write|Edit|MultiEdit",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "python3 ./scripts/check-sql-files.py",
-            "timeout": 15
-          }
-        ]
-      }
-    ]
-  }
-}
diff --git a/plugins/cockroachdb/hooks/hooks.json b/plugins/cockroachdb/hooks/hooks.json
new file mode 100644
index 0000000..382e2ab
--- /dev/null
+++ b/plugins/cockroachdb/hooks/hooks.json
@@ -0,0 +1,30 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "mcp__cockroachdb_toolbox__cockroachdb_execute_sql",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"${PLUGIN_ROOT}/scripts/validate-sql.py\" --codex; exit 0",
+            "timeout": 10,
+            "statusMessage": "Checking SQL with the CockroachDB safety hook"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "apply_patch|Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"${PLUGIN_ROOT}/scripts/check-sql-files.py\" --codex; exit 0",
+            "timeout": 15,
+            "statusMessage": "Linting edited files for CockroachDB anti-patterns"
+          }
+        ]
+      }
+    ]
+  }
+}
diff --git a/plugins/cockroachdb/scripts/check-sql-files.py b/plugins/cockroachdb/scripts/check-sql-files.py
index 3702a28..76e2b5d 100755
--- a/plugins/cockroachdb/scripts/check-sql-files.py
+++ b/plugins/cockroachdb/scripts/check-sql-files.py
@@ -5,6 +5,12 @@
 The advisory message is emitted under both ``systemMessage`` (VS Code Copilot /
 Claude Code, user-visible) and ``additionalContext`` (GitHub Copilot CLI,
 model-visible), so the lint surfaces regardless of which tool runs the hook.
+
+OpenAI Codex and Copilot edit files with ``apply_patch``, whose input is patch
+text (in ``tool_input.command`` for Codex, as the whole ``tool_input`` string
+for Copilot) with no file path key, so the paths come from the patch headers.
+Codex also rejects unknown top-level output keys, so the Codex hooks.json
+passes ``--codex``.
 """
 
 import json
@@ -14,45 +20,109 @@
 
 
 SQL_EXTENSIONS = {".sql", ".go", ".py", ".js", ".ts", ".java", ".rb"}
-
-
-def main():
-    try:
-        data = json.load(sys.stdin)
-    except (json.JSONDecodeError, EOFError):
-        sys.exit(0)
-
-    # tool_input/toolInput (VS Code / Claude) or toolArgs (Copilot CLI). File
-    # path key varies by tool: file_path (Claude), filePath / path (others).
+CODEX = "--codex" in sys.argv[1:]
+# apply_patch file headers (codex-rs/apply-patch/src/parser.rs).
+PATCH_FILE_MARKERS = ("*** Add File: ", "*** Update File: ", "*** Move to: ")
+
+
+def patch_file_paths(patch_text, base_dir):
+    paths = []
+    for line in patch_text.splitlines():
+        for marker in PATCH_FILE_MARKERS:
+            if line.startswith(marker):
+                path = line[len(marker):].strip()
+                if path and base_dir and not os.path.isabs(path):
+                    path = os.path.join(base_dir, path)
+                if path:
+                    paths.append(path)
+    return paths
+
+
+def candidate_files(data):
+    # tool_input/toolInput (Codex / VS Code / Claude) or toolArgs (Copilot CLI).
+    # File path key varies by tool: file_path (Claude), filePath / path (others).
     tool_input = (
         data.get("tool_input")
         or data.get("toolInput")
         or data.get("toolArgs")
         or {}
     )
+    base_dir = data.get("cwd") or ""
+    # Copilot passes apply_patch input as the raw patch text, and its camelCase
+    # format can pass other arguments as a JSON string.
+    if isinstance(tool_input, str):
+        if "*** Begin Patch" in tool_input:
+            return patch_file_paths(tool_input, base_dir)
+        try:
+            tool_input = json.loads(tool_input)
+        except json.JSONDecodeError:
+            return []
     if not isinstance(tool_input, dict):
-        sys.exit(0)
+        return []
     file_path = (
         tool_input.get("file_path")
         or tool_input.get("filePath")
         or tool_input.get("path")
         or ""
     )
-    if not file_path:
+    if file_path:
+        return [file_path]
+    command = tool_input.get("command")
+    if isinstance(command, str) and "*** Begin Patch" in command:
+        return patch_file_paths(command, base_dir)
+    return []
+
+
+def main():
+    try:
+        data = json.load(sys.stdin)
+    except (json.JSONDecodeError, EOFError):
+        sys.exit(0)
+    if not isinstance(data, dict):
+        sys.exit(0)
+
+    findings = []
+    for file_path in dict.fromkeys(candidate_files(data)):
+        warnings = lint(file_path)
+        if warnings:
+            findings.append((file_path, warnings))
+    if not findings:
         sys.exit(0)
 
+    if len(findings) == 1:
+        message = "CockroachDB lint: " + " ".join(findings[0][1])
+    else:
+        message = "CockroachDB lint: " + " ".join(
+            f"{os.path.basename(path)}: {' '.join(warnings)}"
+            for path, warnings in findings
+        )
+    if CODEX:
+        payload = {
+            "systemMessage": message,
+            "hookSpecificOutput": {
+                "hookEventName": "PostToolUse",
+                "additionalContext": message,
+            },
+        }
+    else:
+        payload = {"systemMessage": message, "additionalContext": message}
+    json.dump(payload, sys.stdout)
+    sys.exit(0)
+
+
+def lint(file_path):
     ext = os.path.splitext(file_path)[1]
     if ext not in SQL_EXTENSIONS:
-        sys.exit(0)
+        return []
 
     if not os.path.isfile(file_path):
-        sys.exit(0)
+        return []
 
     try:
         with open(file_path, "r", encoding="utf-8", errors="ignore") as f:
             content = f.read()
     except OSError:
-        sys.exit(0)
+        return []
 
     warnings = []
 
@@ -88,14 +158,7 @@ def main():
                     "Use cockroachdb-jdbc-wrapper RetryableExecutor."
                 )
 
-    if warnings:
-        message = "CockroachDB lint: " + " ".join(warnings)
-        json.dump({
-            "systemMessage": message,
-            "additionalContext": message,
-        }, sys.stdout)
-
-    sys.exit(0)
+    return warnings
 
 
 if __name__ == "__main__":
diff --git a/plugins/cockroachdb/scripts/validate-sql.py b/plugins/cockroachdb/scripts/validate-sql.py
index 87d03ab..e53f17d 100755
--- a/plugins/cockroachdb/scripts/validate-sql.py
+++ b/plugins/cockroachdb/scripts/validate-sql.py
@@ -9,31 +9,49 @@
 - VS Code Copilot and Claude Code read ``hookSpecificOutput`` (and
   ``systemMessage``).
 Emitting both keeps this one script working across all three surfaces.
+
+OpenAI Codex rejects any top-level key it does not know (its hook output
+schema uses deny_unknown_fields), so the Codex hooks.json passes ``--codex``
+and this script then emits only the Codex shape.
 """
 
 import json
 import re
 import sys
 
+CODEX = "--codex" in sys.argv[1:]
+
 
 def deny(reason):
-    json.dump({
+    hook_output = {
+        "hookEventName": "PreToolUse",
         "permissionDecision": "deny",
         "permissionDecisionReason": reason,
-        "hookSpecificOutput": {
-            "hookEventName": "PreToolUse",
+    }
+    if CODEX:
+        payload = {"hookSpecificOutput": hook_output}
+    else:
+        payload = {
             "permissionDecision": "deny",
             "permissionDecisionReason": reason,
-        },
-    }, sys.stdout)
+            "hookSpecificOutput": hook_output,
+        }
+    json.dump(payload, sys.stdout)
     sys.exit(0)
 
 
 def warn(message):
-    json.dump({
-        "systemMessage": message,
-        "additionalContext": message,
-    }, sys.stdout)
+    if CODEX:
+        payload = {
+            "systemMessage": message,
+            "hookSpecificOutput": {
+                "hookEventName": "PreToolUse",
+                "additionalContext": message,
+            },
+        }
+    else:
+        payload = {"systemMessage": message, "additionalContext": message}
+    json.dump(payload, sys.stdout)
     sys.exit(0)
 
 
@@ -43,8 +61,19 @@ def main():
     except (json.JSONDecodeError, EOFError):
         sys.exit(0)
 
-    # tool_input (VS Code / Claude) or toolArgs (Copilot CLI camelCase)
-    tool_input = data.get("tool_input") or data.get("toolArgs") or {}
+    if not isinstance(data, dict):
+        sys.exit(0)
+
+    # tool_input (Codex / VS Code / Claude) or toolArgs (Copilot CLI camelCase,
+    # which can arrive as a JSON string)
+    tool_input = (
+        data.get("tool_input") or data.get("toolInput") or data.get("toolArgs") or {}
+    )
+    if isinstance(tool_input, str):
+        try:
+            tool_input = json.loads(tool_input)
+        except json.JSONDecodeError:
+            sys.exit(0)
     if not isinstance(tool_input, dict):
         sys.exit(0)
     sql = tool_input.get("sql", "") or tool_input.get("statement", "")
diff --git a/plugins/cockroachdb/tools.yaml b/plugins/cockroachdb/tools.yaml
index 4a42c05..1fa669c 100644
--- a/plugins/cockroachdb/tools.yaml
+++ b/plugins/cockroachdb/tools.yaml
@@ -21,9 +21,11 @@ tools:
     type: cockroachdb-execute-sql
     source: crdb-source
     description: |
-      Execute ad-hoc SQL statements against a CockroachDB database.
-      Use this for any SQL: SELECT queries, DDL statements (CREATE, ALTER, DROP),
-      and DML statements (INSERT, UPDATE, DELETE).
+      Execute an ad-hoc SQL statement against a CockroachDB database.
+      The connection is read-only by default: SELECT, SHOW, and EXPLAIN work,
+      while writes and schema changes (INSERT, UPDATE, DELETE, CREATE, ALTER,
+      DROP) are rejected unless write mode is enabled in the Toolbox
+      configuration (enableWriteMode: true).
 
   cockroachdb-list-schemas:
     type: cockroachdb-list-schemas
diff --git a/scripts/validate-marketplace-install.sh b/scripts/validate-marketplace-install.sh
index ecbe84c..20c1c92 100755
--- a/scripts/validate-marketplace-install.sh
+++ b/scripts/validate-marketplace-install.sh
@@ -133,7 +133,7 @@ test_sha() {
   # Step 5: Verify other plugin components
   local plugin_root="${clone_dir}/plugins/cockroachdb"
   echo "[5/5] Checking other components..."
-  echo "      hooks.json:       $(test -f "${plugin_root}/hooks.json" && echo "YES" || echo "NO")"
+  echo "      hooks/hooks.json: $(test -f "${plugin_root}/hooks/hooks.json" && echo "YES" || echo "NO")"
   echo "      .mcp.json:        $(test -f "${plugin_root}/.mcp.json" && echo "YES" || echo "NO")"
   echo "      tools.yaml:       $(test -f "${plugin_root}/tools.yaml" && echo "YES" || echo "NO")"
   echo "      plugin.json:      $(test -f "${plugin_root}/.codex-plugin/plugin.json" && echo "YES" || echo "NO")"
diff --git a/tests/test_plugin_package.py b/tests/test_plugin_package.py
index 2fd5cb2..4b9901d 100644
--- a/tests/test_plugin_package.py
+++ b/tests/test_plugin_package.py
@@ -1,5 +1,8 @@
 import json
+import re
 import shutil
+import subprocess
+import sys
 import tempfile
 import unittest
 from pathlib import Path
@@ -8,6 +11,10 @@
 REPO_ROOT = Path(__file__).resolve().parents[1]
 PLUGIN_ROOT = REPO_ROOT / "plugins" / "cockroachdb"
 MCP_MANIFEST = PLUGIN_ROOT / ".mcp.json"
+HOOKS_FILE = PLUGIN_ROOT / "hooks" / "hooks.json"
+# Top-level keys Codex accepts in PreToolUse/PostToolUse hook output; it rejects
+# any other key and then ignores the whole output.
+CODEX_OUTPUT_KEYS = {"continue", "stopReason", "suppressOutput", "systemMessage", "decision", "reason", "hookSpecificOutput"}
 
 
 class PluginMcpPackageTest(unittest.TestCase):
@@ -68,12 +75,76 @@ def test_cloud_mcp_sources_cluster_header_from_environment(self) -> None:
             {"mcp-cluster-id": "COCKROACHDB_CLUSTER_ID"},
         )
 
-    def test_http_toolbox_remains_an_independent_client_connection(self) -> None:
-        server = self.servers["cockroachdb-toolbox-http"]
+    def test_remote_servers_use_https(self) -> None:
+        for name, server in self.servers.items():
+            if "url" in server:
+                with self.subTest(server=name):
+                    self.assertTrue(server["url"].startswith("https://"), server["url"])
 
-        self.assertEqual(server["type"], "http")
-        self.assertEqual(server["url"], "http://127.0.0.1:5000/mcp")
-        self.assertNotIn("command", server)
+
+def codex_tool_name(server: str, tool: str) -> str:
+    """Codex replaces every character outside [A-Za-z0-9_] in MCP names."""
+    sanitize = lambda name: re.sub(r"[^A-Za-z0-9_]", "_", name)
+    return f"mcp__{sanitize(server)}__{sanitize(tool)}"
+
+
+class PluginHooksPackageTest(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls) -> None:
+        cls.hooks = json.loads(HOOKS_FILE.read_text(encoding="utf-8"))["hooks"]
+
+    def run_script(self, command: str, payload: dict) -> str:
+        script = re.search(r'"\$\{PLUGIN_ROOT\}/(scripts/[^"]+)"', command).group(1)
+        args = [sys.executable, str(PLUGIN_ROOT / script)] + (["--codex"] if "--codex" in command else [])
+        result = subprocess.run(args, input=json.dumps(payload), capture_output=True, text=True, check=True)
+        return result.stdout
+
+    def test_hooks_live_where_codex_discovers_them(self) -> None:
+        manifest = json.loads((PLUGIN_ROOT / ".codex-plugin" / "plugin.json").read_text(encoding="utf-8"))
+        self.assertTrue(HOOKS_FILE.is_file())
+        self.assertFalse((PLUGIN_ROOT / "hooks.json").exists())
+        self.assertNotIn("hooks", manifest)
+
+    def test_sql_hook_matches_the_codex_name_of_the_toolbox_tool(self) -> None:
+        self.assertIn("cockroachdb-toolbox", json.loads(MCP_MANIFEST.read_text(encoding="utf-8"))["mcpServers"])
+        self.assertIn("cockroachdb-execute-sql:", (PLUGIN_ROOT / "tools.yaml").read_text(encoding="utf-8"))
+        matcher = self.hooks["PreToolUse"][0]["matcher"]
+        self.assertEqual(matcher, codex_tool_name("cockroachdb-toolbox", "cockroachdb-execute-sql"))
+
+    def test_lint_hook_matches_apply_patch(self) -> None:
+        self.assertIn("apply_patch", self.hooks["PostToolUse"][0]["matcher"].split("|"))
+
+    def test_hook_commands_use_the_plugin_root_and_fail_open(self) -> None:
+        for event in ("PreToolUse", "PostToolUse"):
+            with self.subTest(event=event):
+                command = self.hooks[event][0]["hooks"][0]["command"]
+                self.assertIn('"${PLUGIN_ROOT}/scripts/', command)
+                self.assertIn(" --codex", command)
+                self.assertTrue(command.endswith("; exit 0"), command)
+                script = re.search(r'"\$\{PLUGIN_ROOT\}/(scripts/[^"]+)"', command).group(1)
+                self.assertTrue((PLUGIN_ROOT / script).is_file(), script)
+
+    def test_sql_hook_denies_in_the_codex_output_shape(self) -> None:
+        command = self.hooks["PreToolUse"][0]["hooks"][0]["command"]
+        out = json.loads(self.run_script(command, {"hook_event_name": "PreToolUse", "tool_input": {"sql": "DROP DATABASE x"}}))
+        self.assertEqual(set(out), {"hookSpecificOutput"})
+        self.assertEqual(out["hookSpecificOutput"]["permissionDecision"], "deny")
+        self.assertEqual(out["hookSpecificOutput"]["hookEventName"], "PreToolUse")
+
+        warning = json.loads(self.run_script(command, {"tool_input": {"sql": "CREATE TABLE t (id SERIAL PRIMARY KEY)"}}))
+        self.assertLessEqual(set(warning), CODEX_OUTPUT_KEYS)
+        self.assertIn("additionalContext", warning["hookSpecificOutput"])
+
+        self.assertEqual(self.run_script(command, {"tool_input": {"sql": "SELECT 1"}}), "")
+
+    def test_lint_hook_reads_apply_patch_paths(self) -> None:
+        command = self.hooks["PostToolUse"][0]["hooks"][0]["command"]
+        with tempfile.TemporaryDirectory() as cwd:
+            Path(cwd, "schema.sql").write_text("CREATE TABLE t (id SERIAL PRIMARY KEY);\n", encoding="utf-8")
+            patch = "*** Begin Patch\n*** Add File: schema.sql\n+CREATE TABLE t (id SERIAL PRIMARY KEY);\n*** End Patch\n"
+            out = json.loads(self.run_script(command, {"cwd": cwd, "tool_name": "apply_patch", "tool_input": {"command": patch}}))
+        self.assertLessEqual(set(out), CODEX_OUTPUT_KEYS)
+        self.assertIn("CockroachDB lint", out["hookSpecificOutput"]["additionalContext"])
 
 
 if __name__ == "__main__":