[FEATURE] PreExitPlanMode hook — intercept before ExitPlanMode call for planning artifact adversarial audit invocation

Summary

Request a new hook trigger PreExitPlanMode (or equivalent name) that fires before the ExitPlanMode tool call completes, so that planning artifacts can be audited / validated / adversarially reviewed by external tooling before plan approval is requested from the user.

Motivation

Claude Code plan mode is powerful for planning-heavy sessions (multi-Round work, architectural decisions, spec docs, etc.). But planning-time compromises tend to surface only at execution time, when correction is expensive.

An advisory discipline of「invoke an adversarial audit before EXIT」 works when applied voluntarily, but:

• No runtime enforcement → agent may skip
• Human review bandwidth = external QC critical path → automation reduces this
• Multi-maintainer transition requires mechanism > memory discipline

A PreExitPlanMode hook would let projects install a mechanism that:

1. Reads the plan artifact (from the plan file specified in Plan mode)
2. Invokes a subagent (or external validator) for adversarial critique
3. Optionally blocks the ExitPlanMode call if critical findings surface
4. Passes findings back to the main-loop agent for revision before user sign-off

Related but semantically distinct existing hooks / proposals

• PostPlanMode (proposed in #14259): fires after ExitPlanMode = too late for pre-EXIT intercept
• SessionEnd / pre-exit turns (proposed in #69750): shell session boundary, not plan-mode boundary
• PreCompact (existing): different event (compaction, not plan exit)

None cover the pre-EXIT planning-artifact-audit use case.

Proposed hook shape (illustrative)

{
  "PreExitPlanMode": {
    "matcher": ".*",
    "hooks": [{
      "type": "command",
      "command": "path/to/audit-script.sh",
      "env": {
        "PLAN_FILE_PATH": "{{plan_file_path}}",
        "SESSION_ID": "{{session_id}}"
      }
    }]
  }
}

Fail-open semantics preferred (script timeout / error → allow ExitPlanMode) to avoid blocking legitimate exits when tooling breaks.

Use case example

Our project (kinosh-jp/bunshin-proxy-productivity-amplifier) has installed a documentation-based canonical step (「Pre-EXIT planning-hygiene」) with 5 mechanisms including adversarial audit invocation via fresh Plan subagents. Current implementation is advisory-only (agent voluntary discipline) because no PreExitPlanMode hook exists.

Reference: our related Round 11 audit agent MVP that DOES leverage PreToolUse hook for AskUserQuestion auditing (docs/adr/20260710-audit-agent-mvp.md in that repo).

Priority signal

Low urgency (documentation-based workaround functional)、 but hook-based mechanism-first alignment would enable:

• Multi-project reuse of planning-quality-gate subagents
• Removal of voluntary-discipline reliance in solo → multi-maintainer transitions
• Consistency with existing PreToolUse-based subagent patterns (e.g., AskUserQuestion auditor)