Session Start to Stop

The Session Lifecycle

A Claude Code session is bookended by startup and shutdown. OrchestKit hooks at every boundary to load context, track metrics, coordinate with other instances, and clean up when you leave -- all without blocking your workflow.

Setup (first run)
  |
  v
SessionStart -----> UserPromptSubmit (repeated) -----> Stop
  |                        |                             |
  |  load context          |  inject memory,             |  fire-and-forget:
  |  check consent         |  detect patterns            |  29 background hooks
  |  enrich PR status      |  track satisfaction         |
  |  prefill guard         |                             v
  v                        v                        SessionEnd
                                                      |
                                                      |  coordination cleanup
                                                      |  metrics summary
                                                      |  pattern sync push
                                                      v
                                                    (done)

Setup Hooks (9 hooks)

Setup hooks run when the plugin is installed or during maintenance windows. They are registered under the Setup event in hooks.json.

Hooks marked "Runs Once" use the "once": true flag in hooks.json, so they execute only on the first invocation per session.

SessionStart Hooks (5 hooks)

When a new session begins, these hooks fire in order:

// The compaction manifest bridges sessions across compactions
const manifest = JSON.parse(readFileSync(compactionManifest, 'utf-8'));
process.env.ORCHESTKIT_LAST_SESSION = manifest.sessionId;
process.env.ORCHESTKIT_LAST_DECISIONS = JSON.stringify(manifest.keyDecisions);

Opus 4.6 deprecation: 3 skill(s) reference deprecated patterns.
Migration: use structured outputs instead of prefilling;
use output_config.format instead of output_format.

SessionEnd Hooks (4 hooks)

When the session formally ends (after Stop hooks have dispatched), these hooks run synchronously:

Coordination Cleanup in Detail

Multi-instance coordination uses a SQLite database at .claude/coordination/.claude.db and heartbeat files at .claude/coordination/heartbeats/{instance-id}.json. The cleanup hook:

1. Loads the instance ID from .claude/.instance_env
2. Updates the heartbeat file status to "stopping"
3. Unregisters the instance from the coordination database (releases all locks)
4. Deletes the .instance_env file

function updateHeartbeatStatus(projectDir: string, instanceId: string): void {
  const heartbeatFile = `${heartbeatsDir}/${instanceId}.json`;
  const content = JSON.parse(readFileSync(heartbeatFile, 'utf-8'));
  content.status = 'stopping';
  writeFileSync(heartbeatFile, JSON.stringify(content, null, 2));
}

PreCompact Hook (1 hook)

When: The context window is about to be compacted (conversation history truncated to fit within token limits).

The lifecycle/pre-compact-saver hook preserves critical context that would otherwise be lost during compaction:

• Key decisions made during the session
• List of files touched
• Current task status and dependencies
• Open problems and blockers

This data is written to .claude/context/session/compaction-manifest.json and is loaded by the session context loader on the next session start.

The Fire-and-Forget Pattern

The most important architectural pattern in OrchestKit's lifecycle hooks is fire-and-forget. When the user types /exit, they should not wait 10+ seconds for 29 cleanup hooks to finish. Instead:

User types /exit
    |
    v
stop-fire-and-forget.mjs called (stdin: hook input)
    |
    v
Writes work payload to .claude/hooks/pending/stop-{uuid}.json
    |
    v
Spawns detached background-worker.mjs (child.unref())
    |
    v
Returns immediately: {"continue": true, "suppressOutput": true}
    |
    v
Session exits instantly (~50ms)
    |
    v
Background worker picks up the payload and runs 29 hooks in parallel

The 29 Stop Hooks

These hooks run in the background after the session has already exited:

Core Session (6):

• auto-save-context -- Save conversation context for next session
• session-patterns -- Extract and persist patterns from the session
• issue-work-summary -- Summarize work done on GitHub issues
• calibration-persist -- Save calibration metrics
• session-profile-aggregator -- Aggregate session profile data
• session-end-tracking -- Final session telemetry

Memory Sync (2):

• graph-queue-sync -- Flush pending graph memory operations
• workflow-preference-learner -- Learn workflow preferences from session behavior

Instance Management (3):

• multi-instance-cleanup -- Clean up multi-instance coordination state
• cleanup-instance -- Remove instance registration
• task-completion-check -- Verify all tasks completed or properly handed off

Analysis (3):

• context-compressor -- Compress session context for storage
• auto-remember-continuity -- Automatically store important decisions for session continuity
• security-scan-aggregator -- Aggregate security findings from the session

Skill Validation (12):

• coverage-check, evidence-collector, coverage-threshold-gate, cross-instance-test-validator, di-pattern-enforcer, duplicate-code-detector, eval-metrics-collector, migration-validator, review-summary-generator, security-summary, test-pattern-validator, test-runner

Heavy Analysis (1):

• full-test-suite -- Run comprehensive test validation

Background Worker Safeguards

The background worker (bin/background-worker.mjs) includes several safety mechanisms:

• 5-minute timeout -- Self-terminates via setTimeout to prevent hangs
• Orphan cleanup -- Removes temp files in .claude/hooks/pending/ older than 10 minutes
• Parallel execution -- All 29 hooks run via Promise.allSettled (failures don't block others)
• Debug logging -- Writes to .claude/logs/hooks/background-worker.log

Multi-Instance Coordination

When multiple Claude Code sessions run on the same project (e.g., one per terminal tab), hooks coordinate through:

1. Instance registration -- Each session registers with a unique instance ID at startup
2. Heartbeat files -- Periodic heartbeat updates at .claude/coordination/heartbeats/
3. File locks -- The multi-instance-lock PreToolUse hook writes locks atomically (temp file + renameSync) to prevent concurrent writes to the same file
4. Quality gates -- The multi-instance-quality-gate checks if another instance is already working on the same area

Unified Dispatchers

OrchestKit uses 6 unified dispatchers across the lifecycle. Each is a single hooks.json entry that fans out to multiple internal hooks:

The fire-and-forget pattern is used exclusively for non-blocking operations: analytics, network I/O, and cleanup tasks that can fail silently without impacting the user's workflow.