handleStopHooks
- Entity ID:
ent-handle-stop-hooks - Type:
service - Scope:
shared
What it is
The central scheduling hub function executed at the end of every query loop iteration in Claude Code. Every background mechanism — speculative execution, auto-dream, magic docs, extract memories, session memory, auto-compact, cron scheduling — traces back to this single function. It transforms the idle time between user inputs into a dense background scheduling window.
Why it exists
Claude Code's philosophy is "idle time is compute." Rather than waiting passively between user inputs, handleStopHooks dispatches background work during the gap. This makes Claude Code a daemon with an autonomous lifecycle rather than a simple REPL. The function is the architectural keystone that connects the foreground agent loop to all background services.
Every background pipeline is triggered from stop hooks rather than independent timers because of the forked agent cache constraint: background tasks must share the parent's prompt cache prefix, which is only valid during the gap between model responses.
What depends on it
All background services depend on handleStopHooks for scheduling: - Speculative Execution — prediction + pre-execution of next user input - Auto-Dream — memory consolidation during idle time - Magic Docs — auto-maintained living documentation (Ant-only) - Extract Memories — persistent knowledge extraction from conversations - Session Memory — session summarization for compaction - Auto-Compact — context window management - Cron Scheduler — scheduled task execution - Prevent Sleep (macOS) — caffeinate during active background tasks - Away Summary — re-orientation summary on user return
Trade-offs and limitations
- Single scheduling point — all background pipelines are coupled to this function. If handleStopHooks is not reached (crash mid-turn, premature exit), no background work runs.
- Not timer-based — background tasks only trigger when the user is actively interacting with Claude Code. If the user hasn't opened Claude Code for 48 hours, auto-dream won't run until the next session.
- Cache constraint — all dispatched tasks must preserve the parent's cache key parameters. This severely limits what background agents can do (only 4 parameters are safely overridable).
Key claims
- Executed at the end of every query loop iteration
- Central hub for all 9+ background services
- Background tasks run during idle time between user inputs, not on independent timers
- Cache-safe: all dispatched work inherits the parent's prompt cache prefix
Relationships
- depends_on: queryengine-ts, forked-agent-pattern, cache-economics
- depended_on_by: speculative-execution, auto-dream, magic-docs, extract-memories, session-memory, auto-compact, cron-scheduler
Evidence
src-20260409-e9925330d110: Round 12 — Background Daemon Architecture