PostToolUse hook

[Forenxics]

Upstream issue draft — cockroachdb plugin v0.1.9 hook ${CLAUDE_PLUGIN_ROOT} not substituted

Plugin: cockroachdb/claude-plugin v0.1.9
Filed by: (operator)
Discovered: 2026-06-16, during Patch project Session 34

Summary

The PostToolUse hook at hooks/hooks.json ships with the command:

json"command": "python3 "${CLAUDE_PLUGIN_ROOT}/scripts/check-sql-files.py""

In our Cowork sandbox runtime, ${CLAUDE_PLUGIN_ROOT} is not being substituted to the plugin's install path. The literal string ${CLAUDE_PLUGIN_ROOT} is passed straight through to bash, which then asks python3 to open:

C:\Users\patri\AppData\Local\Python\pythoncore-3.14-64\python.exe:
can't open file 'C:\Users\patri\AppData\Roaming\Claude
local-agent-mode-sessions<session-id>\outputs${CLAUDE_PLUGIN_ROOT}
\scripts\check-sql-files.py': [Errno 2] No such file or directory

(The bash workdir is the outputs scratchpad, so the un-substituted ${CLAUDE_PLUGIN_ROOT} is interpreted as a relative path under that.)

Impact

Not a correctness break — the hook is PostToolUse, so Write/Edit/MultiEdit complete normally before the hook fires. Files are written; subsequent reads see the updated content.
Visual noise — every Write or Edit emits a PostToolUse:Edit hook blocking error block to the conversation. In a session with dozens of file edits, this fires dozens of times.
Affected scope: the Write|Edit|MultiEdit matcher means the hook fires on every file edit regardless of file type. The script itself filters correctly (SQL_EXTENSIONS = {".sql", ".go", ".py", ".js", ".ts", ".java", ".rb"} + sys.exit(0) on miss), so the actual no-op behaviour on non-SQL files is correct — but only AFTER the script successfully starts. Currently it doesn't.

Reproduction

Install the cockroachdb plugin v0.1.9 in a Cowork session.
Use the Write or Edit tool to touch ANY file (does not have to be SQL).
Observe the PostToolUse:Edit hook blocking error after the write completes.

Root cause hypothesis

Claude Code's documented contract is that ${CLAUDE_PLUGIN_ROOT} in a hooks.json command field is substituted at hook-execution time with the plugin's resolved install path. Our session is evidently not performing that substitution — either because:

This Cowork sandbox runtime uses a different hook-substitution path than Claude Code CLI, OR
The plugin install path lookup is failing silently, leaving ${CLAUDE_PLUGIN_ROOT} un-substituted, OR
The bash shell invocation is escaping the ${CLAUDE_PLUGIN_ROOT} token before substitution.

We don't have Claude Code CLI side-by-side to confirm whether this is a Cowork-specific runtime bug or a general plugin-shape issue. Worth a check on the plugin maintainer's side for whether the hook works in standard Claude Code.

Suggested fixes (any of these)

Move the script reference to an absolute path captured at install time. When the plugin is installed, write the resolved path to a config file the hook command reads — sidesteps the ${CLAUDE_PLUGIN_ROOT} substitution dependency entirely.
Add a matcher filter on file extension so the hook only fires on writes whose tool_input.file_path matches *.{sql,go,py,js,ts,java,rb}. This both reduces hook noise AND limits the blast radius if the substitution does fail.
Have the script itself locate the plugin root via os.path.dirname(file) (or similar self-relative path resolution) so it doesn't need any env var at all when invoked.

Option (3) is the simplest and most robust — the script just needs to know where IT lives, not where the plugin is mounted.

Workaround for operators

If filing upstream takes time, operators in the meantime can:

Ignore — the hook is non-blocking (writes succeed). Just visual noise.
Disable — remove the PostToolUse block from hooks/hooks.json in the locally-installed plugin. Loses SQL-anti-pattern checking for any project that does have SQL files.
Patch in place — replace ${CLAUDE_PLUGIN_ROOT} with the absolute install path (/sessions//mnt/.remote-plugins/plugin_01J1ZUJcofzWJxiajSBsZ8US). Brittle (session-id changes) but works for a single session.

Plugin metadata (for the issue)

Plugin: cockroachdb v0.1.9
License: Apache-2.0
Repository: https://github.com/cockroachdb/claude-plugin
Hook file: hooks/hooks.json
Affected script: scripts/check-sql-files.py (the script itself is correct; only the hook command's path resolution is broken)

[Necmttn]

One correction to the proposed fixes: option 3 only helps after Python has already opened the script. In this failure, Python never reaches scripts/check-sql-files.py; it is trying to open a path that still contains the literal ${CLAUDE_PLUGIN_ROOT}. So os.path.dirname(__file__) inside the script would not fix this specific startup failure.

I would split the fix into two checks:

• Host/runtime compatibility: add a tiny reproduction hook that prints/records the resolved command path and asserts the executed command never contains the literal ${CLAUDE_PLUGIN_ROOT}. That tells you whether this is Cowork-only or standard Claude Code plugin behavior too.
• Plugin blast-radius hardening: keep the file-extension filter inside check-sql-files.py, but add a startup guard/test for the hook command itself. The hooks.json matcher is still Write|Edit|MultiEdit, so it cannot filter by file extension before process startup.

For the plugin-side workaround, the stable shape is probably an install-time rendered hook command or wrapper path, not script self-discovery. Self-discovery is still useful for locating sibling files once the script starts, but it cannot compensate for an unresolved launcher path.

Also worth adding one regression that edits a non-SQL file and asserts the hook produces no stderr/user-visible block. That is the actual UX failure here: the SQL filter is correct, but it runs too late.

---

Generated with ax.

[viragtripathi]

Thanks @Necmttn, your analysis was spot on and shaped the fix. This shipped in #21.

You're right that script self-discovery (os.path.dirname(__file__)) cannot help here: when the launcher path still contains the literal ${CLAUDE_PLUGIN_ROOT} (or resolves past Windows MAX_PATH), Python never reaches the script at all, so there is nothing for the script to self-locate from. The fix had to live at the hook-command layer.

What landed:

• The hook command now loads the script through a small runpy bootstrap and ends with ; exit 0, so whenever the interpreter cannot open the script the hook exits 0 and surfaces no block. That covers both failure modes: the original Windows MAX_PATH case (PostToolUse hook fails on Windows: ${CLAUDE_PLUGIN_ROOT} path exceeds MAX_PATH #20, also handled by prefixing the path with the \\?\ long-path escape on Windows) and the unsubstituted-token case you hit in the Cowork runtime (PostToolUse hook #23).
• A regression suite (scripts/test-hooks.sh, run in CI) asserts exactly the UX contract you called out: editing a non-SQL file produces no block, and a missing or unsubstituted plugin root fails open with exit 0 and no output. It also covers the positive deny/warn/lint cases.

One honest limitation: when the host does not substitute ${CLAUDE_PLUGIN_ROOT} (the Cowork case), the lint still cannot run, because resolving that token is the host's responsibility and a plugin cannot render an install-time absolute path on its own in that runtime. What we can guarantee from the plugin side is that it degrades silently instead of erroring on every edit, which was the actual UX failure in both reports.

Appreciate the careful write-up.