---
title: "Session Start to Stop"
description: "How OrchestKit manages the full session lifecycle -- from environment setup and context loading through metrics, compaction, and fire-and-forget cleanup."
canonical: "https://orchestkit.yonyon.ai/docs/hooks/lifecycle-hooks"
---

# Session Start to Stop

How OrchestKit manages the full session lifecycle -- from environment setup and context loading through metrics, compaction, and fire-and-forget cleanup.

import { Callout } from "fumadocs-ui/components/callout";
import { Steps, Step } from "fumadocs-ui/components/steps";

## 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            |  7 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`.

| Hook | Purpose | Runs Once? |
|------|---------|------------|
| `setup/unified-dispatcher` | Fire-and-forget launcher for background setup tasks | No |
| `setup/setup-check` | Validate plugin installation integrity | Yes |
| `setup/first-run-setup` | Create `.claude/` directories, initialize config files | Yes |
| `setup/setup-maintenance` | Periodic cleanup of stale files and caches | No |
| `setup/setup-repair` | Self-heal corrupted configuration files | No |
| `setup/monorepo-detector` | Detect monorepo structure and set workspace context | Yes |

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:

<Steps>
<Step>
### Unified Dispatcher (fire-and-forget)

Spawns a detached background process that runs startup tasks in parallel without blocking the session:

- **pattern-sync-pull** -- Pull learned patterns from previous sessions
- **coordination-init** -- Register this instance for multi-instance coordination
- **decision-sync-pull** -- Pull decision history
- **dependency-version-check** -- Check for outdated dependencies
</Step>

<Step>
### Session Context Loader

Loads session state using Context Protocol 2.0. Reads from:

- `.claude/context/session/state.json` -- Previous session state
- `.claude/context/identity.json` -- Project identity configuration
- `.claude/context/knowledge/index.json` -- Knowledge index
- `.claude/context/session/compaction-manifest.json` -- Key decisions and files touched from the last compacted session

If an `AGENT_TYPE` environment variable is set (e.g., from `--from-pr` or agent dispatch), the loader also reads agent-specific configuration from `.claude/agents/{agent-type}.md`.

```typescript
// 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);
```
</Step>

<Step>
### Analytics Consent Check

Verifies that analytics tracking has user consent before enabling telemetry hooks.
</Step>

<Step>
### PR Status Enricher

When a session is started with `claude --from-pr 123`, this hook enriches the context with PR status, review comments, and CI check results.
</Step>

<Step>
### Prefill Guard

Scans skills for deprecated patterns (response prefilling, `output_format` parameter) that are unsupported on Opus 4.6+. If detected, it emits a warning with migration guidance:

```
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.
```
</Step>
</Steps>

## SessionEnd Hooks (4 hooks)

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

| Hook | Purpose |
|------|---------|
| `lifecycle/coordination-cleanup` | Unregisters the instance from the coordination database, updates heartbeat status to "stopping", removes `.instance_env` |
| `lifecycle/session-metrics-summary` | Reads session metrics (tool call counts, error counts) and logs a summary |
| `lifecycle/session-cleanup` | Removes temporary files created during the session |
| `lifecycle/pattern-sync-push` | Pushes newly learned patterns to persistent storage |

### 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

```typescript
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 for 7 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 7 hooks in parallel
```

### The 7 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 7 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

<Callout type="warn">
**SEC-001 -- SQL Injection Prevention:** Instance IDs are validated against `/^[a-zA-Z0-9_\-.:]+$/` before any shell-exec SQLite operations. Invalid IDs are silently rejected.
</Callout>

<Callout type="warn">
**SEC-003 -- Atomic File Writes:** Lock files are written to a temp path (`locks.json.{pid}.tmp`) then renamed atomically, preventing TOCTOU race conditions.
</Callout>

## Unified Dispatchers

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

| Dispatcher | Event | Internal Hooks | Execution |
|------------|-------|---------------|-----------|
| `lifecycle/unified-dispatcher` | SessionStart | 7 | Fire-and-forget |
| `posttool/unified-dispatcher` | PostToolUse | 7 | Fire-and-forget |
| `stop-fire-and-forget.mjs` | Stop | 7 | Detached background worker |
| `subagent-stop/unified-dispatcher` | SubagentStop | varies | Fire-and-forget |
| `notification/unified-dispatcher` | Notification | varies | Fire-and-forget |
| `setup/unified-dispatcher` | Setup | varies | Fire-and-forget |

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.