claude-code - 💡(How to fix) Fix Allow hooks to trigger /compact programmatically

Summary

Let hooks request a /compact via their JSON stdout, so long working sessions can compact at natural idle moments instead of waiting for the reactive near-limit auto-compact (or relying on the user to remember to type /compact).

Motivation

Today there are exactly two ways to trigger compaction:

1. The user types /compact.
2. The built-in reactive auto-compact fires when the conversation is near the context ceiling.

For long, intermittent working sessions with context switches, the best compact moments are natural idle points well before the context ceiling: when a subgoal ships, when a subagent delegation returns, when the user steps away. None of these are currently reachable from configuration or hooks.

I verified the current surface exhaustively as of 2026-05-12:

• No hook output field triggers compaction (no triggerCompact, compact, action: "compact", etc. on any hook type — PreCompact / PostCompact / Stop / Notification / SessionStart / SessionEnd / PreToolUse / PostToolUse / UserPromptSubmit / SubagentStop).
• No CLI flag like --auto-compact, --compact-threshold, --compact-on-idle.
• No settings.json key for auto/idle compaction; the built-in threshold is not configurable.
• No slash command, skill, MCP tool, or env var can trigger it.

Proposal

Allow hooks to include a triggerCompact field in their JSON stdout:

```json { "triggerCompact": true, "reason": "60s idle after Stop" } ```

Most useful from:

• Notification (with idle_prompt matcher) — compact while the user is away
• Stop — compact after a logical turn ends, gated by a script's own heuristics
• PostToolUse — compact after subagent delegations return

The reason would surface in the compact summary so the user can tell why it fired.

Related

• #15946 — Context Threshold Hooks (closed)
• #55183 — Native idle settings (closed as duplicate)

Both pointed at the same gap from different angles; this proposal narrows the ask to a single concrete API surface (one extra JSON field) that composes with the existing hook system rather than introducing new config.

Why not just rely on auto-compact

Reactive auto-compact near the ceiling is fine for a single focused task, but in long working sessions it (a) fires at the worst moment (mid-task, not at a subgoal boundary) and (b) misses the user-away windows that are the cheapest time to compact. A hook-driven version lets each user encode their own "good compact moment" heuristic without Anthropic having to ship one policy that fits everyone.