[FEATURE] PrePlanMode and PostPlanMode Hook Events

Feature Request: PrePlanMode and PostPlanMode Hook Events

Summary

Users who create plans in Claude Code cannot hook into plan mode lifecycle events. Adding PrePlanMode and PostPlanMode hook events would enable workflows like archiving existing plans before overwrite, validating prerequisites, and post-plan processing.

Problem Description

Current Behavior

1. User enters plan mode (via /plan or plan permission mode)
2. Claude creates/updates plan file at ~/.claude/plans/<session-name>.md
3. If a plan already exists in that file, it gets overwritten with no backup
4. There's no way to hook into this process

Expected Behavior

Users should be able to:

• PrePlanMode: Run hooks before plan mode starts (archive existing plan, validate state)
• PostPlanMode: Run hooks after plan mode exits (process completed plan, trigger workflows)

Use Cases

1. Auto-Archive Existing Plans

Before a plan is overwritten, archive it for future reference:

# PrePlanMode hook
if [[ -f "$PLAN_FILE" ]]; then
    cp "$PLAN_FILE" "$ARCHIVE_DIR/$(basename $PLAN_FILE .md)-$(date +%s).md"
fi

2. Prerequisite Validation

Ensure certain conditions are met before planning:

# PrePlanMode hook - ensure clean git state
if [[ -n "$(git status --porcelain)" ]]; then
    echo "WARNING: Uncommitted changes exist"
    exit 1  # Block plan mode
fi

3. Plan Processing

After exiting plan mode, trigger downstream workflows:

# PostPlanMode hook
# Convert plan to issue tracker tickets
./scripts/plan-to-tickets.sh "$PLAN_FILE"

4. Plan Persistence to Project

Copy finalized plan into project directory for version control:

# PostPlanMode hook
cp "$PLAN_FILE" ".plans/$(date +%Y%m%d)-plan.md"
git add ".plans/"

Proposed Solution

New Hook Events

{
  "hooks": {
    "PrePlanMode": [
      {
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/plan-archive/hook.sh"
          }
        ]
      }
    ],
    "PostPlanMode": [
      {
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/plan-complete/hook.sh"
          }
        ]
      }
    ]
  }
}

Hook Input Schema

{
  "event": "PrePlanMode",
  "plan_file": "/Users/name/.claude/plans/graceful-kindling-wombat.md",
  "plan_exists": true,
  "plan_content_size": 4096,
  "session_id": "abc123"
}

Exit Code Semantics

| Exit Code | PrePlanMode | PostPlanMode |
|-----------|-------------|--------------|
| 0 | Allow plan mode | Continue normally |
| 1 | User decision (prompt) | N/A |
| 2 | Block plan mode | N/A |

Current Workaround

Using PreToolUse with Write matcher to intercept plan file writes:

{
  "matcher": "Write",
  "hooks": [
    {
      "type": "command",
      "command": ".claude/hooks/plan-archive/hook.sh"
    }
  ]
}

Limitations of this workaround:

• Fires on ALL Write operations (must filter by path)
• Doesn't know if we're entering/exiting plan mode specifically
• No access to plan mode metadata
• Can't block plan mode entry, only individual writes

Impact

Current State

| Capability | Status |
|------------|--------|
| Archive plans before overwrite | Workaround (fragile) |
| Validate prerequisites for planning | Not possible |
| Process completed plans | Not possible |
| Track plan mode sessions | Not possible |

With Feature

| Capability | Status |
|------------|--------|
| Archive plans before overwrite | Native support |
| Validate prerequisites for planning | Enabled |
| Process completed plans | Enabled |
| Track plan mode sessions | Enabled |

Environment

• Claude Code CLI
• Using custom hooks for workflow automation
• Long sessions with multiple planning cycles

Related

This complements existing hook events:

• SessionStart / SessionEnd - session lifecycle
• PreCompact - context management
• PreToolUse / PostToolUse - tool lifecycle

Plan mode is a distinct operational mode that deserves first-class hook support.