From edb65e6be4e091e2fe0f57666c07f9163bc370f1 Mon Sep 17 00:00:00 2001 From: Dan Guido Date: Mon, 15 Jun 2026 09:05:04 -0700 Subject: [PATCH] fix(fp-check): scope completeness hooks to skill/agent frontmatter (#143) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The plugin-level hooks/hooks.json registered Stop and SubagentStop hooks with matcher "*". Because plugin hooks are always-on, both fired on every (sub)agent stop in any session where fp-check was merely installed — burning a 30s LLM turn and injecting stop-feedback even when fp-check was never used, then no-opping via the prompt's own fallback. Root-cause fix: move the hooks into skill/agent frontmatter, which per the Claude Code docs is "scoped to the component's lifecycle and only run when that component is active": - Overall verification-completeness Stop hook -> fp-check SKILL.md frontmatter. Fires only when the fp-check skill is loaded. - Per-subagent output checks -> each agent's own frontmatter as a Stop hook, which auto-converts to SubagentStop. data-flow-analyzer checks Phase 1, exploitability-verifier Phase 2, poc-builder Phase 4. Each fires only when that specific agent runs, so the single SubagentStop prompt's "identify which agent type" branching is no longer needed. - Delete plugins/fp-check/hooks/hooks.json. This fixes both hooks (not just Stop) and keeps full coverage including inline fp-check runs, unlike deleting the Stop hook outright. Hook prompts and the {"ok"/"reason"} response schema are carried over unchanged from the current plugin hooks. Bump 1.0.2 -> 1.0.3. Co-Authored-By: Claude Opus 4.8 (1M context) --- .claude-plugin/marketplace.json | 2 +- plugins/fp-check/.claude-plugin/plugin.json | 2 +- plugins/fp-check/agents/data-flow-analyzer.md | 18 ++++++++++++ .../agents/exploitability-verifier.md | 18 ++++++++++++ plugins/fp-check/agents/poc-builder.md | 19 ++++++++++++ plugins/fp-check/hooks/hooks.json | 29 ------------------- plugins/fp-check/skills/fp-check/SKILL.md | 22 ++++++++++++++ 7 files changed, 79 insertions(+), 31 deletions(-) delete mode 100644 plugins/fp-check/hooks/hooks.json diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 28d336b7..881b3732 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -375,7 +375,7 @@ }, { "name": "fp-check", - "version": "1.0.2", + "version": "1.0.3", "description": "Systematic false positive verification for security bug analysis with mandatory gate reviews", "author": { "name": "Maciej Domanski" diff --git a/plugins/fp-check/.claude-plugin/plugin.json b/plugins/fp-check/.claude-plugin/plugin.json index dd9b410a..9919d561 100644 --- a/plugins/fp-check/.claude-plugin/plugin.json +++ b/plugins/fp-check/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "fp-check", - "version": "1.0.2", + "version": "1.0.3", "description": "Systematic false positive verification for security bug analysis with mandatory gate reviews", "author": { "name": "Maciej Domanski" diff --git a/plugins/fp-check/agents/data-flow-analyzer.md b/plugins/fp-check/agents/data-flow-analyzer.md index 750d280f..8f9c8935 100644 --- a/plugins/fp-check/agents/data-flow-analyzer.md +++ b/plugins/fp-check/agents/data-flow-analyzer.md @@ -7,6 +7,24 @@ tools: - Read - Grep - Glob +hooks: + Stop: + - matcher: "*" + hooks: + - type: prompt + timeout: 30 + prompt: | + You are an output completeness checker for the fp-check data-flow-analyzer subagent, which is about to stop. Verify it produced complete structured output for its assigned Phase 1 work. + + Required sections: + - Phase 1.1: Trust boundary map with source, path, sink, and validation points (each with file:line references) + - Phase 1.2: API contract analysis (built-in protections identified or absence noted) + - Phase 1.3: Environment protection analysis (each classified as 'prevents entirely' or 'raises bar') + - Phase 1.4: Cross-reference analysis (similar patterns, test coverage, history) + - Phase 1 Conclusion with evidence + + If required sections are missing, respond with JSON: {"ok": false, "reason": ""} + If all required sections are present with evidence, respond with JSON: {"ok": true} --- # Data Flow Analyzer diff --git a/plugins/fp-check/agents/exploitability-verifier.md b/plugins/fp-check/agents/exploitability-verifier.md index e08550fb..50c957aa 100644 --- a/plugins/fp-check/agents/exploitability-verifier.md +++ b/plugins/fp-check/agents/exploitability-verifier.md @@ -7,6 +7,24 @@ tools: - Read - Grep - Glob +hooks: + Stop: + - matcher: "*" + hooks: + - type: prompt + timeout: 30 + prompt: | + You are an output completeness checker for the fp-check exploitability-verifier subagent, which is about to stop. Verify it produced complete structured output for its assigned Phase 2 work. + + Required sections: + - Phase 2.1: Attacker control analysis with control level (full/partial/none) and evidence + - Phase 2.2: Mathematical bounds proof with step-by-step algebra, OR explicit 'N/A — not a bounds issue' + - Phase 2.3: Race condition feasibility analysis, OR explicit 'N/A — not a concurrency issue' + - Phase 2.4: Adversarial analysis synthesizing 2.1-2.3 + - Phase 2 Conclusion with evidence + + If required sections are missing, respond with JSON: {"ok": false, "reason": ""} + If all required sections are present with evidence, respond with JSON: {"ok": true} --- # Exploitability Verifier diff --git a/plugins/fp-check/agents/poc-builder.md b/plugins/fp-check/agents/poc-builder.md index 1f62da7a..8f17610f 100644 --- a/plugins/fp-check/agents/poc-builder.md +++ b/plugins/fp-check/agents/poc-builder.md @@ -10,6 +10,25 @@ tools: - Grep - Glob - Bash +hooks: + Stop: + - matcher: "*" + hooks: + - type: prompt + timeout: 30 + prompt: | + You are an output completeness checker for the fp-check poc-builder subagent, which is about to stop. Verify it produced complete structured output for its assigned Phase 4 work. + + Required sections: + - Phase 4.1: Pseudocode PoC with data flow diagram (always required) + - Phase 4.2: Executable PoC or explicit skip with justification + - Phase 4.3: Unit test PoC or explicit skip with justification + - Phase 4.4: Negative PoC showing exploit preconditions + - Phase 4.5: Verification that PoCs demonstrate the vulnerability + - Phase 4 Conclusion + + If required sections are missing, respond with JSON: {"ok": false, "reason": ""} + If all required sections are present with evidence, respond with JSON: {"ok": true} --- # PoC Builder diff --git a/plugins/fp-check/hooks/hooks.json b/plugins/fp-check/hooks/hooks.json deleted file mode 100644 index 54eaf272..00000000 --- a/plugins/fp-check/hooks/hooks.json +++ /dev/null @@ -1,29 +0,0 @@ -{ - "description": "Enforce fp-check verification completeness — prevent premature verdicts and incomplete agent output", - "hooks": { - "Stop": [ - { - "matcher": "*", - "hooks": [ - { - "type": "prompt", - "prompt": "You are a verification completeness checker for the fp-check false positive analysis skill. The agent is about to stop. Check whether the verification process was completed properly.\n\nScan the conversation for evidence of ALL of the following for EVERY bug that was being verified:\n\n1. Phase 1 (Data Flow Analysis): Trust boundaries mapped, API contracts checked, environment protections analyzed, cross-references checked\n2. Phase 2 (Exploitability Verification): Attacker control confirmed or denied, mathematical bounds analyzed (or marked N/A), race conditions analyzed (or marked N/A), adversarial analysis completed\n3. Phase 3 (Impact Assessment): Real security impact vs operational robustness distinguished, primary controls vs defense-in-depth distinguished\n4. Phase 4 (PoC Creation): Pseudocode PoC created, executable/unit test PoCs created or explicitly skipped with justification, negative PoC created, PoC verification completed\n5. Phase 5 (Devil's Advocate): All 13 challenge questions addressed\n6. Gate Review: All 6 gates (Process, Reachability, Real Impact, PoC Validation, Math Bounds, Environment) evaluated with pass/fail\n7. Verdict: Each bug has a TRUE POSITIVE or FALSE POSITIVE verdict with evidence\n\nIf ANY bug is missing ANY of these phases or the gate review, respond with JSON: {\"ok\": false, \"reason\": \"\"}\nIf all bugs have complete verification with verdicts, respond with JSON: {\"ok\": true}\nIf the conversation is not about fp-check verification at all, respond with JSON: {\"ok\": true}", - "timeout": 30 - } - ] - } - ], - "SubagentStop": [ - { - "matcher": "*", - "hooks": [ - { - "type": "prompt", - "prompt": "You are an output completeness checker for fp-check verification agents. A subagent is about to stop. Check whether it produced complete structured output for its assigned phases.\n\nIdentify which agent type this is from the conversation context and verify completeness:\n\n**data-flow-analyzer** must include:\n- Phase 1.1: Trust boundary map with source, path, sink, and validation points (each with file:line references)\n- Phase 1.2: API contract analysis (built-in protections identified or absence noted)\n- Phase 1.3: Environment protection analysis (each classified as 'prevents entirely' or 'raises bar')\n- Phase 1.4: Cross-reference analysis (similar patterns, test coverage, history)\n- Phase 1 Conclusion with evidence\n\n**exploitability-verifier** must include:\n- Phase 2.1: Attacker control analysis with control level (full/partial/none) and evidence\n- Phase 2.2: Mathematical bounds proof with step-by-step algebra, OR explicit 'N/A — not a bounds issue'\n- Phase 2.3: Race condition feasibility analysis, OR explicit 'N/A — not a concurrency issue'\n- Phase 2.4: Adversarial analysis synthesizing 2.1-2.3\n- Phase 2 Conclusion with evidence\n\n**poc-builder** must include:\n- Phase 4.1: Pseudocode PoC with data flow diagram (always required)\n- Phase 4.2: Executable PoC or explicit skip with justification\n- Phase 4.3: Unit test PoC or explicit skip with justification\n- Phase 4.4: Negative PoC showing exploit preconditions\n- Phase 4.5: Verification that PoCs demonstrate the vulnerability\n- Phase 4 Conclusion\n\nIf the agent is not an fp-check agent, respond with JSON: {\"ok\": true}\nIf required sections are missing, respond with JSON: {\"ok\": false, \"reason\": \"\"}\nIf all required sections are present with evidence, respond with JSON: {\"ok\": true}", - "timeout": 30 - } - ] - } - ] - } -} diff --git a/plugins/fp-check/skills/fp-check/SKILL.md b/plugins/fp-check/skills/fp-check/SKILL.md index 259311df..dd571150 100644 --- a/plugins/fp-check/skills/fp-check/SKILL.md +++ b/plugins/fp-check/skills/fp-check/SKILL.md @@ -2,6 +2,28 @@ name: fp-check description: "Systematically verifies suspected security bugs to eliminate false positives. Produces TRUE POSITIVE or FALSE POSITIVE verdicts with documented evidence for each bug." allowed-tools: Read Grep Glob LSP Bash Task Write Edit AskUserQuestion TaskCreate TaskUpdate TaskList TaskGet +hooks: + Stop: + - matcher: "*" + hooks: + - type: prompt + timeout: 30 + prompt: | + You are a verification completeness checker for the fp-check false positive analysis skill. The agent is about to stop. Check whether the verification process was completed properly. + + Scan the conversation for evidence of ALL of the following for EVERY bug that was being verified: + + 1. Phase 1 (Data Flow Analysis): Trust boundaries mapped, API contracts checked, environment protections analyzed, cross-references checked + 2. Phase 2 (Exploitability Verification): Attacker control confirmed or denied, mathematical bounds analyzed (or marked N/A), race conditions analyzed (or marked N/A), adversarial analysis completed + 3. Phase 3 (Impact Assessment): Real security impact vs operational robustness distinguished, primary controls vs defense-in-depth distinguished + 4. Phase 4 (PoC Creation): Pseudocode PoC created, executable/unit test PoCs created or explicitly skipped with justification, negative PoC created, PoC verification completed + 5. Phase 5 (Devil's Advocate): All 13 challenge questions addressed + 6. Gate Review: All 6 gates (Process, Reachability, Real Impact, PoC Validation, Math Bounds, Environment) evaluated with pass/fail + 7. Verdict: Each bug has a TRUE POSITIVE or FALSE POSITIVE verdict with evidence + + If ANY bug is missing ANY of these phases or the gate review, respond with JSON: {"ok": false, "reason": ""} + If all bugs have complete verification with verdicts, respond with JSON: {"ok": true} + If the conversation is not about fp-check verification at all, respond with JSON: {"ok": true} --- # False Positive Check