[Feature Request] Permission mode change hooks + context-aware fast mode toggling

Summary

There's currently no way to react programmatically when a user switches permission modes (e.g., entering/exiting plan mode). Adding a PermissionModeChange hook event — combined with the ability for hooks to trigger settings changes — would unlock workflows where session behavior adapts to the current mode. The most immediate use case: automatically enabling fast mode during interactive plan mode and disabling it during autonomous execution.

Why existing mechanisms aren't enough

Several related issues and features touch parts of this problem, but none solve it end-to-end:

| What exists | Why it's not enough |
|---|---|
| permission_mode in common hook input fields (#6227, now resolved) | Every hook knows the current mode, but no hook fires on mode change. If you switch to plan mode and haven't submitted a prompt yet, nothing triggers. And even when a hook does fire, it can only block/allow/modify its own event — it can't write settings like fastMode. |
| PostToolUse:EnterPlanMode (#15660, closed not-planned) | Only fires when Claude calls the EnterPlanMode tool, not when the user toggles via Shift+Tab or --permission-mode plan. Covers ~10% of plan mode entries. |
| Permission mode switching in hooks (#14044, open) | Lets hooks change the permission mode from within a PermissionRequest event — the opposite direction. We need mode changes to trigger hooks and modify settings, not hooks to change modes. |
| ConfigChange hook | Fires when settings files change on disk, not when runtime state like permission mode changes. Even if you wrote to settings.json from a hook script, fastMode likely doesn't hot-reload mid-session. |

Motivation

Plan mode is interactive — you're actively waiting on each response, iterating on approach. Fast mode shines here. But once you approve a plan and switch to execution, Claude runs autonomously and latency matters far less. Today the only option is manually typing /fast twice per plan→execute cycle.

Proposed changes

1. New hook event: PermissionModeChange

Fire a hook when the permission mode changes, with input like:

{
  "hook_event_name": "PermissionModeChange",
  "previous_mode": "default",
  "new_mode": "plan",
  "session_id": "..."
}

This would be consistent with ConfigChange — both are user-initiated state transitions that other automation may want to react to. Matchers could filter on mode name (e.g., only fire when entering plan).

2. Hook capability: settings side-effects

Today hooks can return decision and reason but cannot trigger settings changes. A general-purpose mechanism for hooks to request settings modifications would enable many workflows:

{
  "settings": {
    "fastMode": true
  }
}

This could be scoped to a safe allowlist of runtime-toggleable settings (fastMode, effortLevel, etc.) rather than opening up all configuration.

3. Simpler alternative: fastModeInModes

If the above is too general, a targeted setting would solve the primary use case:

{
  "fastModeInModes": ["plan"]
}

This follows the pattern of fastModePerSessionOptIn — an admin/user-configurable policy that governs when fast mode is active. Claude Code would auto-enable fast mode when entering a listed mode and auto-disable when leaving.

Use cases beyond fast mode

A PermissionModeChange hook with settings side-effects would also enable:

• Effort level adjustment — higher effort in plan mode, lower in auto-accept
• Notifications — alert when a session switches to autonomous mode
• Logging/auditing — track mode transitions
• Custom status bar updates — related to #24279

Related issues

• #15660 — PostToolUse:EnterPlanMode doesn't fire for user-initiated plan mode (closed, not planned)
• #14044 — Allow permission mode switching in PermissionRequest hooks (open)
• #6227 — Expose active permission mode to hooks and statusline (closed, resolved)
• #24279 — Expose fast mode state in statusline JSON (open)
• #2988 — Prevent auto-accept from enabling when exiting plan mode

Environment

• Claude Code v2.1.70
• macOS (Darwin 24.2.0)