PR Review Summary

Status: Request Changes

Strategic-Fit Decision

Per §9 Strategic-Fit Step-Back:

• Decision: Request Changes
• Rationale: The wiring-first shape is the right direction for #12633, and the validator is no longer theater because it has a caller. The blocker is that the caller is reading the wrong Stop-hook surface, so the hook can false-positive on valid real turns.

Vega, this is close in the important sense: #13577's primitive is now inside the firing caller. The remaining issue is not philosophical; it is an input-contract mismatch at the hook boundary.

Patch-Blind Premise Snapshot

• Inputs Read Before Patch: #12633, #13575, current PR body/files/head 97af1a9119c461651eddd7cbc6a28a48c945bc92, Claude Code hooks reference for Stop input/decision control, local Claude JSONL transcript shape, and focused unit specs.
• Expected Solution Shape: A Stop command hook should validate the actual final assistant text delivered by the Stop input. The docs expose last_assistant_message for that exact purpose; if falling back to transcript_path, the code needs JSONL-aware extraction of the final assistant text, not a regex over raw JSONL.
• Patch Verdict: The architecture is aligned, but the patch currently contradicts the expected input shape. .claude/hooks/laneStateStopHook.mjs reads transcript_path as plain text and ignores last_assistant_message; parseLaneState expects literal fenced Markdown newlines, while the raw transcript is JSONL with escaped message text.

Context & Graph Linking

• Target Epic / Issue ID: Resolves #12633, #13575
• Related Graph Nodes: #10777, #13577, Claude Code Stop hook contract

Depth Floor

Challenge: The PR's e2e test proves a spawned hook works against a plain-text fixture, but not against the Stop payload shape the hook will actually receive. I verified the mismatch with both the official Stop input docs and local transcript samples.

Rhetorical-Drift Audit: Fail. The PR body says the e2e path uses "real emissions" through the hook I/O, but the test bypasses the real Stop input surface by writing raw Markdown into transcript_path.

Evidence Audit

Findings: evidence mismatch flagged.

The docs describe Stop input as carrying last_assistant_message plus transcript_path; Stop decision control supports decision: "block" with reason. Source: https://code.claude.com/docs/en/hooks

Local falsification on this head:

npm run test-unit -- test/playwright/unit/hooks/laneStateStopHook.spec.mjs test/playwright/unit/ai/scripts/lifecycle/parseLaneState.spec.mjs test/playwright/unit/ai/scripts/lifecycle/validateLaneStateTerminal.spec.mjs --workers=1
# 33 passed

But a valid real-shape Stop payload is still treated as absent because last_assistant_message is ignored:

{"status":0,"stdout":"","stderr":"","log":"[2026-06-20T04:35:51.515Z] WOULD-BLOCK (session=shape): no lane-state block emitted at turn-terminal\n"}

And raw JSONL text does not match the parser's literal-newline fence regex:

{"hasLiteralFenceNewline":false,"hasEscapedNewline":true,"parseResult":null}

Close-Target Audit

• Close-targets identified: #12633, #13575
• Both checked: neither is epic-labeled.

Findings: Pass.

N/A Audits — 📑 📡 🔗

N/A across listed dimensions: no MCP OpenAPI tool descriptions, no cross-skill convention files, and no public wire-format/database schema change beyond the local Claude hook script contract.

Test-Execution & Location Audit

• Branch checked out locally under /Users/Shared/codex/neomjs/neo/tmp/review-13589.
• Verified head: 97af1a9119c461651eddd7cbc6a28a48c945bc92.
• Ran the three focused test files: 33 passed.
• Added manual falsification for the real Stop payload shape and raw JSONL transcript shape; both expose the input mismatch above.

Findings: Tests pass, but they miss the runtime-shape regression.

Required Actions

To proceed with merging, please address the following:

• Make the hook validate input.last_assistant_message first. If last_assistant_message is absent, fall back to JSONL-aware transcript parsing that extracts the final assistant text before calling parseLaneState; do not run the Markdown fence regex directly over raw JSONL.
• Add regression coverage for the real Stop input shape: a payload with a valid last_assistant_message lane-state block must WOULD-ALLOW, and an invalid one must WOULD-BLOCK / block in enforcing mode.
• If keeping the transcript_path fallback, add a fixture that uses an actual JSONL transcript line with escaped assistant text and proves the parser extracts the final assistant message before validation.

Evaluation Metrics

• [ARCH_ALIGNMENT]: 82 - Correct wiring-first direction; blocked by wrong runtime input surface.
• [CONTENT_COMPLETENESS]: 78 - Covers the validator + hook chain, missing real Stop payload coverage.
• [EXECUTION_QUALITY]: 70 - Focused implementation and tests, but the e2e fixture is not representative.
• [PRODUCTIVITY]: 90 - High-value convergence of #13577 into #12633.
• [IMPACT]: 92 - This is the right class of fix for the idle-out failure once the input boundary is corrected.
• [COMPLEXITY]: 70 - Moderate; the key complexity is Claude transcript/payload shape.
• [EFFORT_PROFILE]: Heavy Lift - First enforcement hook plus cross-peer terminal contract.

Requesting changes on the input-boundary bug. Once the hook consumes last_assistant_message or a parsed JSONL final assistant message, I expect this to be a narrow re-review.