Add verify-deliverables SubagentStop hook to harden subagent completion claims

[TechNickAI]

Problem

When a subagent (Task tool) finishes and claims success, there is currently no structural verification that it actually produced the artifacts it promised. We rely on prompt discipline — the <epistemic-honesty> block in CLAUDE.md, the verify-fix skill, the verification-before-completion superpower — but prompts are advisory, not enforceable. A subagent can return "done, all tests pass" without having written the file, run the test, or produced the artifact.

This is the single most-cited failure mode in our own rules. We should fix it at the harness level, not via more prompt discipline.

What to build

A SubagentStop hook that intercepts subagent completion, parses the subagent's claimed deliverables out of its final message, and verifies they exist before letting the parent treat the task as complete. If verification fails, the hook either:

• blocks the stop and forces the subagent to actually produce the artifact, OR
• surfaces the discrepancy to the parent agent with a structured "unverified claim" payload.

Implementation strategy is open — the worker should research current SubagentStop hook capabilities in Claude Code (see https://docs.claude.com/en/docs/claude-code/hooks) and decide which approach the hook lifecycle actually supports.

Reference

oh-my-claudecode (https://github.com/yeachan-heo/oh-my-claudecode) implements a `verify-deliverables` SubagentStop hook. Worth reading their implementation to understand how they parse claimed artifacts and what validation they run. Don't copy verbatim — their stack and ours differ — but their lifecycle pattern is the prior art.

Their broader pattern is interesting: they shift discipline that we currently enforce via prompts into hook lifecycle interceptors. We should think about whether other prompt-enforced rules (e.g. "never claim a fix without running tests") have a similar harness-level home.

Open questions for the implementer

• How does the hook know what was "promised"? Parse the subagent's final message? Require subagents to emit a structured deliverables list? Read the parent's Task prompt?
• What's the failure mode when verification fails — block, warn, or annotate?
• Should this be opt-in (per-skill, per-task) or always-on?
• Where does it live in our plugin layout (`plugins/core/hooks/`)?
• How do we test it without a real Claude Code session?

Success criteria

• A subagent that lies about completing work cannot have that lie reach the parent unchallenged.
• Our existing skills (`do-issue`, `autotask`, `ship`, etc.) all benefit automatically without per-skill changes.
• The hook is documented and installable as part of the plugin.

Out of scope

• Verifying correctness of artifacts (that's what `verify-fix` and tests are for). This issue is about existence — did the subagent actually do the thing it said it did.

[TechNickAI]

Picking this up. Approach:

• Research current SubagentStop hook capabilities in Claude Code (docs + read oh-my-claudecode's implementation as prior art) before settling on a design.
• Build the hook in plugins/core/hooks/ — likely parses the subagent's final message for completion claims (artifact paths, "created X", "tests pass") and verifies against filesystem state and the actual tool-call record. Failure mode TBD by research: prefer "annotate parent with structured discrepancy" over "block stop" unless the lifecycle clearly supports the latter.
• Ship as opt-in via settings.json first, with docs and a test harness that doesn't require a live Claude Code session.

PR will land with Fixes #51.

[TechNickAI]

Implemented in PR #54: #54

The hook reads agent_transcript_path (the subagent's own transcript) from the SubagentStop payload, cross-references tool-call records against filesystem state, and emits a structured advisory via hookSpecificOutput.additionalContext when it finds discrepancies. Always exits 0 — never blocks. 19 test cases, no live session required to run them.