feat(guardrails): declare node requirement and warn at session start when it is missing - #5547
Conversation
Refs #3708 Add a README Requirements entry for node in instruction-placement, testing and source-control, and a setup check row that probes `command -v node` and reports a missing node as FAIL in instruction-placement and testing. No version floor. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…sing Refs #3708 Add a shell-form SessionStart row to guardrails and disk-hygiene that runs `command -v node` and, when node is absent, prints a JSON notice: systemMessage for the user and additionalContext for the model, both saying the plugin's guards cannot launch and enforce nothing. It needs no node, exits 0, and is silent when node is present. Cover both rows in the plugin tests. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…-shell-form-detector
Refs #3708 Record the shell-form SessionStart row in each README with the hooks-page basis for why it prints JSON: systemMessage reaches the user and additionalContext reaches the model, while plain stdout reaches only the model and exit-2 stderr only the user. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Refs #3708 Register the Stop row as `"shell": "bash"` with the script run through bash and no args, so the detector that reports failed hook launches does not itself need node. Update the README and the setup skill to say every other row still starts through node. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…-shell-form-detector
Refs #3708 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
PR body contract — issue linkage This PR body conforms to the issue-linkage contract. Nothing to do. |
…-shell-form-detector Renumber claude-ops to 0.71.2 and source-control to 0.64.1 above main's 0.71.1 and 0.64.0. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…-shell-form-detector
…rsions Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ows and pin the claude-ops detector row The hook-budget "What shipped" and "Prerequisite" bullets, the guardrails setup node check and the disk-hygiene setup node check still said every hook row runs node, which the shell-form SessionStart notice rows and the hook-failure-audit Stop row contradict. The hook-budget Scope bullet said no gate enforces the exceptions; the claude-ops row now has a test like the other two. The disk-hygiene run-python-hook test's later EXIT trap also dropped NOPY_DIR, leaking that temp directory. Refs: #3708 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… eval The setup eval's expected output still said every hook row starts through node, which the setup skill body no longer says. Refs: #3708 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Take origin/main's instruction-placement files: the Requirements section and the node probe in setup already landed there, so this branch no longer changes that plugin. Renumber claude-ops, disk-hygiene, source-control and testing above main's current versions and keep each changelog entry on top of main's. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…-shell-form-detector # Conflicts: # plugins/disk-hygiene/.claude-plugin/plugin.json # plugins/disk-hygiene/CHANGELOG.md
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
|
Claude finished @kyle-sexton's task in 1m 18s —— View job Security reviewNo security issues found. Scope reviewed: the diff against What changed, from a security lens:
Instruction-surface deletion lens: No CRITICAL, IMPORTANT, or SUGGESTION findings to report. |
|
Claude finished @kyle-sexton's task in 6m 10s —— View job Code review complete
No blocking findings. I reviewed the full diff ( What I specifically checked and verified (independently, not just author-claimed):
No inline comments were needed — I found nothing that clears the "a careful reviewer would block or flag" bar. Nice work tracing the two failure branches (missing bash vs. missing node) separately in the disk-hygiene README's fail-open table rather than conflating them. |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: e254d8a985
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Bump disk-hygiene to 0.34.0, guardrails to 0.44.0 and source-control to 0.65.5 above main, keep main's changelog entries, and document that the guardrails SessionStart notice does not read the per-guard toggles. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Claude finished @kyle-sexton's task in 1m 34s —— View job Security review
Skip gate: this head already has an applicable successful security review. I ran For completeness, I independently re-checked the PR's own security-relevant surface (scoped to this PR's diff, not the interim main commits):
No CRITICAL, IMPORTANT, or SUGGESTION security findings. (Note: the Codex bot's P2 review comment about the notice firing even when all guards are disabled is a UX/noise concern, not a security issue — it doesn't weaken any guard or open an exploit path, so it's out of this lane's scope.) |
|
Claude finished @kyle-sexton's task in 33s —— View job Review skipped — no new content since last review
The current head Per the skip gate in |
Keep main's changelog entries, bump guardrails to 0.44.0, disk-hygiene to 0.34.0 and source-control to 0.65.6 above main. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Keep main's disk-hygiene 0.34.3 entry below this PR's 0.35.0. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Claude finished @kyle-sexton's task in 41s —— View job Security review
Skip gate: this head already has an applicable successful security review.
For completeness, the PR's own security-relevant surface remains unchanged from the prior reviews:
No CRITICAL, IMPORTANT, or SUGGESTION security findings. (Note: Codex's earlier P2 comment about the notice firing even when all guards are disabled is a UX/noise concern, not a security issue — it doesn't weaken any guard or open an exploit path, and the author already declined it in-thread with a reasoned explanation. Out of this lane's scope.) |
|
Claude finished @kyle-sexton's task in 1m 0s —— View job Tasks
Review skipped — no new content since last reviewThe current head
Per the skip gate in Nothing new to report. The one open review thread (Codex's P2 suggestion to suppress the node-missing notice when every guard toggle is off, on |
Keep main's disk-hygiene 0.34.4 entry below this PR's 0.35.0. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Claude finished @kyle-sexton's task in 58s —— View job Tasks
Review skipped — no new content since last reviewThe current head
I diffed this PR's own file set between the last-reviewed head ( Per the skip gate in Nothing new to report. The one open review thread (Codex's P2 suggestion to suppress the node-missing notice when every guard toggle is off, on |
|
Claude finished @kyle-sexton's task in 1m 0s —— View job Security review
Skip gate: this head already has an applicable successful security review.
For completeness, the PR's own security-relevant surface remains unchanged from the prior reviews:
No CRITICAL, IMPORTANT, or SUGGESTION security findings. (Note: Codex's earlier P2 comment about the notice firing even when all guards are disabled is a UX/noise concern, not a security issue — it doesn't weaken any guard or open an exploit path, and the author already declined it in-thread with a reasoned explanation. Out of this lane's scope.) |
Bump disk-hygiene to 0.36.0 and source-control to 0.67.1 above main and keep main's changelog entries. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Claude finished @kyle-sexton's task in 1m 22s —— View job Tasks
Security reviewSkip gate: this head already has an applicable successful security review.
I diffed this PR's own file set between the last-reviewed head ( → empty. Four files did pick up interleaved content from the For completeness, the PR's own security-relevant surface remains unchanged from the prior reviews:
No CRITICAL, IMPORTANT, or SUGGESTION security findings. (Note: Codex's earlier P2 comment about the notice firing even when all guards are disabled is a UX/noise concern, not a security issue — it doesn't weaken any guard or open an exploit path, and the author already declined it in-thread with a reasoned explanation. Out of this lane's scope.) |
|
Claude finished @kyle-sexton's task in 45s —— View job Tasks
Review skipped — no new content since last reviewThe current head
I diffed this PR's own functional file set between the last-reviewed head ( Per the skip gate in Nothing new to report. The one open review thread (Codex's P2 suggestion to suppress the node-missing notice when every guard toggle is off, on |
Keep main's disk-hygiene 0.35.1 entry below this PR's 0.36.0. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Claude finished @kyle-sexton's task in 1m 15s —— View job Tasks
Review skipped — no new content since last reviewThe current head
Per the skip gate in Nothing new to report. The one open review thread (Codex's P2 suggestion to suppress the node-missing notice when every guard toggle is off, on |
|
Claude finished @kyle-sexton's task in 3m 8s —— View job Tasks
Security reviewSkip gate: this head already has an applicable successful security review.
I diffed this PR's own 29 changed files between the last-reviewed head ( → empty. Per the skip gate, I'm not re-litigating a review that already applies to this exact diff. For completeness, the PR's own security-relevant surface remains unchanged from the prior reviews:
No CRITICAL, IMPORTANT, or SUGGESTION security findings. (Note: Codex's earlier P2 comment about the notice firing even when all guards are disabled is a UX/noise concern, not a security issue — it doesn't weaken any guard or open an exploit path, and the author already declined it in-thread with a reasoned explanation. Out of this lane's scope.) |
Bump claude-ops to 0.75.3, source-control to 0.67.2 and testing to 0.11.9 above main and keep main's changelog entries. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Claude finished @kyle-sexton's task in 1m 41s —— View job Tasks
Security reviewSkip gate: this head already has an applicable successful security review.
The merge itself ( → empty. The one visible change against the new For completeness, the PR's own security-relevant surface remains unchanged from the prior reviews:
No CRITICAL, IMPORTANT, or SUGGESTION security findings. (Note: Codex's earlier P2 comment about the notice firing even when all guards are disabled is a UX/noise concern, not a security issue — it doesn't weaken any guard or open an exploit path, and the author already declined it in-thread with a reasoned explanation. Out of this lane's scope.) |
|
Claude finished @kyle-sexton's task in 37s —— View job Tasks
Review skipped — no new content since last reviewThe current head
Per the skip gate in Nothing new to report. The one open review thread (Codex's P2 suggestion to suppress the node-missing notice when every guard toggle is off, on |
Keep main's disk-hygiene 0.35.2 entry below this PR's 0.36.0. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Claude finished @kyle-sexton's task in 43s —— View job Tasks
Security reviewSkip gate: this head already has an applicable successful security review.
I confirmed directly that this PR's security-relevant surface is untouched since the last review: → empty. Per the skip gate, I'm not re-litigating a review that already applies to this exact diff. For completeness, the PR's own security-relevant surface remains unchanged from the prior reviews:
No CRITICAL, IMPORTANT, or SUGGESTION security findings. (Note: Codex's earlier P2 comment about the notice firing even when all guards are disabled is a UX/noise concern, not a security issue — it doesn't weaken any guard or open an exploit path, and the author already declined it in-thread with a reasoned explanation. Out of this lane's scope.) |
|
Claude finished @kyle-sexton's task in 46s —— View job Tasks
Review skipped — no new content since last reviewThe current head
I diffed this PR's own functional files directly between the last-reviewed head ( Per the skip gate in Nothing new to report. The one open review thread (Codex's P2 suggestion to suppress the node-missing notice when every guard toggle is off, on |
Bump claude-ops to 0.76.1 above main and keep main's 0.76.0 entry. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Claude finished @kyle-sexton's task in 2m 6s —— View job Tasks
Security reviewSkip gate: this head already has an applicable successful security review.
I read the full current diff directly (
Per the skip gate, I'm not re-litigating a review that already applies to this exact diff. No CRITICAL, IMPORTANT, or SUGGESTION security findings. (Note: Codex's earlier P2 comment about the notice firing even when all guards are disabled is a UX/noise concern, not a security issue — it doesn't weaken any guard or open an exploit path, and the author already declined it in-thread with a reasoned explanation. Out of this lane's scope.) |
|
Claude finished @kyle-sexton's task in 1m 19s —— View job Tasks
Review skipped — no new content since last reviewThe current head
I diffed this PR's own functional files directly between the last-reviewed head ( → empty. The only files that picked up any content from the merge overlap this PR's file set in Per the skip gate in Nothing new to report. The one open review thread (Codex's P2 suggestion to suppress the node-missing notice when every guard toggle is off, on |
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Claude finished @kyle-sexton's task in 50s —— View job Tasks
Review skipped — no new content since last reviewThe current head
I diffed this PR's own file set directly between the last-reviewed head ( The only overlap is Per the skip gate in Nothing new to report. The one open review thread (Codex's P2 suggestion to suppress the node-missing notice when every guard toggle is off, on |
|
Claude finished @kyle-sexton's task in 1m 51s —— View job Tasks
Security reviewSkip gate: this head already has an applicable successful security review.
I diffed this PR's own 29-file set directly between the last-reviewed head (
I confirmed directly that this PR's security-relevant surface is byte-identical to what was already reviewed: → empty. Per the skip gate, I'm not re-litigating a review that already applies to this exact diff. For completeness, the PR's own security-relevant surface remains unchanged from the prior reviews:
No CRITICAL, IMPORTANT, or SUGGESTION security findings. (Note: Codex's earlier P2 comment about the notice firing even when all guards are disabled is a UX/noise concern, not a security issue — it doesn't weaken any guard or open an exploit path, and the author already declined it in-thread with a reasoned explanation. Out of this lane's scope.) |
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Claude finished @kyle-sexton's task in 1m 4s —— View job Tasks
Review skipped — no new content since last reviewThe current head
I diffed this PR's own functional files directly between the last-reviewed head ( → empty. The only overlap with this PR's changed-file set is Per the skip gate in Nothing new to report. The one open review thread (Codex's P2 suggestion to suppress the node-missing notice when every guard toggle is off, on |
|
Claude finished @kyle-sexton's task in 40s —— View job Tasks
Security reviewSkip gate: this head already has an applicable successful security review.
I confirmed directly that this PR's security-relevant surface is byte-identical to what was already reviewed: → empty. Per the skip gate, I'm not re-litigating a review that already applies to this exact diff. For completeness, the PR's own security-relevant surface remains unchanged from the prior reviews:
No CRITICAL, IMPORTANT, or SUGGESTION security findings. (Note: Codex's earlier P2 comment about the notice firing even when all guards are disabled is a UX/noise concern, not a security issue — it doesn't weaken any guard or open an exploit path, and the author already declined it in-thread with a reasoned explanation. Out of this lane's scope.) |

Refs: #3708
Summary
Hook rows launch through
node, and Claude Code's native binary does not ship Node. A host withoutnodetherefore ran guards that enforced nothing, with no signal. This implements the owner decision (2026-09-29) on #3708: Q1(A) declare the requirement, Q1(B) add a shell-form notice, Q3(a) move the detector row to shell form. Q2 (whether a missingnodeshould block) stays with the owner; the evidence is posted on the issue, which stays open withneeds-human.Fix
nodeprobe in its setupcheck; source-control's existing Node.js line moves into a Requirements section. claude-ops and instruction-placement already declare it on main (instruction-placement from fix(instruction-placement): align /memory claims, consolidate cutover records, neutralize owner-decision records #5285, which this PR does not touch); claude-ops changes only to name thehook-failure-auditexception.nodeis not onPATH.hook-failure-auditStop row runs in shell form, so the detector works whennodeis the missing piece.docs/plugin-philosophy.mdHooks row anddocs/conventions/hook-budget/README.mdname the three shell-form exceptions;scripts/check-killswitch-hoist.shdocuments the inline rows as not scanned.Verification
Run on the merged head 365c8f9, which merges origin/main at 681789d:
git merge-tree --write-tree HEAD origin/main: no conflicts.scripts/check-changelog-parity.sh --check,--check-order,--check-bump origin/main,--check-preserved origin/main: pass;scripts/check-stale-base-overlap.sh --check origin/main: up to date.scripts/validate-plugins.sh: all manifests and the catalog validated.bash plugins/guardrails/hooks/exec-bash.test.sh: pass, including the notice row with and without node.bash plugins/disk-hygiene/hooks/run-python-hook.test.sh: pass.bash plugins/claude-ops/hooks/hook-failure-audit.test.sh: pass (126 checks), including a pin that the Stop row stays shell form.bash scripts/check-killswitch-hoist.sh,check-hook-exec-form.sh,check-hook-slow-shapes.sh,check-hook-userconfig-argv.sh,check-hooks-description.sh: clean.hook-census.test.sh(needs strace, unavailable here).Related
🤖 Generated with Claude Code