feat(claude-ops): surface missing fleet prerequisites without installing (#4240)

[kyle-sexton]

Closes #4240

Summary

Missing external tools now surface to the main session and are reported, never installed. This follows the operator decision on #4240: a claude-ops:prerequisites skill backed by a prerequisites.json manifest per plugin, with every probe reading that file.

Fix

• prerequisites.json at the root of biome-format, go-format, markdown-format, context7, and playwright declares each tool: name, optional local_bin, check, and install.
• claude-ops:prerequisites (check-prerequisites.sh) reads the manifest of each enabled plugin and prints a present/missing table. It does not install, download, or run npx.
• The session-start hooks/probe-prerequisite.sh in biome-format, go-format, and markdown-format is one shared script. It takes every tool name, local_bin, check command, and install line from its plugin's prerequisites.json; no binary name or install text is hardcoded.
• hook::notice_once takes an optional prerequisite class: the notice latches once per session instead of per agent, and a renewal keeps the install route. Callers that omit the class, including every guardrails, context-guard, and rate-limit-guard hook, behave exactly as before. The shared lib/hook-utils.sh is synced to all 17 copies.
• The per-edit format hooks share the probe's notice key, so a session sees one notice, not two.
• Per-plugin check skills for the three format plugins are read-only and never run apply.
• Every touched plugin is bumped one patch above main with a CHANGELOG entry.

Verification

• scripts/check-prerequisite-probes.test.sh (new, 18 cases). It fails when a probe differs from the shared manifest reader, contains an install command, omits a declared tool's name, check, or install text from its notice while the tool is missing, or prints anything when every declared tool is present.
• check-prerequisites.test.sh 6/0, lib/hook-utils.test.sh 582/0, sync-hook-utils.sh --check, go-format 63/0, biome-format 54/0.
• markdown-format (175/2) and guardrails run-guards.test.sh (309/2) fail the same two cases each on a clean origin/main checkout on this machine, so those failures are not from this diff.
• Guard plugins: the only code change is the synced hook-utils.sh notice path. No guard hook passes the prerequisite class, so their allow and deny decisions are unchanged from main.
• validate-plugins.sh, check-changelog-parity.sh --check --check-order, check-changed-skills.sh origin/main, validate-plugin-contracts.mjs, catalog and cheat-sheet --check, skill-count claims, skill leaf names, purged em dashes, and shellcheck all pass.

Related

• Operator decision: hooks: missing external tools are not surfaced to the user; add a model-invocable fleet-wide prerequisites check (no auto-install) #4240 comment of 2026-09-29.

🤖 Generated with Claude Code

https://claude.ai/code/session_01WejvGhkHUSWPRim2caW2Wh

[github-actions]

PR body contract — issue linkage

This PR body conforms to the issue-linkage contract. Nothing to do.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-29T02:04:50.562756Z	6c144df	Draft marked ready

ℹ️ 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" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 6c144dfdbc

ℹ️ 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".

[claude]

Claude finished @kyle-sexton's task in 2m 45s —— View job

---

Security review — /review:security-review

• Gather context (PR diff, changed files)
• Run /review:security-review criteria over the diff
• Report findings

No security issues found in this PR's diff.

What I reviewed: the new check-prerequisites.sh fleet-prerequisite reader (plugins/claude-ops/skills/prerequisites/scripts/check-prerequisites.sh), the shared probe-prerequisite.sh now templated from each plugin's prerequisites.json (e.g. plugins/go-format/hooks/probe-prerequisite.sh), and the hook::notice_once/hook::emit_skip_notice changes synced to all 17 hook-utils.sh copies (e.g. lib/hook-utils.sh#L193-L218).

Notes:

• field() in probe-prerequisite.sh extracts check/install text from prerequisites.json via regex and only ever interpolates it into a notice string (hook::emit_skip_notice ... "Install: $(field install "$entry")"); that substitution happens once and the result is never re-evaluated as shell, so embedded shell metacharacters in a manifest value can't achieve command injection. prerequisites.json is also a repo-committed, plugin-author-controlled file, not runtime/attacker input, so it isn't a trust-boundary crossing either way.
• check-prerequisites.sh's embedded Python only reads local ~/.claude config/state (settings.json, installed_plugins.json, prerequisites.json) with json.load and does presence checks via shutil.which — no subprocess/eval/os.system calls, so there's no injection surface from plugin or config content.
• Confirmed the guardrails/rate-limit-guard/context-guard hook-utils.sh diffs are the synced notice-path change only (plugins/guardrails/hooks/hook-utils.sh) — no guard hook in this diff passes the new prerequisite class to hook::notice_once, so allow/deny decisions are unaffected, matching the PR description.
• No new network calls, credential handling, or install/download execution were introduced; every check/probe path is read-only as documented, and apply-style install skills stay gated behind explicit user request in the check SKILL.md files.

Out of scope for this lane (functional, not security — already flagged by the Codex review and better suited to /review:code-review): check-prerequisites.sh's enabled-plugin discovery only reads user/machine-scope settings.json/settings.local.json under CLAUDE_CONFIG_DIR, so project/local-scoped plugin enablement isn't merged in, and an empty resolved fleet falls through to the repo-wide plugins/*/prerequisites.json scan — both can produce a misleading present/missing table, but neither is an exploitable vulnerability.

[claude]

Claude finished @kyle-sexton's task in 3m 17s —— View job

---

Code review — /review:code-review

• Gather context (PR diff, files, existing Codex feedback)
• Invoke /review:code-review skill per instructions
• Post inline comments for anchorable findings
• Update summary comment with overview

Reviewed the changed files per the code-review lane's criteria (correctness + CLAUDE.md/AGENTS.md alignment, scoped to files changed in this PR). This PR's core surface is: the new claude-ops:prerequisites skill and its check-prerequisites.sh fleet reader, the shared probe-prerequisite.sh SessionStart probe (synced identically into biome-format, go-format, markdown-format), the prerequisites.json manifests, and the hook::notice_once prerequisite class added to lib/hook-utils.sh (synced to all 17 copies).

3 findings posted as inline comments:

1. plugins/claude-ops/skills/prerequisites/scripts/check-prerequisites.sh:37 — the no-args discovery path reads enabledPlugins only from $CLAUDE_CONFIG_DIR (~/.claude)'s settings.json/settings.local.json, never from the current repo's .claude/settings.json / settings.local.json. A plugin enabled only at project/local scope is invisible to this checker, so the table can report the fleet as healthy while a project-enabled plugin's prerequisite is actually missing. plugins/claude-ops/skills/plugins/scripts/fleet-state.sh (~lines 773-804) already merges user+project+local scopes; this script should do the same. check-prerequisites.test.sh only covers the explicit --plugin-root path, so this gap is untested.
2. plugins/claude-ops/skills/prerequisites/scripts/check-prerequisites.sh:79 — an empty ROOTS array is treated identically whether the settings/installed_plugins.json read succeeded with zero enabled plugins or genuinely failed. Both fall through to scanning this repo's own plugins/*/prerequisites.json, so running the checker from a fresh claude-code-plugins checkout with nothing enabled reports all 5 in-repo manifests as "the fleet" — the opposite of "does this host have what the enabled plugins need?" The read-succeeded-but-empty case needs to be distinguished from read-failed before falling back.
3. plugins/claude-ops/skills/prerequisites/SKILL.md:29 (low severity) — the ## Next bullet hard-codes /markdown-format:check as the outcome for "a tool is missing," which is wrong for 4 of the 5 declared tools. Not actively harmful since line 32 immediately corrects it ("Run the named check"), but worth generalizing the bullet.

Findings 1 and 2 substantively overlap with the existing Codex review comments on this PR — I verified both independently against fleet-state.sh's scope-merge logic and by tracing the empty-vs-absent-state branch, and both hold up as real, concretely-triggerable bugs (I did not just restate Codex's text).

Everything else checked out: the shared hook::notice_once "prerequisite" class in lib/hook-utils.sh correctly scopes the latch to session-only (not per-agent) while leaving every non-prerequisite caller's behavior unchanged (verified by reading the full function and its new test cases in lib/hook-utils.test.sh:1300-1339); the per-edit format hooks (biome-format.sh:124, go-format.sh:140, markdown-format.sh:689) and their SessionStart probes key on the identical <plugin>-<tool> string, so the "one notice, not two" claim checks out; probe-prerequisite.sh is byte-identical across all three format plugins (confirmed via the SHA in the file listing) and contains no install/download command; and the prerequisites.json manifests for context7/playwright are plain declarative data with no logic to review.

Author-claimed and not independently re-run by me (no test/build tooling available in this session): the test counts and pass/fail figures in the PR's Verification section, sync-hook-utils.sh --check, and the various validate-*/check-* gate scripts.

[claude]

Claude finished @kyle-sexton's task in 1m 47s —— View job

---

Code review — /review:code-review

• Gather context (PR diff, files, existing Codex/Claude feedback)
• Invoke /review:code-review skill per instructions
• Post inline comments for anchorable findings
• Update summary comment with overview

Reviewed the full diff (origin/main...HEAD, 94 files, +1424/-163) at head 1d32bf0. The only change since the prior review pass (base 253ef75/6c144df) is 0449898 — registering the synced probe-prerequisite.sh in scripts/cross-plugin-source-registry.txt and portability-hardening two grep patterns in scripts/check-prerequisite-probes.test.sh. That commit is correct: it uses an associative-array membership check instead of the GNU-only \b/piped-grep -q pattern, and adds the registry entry so hooks/probe-prerequisite.sh (byte-identical across biome-format, go-format, markdown-format) has a drift check.

The substantive surface — check-prerequisites.sh, the shared probe, the hook::notice_once "prerequisite" class in lib/hook-utils.sh, and the prerequisites.json manifests — is unchanged from the previously-reviewed commit, so the 3 findings from that pass still hold and are posted as inline comments on the current HEAD:

1. check-prerequisites.sh:42 — no-args discovery reads enabledPlugins only from $CLAUDE_CONFIG_DIR, never from the current repo's project/local .claude/settings*.json. A project-only-enabled plugin's prerequisite is silently invisible to the table.
2. check-prerequisites.sh:89 — a successfully-read, legitimately-empty enabled fleet is indistinguishable from "state absent" and falls back to scanning this repo's own plugins/*/prerequisites.json, reporting an unrelated 5-tool "fleet" from a fresh checkout with nothing enabled.
3. SKILL.md:29 (low severity) — ## Next hard-codes /markdown-format:check as the missing-tool outcome, wrong for 4 of 5 declared tools; corrected two lines later but misleading as the headline bullet.

Findings 1 and 2 are P2 correctness bugs on the no-args discovery path, which check-prerequisites.test.sh doesn't cover (it only exercises --plugin-root). Both were independently raised by Codex and a prior claude review pass on commit 253ef75/6c144df and remain unaddressed on this HEAD.

Everything else checked out on this pass: lib/hook-utils.sh's new HOOK_NOTICE_KEEP_BODY/session_only path for the prerequisite class only changes behavior when a caller passes that class (verified no guard/rate-limit/context-guard hook does); probe-prerequisite.sh correctly derives every name/local_bin/check/install string from prerequisites.json with no hardcoded binary or install command; and the per-edit hook / SessionStart probe notice keys match (e.g. biome-format-biome in both biome-format.sh:124 and probe-prerequisite.sh:52), so the "one notice, not two" claim holds.

[claude]

Claude finished @kyle-sexton's task in 1m 1s —— View job

---

Security review — /review:security-review

• Gather context (PR diff, changed files)
• Run /review:security-review criteria over the diff
• Report findings

No security issues found in this PR's diff.

What changed since the last security review on this head: the only new commits since the prior /review:security-review pass (at 253ef75) are 0449898 (registers hooks/probe-prerequisite.sh in the cross-plugin source registry and swaps a GNU-\b grep for a POSIX-compatible pattern in check-prerequisite-probes.test.sh) and the merge commit 1d32bf0. I confirmed the security-relevant surface — plugins/claude-ops/skills/prerequisites/scripts/check-prerequisites.sh, the three probe-prerequisite.sh copies (biome-format, go-format, markdown-format), and lib/hook-utils.sh — is byte-identical to what was already reviewed with no findings; the new commit touches only a test script and a registry doc entry, neither of which executes against untrusted input or handles credentials/tokens.

New commit reviewed on its own merits:

• scripts/check-prerequisite-probes.test.sh: the \b-word-boundary grep was replaced with [[:space:]]|$ and the piped printf … | grep -qxF early-exit was replaced with an associative-array membership check (IS_DECLARED[$base]). Both are portability/style fixes to test-harness code that only inspects this repo's own prerequisites.json manifests and local $PATH binaries — no injection surface, no untrusted input, no privilege boundary.
• scripts/cross-plugin-source-registry.txt: adds a comment line documenting that hooks/probe-prerequisite.sh is a synced file guarded by the new drift test. Pure documentation.

This reaffirms the prior pass's conclusions: check-prerequisites.sh's embedded Python only does read-only json.load/shutil.which checks against local ~/.claude state (no subprocess/eval/os.system), probe-prerequisite.sh's field() extraction only interpolates prerequisites.json values into a notice string (never re-evaluated as shell), and no guard hook (guardrails/rate-limit-guard/context-guard) passes the new prerequisite notice class, so their allow/deny decisions are unchanged.

(Functional/correctness observations — project/local plugin-scope discovery gap and the empty-vs-absent ROOTS fallback — are already tracked via Codex's and the prior code-review pass's inline comments; out of scope for this security lane.)

[claude]

Claude finished @kyle-sexton's task in 53s —— View job

---

Security review — /review:security-review

• Gather context (PR diff, changed files)
• Run /review:security-review criteria over the diff
• Report findings

No security issues found in this PR's diff.

What changed since the last security review on this branch: the only new commit is b44b45e (fix(claude-ops): read project-scope enablement; no repo scan for an empty fleet), which addresses the two P2 correctness findings raised by Codex and prior claude review passes (project/local-scope plugin discovery, and distinguishing "state read but empty" from "state absent"). It touches only plugins/claude-ops/skills/prerequisites/scripts/check-prerequisites.sh, its test, and SKILL.md prose — no other file changed.

Reviewed on its own merits:

• The embedded Python (lines 36–83) now also reads $CLAUDE_PROJECT_DIR/.claude/settings.json / settings.local.json in addition to $CLAUDE_CONFIG_DIR's, and merges enabledPlugins across scopes. All four paths are opened with plain json.load — no subprocess/eval/os.system — so this is a read-only widening of which trusted-looking file paths get parsed, not a new execution surface.
• The set of enabled keys can now be influenced by a project-scope .claude/settings.local.json inside a checked-out repo, but the actual installPath used to locate each plugin's prerequisites.json still comes only from $CLAUDE_CONFIG_DIR/plugins/installed_plugins.json (line 62), which is user/machine-scope, not repo-controlled. So a hostile repo's settings.local.json can at most toggle which already-installed plugin's prerequisites get checked — it can't point the script at an attacker-chosen path or inject a new check/install string, since those still come from that installed plugin's own prerequisites.json on disk. No new injection or path-traversal surface.
• project (from $CLAUDE_PROJECT_DIR or git rev-parse --show-toplevel) is passed to Python only as an argv string consumed via os.path.join/os.path.isfile — never interpolated into a shell command or eval'd. The STATE_READ sentinel line is parsed back in bash with a literal == string comparison (line 90), not eval, so no injection there either.
• This mirrors the existing scope-merge trust model already used by plugins/claude-ops/skills/plugins/scripts/fleet-state.sh for the equivalent "effective fleet" computation, so it doesn't introduce a new trust boundary — it fixes an inconsistency with it.
• The new test cases in check-prerequisites.test.sh (project-local enablement, empty-fleet fallback) only exercise local fixture directories under $WORK; no network calls, credentials, or execution of untrusted content.

This reaffirms the conclusions of the prior security-review passes on this PR (253ef75/1d32bf0): check-prerequisites.sh remains read-only, probe-prerequisite.sh's field() extraction only interpolates manifest text into a notice string, and no guard hook passes the prerequisite notice class.

(The correctness fix itself — and whether it fully resolves the Codex/code-review P2 findings — is /review:code-review's lane, not this one.)

[claude]

Claude finished @kyle-sexton's task in 2m 54s —— View job

---

Code review — /review:code-review

• Gather context (PR diff, files, existing Codex/Claude feedback)
• Invoke /review:code-review skill per instructions
• Post inline comments for anchorable findings
• Update summary comment with overview

The only change since the last review pass on this lane (base 1d32bf0) is b44b45e, which touches exactly check-prerequisites.sh, check-prerequisites.test.sh, and SKILL.md in plugins/claude-ops/skills/prerequisites/. I traced the new logic by hand (line by line, including the embedded Python) rather than restating the author's own test-count claims, since I could not execute check-prerequisites.test.sh in this sandbox (script execution was denied by the permission gate). I did not find any new correctness issues, and the three findings raised by Codex and prior claude review passes on the earlier commit are each resolved:

1. Project/local-scope enablement now merges in. check-prerequisites.sh:38-95 now reads enabledPlugins from $CLAUDE_CONFIG_DIR/settings.json, settings.local.json, and $CLAUDE_PROJECT_DIR/.claude/settings.json/settings.local.json (falling back to git rev-parse --show-toplevel when CLAUDE_PROJECT_DIR is unset), applying each scope's true/false in that order so a later scope's value wins per key. I traced the new test case ("project-local enablement is read") by hand: a plugin disabled in user settings.json but enabled in the project's settings.local.json correctly resolves to enabled and its installed_plugins.json record is picked up.
2. Empty-but-read state no longer triggers the repo-scan fallback. The Python block now emits a separate STATE_READ marker whenever any settings file parsed successfully or installed_plugins.json exists (lines 60-68), and the repo-scan/error branches (lines 99, 109) now gate on STATE_READ == 0, not just an empty ROOTS array. I traced the new "empty enabled fleet exits 0" test case: with settings read successfully and zero plugins enabled, the script now prints an empty table (missing=0 present=0, exit 0) instead of scanning this repo's own plugins/*/prerequisites.json.
3. SKILL.md's ## Next bullet is now generic. SKILL.md:29 reads "A tool is missing: the check skill that row names" instead of hard-coding /markdown-format:check.

One thing worth noting but not blocking: the merge order comment says "User, then project, then local" (line 46), but the actual scope list also includes the user-level settings.local.json between user and project scopes — a scope fleet-state.sh's merge doesn't model at all. That's pre-existing behavior carried over from before this PR (not introduced by b44b45e), and it's arguably more complete than fleet-state.sh, so I'm not raising it as a finding.

No inline comments to post — no new anchorable findings on this head.

Author-claimed and not independently re-run by me in this session (no ability to execute scripts): the specific test pass counts in the PR description, sync-hook-utils.sh --check, and the various validate-*/check-* gate scripts.