Skip to content

fix: start the capture guard's Node process only for calls it can block - #91

Merged
katodea merged 2 commits into
trunkfrom
fix/bash-hook-error-notices
Nov 19, 2026
Merged

katodea merged 2 commits into
trunkfrom
fix/bash-hook-error-notices

Conversation

@ecairol

@ecairol ecairol commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor

Why

kosh registers a PreToolUse hook that runs node hooks/guard-capture.js before every Bash, Write, Edit and MultiEdit call.

Plugin hooks run in every project where kosh is enabled, so this hook runs even when kosh is not being used.

In my particular case, this was showing up a ton of errors I think because my Node version loads from .zshrc, but not 100% sure about this:

⏺ Update(~/.claude/CLAUDE.md)
PreToolUse:Edit hook error
Failed with non-blocking status code: /bin/sh: node: command not found

I was getting that "hook error" and failed message pretty often, almost on every interaction with Claude Code.

What changes

The hook still runs on every Bash, Write, Edit and MultiEdit call, but it is now a quick shell check. Node starts only when the command or file path names capture, links, jsonl or kosh-reports.

  • hooks/guard-capture.sh: This new script runs before guard-capture.js. It starts Node only when the call's command or file_path contains capture, links, jsonl or kosh-reports. Every rule in the guard needs one of these words, so the guard still blocks every case it blocked before.
  • Input filter: The script checks only command and file_path, because the guard reads only those fields. Other fields, such as the transcript path or the text of an edit, do not start Node.
  • Missing Node: If Node is missing and the call could match a rule, the hook blocks the call with exit code 2. Before this change, the call ran unchecked.
  • hooks/hooks.json: The hook now runs the .sh file.

Problems fixed:

  • Error on every call: Claude Code runs hooks in a non-interactive /bin/sh, which does not read .zshrc. If a user loads Node through nvm or a similar tool in .zshrc, node is missing from the hook's PATH. Every Bash, Write, Edit and MultiEdit call then shows PreToolUse:Bash hook error … node: command not found.
  • The guard lets calls through: That error is non-blocking, so Claude Code runs the call anyway. During a real kosh run, the capture guard then checks nothing.

Every call also starts a Node process, but most calls can never match a rule.

Tests

  • Existing cases: Every guard case now runs through the new script. If the filter skips a case that the guard blocks, the test fails.
  • Real input: Test inputs now include transcript_path, as Claude Code's real input does.
  • Missing Node: A new test runs without Node. A matching call is blocked, and an unrelated call passes.
  • Suite: node --test "tests/*.test.js" passes all 668 tests.
  • Manual check: start claude --plugin-dir <path/to/updated/kosh> on a machine without Node on the hook's PATH. git status ran with no hook error.

Effect on users whose hooks cannot find Node"

Calls that do not involve kosh no longer show an error. When kosh needs Node and cannot find it, a message tells the user to add Node to their PATH. For example, they can link it into ~/.local/bin.

Screenshots

Asking Claude to update a file:
Screenshot 2026-11-05 at 3 29 42 PM

For every Bash execution on Claude Code:
Screenshot 2026-11-05 at 3 30 16 PM

Note: You need /focus disabled to actually see the trail like the screenshots above.

This fixes a bunch of messages in Claude Code:
PreToolUse:Bash hook error
Failed with non-blocking status code: /bin/sh: node: command not found

* Introduced guard-capture.sh to manage plugin hooks and ensure Node.js is available for execution.
* Updated hooks.json to reference the new shell script instead of the previous JavaScript file.
* Modified tests to validate the functionality of the new guard mechanism and ensure proper blocking behavior without Node.js in the PATH.
@t51eng-poseidon

t51eng-poseidon Bot commented Nov 5, 2026 •

Copy link
Copy Markdown

🔱 Poseidon started reviewing this PR — central run.

Comment thread hooks/guard-capture.sh
# Only tool_input can trip a rule; the transcript path always ends in .jsonl and the cwd can hold any word. Inside a JSON string a key's quotes are escaped, so this never cuts tool_input.
printf '%s' "$input" \
| sed -E 's/"(transcript_path|agent_transcript_path|cwd)"[[:space:]]*:[[:space:]]*"[^"]*"//g' \
| grep -qiE 'capture|links|jsonl|kosh-reports' || exit 0

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The pre-filter greps the whole tool_input, so an Edit/Write/MultiEdit whose content, old_string or new_string contains links, capture or jsonl gets through to Node. guard-capture.js never reads those fields: for edit tools it only tests args.file_path (hooks/guard-capture.js:60). For the users this PR targets (no node on the hook's PATH), that call now hits exit 2. So in any project, even with kosh unused, Claude can't write a README, HTML template or JS file that mentions "links" or "capture". Before this PR the same call went through with a non-blocking error; now it's a hard block. Match only the fields the guard reads, e.g. grep -oE '"(file_path|command)"[[:space:]]*:[[:space:]]*"([^"\\]|\\.)*"' | grep -qiE 'capture|links|jsonl|kosh-reports' || exit 0. That is safe for the same reason the existing sed is: a key quoted inside a JSON string is always escaped.

🤖 Fix prompt for AI agents
Verify each finding against the current code and only fix it if
needed.

In `hooks/guard-capture.sh`:
- Line 7: The pre-filter pipes all of `tool_input` into
  `grep -qiE 'capture|links|jsonl|kosh-reports'`. That includes Write
  `content` and Edit/MultiEdit `old_string`/`new_string`, but
  `blocked()` in hooks/guard-capture.js only tests `args.file_path`
  for edit tools and `args.command` for Bash. When node is missing,
  any edit whose text mentions "links" or "capture" therefore reaches
  the `exit 2` branch and is refused in every project, a regression
  from the old non-blocking error. Narrow the check to the
  `file_path` and `command` values, for example by first extracting
  them with `grep -oE '"(file_path|command)"[[:space:]]*:[[:space:]]*"([^"\\]|\\.)*"'`,
  then applying the keyword grep. Keep the transcript_path/cwd
  stripping, the `command -v node` fail-closed branch and the final
  `node "$(dirname "$0")/guard-capture.js"` call unchanged. Add a test
  to tests/guard-capture.test.js's no-node test showing that an Edit
  whose new_string contains "links" exits 0.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in d5443ab

t51eng-poseidon[bot]

This comment was marked as resolved.

The keyword grep runs over all of tool_input, including Write content and Edit old_string/new_string, but the guard only reads file_path for edit tools. With no node on PATH, an edit whose text mentions "links" or "capture" was now refused

@t51eng-poseidon t51eng-poseidon Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔱 Poseidon Review

Summary — The latest push narrows the sh pre-filter to the command and file_path values, the only fields guard-capture.js reads, so edit text no longer trips the no-node block. No issues found on this pass; low risk.

Walkthrough

  • 🐛 Fix — hooks/guard-capture.sh now extracts "file_path"/"command" key-value pairs with grep -oE before the keyword check, replacing the sed that stripped transcript_path/cwd
  • 🧪 Tests — no-node test adds an Edit and a Write whose text mentions captures, and expects exit 0
  • 📝 Docs — AGENTS.md describes the narrower filter

♻️ Previously flagged

Resolved

  • ✅ hooks/guard-capture.sh:L7 — filter now greps only command/file_path values (top-level blocked() reads in hooks/guard-capture.js:L58-L63 are a subset), and a quoted key inside a string stays escaped, so it can't match

ℹ️ Review info
  • Commit: d5443ab
  • Files reviewed: AGENTS.md, hooks/guard-capture.sh, hooks/hooks.json, tests/guard-capture.test.js
  • Files skipped: none
  • Model: claude-opus-5-5

@ecairol
ecairol requested a review from katodea November 5, 2026 22:03
@katodea
katodea merged commit a3d2c9c into trunk Nov 19, 2026
3 checks passed
@katodea
katodea deleted the fix/bash-hook-error-notices branch November 19, 2026 15:40
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants