feat(codex): SubagentStop block surface

[VDP89]

What

Increment 2 of deepening the Codex hook integration: the SubagentStop block surface. fscar init --adapter codex now also registers SubagentStop, and a scar with event_type = HookEventType.SUBAGENT_STOP can keep a subagent from stopping by blocking — e.g. a "the batch subagent must report coverage before it stops" gate.

Follows #12 (PermissionRequest). SubagentStart / Pre-PostCompact (context injection, lower value) are the intended next increment.

Shape (verified against the official doc)

SubagentStop blocks with the top-level feedback form, same as the other non-PreToolUse events:

{"decision": "block", "reason": "report batch coverage before you stop."}

This is already what emit_output's existing feedback branch produces, so the adapter change is just: add HookEventType.SUBAGENT_STOP, map the event (+ lowercase alias), and add it to WANTED_EVENTS (so install / doctor / the manifest pick it up automatically).

Two deliberate differences from PermissionRequest

• Exit code 2 is a documented block path for SubagentStop (the doc shows decision:"block" or exit 2 with reason on stderr), so run_hook returns the normal block exit code — no special-casing like PermissionRequest needed.
• Filtering is by agent_type, not tool_name. SubagentStop carries no tool, so the engine tool-matcher filter is intentionally not extended to it. A scar reads payload.raw["agent_type"] / payload.raw["last_assistant_message"] in its matches().

Verification

• fscar init --adapter codex registers SubagentStop in .codex/hooks.json + manifest (via WANTED_EVENTS).
• End-to-end: a SubagentStop scar that blocks when last_assistant_message lacks "coverage" emits decision:"block" + reason and exits 2.
• Gate: 189 passed (+3), ruff check fscars cookbook tests clean, mypy fscars strict clean.

Review focus

1. Confirm the decision:"block" + top-level reason shape is what Codex expects for SubagentStop (vs the continue:false alternative the doc also mentions — I chose decision:"block" as the documented primary).
2. Confirm exit 2 alongside the JSON block is correct for SubagentStop (the doc lists it; this is the opposite of the PermissionRequest decision in feat(codex): PermissionRequest deny surface #12).
3. Confirm not extending the engine tool_matchers filter to SubagentStop is right (it filters on agent_type, which a scar handles in matches()).

Version not bumped — [Unreleased]; cut is your call (could pair with the next increment or stand alone like #12 → 0.8.0).

🤖 Generated with Claude Code

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 2e20b0c0d9

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

[chatgpt-codex-connector]

Return SubagentStop JSON blocks with exit 0

Adding SubagentStop here routes blocking scars through the existing run_hook path, which writes the JSON {"decision":"block","reason":...} to stdout and then returns exit code 2 for every non-PermissionRequest block. I checked the current Codex hooks doc: for SubagentStop, JSON stdout is the contract when the hook exits 0, while the exit-2 alternative requires the continuation reason on stderr. Since this hook emits no stderr, a subagent coverage gate can be ignored or continued without the requested prompt whenever it blocks; this surface needs a Codex-specific exit-0 path (or stderr output) before registration.

Useful? React with 👍 / 👎.

[VDP89]

P2 fixed (commit 41558b8)

Verified the generated schema directly (subagent-stop.command.output.schema.json): top-level only — continue / decision / reason / stopReason / suppressOutput / systemMessage, additionalProperties: false, no hookSpecificOutput. My reuse of the generic feedback branch (which appends hookSpecificOutput) produced output the schema would reject.

Fix: emit_output now special-cases SUBAGENT_STOP — emits decision/reason on block and systemMessage as the only context channel, never hookSpecificOutput. Regression updated to assert hookSpecificOutput is absent, plus a non-block case that routes context to systemMessage. Docs + CHANGELOG note the strict schema.

PreToolUse / PostToolUse / other events are unchanged (still echo hookSpecificOutput). exit-2-on-block for SubagentStop unchanged (it's documented for this surface).

Gate: 190 passed, ruff clean, mypy strict clean. Re-requesting review.