Preface

Read the Chinese edition

Harness Engineering — known informally in Chinese as "The Horse Book" (because the Chinese title sounds like "harness" as in horse harness).

I believe the best way to "consume" the Claude Code source code is to transform it into a book for systematic learning. For me, learning from a book is more comfortable than reading raw source code, and it makes it easier to form a complete cognitive framework.

So I had Claude Code extract a book from the leaked TypeScript source code. The book is now open-sourced, and everyone can read it online:

• Repository: https://github.com/ZhangHanDong/harness-engineering-from-cc-to-ai-coding
• Read online: https://zhanghandong.github.io/harness-engineering-from-cc-to-ai-coding/

If you want to read the book while gaining a more intuitive understanding of Claude Code's internal mechanisms, pairing it with this visualization site is highly recommended:

• Visualization site: https://ccunpacked.dev

To ensure the best possible AI writing quality, the extraction process was not as simple as "throw the source code at the model and let it generate." Instead, it followed a fairly rigorous engineering workflow:

1. First, discuss and clarify DESIGN.md based on the source code — that is, establish the outline and design of the entire book.
2. Then write specs for each chapter, using my open-source agent-spec to constrain chapter objectives, boundaries, and acceptance criteria.
3. Next, create a plan, breaking down the specific execution steps.
4. Finally, layer on my own technical writing skill before having the AI begin formal writing.

This book is not intended for publication — it's meant to help me learn Claude Code more systematically. My basic judgment is: AI certainly won't write a perfect book, but as long as the initial version is open-sourced, everyone can read, discuss, and gradually improve it together, co-building it into a truly valuable public-domain book.

That said, objectively speaking, this initial version is already quite well-written. Contributions and discussions are welcome. Rather than creating a separate discussion group, all related conversations are hosted on GitHub Discussions:

• Discussions: https://github.com/ZhangHanDong/harness-engineering-from-cc-to-ai-coding/discussions

Reading Preparation

Prerequisites

This book assumes readers have the following basics — you don't need to be an expert, just able to read and understand:

• TypeScript / JavaScript: All source code in the book is TypeScript. You need to understand async/await, interface definitions, generics, and other basic syntax, but you don't need to write it.
• CLI development concepts: Processes, environment variables, stdin/stdout, subprocess communication. If you've used terminal tools (git, npm, cargo), these concepts are already familiar.
• LLM API basics: Understanding the messages API (system/user/assistant roles), tool_use (function calling), streaming (streamed responses). If you've called any LLM API, that's enough.

Not required: React / Ink experience, Bun runtime knowledge, Claude Code usage experience.

Recommended Reading Paths

The book's 30 chapters are organized into 7 parts, but you don't have to read from start to finish. Here are three paths for readers with different goals:

Path A: Agent Builders (if you want to build your own AI Agent)

Chapter 1 (Tech Stack) → Chapter 3 (Agent Loop) → Chapter 5 (System Prompt) → Chapter 9 (Auto Compaction) → Chapter 20 (Agent Spawning) → Chapters 25-27 (Pattern Extraction) → Chapter 30 (Hands-on)

This path covers architecture to loop to prompts to context management to multi-agent, culminating in Chapter 30 where you build a complete code review Agent in Rust.

Path B: Security Engineers (if you care about AI Agent security boundaries)

Chapter 16 (Permission System) → Chapter 17 (YOLO Classifier) → Chapter 18 (Hooks) → Chapter 19 (CLAUDE.md) → Chapter 4 (Tool Orchestration) → Chapter 25 (Fail-Closed Principle)

This path focuses on defense in depth — from permission models to automatic classification to user interception points, understanding how Claude Code balances autonomy and safety.

Path C: Performance Optimization (if you care about LLM application costs and latency)

Chapter 9 (Auto Compaction) → Chapter 11 (Micro Compaction) → Chapter 12 (Token Budget) → Chapter 13 (Cache Architecture) → Chapter 14 (Cache Break Detection) → Chapter 15 (Cache Optimization) → Chapter 21 (Effort/Thinking)

This path covers context management to prompt caching to reasoning control, understanding how Claude Code reduces API costs by 90%.

About chapter numbering: Some chapters have letter suffixes (e.g., ch06b, ch20b, ch20c, ch22b) — these are in-depth extensions of main chapters. For example, ch20b (Teams) and ch20c (Ultraplan) are deep dives into ch20 (Agent Spawning).

Book Knowledge Map

graph TD
    P1["Part 1<br/>Architecture"]
    P2["Part 2<br/>Prompt Engineering"]
    P3["Part 3<br/>Context Management"]
    P4["Part 4<br/>Prompt Cache"]
    P5["Part 5<br/>Safety & Permissions"]
    P6["Part 6<br/>Advanced Subsystems"]
    P7["Part 7<br/>Lessons"]

    CH03(("Chapter 3<br/>Agent Loop<br/>🔗 Book Anchor"))

    P1 --> P2
    P1 --> P3
    P1 --> P5
    P2 --> P3
    P3 --> P4
    P5 --> P6
    P2 --> P6
    P3 --> P6
    P1 --> P7
    P2 --> P7
    P3 --> P7
    P5 --> P7

    CH03 -.->|"When tools execute in the loop"| P1
    CH03 -.->|"When prompts are injected in the loop"| P2
    CH03 -.->|"When context is compressed in the loop"| P3
    CH03 -.->|"When permissions are checked in the loop"| P5

    style CH03 fill:#f47067,stroke:#fff,color:#fff
    style P1 fill:#58a6ff,stroke:#30363d
    style P2 fill:#3fb950,stroke:#30363d
    style P3 fill:#d29922,stroke:#30363d
    style P4 fill:#d29922,stroke:#30363d
    style P5 fill:#f47067,stroke:#30363d
    style P6 fill:#bc8cff,stroke:#30363d
    style P7 fill:#39d353,stroke:#30363d

Chapter 3 (Agent Loop) is the book's anchor — it defines the complete cycle from user input to model response. Other parts each analyze the deep mechanisms of a particular stage within that cycle.

Reading Notation

This book uses the following conventions:

• Source references: Format is restored-src/src/path/file.ts:line, pointing to the restored source of Claude Code v2.1.88.
• Evidence levels:
  • "v2.1.88 source evidence" — has complete source code and line number references, highest confidence
  • "v2.1.91/v2.1.92 bundle reverse engineering" — inferred from bundle string signals; Anthropic removed source maps starting from v2.1.89
  • "Inference" — speculation from event names or variable names only, no direct source evidence
• Mermaid diagrams: Flowcharts and architecture diagrams use Mermaid syntax, rendered automatically when reading online.
• Interactive visualizations: Some chapters provide D3.js interactive animation links (marked as "click to view"), which need to be opened in a browser. Each animation also has a static Mermaid diagram as a fallback.

Chapter 1: The Full Tech Stack of an AI Coding Agent

Positioning: This chapter analyzes Claude Code's complete tech stack — Bun runtime, React Ink terminal UI, TypeScript type system — and how the Three-Layer Architecture is concretely implemented on top of these technology choices. Prerequisites: none, can be read independently. Target audience: readers encountering CC's architecture for the first time, or developers wanting to understand the Bun + React Ink + TypeScript technology selection.

Why This Matters

To understand how an AI coding agent goes from "receiving user input" to "performing actions in your codebase," you first need to understand its technology stack. The tech stack doesn't just determine the performance ceiling — it determines the architectural boundaries: what can be done at compile time, what must be deferred to runtime, and what needs the model itself to decide.

Claude Code's tech stack choices reveal a core philosophy: An AI coding agent is not a traditional CLI tool — it's a system running "on distribution," where the model doesn't just use tools but can write its own tools. This means the entire tech stack must be designed with "the model as a first-class citizen" in mind, from entry-point startup optimizations to build-time Feature Flag elimination — every layer serves this goal.

This chapter establishes a core concept that runs throughout the entire book — the Three-Layer Architecture — and demonstrates through source code analysis how it's concretely implemented in Claude Code v2.1.88. If you're building your own AI Agent, the architectural model and startup optimization strategies in this chapter can be directly borrowed; if you just want to understand why Claude Code works the way it does, the Three-Layer Architecture is the most fundamental reference framework in the book.

Source Code Analysis

1.1 Tech Stack Overview: TypeScript + React Ink + Bun

Claude Code's technology choices can be summarized in one sentence: TypeScript for type safety, React Ink for componentized terminal UI capabilities, and Bun for startup speed and build-time optimizations.

TypeScript: The Application-Layer Language

The entire codebase consists of 1,884 TypeScript source files. TypeScript's type system has a unique advantage in AI Agent development: tool input/output schemas can be generated directly from type definitions, and these schemas become the JSON Schema sent to the model — type definitions, runtime validation, and model instructions unified as one.

React Ink: The Terminal UI Framework

Claude Code's interactive interface is not a traditional readline REPL but a full React application. React Ink brings React's component model to the terminal, allowing complex UI state management (streaming output, parallel multi-tool display, permission dialogs) to be expressed declaratively. The main UI component is located in restored-src/src/screens/REPL.tsx, which is itself a React component exceeding 5,000 lines.

Bun: Runtime and Build Tool

Bun plays a dual role here:

1. Runtime: Faster startup speed than Node.js, critical for CLI tools — users expect an immediate response after typing claude
2. Build tool: Through the feature() function provided by bun:bundle, it enables build-time Dead Code Elimination (DCE), which is the cornerstone of the entire Feature Flag system

1.2 Entry Point Analysis: Startup Orchestration in main.tsx

main.tsx is the entry point for the entire application. Its first 20 lines of code demonstrate a carefully designed startup optimization strategy.

Parallel Prefetch

// restored-src/src/main.tsx:9-20 (ESLint comments and blank lines omitted)
import { profileCheckpoint, profileReport } from './utils/startupProfiler.js';
profileCheckpoint('main_tsx_entry');

import { startMdmRawRead } from './utils/settings/mdm/rawRead.js';
startMdmRawRead();

import { ensureKeychainPrefetchCompleted, startKeychainPrefetch }
  from './utils/secureStorage/keychainPrefetch.js';
startKeychainPrefetch();

Note the code organization: each import is immediately followed by a side-effect call. The source comments (restored-src/src/main.tsx:1-8) explicitly explain the design intent:

1. profileCheckpoint: Marks the entry timestamp before any heavyweight module evaluation begins
2. startMdmRawRead: Spawns an MDM (Mobile Device Management) subprocess (plutil on macOS / reg query on Windows), allowing it to run in parallel with the subsequent ~135ms of import evaluation
3. startKeychainPrefetch: Launches two macOS Keychain read operations in parallel (OAuth tokens and legacy API keys) — without prefetching, isRemoteManagedSettingsEligible() would read them sequentially via synchronous spawn, adding ~65ms to each startup

These three operations follow the same pattern: push I/O-intensive operations into the "dead time" during module loading to run in parallel. This isn't an accidental optimization — the ESLint comment // eslint-disable-next-line custom-rules/no-top-level-side-effects indicates the team has a custom rule prohibiting top-level side effects; this is a deliberate exemption after careful consideration.

Failure mode: These prefetch operations are all "best effort." If Keychain access is denied (user hasn't authorized), ensureKeychainPrefetchCompleted() returns null and the app falls back to interactive credential prompting. If the MDM subprocess times out, subsequent plutil calls retry synchronously. This "optimistic parallel + pessimistic fallback" design ensures that prefetch failures never block startup.

Lazy Import

After parallel prefetch, main.tsx demonstrates a second startup optimization strategy — conditional lazy import:

// restored-src/src/main.tsx:70-80 (helper functions and ESLint comments omitted)
const getTeammateUtils = () =>
  require('./utils/teammate.js') as typeof import('./utils/teammate.js');
// ...

const coordinatorModeModule = feature('COORDINATOR_MODE')
  ? require('./coordinator/coordinatorMode.js') as ...
  : null;

const assistantModule = feature('KAIROS')
  ? require('./assistant/index.js') as ...
  : null;

There are two different lazy loading strategies here:

• Function-wrapped require (like getTeammateUtils): Used to break circular dependencies (teammate.ts -> AppState.tsx -> ... -> main.tsx), resolving the module only when called
• Feature Flag-guarded require (like coordinatorModeModule): Uses Bun's feature() for build-time elimination — when COORDINATOR_MODE is false, the entire require expression and its imported module tree are removed from the build output

Startup Flow Overview

flowchart TD
    A["main.tsx Entry"] --> B["profileCheckpoint<br/>Mark entry time"]
    B --> C["Parallel Prefetch"]
    C --> C1["startMdmRawRead<br/>MDM Subprocess"]
    C --> C2["startKeychainPrefetch<br/>Keychain Read"]
    C --> C3["Module Loading<br/>~135ms import evaluation"]
    C1 & C2 & C3 --> D["feature() Evaluation<br/>Build-time Flag Resolution"]
    D --> E["Conditional require<br/>Lazy Import of Experimental Modules"]
    E --> F["React Ink Render<br/>REPL.tsx Mount"]

    style C fill:#e8f4f8,stroke:#2196F3
    style D fill:#fff3e0,stroke:#FF9800

Figure 1-1: main.tsx Startup Flow

Feature Flags as Gates

Starting from line 21, the feature('...') function appears throughout the entry file:

// restored-src/src/main.tsx:21
import { feature } from 'bun:bundle';

This feature() function from bun:bundle is key to understanding the entire Feature Flag system. It's not a runtime conditional — it's a compile-time constant. When Bun's bundler processes feature('X'), it replaces it with a true or false literal based on the build configuration, and the JavaScript engine's dead code elimination removes unreachable branches.

Note: bun:bundle's feature() is not a publicly documented Bun API but a custom conditional compilation mechanism in Anthropic's build pipeline. This means Claude Code's build is tightly coupled to a specific version of Bun.

1.3 Three-Layer Architecture

Claude Code's architecture can be divided into three layers, each with clearly defined responsibilities. This architectural model will be referenced repeatedly in subsequent chapters — Chapter 3's Agent Loop runs in the Application Layer, Chapter 4's tool execution orchestration spans the Application and Runtime Layers, and Chapters 13-15's caching optimizations involve collaboration across all three layers.

graph TB
    subgraph L1["Application Layer"]
        direction TB
        TS["TypeScript Source<br/>1,884 files"]
        RI["React Ink<br/>Terminal UI Framework"]
        AL["Agent Loop<br/>query.ts State Machine"]
        TL["Tool System<br/>40+ tools"]
        SP["System Prompt<br/>Segmented Composition"]

        TS --> RI
        TS --> AL
        TS --> TL
        TS --> SP
    end

    subgraph L2["Runtime Layer"]
        direction TB
        BUN["Bun Runtime<br/>Fast Startup + ESM"]
        BB["bun:bundle<br/>feature() DCE"]
        JSC["JavaScriptCore<br/>JS Engine"]

        BUN --> BB
        BUN --> JSC
    end

    subgraph L3["External Dependencies Layer"]
        direction TB
        NPM["npm Packages<br/>commander, chalk, lodash-es..."]
        API["Anthropic API<br/>Model Calls + Prompt Cache"]
        MCP_S["MCP Servers<br/>External Tool Extensions"]
        GB["GrowthBook<br/>Runtime Feature Flags"]
    end

    L1 --> L2
    L2 --> L3
    L3 -.->|"Model responses, Flag values<br/>percolate upward"| L1

    style L1 fill:#e8f4f8,stroke:#2196F3,stroke-width:2px
    style L2 fill:#fff3e0,stroke:#FF9800,stroke-width:2px
    style L3 fill:#f3e5f5,stroke:#9C27B0,stroke-width:2px

Figure 1-2: Claude Code Three-Layer Architecture

Application Layer (TypeScript)

The Application Layer is where all business logic resides. It contains:

• Agent Loop (query.ts): The core state machine orchestrating the "model call -> tool execution -> continuation decision" loop (see Chapter 3)
• Tool System (tools.ts + tools/ directory): Registration, permission checking, and execution of 40+ tools (see Chapter 2)
• System Prompt (constants/prompts.ts): Segmented composition prompt architecture (see Chapter 5)
• React Ink UI (screens/REPL.tsx): Declarative rendering of the terminal interface

Runtime Layer (Bun/JSC)

The Runtime Layer provides three key capabilities:

1. Fast startup: Bun's startup speed is critical for CLI tool experience
2. Build-time optimization: bun:bundle's feature() function enables compile-time Feature Flag elimination
3. JavaScript engine: Bun uses JavaScriptCore (JSC, Safari's JS engine) under the hood rather than V8

External Dependencies Layer

The External Dependencies Layer includes:

• npm packages: commander (CLI argument parsing), chalk (terminal coloring), lodash-es (utility functions), etc.
• Anthropic API: Server-side for model calls and Prompt Cache
• MCP (Model Context Protocol) Servers: External tool extension capabilities
• GrowthBook: Runtime A/B testing and Feature Flag service

AppState: Cross-Layer State Management

The Three-Layer Architecture describes the static organization of code, but at runtime, the layers need a shared state container to coordinate behavior. Claude Code's solution is AppState — a Zustand-inspired immutable state store, defined in the restored-src/src/state/ directory.

The Store's Minimal Implementation

The core of the state store is only 34 lines of code (restored-src/src/state/store.ts:1-34):

// restored-src/src/state/store.ts:10-34
export function createStore<T>(
  initialState: T,
  onChange?: OnChange<T>,
): Store<T> {
  let state = initialState
  const listeners = new Set<Listener>()

  return {
    getState: () => state,
    setState: (updater: (prev: T) => T) => {
      const prev = state
      const next = updater(prev)
      if (Object.is(next, prev)) return   // Reference equality → skip notification
      state = next
      onChange?.({ newState: next, oldState: prev })
      for (const listener of listeners) listener()
    },
    subscribe: (listener: Listener) => {
      listeners.add(listener)
      return () => listeners.delete(listener)
    },
  }
}

This Store has three key design characteristics:

1. Immutable updates: setState accepts an (prev) => next updater function; callers must return a new object (rather than mutating in place), with Object.is determining whether a real change occurred
2. Publish-subscribe: The observer pattern is implemented via subscribe / listeners; any code (React or non-React) can subscribe to state changes
3. Change callback: The onChange hook is called on every state change; onChangeAppState (restored-src/src/state/onChangeAppState.ts:43) uses it to synchronize permission mode changes to CCR/SDK, clear credential caches, apply environment variables, and other side effects

React Side: useSyncExternalStore Integration

React components subscribe to state slices via the useAppState Hook (restored-src/src/state/AppState.tsx:142-163):

// restored-src/src/state/AppState.tsx:142-163
export function useAppState(selector) {
  const store = useAppStore();
  const get = () => selector(store.getState());
  return useSyncExternalStore(store.subscribe, get, get);
}

useSyncExternalStore is a React 18 API designed specifically for safe integration of external stores with React's concurrent mode. Each component subscribes only to the slice it cares about — for example, useAppState(s => s.verbose) only triggers a re-render when the verbose field changes. REPL.tsx has over 20 useAppState calls (restored-src/src/screens/REPL.tsx:618-639), each precisely selecting a single state field, avoiding unnecessary UI refreshes.

Non-React Side: Direct Store Access

Outside the React component tree — CLI handlers, tool executors, Hook callbacks — code reads state via store.getState() directly and writes via store.setState(). For example:

• Reading the task list during request cancellation: store.getState().tasks (restored-src/src/hooks/useCancelRequest.ts:173)
• Reading the client list in MCP connection management: store.getState().mcp.clients (restored-src/src/services/mcp/useManageMCPConnections.ts:1044)
• Reading team context in inbox polling: store.getState() (restored-src/src/hooks/useInboxPoller.ts:143)

This dual-access pattern — React via subscription-based useAppState, non-React via imperative getState() — allows the same state store to simultaneously serve declarative UI rendering and imperative business logic.

The Scale of State

AppState's type definition (restored-src/src/state/AppStateStore.ts:89-452) spans 360+ lines, containing 60+ top-level fields covering: settings snapshot (settings), permission context (toolPermissionContext), MCP connection state (mcp), plugin system (plugins), task registry (tasks), team collaboration context (teamContext), speculative execution (speculation), and more. Core fields are wrapped with DeepImmutable<> for compile-time immutability guarantees, but fields containing function types like tasks, mcp, and plugins are excluded.

This state store's design reflects a Claude Code architectural philosophy: replace scattered module-level variables with a single global state store, making state flow and dependencies trackable. When subsequent chapters mention "the Agent Loop reads the permission mode" or "the tool executor checks MCP connections," they are all accessing different slices of the same AppState instance.

The Significance of Layer Boundaries

The key to the Three-Layer Architecture lies in the direction of information flow between layers:

• Application Layer -> Runtime Layer: TypeScript code compiles to JavaScript; feature() calls are resolved at this point
• Runtime Layer -> External Dependencies Layer: HTTP requests, npm package loading, MCP connections
• External Dependencies Layer -> Application Layer: Model responses, tool results, Feature Flag values — this information percolates upward through both layers back to the Application Layer

Understanding this percolation path is important: when GrowthBook returns a new value for a tengu_* Feature Flag, it doesn't affect the build-time feature() function (those are already baked in at build time) but rather the runtime conditional logic. Claude Code has two parallel Feature Flag mechanisms: build-time feature() and runtime GrowthBook, serving different purposes (discussed in detail later).

1.4 Why "On Distribution" Matters

"On distribution" is a key concept for understanding Claude Code's architectural decisions and one of the core arguments of this book. Traditional CLI tools define all their functionality at development time and then distribute to users. But AI coding agents are different — their behavior is dynamically determined by the model at usage time.

Specifically:

1. The model selects tools: In each iteration of the Agent Loop, the model decides which tool to call and what parameters to pass. A tool's description and inputSchema are not just documentation — they are instructions sent to the model
2. The model writes its own tools: Through BashTool, the model can execute arbitrary shell commands; through FileWriteTool, the model can create new files; through SkillTool, the model can load and execute user-defined prompt templates
3. The model acts on its own context: Through Compaction, Microcompact, and Context Collapse, the model participates in managing its own context window

This means the tech stack must consider a dimension that traditional software doesn't: the model is part of the runtime, and its behavior is not entirely controlled by code but is shaped collectively by prompts, tool descriptions, and context.

Deep Impact on Architecture

"On distribution" is not just an abstract concept — it directly shapes several of Claude Code's core architectural decisions:

The fundamental difficulty of testing and verification. Traditional software can cover all code paths through unit and integration tests. But when the model participates in decisions, the same input might produce different tool call sequences. Claude Code's approach is not to try covering all possible model behaviors but rather: (a) through fail-closed defaults (see Chapter 2) ensure any tool call is safe, (b) through the permission system (see Chapter 16) set human checkpoints before dangerous operations, (c) through A/B testing (see Chapter 7) validate behavior changes in real usage.

Tool descriptions as API contracts. In traditional software, API documentation is for human developers; in AI Agents, tool descriptions are instructions for the model. This means a tool's description field can't just describe "what this tool does" — it must also guide "when the model should use this tool." Chapter 8 will analyze in depth how tool prompts serve as "micro-harnesses."

Feature Flags control the model's cognitive boundaries. When feature('WEB_BROWSER_TOOL') is false, the model not only can't use the browser tool — it doesn't even know the browser tool exists, because the tool schema doesn't include it:

// restored-src/src/tools.ts:117-119
const WebBrowserTool = feature('WEB_BROWSER_TOOL')
  ? require('./tools/WebBrowserTool/WebBrowserTool.js').WebBrowserTool
  : null;

This is the most direct manifestation of "on distribution": build-time decisions directly affect the model's runtime capability boundaries.

Comparison with Traditional Software

1.5 Build-Time Dead Code Elimination: How feature() Works

The feature() function comes from Bun's bundler module bun:bundle and is extensively used in Claude Code to implement build-time conditional compilation.

Mechanism

When Bun's bundler encounters a feature('X') call:

1. It looks up the value of X in the build configuration
2. It replaces feature('X') with a literal true or false
3. The JavaScript engine's optimizer identifies unreachable branches and removes them

This means the following code:

const SleepTool = feature('PROACTIVE') || feature('KAIROS')
  ? require('./tools/SleepTool/SleepTool.js').SleepTool
  : null;

In a build with PROACTIVE=false, KAIROS=false becomes:

const SleepTool = false || false
  ? require('./tools/SleepTool/SleepTool.js').SleepTool
  : null;

Which is then optimized to const SleepTool = null;, and SleepTool.js along with its entire dependency tree won't appear in the final bundle.

Usage Patterns

In tools.ts, feature() usage follows four patterns: single Flag guard, multi-Flag OR combination, multi-Flag AND combination, and array spread. These patterns also appear in commands.ts (restored-src/src/commands.ts:59-100), controlling the availability of slash commands. The complete analysis of the tool registration pipeline is covered in Chapter 2.

Distinction from Runtime Flags

Claude Code has two Feature Flag mechanisms that are easy to confuse:

The two are complementary: feature() is for "does this feature exist," while GrowthBook is for "which users get this feature." A feature typically has its module loading guarded by feature() first, then its runtime behavior controlled by GrowthBook.

1.6 Tool Registration Pipeline: Feature Flags in Practice

The getAllBaseTools() function in tools.ts (restored-src/src/tools.ts:193-251) is the most concentrated showcase of the Feature Flag system. It demonstrates four different tool registration strategies:

Strategy 1: Unconditional Registration

// restored-src/src/tools.ts:195-209 (only listing some core tools)
AgentTool,
TaskOutputTool,
BashTool,
// ... GlobTool/GrepTool (conditional, see Strategy 4)
FileReadTool,
FileEditTool,
FileWriteTool,
NotebookEditTool,
WebFetchTool,
WebSearchTool,
// ...

These are core tools (about a dozen), always available with no conditions.

Strategy 2: Build-time Feature Flag Guard

// restored-src/src/tools.ts:217
...(WebBrowserTool ? [WebBrowserTool] : []),

WebBrowserTool is guarded at the top of the file via feature('WEB_BROWSER_TOOL') — if the Flag is false, the variable is null, and this spreads to an empty array. The tool's entire code doesn't exist in the build output.

Strategy 3: Runtime Environment Variable Guard

// restored-src/src/tools.ts:214-215
...(process.env.USER_TYPE === 'ant' ? [ConfigTool] : []),
...(process.env.USER_TYPE === 'ant' ? [TungstenTool] : []),

ConfigTool and TungstenTool are controlled by the runtime environment variable USER_TYPE — their code exists in the build output but is only visible to Anthropic internal users (ant). This is a "staging area" pattern for A/B testing: validate internally before opening to external users.

Strategy 4: Runtime Function Guard

// restored-src/src/tools.ts:201
...(hasEmbeddedSearchTools() ? [] : [GlobTool, GrepTool]),

This is a reverse guard: when Bun's single-file executable has search tools embedded (bfs/ugrep), the standalone GlobTool and GrepTool are actually removed — because the model can access these embedded tools through BashTool. This strategy ensures equivalent search capabilities across different build versions, just with different underlying implementations.

1.7 The Full Landscape of 89 Feature Flags

By extracting all feature('...') calls from the source code, we identified 89 build-time Feature Flags. The complete list and categorization can be found in Appendix D. Here we focus on what these Flags reveal about product direction:

The KAIROS family (6 Flags, 84+ combined references): This is the largest Flag cluster, pointing to a complete "assistant mode" product — autonomous background operation (KAIROS), memory curation (KAIROS_DREAM), push notifications (KAIROS_PUSH_NOTIFICATION), GitHub Webhook integration (KAIROS_GITHUB_WEBHOOKS). This isn't an enhancement of a CLI tool — it's an entirely different product form.

Multi-Agent orchestration (COORDINATOR_MODE + TEAMMEM + UDS_INBOX, 90+ combined references): Infrastructure for multi-Agent collaboration — Worker allocation, teammate memory sharing, Unix Domain Socket inter-process communication (see Chapter 20).

Remote and distributed (BRIDGE_MODE + DAEMON + CCR_*): Remote control and distributed execution — extending Claude Code from a local CLI to a remotely controllable Agent platform.

Context optimization (CONTEXT_COLLAPSE + CACHED_MICROCOMPACT + REACTIVE_COMPACT): Three different granularities of context management strategies, reflecting the team's ongoing exploration within the 200K token window (see Part 3).

Classifier system (TRANSCRIPT_CLASSIFIER 69 references + BASH_CLASSIFIER 33 references): The two major classifiers are the core of auto mode — the former determines permissions, the latter analyzes command safety (see Chapter 17).

The sheer number of 89 Flags tells a story: Claude Code is not a stable finished product but a rapidly iterating experimentation platform. Each Flag represents a direction being explored, and their existence is a direct manifestation of the "on distribution" philosophy — the team is continuously experimenting with what the model can do and should do.

Pattern Extraction

Pattern 1: Parallel Prefetch at Startup

• Problem solved: CLI tool startup time directly affects user experience; I/O operations (Keychain reads, MDM queries) block startup
• Core approach: Push I/O-intensive operations into the "dead time" during module loading to run in parallel; use ensureXxxCompleted() to await results when needed
• Prerequisites: I/O operations must be idempotent, fail-safe, and have clear timeouts and fallback paths
• Source reference: restored-src/src/main.tsx:9-20

Pattern 2: Dual-Layer Feature Flags

• Problem solved: Experimental features need control at different granularities — "does the feature exist in the code" and "which users get the feature" are two independent dimensions
• Core approach: Build-time feature() eliminates entire module trees; runtime GrowthBook controls behavior parameters. The former determines which tools the model can "see"; the latter determines the model's behavior configuration
• Prerequisites: Build tools support compile-time constant replacement and DCE; a runtime Flag service (e.g., GrowthBook, LaunchDarkly) is available
• Source reference: restored-src/src/main.tsx:21 (feature import), restored-src/src/tools.ts:117-119 (tool gating)

Pattern 3: Model-Aware API Design

• Problem solved: AI Agent architecture must be designed not only for human developers but also for the model — tool descriptions are the model's instructions, not just documentation
• Core approach: A tool's description and inputSchema simultaneously serve three purposes: human documentation, runtime validation, and model instructions. Type definitions -> Schema -> Model instructions are unified as one
• Prerequisites: A type system that supports Schema generation (e.g., TypeScript + Zod)
• Source reference: restored-src/src/Tool.ts (tool interface definition, see Chapter 2)

Pattern 4: Fail-Closed Defaults

• Problem solved: New tools may introduce security or concurrency risks; defaults determine the behavior when "someone forgets to configure"
• Core approach: All tool properties default to the safest values (isConcurrencySafe: false, isReadOnly: false); explicit declaration is required to unlock
• Prerequisites: Clear definitions of "safe" and "unsafe," with defaults managed in a central location
• Source reference: restored-src/src/Tool.ts:748-761 (TOOL_DEFAULTS, see Chapter 2 and Chapter 25)

What You Can Do

If you're building your own AI Agent system, here are actionable suggestions you can directly apply from this chapter's analysis:

1. Optimize startup time. Identify I/O blocking points in your Agent's startup path (credential reads, configuration loading, model warm-up) and parallelize them. The user-perceived "time to first response" directly affects their judgment of tool quality
2. Distinguish between build-time and runtime Flags. If you have experimental features, consider using build-time elimination to control "whether the feature exists" (affecting which tools the model can see), and runtime Flags to control "who gets the feature" (A/B testing, progressive rollout)
3. Design model-friendly tool descriptions. Your tool descriptions aren't just for humans — they're the basis for the model's tool selection. Test different description wording and observe whether the model's tool selection behavior changes
4. Audit your defaults. Check the default value of every configuration item in your tool system — if a new tool's developer forgets to set a property, the system's behavior should be the safest, not the most permissive
5. Use the Three-Layer Architecture as a diagnostic framework. When Agent behavior is abnormal, use the three-layer model to locate the problem: Is it application-layer logic (prompt/tool description)? Runtime-layer configuration (Feature Flag state)? Or external-dependency-layer response (API return/MCP server status)?

In the next chapter, we'll dive deep into the tool system — the model's "hands" — and see how 40+ tools form an extensible capability system through a unified interface contract, permission model, and Feature Flag guards.

Version Evolution Notes

The core analysis in this chapter is based on v2.1.88 source code. As of v2.1.92, there are no major structural changes to the tech stack and startup flow covered in this chapter. For specific signal changes, see Appendix E.

Chapter 2: Tool System — 40+ Tools as the Model's Hands

Why the Tool System Is the Core of Claude Code

Large language models "think" in the text domain, while software engineering operations happen in the file system, terminal, and network. The tool system is the bridge connecting these two worlds: it translates the model's intent into real side effects, then translates the side effects' results back into text the model can consume.

Claude Code's tool system manages 40+ built-in tools and an unlimited number of MCP extension tools. These tools are not a flat array — they pass through a precise pipeline: Definition -> Registration -> Filtering -> Invocation -> Rendering. Each step has a clear contract. This chapter starts from the Tool.ts interface definition and dissects each layer of this pipeline's design decisions.

2.1 The Tool Interface Contract

All tools — whether the built-in BashTool or third-party tools loaded via the MCP protocol — must satisfy the same TypeScript interface. This interface is defined in restored-src/src/Tool.ts:362-695 and is the cornerstone of the entire tool system.

Core Fields Overview

Fields marked * have default values provided by buildTool() and can be omitted in tool definitions.

Several design choices worth examining in depth:

description is a function, not a string. The same tool may need different descriptions under different permission modes. For example, when a user configures an alwaysDeny rule prohibiting certain subcommands, the tool description can proactively inform the model "don't attempt these operations," avoiding useless tool calls at the prompt level.

inputSchema uses Zod v4. This allows strict runtime validation of tool parameters while automatically generating JSON Schema for the Anthropic API via z.toJSONSchema(). Zod's z.strictObject() ensures the model doesn't pass undefined parameters.

call receives a canUseTool callback. This is an extremely important design — a tool may need to recursively check permissions for sub-operations during execution. For example, AgentTool needs to check whether a sub-Agent has permission to use specific tools when spawning it. Permission checking is not a one-time gate but a continuous verification throughout the execution process.

Rendering Contract: Three Method Groups

The Tool interface defines a set of rendering methods that constitute the tool's complete lifecycle representation in the terminal UI (see Section 2.5):

renderToolUseMessage          // Displayed when the tool is invoked
renderToolUseProgressMessage  // Displays progress during execution
renderToolResultMessage       // Displays results after execution completes

There are also optional methods like renderToolUseErrorMessage, renderToolUseRejectedMessage (permission denied), and renderGroupedToolUse (grouped display of parallel tools).

2.2 The buildTool() Factory Function and Fail-Closed Defaults

Every concrete tool is not directly exported as an object satisfying the Tool interface but is constructed through the buildTool() factory function. This function is defined in restored-src/src/Tool.ts:783-792:

export function buildTool<D extends AnyToolDef>(def: D): BuiltTool<D> {
  return {
    ...TOOL_DEFAULTS,
    userFacingName: () => def.name,
    ...def,
  } as BuiltTool<D>
}

The runtime behavior is minimal — just an object spread. But its type-level design (BuiltTool<D> type) precisely models the semantics of { ...TOOL_DEFAULTS, ...def }: if the tool definition provides a method, use the tool definition's version; otherwise use the default.

Defaults and the "Fail-Closed" Philosophy

TOOL_DEFAULTS (restored-src/src/Tool.ts:757-769) is designed following a safety principle — assume the most dangerous scenario when uncertain:

The two most important defaults are isConcurrencySafe: false and isReadOnly: false. This means: if a new tool forgets to declare these properties, the system automatically treats it as "may modify the file system and cannot execute concurrently" — the most conservative, safest assumption. Only when a tool developer actively declares isConcurrencySafe() { return true } and isReadOnly() { return true } does the system relax restrictions.

How Actual Tools Use buildTool

Taking GrepTool as an example (restored-src/src/tools/GrepTool/GrepTool.ts:160-194):

export const GrepTool = buildTool({
  name: GREP_TOOL_NAME,
  searchHint: 'search file contents with regex (ripgrep)',
  maxResultSizeChars: 20_000,
  strict: true,
  // ...
  isConcurrencySafe() { return true },   // Search is a safe concurrent operation
  isReadOnly() { return true },           // Search doesn't modify files
  // ...
})

GrepTool explicitly overrides two defaults because search operations are inherently read-only and concurrency-safe. In contrast, BashTool (restored-src/src/tools/BashTool/BashTool.tsx:434-441) has conditional concurrency safety:

isConcurrencySafe(input) {
  return this.isReadOnly?.(input) ?? false;
},
isReadOnly(input) {
  const compoundCommandHasCd = commandHasAnyCd(input.command);
  const result = checkReadOnlyConstraints(input, compoundCommandHasCd);
  return result.behavior === 'allow';
},

BashTool only allows concurrency when the command is determined to be read-only — a git status can execute concurrently, but git push cannot. This input-aware concurrency control is why buildTool's method signatures accept an input parameter.

2.3 Tool Registration Pipeline: tools.ts

restored-src/src/tools.ts is the assembly center for the Tool Pool. It answers a core question: In the current environment, which tools can the model use?

Three-Level Filtering

Tools go through three levels of filtering from definition to final availability:

Level 1: Compile-time/startup-time conditional loading. Many tools are conditionally loaded via Feature Flags (restored-src/src/tools.ts:16-135):

const SleepTool =
  feature('PROACTIVE') || feature('KAIROS')
    ? require('./tools/SleepTool/SleepTool.js').SleepTool
    : null

const cronTools = feature('AGENT_TRIGGERS')
  ? [
      require('./tools/ScheduleCronTool/CronCreateTool.js').CronCreateTool,
      require('./tools/ScheduleCronTool/CronDeleteTool.js').CronDeleteTool,
      require('./tools/ScheduleCronTool/CronListTool.js').CronListTool,
    ]
  : []

The feature() function comes from bun:bundle and is evaluated at bundle time. This means disabled tools don't appear in the final JavaScript bundle at all — a more thorough form of dead code elimination than runtime if statements.

Besides Feature Flags, there's also environment variable-driven conditional loading:

const REPLTool =
  process.env.USER_TYPE === 'ant'
    ? require('./tools/REPLTool/REPLTool.js').REPLTool
    : null

USER_TYPE === 'ant' marks special tools for Anthropic internal employees (like REPLTool, ConfigTool, TungstenTool), which are unavailable in the public version.

Level 2: getAllBaseTools() assembles the base tool pool. This function (restored-src/src/tools.ts:193-251) collects all tools that passed Level 1 filtering into an array. It's the system's "tool registry" — all potentially existing tools are registered here. The current version contains about 40+ built-in tools, dynamically adjusted based on which Feature Flags are enabled.

export function getAllBaseTools(): Tools {
  return [
    AgentTool,
    TaskOutputTool,
    BashTool,
    ...(hasEmbeddedSearchTools() ? [] : [GlobTool, GrepTool]),
    FileReadTool,
    FileEditTool,
    FileWriteTool,
    // ... 30+ more tools omitted
    ...(isToolSearchEnabledOptimistic() ? [ToolSearchTool] : []),
  ]
}

Note an interesting condition: hasEmbeddedSearchTools(). In Anthropic's internal builds, bfs (fast find) and ugrep are embedded in the Bun binary, at which point find and grep in the shell are already aliased to these fast tools, making standalone GlobTool and GrepTool redundant.

Level 3: getTools() runtime filtering. This is the final filtering layer (restored-src/src/tools.ts:271-327), performing three operations:

1. Permission denial filtering: filterToolsByDenyRules() removes tools covered by alwaysDeny rules. If a user configures "Bash": "deny", BashTool won't appear in the tool list sent to the model at all.
2. REPL mode hiding: When REPL mode is enabled, Bash, Read, Edit, and other basic tools are hidden — they're indirectly exposed through REPLTool's VM context.
3. isEnabled() final check: Each tool's isEnabled() method is the last switch.

Simple Mode vs. Full Mode

getTools() also supports a "simple mode" (CLAUDE_CODE_SIMPLE), exposing only Bash, FileRead, and FileEdit — three core tools. This is useful in some integration scenarios — reducing the number of tools lowers token consumption and reduces the model's decision burden.

MCP Tool Integration

The final tool pool is assembled by assembleToolPool() (restored-src/src/tools.ts:345-367):

export function assembleToolPool(
  permissionContext: ToolPermissionContext,
  mcpTools: Tools,
): Tools {
  const builtInTools = getTools(permissionContext)
  const allowedMcpTools = filterToolsByDenyRules(mcpTools, permissionContext)
  const byName = (a: Tool, b: Tool) => a.name.localeCompare(b.name)
  return uniqBy(
    [...builtInTools].sort(byName).concat(allowedMcpTools.sort(byName)),
    'name',
  )
}

Two key designs here:

1. Built-in tools take priority: uniqBy retains the first occurrence of each name; built-in tools are listed first, so they win in name conflicts.
2. Sorting by name for stable prompt caching: Built-in tools and MCP tools are each sorted and then concatenated (rather than interleaved), ensuring built-in tools appear as a "contiguous prefix." This works with the API server-side's cache breakpoint design — if MCP tools were interspersed among built-in tools, any addition or removal of an MCP tool would invalidate all downstream cache keys. See Chapter 13.

2.4 Tool Result Size Budget

When a tool returns a result, the system faces a core tension: the model needs to see complete information to make correct decisions, but the context window is limited. Claude Code solves this through a two-level budget.

Level 1: Per-Tool Result Limit maxResultSizeChars

Each tool declares its own result size limit via the maxResultSizeChars field. Results exceeding this limit are persisted to disk, and the model only sees a preview plus the disk file path.

Here's a comparison of maxResultSizeChars across different tools:

FileReadTool's maxResultSizeChars: Infinity is a special design — avoiding the circular reference of Read -> persist to file -> Read. The system also has a global ceiling DEFAULT_MAX_RESULT_SIZE_CHARS = 50,000 (restored-src/src/constants/toolLimits.ts:13), which serves as a hard cap regardless of what a tool declares.

Level 2: Per-Message Aggregate Limit

When the model calls multiple tools in parallel within a single turn, all tool results are sent as multiple tool_result blocks within the same user message. MAX_TOOL_RESULTS_PER_MESSAGE_CHARS = 200,000 (restored-src/src/constants/toolLimits.ts:49) limits the total size of tool results in a single message, preventing N parallel tools from collectively overwhelming the context window.

The FileReadTool Infinity design rationale, per-message budget persistence implementation details (including ContentReplacementState decision persistence and the Infinity exemption mechanism) are covered in Chapter 4.

Size Budget Parameters Summary

2.5 Three-Phase Rendering Flow

A tool's presentation in the terminal UI is not a one-time event but a three-phase progressive process. These three phases correspond one-to-one with the tool execution lifecycle.

Flow Diagram

flowchart TD
    A["Model emits tool_use block<br/>(parameters may not be fully streamed yet)"] --> B
    B["Phase 1: renderToolUseMessage<br/>Tool invoked, display name and parameters<br/>Parameters are Partial&lt;Input&gt; (streaming)"]
    B -->|Tool starts executing| C
    C["Phase 2: renderToolUseProgressMessage<br/>Executing, show progress<br/>Updated via onProgress callback"]
    C -->|Tool execution complete| D
    D["Phase 3: renderToolResultMessage<br/>Complete, display results"]

Phase 1: renderToolUseMessage — Intent Display

When the model outputs a tool_use block, this method is called immediately. Note the key type in its signature:

renderToolUseMessage(
  input: Partial<z.infer<Input>>,  // Note: Partial!
  options: { theme: ThemeName; verbose: boolean; commands?: Command[] },
): React.ReactNode

input is Partial because: the API returns tool parameter JSON in a streaming fashion, and before JSON parsing is complete, only some fields are available. The UI must be able to render even when parameters are incomplete — users shouldn't see a blank screen.

Taking BashTool as an example, even if the command field hasn't been fully received, the UI can already display the "Bash" label and the partial command text received so far.

Phase 2: renderToolUseProgressMessage — Process Visibility

This is an optional method. For long-running tools (like BashTool, AgentTool), progress feedback is crucial. BashTool starts showing progress after a shell command has been executing for more than 2 seconds (PROGRESS_THRESHOLD_MS = 2000, restored-src/src/tools/BashTool/BashTool.tsx:55).

Progress is delivered via the onProgress callback. Each tool's progress data structure is different — BashTool's BashProgress contains stdout/stderr fragments, while AgentTool's AgentToolProgress contains the sub-Agent's message stream. These types are uniformly defined in restored-src/src/types/tools.ts, constrained through the ToolProgressData union type.

Phase 3: renderToolResultMessage — Result Presentation

This is also an optional method — when omitted, tool results are not rendered in the terminal (for example, TodoWriteTool's results are shown through a dedicated panel, not in the conversation flow).

renderToolResultMessage accepts a style?: 'condensed' option. In non-verbose mode, search-type tools (GrepTool, GlobTool) display concise summaries (like "Found 42 files across 3 directories"), while in verbose mode they show full results. Tools can use isResultTruncated(output) to tell the UI whether the current result is truncated, enabling "click to expand" interaction in fullscreen mode.

Grouped Rendering: renderGroupedToolUse

When the model calls multiple tools of the same type in parallel within a single turn (e.g., 5 Grep searches), rendering each individually would consume significant screen space. The renderGroupedToolUse method allows tools to merge multiple parallel calls into a compact grouped view — for example, "Searched 5 patterns, found 127 results across 34 files."

This method only takes effect in non-verbose mode. In verbose mode, each tool call is still rendered independently at its original position, ensuring no information is lost during debugging.

2.6 Design Patterns from Specific Tools

BashTool: The Most Complex Tool

BashTool (restored-src/src/tools/BashTool/BashTool.tsx) is the most complex single tool in the entire tool system, because the semantic space of shell commands is infinite. It needs to:

• Parse command structure to determine if it's read-only (via checkReadOnlyConstraints and parseForSecurity)
• Understand pipes and compound commands (ls && echo "---" && ls is still read-only)
• Conditional concurrency: Only read-only commands can execute concurrently
• Progress tracking: Commands running longer than 2 seconds display streaming stdout output
• File change tracking: Record file modifications caused by shell commands via fileHistoryTrackEdit and trackGitOperations
• Sandbox execution: Execute in isolation via SandboxManager under certain conditions

BashTool's maxResultSizeChars is set to 30,000 — more generous than GrepTool's 20,000, because shell output typically contains more structured information (compilation errors, test results, etc.) and the model needs to see enough context to make correct decisions.

GrepTool: The Exemplar of Concurrency Safety

GrepTool's design is relatively clean. It unconditionally declares isConcurrencySafe: true and isReadOnly: true, because search operations never modify the file system. Its maxResultSizeChars is set to 20,000 — search results exceeding this length suggest the model's search scope is too broad, and persisting to disk with a preview actually helps the model adjust its strategy.

FileReadTool: The Philosophy of Infinity

FileReadTool sets maxResultSizeChars to Infinity, choosing instead to control output size through its own maxTokens and maxSizeBytes limits. This avoids the circular read problem mentioned earlier and means FileReadTool's results are never replaced with disk references — the model always sees file content directly.

2.7 Deferred Loading and ToolSearch

When the number of tools exceeds a certain threshold (especially after many MCP tools are connected), sending all tools' complete schemas to the model consumes substantial tokens. Claude Code solves this through a Deferred Loading mechanism.

Tools marked with shouldDefer: true only send the tool name in the initial prompt (defer_loading: true), not the full parameter schema. The model must first call ToolSearchTool to search by keyword and retrieve the tool's full definition before it can call these deferred tools.

Each tool's searchHint field is designed for this purpose — it provides a 3-10 word capability description to help ToolSearchTool perform keyword matching. For example, GrepTool's searchHint is 'search file contents with regex (ripgrep)'.

Tools marked with alwaysLoad: true are never deferred — their full schema always appears in the initial prompt. This is for core tools that the model must be able to call directly in the first conversation turn.

2.8 Pattern Extraction

From Claude Code's tool system design, several patterns of universal value for AI Agent builders can be extracted:

Pattern 1: Fail-closed defaults. buildTool()'s defaults assume the most dangerous scenario (not concurrency-safe, not read-only), requiring tool developers to actively declare safe properties. This flips safety from "opt-in" to "opt-out," significantly reducing risk from omissions.

Pattern 2: Layered budget control. Single tool results have a cap, and single messages also have an aggregate cap. The two levels complement each other — per-tool limits prevent single-point runaway, and message limits prevent collective explosion from parallel calls.

Pattern 3: Input-aware properties. isConcurrencySafe(input) and isReadOnly(input) receive the tool input rather than making global judgments. The same BashTool has completely different safety properties for ls versus rm. This fine-grained input awareness is the foundation for precise permission control. See Chapter 4.

Pattern 4: Progressive rendering. Three-phase rendering (intent -> progress -> result) gives users visibility at every stage of tool execution. The Partial<Input> design ensures the UI isn't blank even during parameter streaming. This is critical for user trust — users need to know what the Agent is doing, rather than staring at a spinning loading icon.

Pattern 5: Compile-time elimination vs. runtime filtering. Feature Flags use bun:bundle's feature() to eliminate disabled tool code at compile time, while permission rules filter the tool list at runtime. The two mechanisms serve different purposes: the former reduces bundle size and attack surface, the latter supports user-level configuration.

What You Can Do

Based on Claude Code's tool system design experience, here are actions you can take when building your own AI Agent tool system:

• Adopt "fail-closed" defaults. In your tool registration framework, set the default values of safety properties like isConcurrencySafe and isReadOnly to the most conservative options. Have tool developers actively declare safety properties rather than assuming safety by default.
• Set result size limits for every tool. Don't let tools return infinitely large results. Set per-tool limits (like maxResultSizeChars) and per-message aggregate limits; when exceeded, persist to disk and return a preview.
• Make tool descriptions functions, not static strings. If your tools have different behavior restrictions under different permission modes or contexts, dynamically generating descriptions can guide the model to avoid invalid calls at the prompt level.
• Implement three-phase rendering. Provide progress feedback for long-running tools (intent display -> execution progress -> final result), so users always know what the Agent is doing. Support Partial<Input> to enable rendering even during parameter streaming.
• Use conditional loading to reduce the tool set. Filter out unneeded tools at compile time/startup through Feature Flags or environment variables, reducing token consumption and model decision burden. For scenarios with many MCP tools, consider a deferred loading mechanism.
• Keep tool ordering stable. If you use API prompt caching, ensure the tool list order remains stable across requests. Place built-in tools as a contiguous prefix, append MCP tools sorted by name, and avoid frequent cache key invalidation.

Summary

Claude Code's tool system is a carefully layered architecture: the Tool interface defines the contract, buildTool() provides safe defaults, the tools.ts registration pipeline assembles the tool pool through compile-time and runtime two-level filtering, size budget mechanisms control context consumption at both per-tool and per-message levels, and three-phase rendering makes the tool execution process fully transparent to users.

The design philosophy of this system can be summarized in one sentence: Make the right thing easy, and the dangerous thing hard. buildTool()'s fail-closed defaults make "forgetting to declare safety properties" a safe mistake; layered budgets make "tools returning too much data" a controllable degradation; conditional loading makes "adding experimental tools" a zero-risk operation.

Tool invocation and orchestration — including the complete permission checking flow, concurrency execution scheduling strategy, and streaming progress propagation mechanism — will be covered in detail in Chapter 4.

Chapter 3: Agent Loop — The Full Lifecycle from User Input to Model Response

"A loop is not a loop when every iteration reshapes the world it runs in."

This chapter is the anchor of the entire book. From Chapter 5's API call construction to Chapter 9's automatic compaction strategy, from Chapter 13's streaming response handling to Chapter 16's permission checking system — nearly all subsystems discussed in subsequent chapters are ultimately orchestrated, coordinated, and driven within the queryLoop() core loop. Understanding this loop means understanding the beating heart of Claude Code as an AI Agent.

3.1 Why the Agent Loop Is Not a Simple REPL

A traditional REPL (Read-Eval-Print Loop) is a stateless three-step cycle: read input, evaluate, print result. There's no context passing between iterations, no automatic recovery, no awareness of its own state.

The Agent Loop is fundamentally different. Consider this comparison table:

Every iteration of the Agent Loop may change its own operating conditions: compaction reduces the message array, model degradation switches the inference backend, stop hooks inject new constraint messages. This isn't a loop — it's a self-modifying state machine.

3.2 queryLoop State Machine Overview

3.2.1 Entry: query() and queryLoop()

The entry function query() is a thin wrapper. It calls queryLoop() to get the result, then notifies all consumed commands of lifecycle completion:

restored-src/src/query.ts:219-238

export async function* query(params: QueryParams): AsyncGenerator<...> {
  const consumedCommandUuids: string[] = []
  const terminal = yield* queryLoop(params, consumedCommandUuids)
  for (const uuid of consumedCommandUuids) {
    notifyCommandLifecycle(uuid, 'completed')
  }
  return terminal
}

The real state machine lives in queryLoop() (restored-src/src/query.ts:241). It's a while (true) loop that enters the next iteration via state = next; continue, or terminates via return { reason: '...' }.

3.2.2 The State Type: Mutable State Across Iterations

The State type defines all mutable state the loop needs to carry between iterations (restored-src/src/query.ts:204-217):

Note a key design decision: the source comments explicitly state "Continue sites write state = { ... } instead of 9 separate assignments" (restored-src/src/query.ts:267). This means every continuation point must explicitly construct a complete State object. This approach eliminates the "forgot to reset a field" bug class — in a loop with 7 continuation points, this isn't a theoretical risk but an inevitable accident.

3.2.3 Continue Transition Types

The loop has 7 continue sites internally, each recording its transition reason. The complete enumeration extracted from source code:

3.2.4 Terminal Termination Reasons

The loop terminates via return, with a return value containing a reason field. The complete enumeration extracted from source code:

Interactive version: Click to view the Agent Loop animated visualization — Watch how a complete "help me fix a bug" conversation flows through the state machine, with each stage clickable for source references and detailed explanations.

The flow diagram below shows the complete topology of the state machine:

flowchart TD
    Entry["queryLoop() Entry<br/>Initialize State, budgetTracker, config"] --> Loop

    subgraph Loop["while (true)"]
        direction TB
        Start["Destructure state<br/>yield stream_request_start"] --> Phase1
        Phase1["Phase 1: Context Preprocessing<br/>applyToolResultBudget → snipCompact<br/>→ microcompact → contextCollapse<br/>→ autocompact"] --> Phase2
        Phase2{"Phase 2: Blocking limit<br/>token count > hard limit?"}
        Phase2 -->|YES| T_Blocking["return blocking_limit"]
        Phase2 -->|NO| Phase3
        Phase3["Phase 3: API Call<br/>callModel + attemptWithFallback<br/>Stream response → assistantMessages + toolUseBlocks"] --> Phase4
        Phase4{"Phase 4: Abort check<br/>aborted?"}
        Phase4 -->|YES| T_Aborted["return aborted_*"]
        Phase4 -->|NO| Branch
        Branch{"needsFollowUp?"}
        Branch -->|"false (no tool_use)"| Phase5
        Branch -->|"true (has tool_use)"| Phase6

        Phase5["Phase 5: Recovery & Termination Decision<br/>prompt-too-long → collapse drain / reactive compact<br/>max_output_tokens → escalate / recovery x3<br/>stop hooks → blocking errors injection<br/>token budget → nudge continuation"]
        Phase5 -->|Recovery succeeded| Continue1["state = next; continue"]
        Phase5 -->|All exhausted| T_Completed["return completed"]

        Phase6["Phase 6: Tool Execution<br/>StreamingToolExecutor / runTools"] --> Phase7
        Phase7["Phase 7: Attachment Injection<br/>memory prefetch / skill discovery / commands"] --> Phase8
        Phase8{"Phase 8: Continuation Decision<br/>maxTurns?"}
        Phase8 -->|Below limit| Continue2["state = next_turn; continue"]
        Phase8 -->|At limit| T_MaxTurns["return max_turns"]
    end

    Continue1 --> Start
    Continue2 --> Start

Below is the original ASCII version for readers who need a plain-text reading environment:

┌──────────────────────────────────────────────────────────────────────┐
│                        queryLoop() Entry                            │
│  Initialize State, budgetTracker, config, pendingMemoryPrefetch     │
└──────────────┬───────────────────────────────────────────────────────┘
               │
               ▼
┌──────────────────────────────────────────────────┐
│              while (true) {                      │
│  Destructure state → messages, toolUseContext, ...│
│  yield { type: 'stream_request_start' }          │
├──────────────────────────────────────────────────┤
│                                                  │
│  ┌─────────────────────────────────────────┐     │
│  │ Phase 1: Context Preprocessing           │     │
│  │ applyToolResultBudget                    │     │
│  │ → snipCompact (HISTORY_SNIP)             │     │
│  │ → microcompact                           │     │
│  │ → contextCollapse (CONTEXT_COLLAPSE)     │     │
│  │ → autocompact ───── See Ch.9 ──────────  │     │
│  └──────────────┬──────────────────────────┘     │
│                 │                                 │
│                 ▼                                 │
│  ┌─────────────────────────────────────────┐     │
│  │ Phase 2: Blocking limit check            │     │
│  │ token count > hard limit ?               │     │
│  │   YES → return {reason:'blocking_limit'} │     │
│  └──────────────┬──────────────────────────┘     │
│                 │ NO                              │
│                 ▼                                 │
│  ┌─────────────────────────────────────────┐     │
│  │ Phase 3: API Call ── See Ch.5 & Ch.13 ── │     │
│  │ attemptWithFallback loop                  │     │
│  │ callModel({                              │     │
│  │   messages: prependUserContext(...)       │     │
│  │   systemPrompt: appendSystemContext(...) │     │
│  │ })                                       │     │
│  │                                          │     │
│  │ Stream response → assistantMessages[]    │     │
│  │                → toolUseBlocks[]         │     │
│  │ FallbackTriggeredError → switch model    │     │
│  └──────────────┬──────────────────────────┘     │
│                 │                                 │
│                 ▼                                 │
│  ┌─────────────────────────────────────────┐     │
│  │ Phase 4: Abort check                     │     │
│  │ abortController.signal.aborted ?        │     │
│  │   YES → return {reason:'aborted_*'}     │     │
│  └──────────────┬──────────────────────────┘     │
│                 │ NO                              │
│                 ▼                                 │
│  ┌─────────────────────────────────────────┐     │
│  │ Phase 5: needsFollowUp == false branch   │     │
│  │ (model did not return tool_use)          │     │
│  │                                          │     │
│  │ ┌─ prompt-too-long recovery ──────────┐ │     │
│  │ │ collapse drain → reactive compact   │ │     │
│  │ │ Success → state=next; continue      │ │     │
│  │ └────────────────────────────────────-┘ │     │
│  │ ┌─ max_output_tokens recovery ────────┐ │     │
│  │ │ escalate(8k→64k) → recovery(×3)    │ │     │
│  │ │ Success → state=next; continue      │ │     │
│  │ └────────────────────────────────────-┘ │     │
│  │ ┌─ stop hooks ── See Ch.16 ──────────┐ │     │
│  │ │ blockingErrors → state=next;continue│ │     │
│  │ └────────────────────────────────────-┘ │     │
│  │ ┌─ token budget check ────────────────┐ │     │
│  │ │ budget remaining → state=next;      │ │     │
│  │ │ continue                            │ │     │
│  │ └────────────────────────────────────-┘ │     │
│  │                                          │     │
│  │ return { reason: 'completed' }           │     │
│  └──────────────────────────────────────-──┘     │
│                 │                                 │
│           needsFollowUp == true                  │
│                 │                                 │
│                 ▼                                 │
│  ┌─────────────────────────────────────────┐     │
│  │ Phase 6: Tool Execution                  │     │
│  │ streamingToolExecutor.getRemainingResults│     │
│  │ or runTools() ── See Ch.4 ────────────── │     │
│  │ → toolResults[]                         │     │
│  └──────────────┬──────────────────────────┘     │
│                 │                                 │
│                 ▼                                 │
│  ┌─────────────────────────────────────────┐     │
│  │ Phase 7: Attachment Injection            │     │
│  │ getAttachmentMessages()                 │     │
│  │ pendingMemoryPrefetch consume           │     │
│  │ skillDiscoveryPrefetch consume          │     │
│  │ queuedCommands drain                    │     │
│  └──────────────┬──────────────────────────┘     │
│                 │                                 │
│                 ▼                                 │
│  ┌─────────────────────────────────────────┐     │
│  │ Phase 8: Continuation Decision           │     │
│  │ maxTurns check                          │     │
│  │ state = { reason: 'next_turn', ... }    │     │
│  │ continue                                │     │
│  └─────────────────────────────────────────┘     │
│                                                  │
└──────────────────────────────────────────────────┘

3.3 Complete Flow of a Single Iteration

Let's trace every phase of a single iteration, from start to finish.

3.3.1 Context Preprocessing Pipeline

At the start of each iteration, the raw messages array must go through four to five levels of processing before being sent to the API. These stages execute in strict order, and the order is not interchangeable.

Level 1: Tool Result Budget Trimming

restored-src/src/query.ts:379-394

applyToolResultBudget() applies size limits to aggregated tool results. It runs before all compaction stages because subsequent cached microcompact operates only on tool_use_id without inspecting content — trimming content first doesn't interfere with it.

Level 2: History Snip

restored-src/src/query.ts:401-410

snipCompactIfNeeded() is a lightweight compaction: it snips old messages from history to free token space. Crucially, it returns a tokensFreed value — this is passed to autocompact so its threshold decision can account for the space already freed by snip.

Level 3: Microcompact

restored-src/src/query.ts:414-426

Microcompact is a fine-grained compaction that runs before autocompact. It also supports a "cached edit" mode (CACHED_MICROCOMPACT) that leverages the API's cache deletion mechanism to achieve zero-additional-API-call compaction.

Level 4: Context Collapse

restored-src/src/query.ts:440-447

Context Collapse is a read-time projection mechanism. Source comments reveal an elegant design:

"Nothing is yielded — the collapsed view is a read-time projection over the REPL's full history. Summary messages live in the collapse store, not the REPL array." (restored-src/src/query.ts:434-436)

This means the collapse doesn't modify the original message array but re-projects at each iteration. The collapsed result is passed via state.messages at continuation points; the next projectView() becomes a no-op since archived messages are already absent from the input.

Level 5: Autocompact (see Chapter 9)

restored-src/src/query.ts:454-468

Automatic compaction is the heaviest preprocessing step. It runs after context collapse — if the collapse has already reduced the token count below the threshold, autocompact becomes a no-op, preserving finer-grained context rather than generating a single summary.

The design of this five-level pipeline follows one principle: from light to heavy, from local to global. Each level tries to free space without losing too much information; only when earlier levels aren't sufficient do later levels activate.

3.3.2 Context Injection: prependUserContext and appendSystemContext

After message preprocessing is complete, context is injected into the API request via two functions:

appendSystemContext (restored-src/src/utils/api.ts:437-447):

export function appendSystemContext(
  systemPrompt: SystemPrompt,
  context: { [k: string]: string },
): string[] {
  return [
    ...systemPrompt,
    Object.entries(context)
      .map(([key, value]) => `${key}: ${value}`)
      .join('\n'),
  ].filter(Boolean)
}

System context is appended to the end of the system prompt. This content (like current date, working directory, etc.) benefits from the system prompt's special caching position — the API's prompt caching is most friendly to system prompts.

prependUserContext (restored-src/src/utils/api.ts:449-474):

export function prependUserContext(
  messages: Message[],
  context: { [k: string]: string },
): Message[] {
  // ...
  return [
    createUserMessage({
      content: `<system-reminder>\n...\n</system-reminder>\n`,
      isMeta: true,
    }),
    ...messages,
  ]
}

User context is wrapped in <system-reminder> tags and prepended as the first user message to the message array. This position choice is not arbitrary — it ensures context appears before all conversation and is marked as isMeta: true (not displayed in the user UI). An important prompt text is included: "this context may or may not be relevant to your tasks" — this gives the model freedom to ignore irrelevant context.

Note the call timing (restored-src/src/query.ts:660):

messages: prependUserContext(messagesForQuery, userContext),
systemPrompt: fullSystemPrompt,  // already appendSystemContext'd

prependUserContext is executed at API call time, not during the preprocessing pipeline. This means user context doesn't participate in token counting or compaction decisions — it's a "transparent" injection.

3.3.3 Message Normalization Pipeline

During the API call construction phase (restored-src/src/services/api/claude.ts:1259-1314), messages pass through a four-step normalization pipeline. This pipeline's responsibility is to convert Claude Code's rich internal message types into the strict format accepted by the Anthropic API.

Step 1: normalizeMessagesForAPI() (restored-src/src/utils/messages.ts:1989)

This is the most complex normalization step. It performs the following work:

1. Attachment reordering: Via reorderAttachmentsForAPI(), moves attachment messages upward until hitting a tool_result or assistant message
2. Virtual message filtering: Removes messages marked isVirtual that are display-only (like REPL internal tool calls)
3. System/progress message stripping: Filters out progress type messages and non-local_command system messages
4. Synthetic error message handling: Detects PDF/image/request-too-large errors, searches backward to strip corresponding media blocks from source user messages
5. Tool input normalization: Processes tool input format via normalizeToolInputForAPI
6. Message merging: Adjacent same-role messages are merged (API requires strict user/assistant alternation)

Step 2: ensureToolResultPairing() (restored-src/src/utils/messages.ts:5133)

Fixes tool_use / tool_result pairing mismatches. This mismatch is especially common when recovering remote sessions (remote/teleport sessions). It inserts synthetic error tool_result for orphaned tool_use blocks and strips orphaned tool_result blocks that reference non-existent tool_use.

Step 3: stripAdvisorBlocks() (restored-src/src/utils/messages.ts:5466)

Strips advisor blocks. These blocks require a specific beta header to be accepted by the API (restored-src/src/services/api/claude.ts:1304):

if (!betas.includes(ADVISOR_BETA_HEADER)) {
  messagesForAPI = stripAdvisorBlocks(messagesForAPI)
}

Step 4: stripExcessMediaItems() (restored-src/src/services/api/claude.ts:956)

The API limits each request to a maximum of 100 media items (images + documents). This function silently removes excess media items starting from the oldest messages, rather than raising an error — this is important in Cowork/CCD scenarios where hard errors are difficult to recover from.

The execution order of this pipeline is not arbitrary. Source comments explain why normalization must come before ensureToolResultPairing (restored-src/src/services/api/claude.ts:1272-1276):

"normalizeMessagesForAPI uses isToolSearchEnabledNoModelCheck() because it's called from ~20 places (analytics, feedback, sharing, etc.), many of which don't have model context."

This reveals an architectural fact: normalizeMessagesForAPI is a widely reused function whose interface can't casually accept additional parameters. Model-specific post-processing (like tool search field stripping) must run as an independent step after it.

3.3.4 API Call Phase (see Chapter 5 and Chapter 13)

The API call is wrapped in an attemptWithFallback loop (restored-src/src/query.ts:650-953):

let attemptWithFallback = true
while (attemptWithFallback) {
  attemptWithFallback = false
  try {
    for await (const message of deps.callModel({
      messages: prependUserContext(messagesForQuery, userContext),
      systemPrompt: fullSystemPrompt,
      // ...
    })) {
      // Process streaming response messages
    }
  } catch (innerError) {
    if (innerError instanceof FallbackTriggeredError && fallbackModel) {
      currentModel = fallbackModel
      attemptWithFallback = true
      // Clean up orphaned messages, reset executor
      continue
    }
    throw innerError
  }
}

Several elegant designs are worth noting here:

Message immutability. Streaming messages are cloned before yield: the original message is pushed to the assistantMessages array (sent back to the API), while the cloned version (with backfilled observable input) is yielded to the SDK caller. Source comments (restored-src/src/query.ts:744-746) directly explain why: "mutating it would break prompt caching (byte mismatch)".

Error withholding mechanism. Recoverable errors (prompt-too-long, max-output-tokens, media-size) are withheld during the streaming phase — not immediately yielded to the caller. Only when subsequent recovery logic confirms recovery is impossible are they released to the caller. This prevents SDK consumers (like Desktop/Cowork) from prematurely terminating sessions.

Tombstone handling. When streaming fallback occurs, partially yielded messages are notified for deletion as tombstones (restored-src/src/query.ts:716-718). This solves a subtle problem: partial messages (especially thinking blocks) carry signatures that, after degradation, would cause the API to report a "thinking blocks cannot be modified" error.

3.3.5 Tool Execution Phase (see Chapter 4)

After the model response completes, if tool_use blocks are present, the loop enters the tool execution phase (restored-src/src/query.ts:1363-1408).

Claude Code supports two tool execution modes:

1. Streaming parallel execution (StreamingToolExecutor): Tools begin executing while the model is still streaming. During the API call phase, each tool_use block is addTool()'d to the executor upon arrival (restored-src/src/query.ts:841-843). After streaming ends, getRemainingResults() collects all completed and pending results.
2. Batch execution (runTools()): All tool_use blocks are collected first, then executed in one batch.

Tool execution results are normalized via normalizeMessagesForAPI and appended to the toolResults array.

3.3.6 Stop Hooks and Continuation Decision

When the model response contains no tool_use (needsFollowUp == false), the loop enters the termination decision path. This path includes multiple layers of recovery logic and hook checks.

Stop Hooks (restored-src/src/query.ts:1267-1306):

const stopHookResult = yield* handleStopHooks(
  messagesForQuery, assistantMessages,
  systemPrompt, userContext, systemContext,
  toolUseContext, querySource, stopHookActive,
)

If a stop hook returns blockingErrors, the loop injects these error messages and continues (transition: { reason: 'stop_hook_blocking' }), giving the model a chance to correct. This is a key execution point in Claude Code's permission system — see Chapter 16.

Token Budget Check (restored-src/src/query.ts:1308-1355):

When the TOKEN_BUDGET feature is enabled, the loop checks whether the current turn's token consumption is within budget. If the model "finishes early" but budget remains, the loop injects a nudge message (transition: { reason: 'token_budget_continuation' }) encouraging the model to keep working. This mechanism also supports "diminishing returns" detection — if the model's incremental output is no longer substantively contributing, it stops early even if the budget isn't exhausted.

3.3.7 Attachment Injection and Turn Preparation

After tool execution completes, the loop injects attachments before entering the next turn (restored-src/src/query.ts:1580-1628):

1. Queued command processing: Pull commands from the global command queue for the current agent address (distinguishing between main thread and sub-agents), converting them to attachment messages
2. Memory prefetch consumption: If memory prefetch (started at startRelevantMemoryPrefetch at the loop entry) has completed and hasn't been consumed this turn, inject the results
3. Skill discovery consumption: If skill discovery prefetch has completed, inject the results

These injections leverage the latency of model streaming and tool execution — they run in parallel in the background and are typically complete by this point.

3.4 Abort/Retry/Degradation

3.4.1 FallbackTriggeredError and Model Switching

When an API call fails due to high load or similar reasons, a FallbackTriggeredError is thrown (restored-src/src/query.ts:894-950). The handling flow:

1. Switch currentModel to fallbackModel
2. Clear assistantMessages, toolResults, toolUseBlocks
3. Discard and rebuild StreamingToolExecutor (prevent orphaned tool_result leaks)
4. Update toolUseContext.options.mainLoopModel
5. Strip thinking signature blocks (because they're model-bound and would cause 400 errors on the degraded model)
6. Yield a system message notifying the user

Crucially, this degradation happens inside the attemptWithFallback loop. It sets attemptWithFallback = true and continue, immediately retrying within the same iteration — no need to re-enter the outer while (true) loop.

3.4.2 max_output_tokens Recovery: Three Chances

When model output is truncated, the recovery strategy has two layers:

Layer 1: Escalation. If currently using the default 8k limit and no override has been applied, directly set maxOutputTokensOverride to 64k (ESCALATED_MAX_TOKENS) and retry the same request. This is "free" recovery — no multi-turn conversation needed.

Layer 2: Multi-turn recovery. If truncation persists after escalation, inject a meta message:

"Output token limit hit. Resume directly — no apology, no recap of what you were doing.
Pick up mid-thought if that is where the cut happened.
Break remaining work into smaller pieces."

This message is carefully worded: no apologies (wastes tokens), no recaps (repeats information), break work down (reduce per-output demand). Up to 3 retries (MAX_OUTPUT_TOKENS_RECOVERY_LIMIT, restored-src/src/query.ts:164).

3.4.3 Reactive Compact: The Last Line of Defense for prompt-too-long

When the API returns a prompt-too-long error, the recovery strategy also has two layers:

1. Context Collapse Drain: First attempt to submit all staged context collapses. This is a cheap operation that preserves fine-grained context
2. Reactive Compact: If the drain isn't sufficient, execute a full reactive compact. Mark hasAttemptedReactiveCompact = true to prevent retry death loops

If both fail, the error is released to the caller and the loop terminates. Source comments specifically emphasize why stop hooks can't be run here (restored-src/src/query.ts:1169-1172):

"Do NOT fall through to stop hooks: the model never produced a valid response, so hooks have nothing meaningful to evaluate. Running stop hooks on prompt-too-long creates a death spiral: error -> hook blocking -> retry -> error -> ..."

3.5 Single Iteration Sequence Diagram

User          queryLoop         PreProcess       API          Tools          StopHooks
 │                │                  │              │              │              │
 │   messages     │                  │              │              │              │
 │───────────────>│                  │              │              │              │
 │                │                  │              │              │              │
 │                │ applyToolResult  │              │              │              │
 │                │ Budget           │              │              │              │
 │                │─────────────────>│              │              │              │
 │                │                  │              │              │              │
 │                │  snipCompact     │              │              │              │
 │                │─────────────────>│              │              │              │
 │                │                  │              │              │              │
 │                │  microcompact    │              │              │              │
 │                │─────────────────>│              │              │              │
 │                │                  │              │              │              │
 │                │  contextCollapse │              │              │              │
 │                │─────────────────>│              │              │              │
 │                │                  │              │              │              │
 │                │  autocompact     │              │              │              │
 │                │─────────────────>│              │              │              │
 │                │  messagesForQuery│              │              │              │
 │                │<─────────────────│              │              │              │
 │                │                  │              │              │              │
 │                │ prependUserContext               │              │              │
 │                │ appendSystemContext              │              │              │
 │                │                  │              │              │              │
 │                │  callModel(...)  │              │              │              │
 │                │────────────────────────────────>│              │              │
 │                │                  │              │              │              │
 │                │  stream messages │              │              │              │
 │<───────────────│<────────────────────────────────│              │              │
 │  (yield)       │                  │              │              │              │
 │                │                  │              │  tool_use?   │              │
 │                │                  │              │              │              │
 │                │──────── needsFollowUp ─────────────────────────>│              │
 │                │         runTools / StreamingToolExecutor        │              │
 │<───────────────│<───────────────────────────────────────────────│              │
 │  (yield results)                  │              │              │              │
 │                │                  │              │              │              │
 │                │  attachments (memory, skills, commands)        │              │
 │                │                  │              │              │              │
 │                │   state = { reason: 'next_turn', ... }        │              │
 │                │   continue ──────────────────────────> next iteration         │
 │                │                  │              │              │              │
 │          ──── OR ── needsFollowUp == false ────────────────────>│              │
 │                │                  │              │              │              │
 │                │  handleStopHooks │              │              │              │
 │                │────────────────────────────────────────────────────────────>│
 │                │  blockingErrors? │              │              │              │
 │                │<───────────────────────────────────────────────────────────│
 │                │                  │              │              │              │
 │                │  return { reason: 'completed' }│              │              │
 │<───────────────│                  │              │              │              │

3.6 Pattern Extraction

After reading through the 1,730 lines of queryLoop() source code, several deep patterns emerge:

Pattern 1: Explicit State Reconstruction Over Incremental Modification

Every continue site constructs a complete new State object. There's no state.maxOutputTokensRecoveryCount++, only state = { ..., maxOutputTokensRecoveryCount: maxOutputTokensRecoveryCount + 1, ... }. This brings three benefits:

1. Forgetting immunity: It's impossible to forget to reset a field
2. Auditability: Each continuation point's complete intent is visible in a single object literal
3. Testability: The transition field lets tests assert whether recovery paths actually fired

Pattern 2: Withhold-Release

Recoverable errors are not immediately exposed to consumers. They are withheld (pushed to assistantMessages but not yielded), and only released when all recovery means are exhausted. This pattern solves a real-world problem: SDK consumers (Desktop, Cowork) terminate sessions upon seeing errors — if recovery succeeds, prematurely exposing the error was an unnecessary interruption.

Pattern 3: Light-to-Heavy Layered Recovery

Whether it's context compaction (snip -> microcompact -> collapse -> autocompact) or error recovery (escalate -> multi-turn -> reactive compact), the strategy always starts from the lightest means (least information loss) and escalates progressively. This isn't just performance optimization but an information preservation strategy — each level trades "the minimum cost for the maximum space."

Pattern 4: Background Parallelization's Sliding Window

Memory prefetch starts at the loop entry, tool summaries launch asynchronously after tool execution, skill discovery starts asynchronously at iteration begin — they all complete during the 5-30 second window while the model generates its streaming response. This "complete preparatory work while waiting" pattern hides latency almost invisibly.

Pattern 5: Death Loop Protection via Single-Attempt Guards

hasAttemptedReactiveCompact, maxOutputTokensRecoveryCount, state.transition?.reason !== 'collapse_drain_retry' — these guards ensure each recovery strategy executes at most once (or a limited number of times). In a while (true) loop, without these guards is an invitation for infinite loops. The phrase "death spiral" recurring in source comments (restored-src/src/query.ts:1171, 1295) indicates this isn't a theoretical concern — these guards were learned from actual production incidents.

What You Can Do

If you're building your own AI Agent system, here are practices you can directly borrow from queryLoop()'s design:

• Set single-attempt guards for every recovery strategy. In a while (true) loop, every automatic recovery (compaction, retry, degradation) must have a boolean flag or counter to prevent infinite loops. Name them hasAttempted* to make the intent obvious.
• Adopt a "light-to-heavy" layered compaction strategy. Don't jump straight to full summarization when context exceeds limits. First try trimming old messages (snip), then microcompact, then collapse, and only then full compaction (autocompact). Each layer preserves as much context information as possible.
• Replace incremental modification with full state reconstruction. At every continue site in the loop, construct a complete new state object rather than modifying fields one by one. This eliminates the "forgot to reset a field" bug class, especially when there are multiple continuation paths.
• Withhold recoverable errors. Don't expose errors to upper-level consumers at the first opportunity. Try all recovery means first; only release the error after all attempts fail. This prevents upper layers from prematurely terminating sessions upon seeing an error.
• Leverage the model response wait window for parallel prefetch. Start memory prefetch, skill discovery, and other async tasks simultaneously with the API call. The 5-30 seconds while the model generates its response is "free" computation time.
• Record transition reasons. Record why the loop continued in the state (e.g., next_turn, reactive_compact_retry) — this aids debugging and lets automated tests assert whether specific recovery paths were triggered.

3.7 Chapter Summary

queryLoop() is Claude Code's heartbeat. It doesn't simply pass messages between user and model; instead, it actively manages context capacity, orchestrates tool execution, handles error recovery, and executes permission checks at every iteration. Once you understand the topology and transition semantics of this loop, every subsystem discussed in subsequent chapters — autocompact (Chapter 9), API call construction (Chapter 5), streaming response handling (Chapter 13), permission checking (Chapter 16) — can be precisely located in your mental model at the exact position and timing where they're invoked.

The most profound design characteristic of this loop is: it knows it might fail and is prepared for it. Not an optimistic "if everything goes well" path, but a defensive design of "how to gracefully recover when things go wrong." This is precisely the key engineering decision that transforms a demo-level AI chat interface into a production-grade AI Agent.

Chapter 4: Tool Execution Orchestration — Permissions, Concurrency, Streaming, and Interrupts

Positioning: This chapter analyzes how CC concurrently executes tool calls — partition scheduling, the permission decision chain, the streaming executor, and large result persistence. Prerequisites: Chapter 2 (Tool System), Chapter 3 (Agent Loop). Target audience: readers wanting to understand how CC concurrently executes tool calls, permission checks, and streaming output.

Chapter 3 dissected the full lifecycle of the Agent Loop. When the model returns content blocks of type tool_use, the loop enters the "tool execution phase." This chapter dives deep into the internal implementation of this phase: how tool calls are partitioned and scheduled, what lifecycle steps a single tool execution goes through, how the permission decision chain filters layer by layer, how large results are persisted, and how the streaming executor handles concurrency and interrupts.

4.1 Why Tool Execution Orchestration Is Critical

In a single Agent Loop iteration, the model may request multiple tool calls simultaneously. For example, the model might issue three Read calls to read different files, followed by a Bash call to run tests. These calls can't all execute in parallel — read operations are safe, but a git checkout could change working directory state, causing parallel reads to get inconsistent results.

Claude Code's tool orchestration layer solves three core problems:

1. Safe concurrency: Read-only tools can execute in parallel to improve throughput; write tools must execute serially to guarantee consistency
2. Permission gating: Every tool must pass through the permission decision chain before execution, ensuring users retain control over dangerous operations
3. Result management: Tool output can be enormous (a cat command might return hundreds of thousands of characters), requiring intelligent trimming to avoid context window overflow

The solutions to these three problems are distributed across three core files: toolOrchestration.ts (batch scheduling), toolExecution.ts (single-tool lifecycle), and StreamingToolExecutor.ts (streaming concurrent executor).

4.2 partitionToolCalls: Tool Call Partitioning

4.2.1 The Partitioning Algorithm

When the Agent Loop hands a batch of ToolUseBlocks to the orchestration layer, the first step is to partition them into alternating "concurrency-safe batches" and "serial batches." This is the responsibility of the partitionToolCalls function:

flowchart TD
    Input["Model's tool call sequence (in order)<br/>[Read A] [Read B] [Grep C] [Bash D] [Read E] [Edit F]"]
    Input -->|partitionToolCalls| B1
    B1["Batch 1 (concurrency-safe)<br/>Read A, Read B, Grep C<br/>Three read-only tools merged into one batch"]
    B1 --> B2["Batch 2 (serial)<br/>Bash D<br/>Write tool gets exclusive batch"]
    B2 --> B3["Batch 3 (concurrency-safe)<br/>Read E<br/>New read-only batch"]
    B3 --> B4["Batch 4 (serial)<br/>Edit F<br/>Write tool gets exclusive batch"]

    style B1 fill:#d4edda,stroke:#28a745
    style B3 fill:#d4edda,stroke:#28a745
    style B2 fill:#f8d7da,stroke:#dc3545
    style B4 fill:#f8d7da,stroke:#dc3545

Figure 4-1: partitionToolCalls partitioning logic. Consecutive concurrency-safe tools are merged into the same batch (green); non-concurrency-safe tools each get their own exclusive batch (red).

The core of the partitioning logic is a reduce operation (restored-src/src/services/tools/toolOrchestration.ts:91-116):

function partitionToolCalls(
  toolUseMessages: ToolUseBlock[],
  toolUseContext: ToolUseContext,
): Batch[] {
  return toolUseMessages.reduce((acc: Batch[], toolUse) => {
    const tool = findToolByName(toolUseContext.options.tools, toolUse.name)
    const parsedInput = tool?.inputSchema.safeParse(toolUse.input)
    const isConcurrencySafe = parsedInput?.success
      ? (() => {
          try {
            return Boolean(tool?.isConcurrencySafe(parsedInput.data))
          } catch {
            return false  // Conservative strategy: parse failure = unsafe
          }
        })()
      : false
    if (isConcurrencySafe && acc[acc.length - 1]?.isConcurrencySafe) {
      acc[acc.length - 1]!.blocks.push(toolUse)  // Merge into previous concurrent batch
    } else {
      acc.push({ isConcurrencySafe, blocks: [toolUse] })  // Create new batch
    }
    return acc
  }, [])
}

Key design decisions:

• Validate before classifying: Input must pass Zod schema validation before isConcurrencySafe is called. If the model generates invalid input, the tool is conservatively marked as not concurrency-safe.
• Exception means unsafe: If isConcurrencySafe itself throws an exception (e.g., shell-quote fails to parse a Bash command), it also falls back to serial execution. This is the classic "fail-closed" security pattern.
• Greedy merging: Consecutive concurrency-safe tools are merged into the same batch until a non-safe tool is encountered. This maintains relative call order while maximizing parallelism.

4.2.2 isConcurrencySafe Determination Logic

isConcurrencySafe is a required method on the Tool interface (restored-src/src/Tool.ts:402), with a default implementation returning false (restored-src/src/Tool.ts:759). Each tool provides its own implementation based on its semantics:

Taking BashTool as an example (restored-src/src/tools/BashTool/BashTool.tsx:434-436):

isConcurrencySafe(input) {
  return this.isReadOnly?.(input) ?? false;
},

Bash tool's concurrency safety depends entirely on the command content: ls, cat, git log are safe, while rm, git checkout, npm install are not. isReadOnly parses the command structure to make this determination.

4.3 runTools: The Batch Scheduling Engine

runTools (restored-src/src/services/tools/toolOrchestration.ts:19-82) is the orchestration layer's entry point. It iterates over the partitioned batches, calling runToolsConcurrently for concurrency-safe batches and runToolsSerially for serial batches.

4.3.1 Concurrent Execution Path

The concurrent path uses the all() utility function (restored-src/src/utils/generators.ts:32) to merge multiple async generators into one, with a concurrency cap:

async function* runToolsConcurrently(...) {
  yield* all(
    toolUseMessages.map(async function* (toolUse) {
      yield* runToolUse(toolUse, ...)
      markToolUseAsComplete(toolUseContext, toolUse.id)
    }),
    getMaxToolUseConcurrency(),  // Default 10, overridable via env var
  )
}

The concurrency cap is configured via the environment variable CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY (restored-src/src/services/tools/toolOrchestration.ts:8-11), defaulting to 10.

An important detail is deferred application of context modifiers. Concurrently executing tools may each produce context modifications (e.g., updating the available tool list), but these modifications can't be applied immediately during concurrent execution — that would cause race conditions. Therefore, modifiers are collected into a queue and applied sequentially in tool appearance order after the entire concurrent batch completes (restored-src/src/services/tools/toolOrchestration.ts:31-63).

4.3.2 Serial Execution Path

The serial path directly executes each tool in sequence, applying context modifications immediately after each execution:

for (const toolUse of toolUseMessages) {
  for await (const update of runToolUse(toolUse, ...)) {
    if (update.contextModifier) {
      currentContext = update.contextModifier.modifyContext(currentContext)
    }
    yield { message: update.message, newContext: currentContext }
  }
}

This guarantees that write tools can see the context state modified by the previous tool.

4.4 Single-Tool Execution Lifecycle

Every tool call, whether through the concurrent or serial path, ultimately enters runToolUse (restored-src/src/services/tools/toolExecution.ts:337) and checkPermissionsAndCallTool (restored-src/src/services/tools/toolExecution.ts:599). These two functions compose the complete lifecycle of a single tool.

┌─────────────────────────────────────────────────────────────────┐
│                    Single-Tool Execution Lifecycle                │
│                                                                  │
│  ① Tool Lookup ──→ ② Schema Validation ──→ ③ Input Validation   │
│       │              │                  │                         │
│   Tool not found? Validation failed? Validation failed?          │
│   ↓ Return error  ↓ Return error     ↓ Return error              │
│                                                                  │
│  ④ PreToolUse Hooks ──→ ⑤ Permission Decision ──→ ⑥ tool.call() │
│       │                      │               │                   │
│   Hook blocked?        Permission denied? Execution error?       │
│   ↓ Return error      ↓ Return error     ↓ Return error         │
│                                                                  │
│  ⑦ Result Mapping ──→ ⑧ Large Result Persistence ──→ ⑨ PostToolUse Hooks │
│                                          │                       │
│                                   Hook prevents continuation?    │
│                                   ↓ Stop subsequent loops        │
└─────────────────────────────────────────────────────────────────┘

Figure 4-2: Single-tool lifecycle flow. Each stage can produce an error message that terminates the flow; the success path traverses all nine stages from left to right.

4.4.1 Phase 1: Tool Lookup and Input Validation

runToolUse first searches for the target tool in the available tool set (restored-src/src/services/tools/toolExecution.ts:345-356). If not found, it also checks deprecated tool aliases — this ensures tool calls from old session records can still execute.

Input validation has two steps:

1. Schema validation: Uses Zod's safeParse for type checking against the model's output parameters (restored-src/src/services/tools/toolExecution.ts:615-616). Model-generated parameter types aren't always correct — for example, it might output a string for a parameter that should be an array.

2. Semantic validation: Tool-specific business logic validation via tool.validateInput() (restored-src/src/services/tools/toolExecution.ts:683-684). For example, the FileEdit tool might check whether the target file exists.

A noteworthy detail: when a tool is a deferred tool and its schema wasn't sent to the API, the system appends a hint in the Zod error message guiding the model to first load the tool schema via ToolSearch before retrying (restored-src/src/services/tools/toolExecution.ts:578-597).

4.4.2 Phase 2: Speculative Classifier Launch

Before entering permission checking, if the current tool is a Bash tool, the system speculatively launches the allow classifier (speculative classifier check, restored-src/src/services/tools/toolExecution.ts:740-752). This classifier runs in parallel with PreToolUse Hooks, so the result may already be ready when the user needs to make a permission decision. This is an optimization — avoiding the user waiting for classifier latency.

4.4.3 Phase 3: PreToolUse Hooks

The system executes all registered PreToolUse hooks (restored-src/src/services/tools/toolExecution.ts:800-862). Hooks can produce the following effects:

• Modify input: Return updatedInput to replace original parameters
• Make permission decisions: Return allow, deny, or ask to influence subsequent permission checking
• Block execution: Set the preventContinuation flag
• Add context: Inject additional information for the model's reference

If the hook execution is interrupted by an abort signal, the system immediately terminates and returns a cancellation message.

4.4.4 Phase 4: Permission Decision Chain

The permission system is the most complex part of the tool execution lifecycle. The decision chain is coordinated by resolveHookPermissionDecision (restored-src/src/services/tools/toolHooks.ts:332-433), following this priority:

┌──────────────────────────────────────────────────────────────────┐
│                       Permission Decision Chain                    │
│                                                                    │
│  PreToolUse Hook Decision                                          │
│  ├─ allow ──→ Check rule permissions (settings.json deny/ask)      │
│  │            ├─ No matching rule ──→ Allow (skip user prompt)     │
│  │            ├─ deny rule ──→ Deny (rule overrides Hook)          │
│  │            └─ ask rule ──→ Prompt user (rule overrides Hook)    │
│  ├─ deny ──→ Deny directly                                        │
│  └─ ask ──→ Enter normal permission flow (with Hook's              │
│             forceDecision)                                          │
│                                                                    │
│  No Hook Decision ──→ Normal permission flow                       │
│  ├─ Tool's own checkPermissions                                    │
│  ├─ General rule matching (settings.json)                          │
│  ├─ YOLO/Auto classifier (see Chapter 17)                          │
│  └─ User interactive prompt (see Chapter 16)                       │
└──────────────────────────────────────────────────────────────────┘

Figure 4-3: Permission decision chain diagram. A Hook's allow cannot override deny rules in settings.json — this is defense in depth in action.

A key invariant of the decision chain: A Hook's allow decision cannot bypass deny/ask rules in settings.json. Even if a hook approves an operation, if settings.json contains an explicit deny rule, the operation is still denied. This ensures user-configured security boundaries are always effective (restored-src/src/services/tools/toolHooks.ts:373-405).

The complete architecture of the permission system is covered in Chapter 16; the YOLO classifier implementation is covered in Chapter 17.

4.4.5 Phase 5: Tool Execution

After permissions pass, the system calls tool.call() (restored-src/src/services/tools/toolExecution.ts:1207-1222). The execution is wrapped between startSessionActivity('tool_exec') and stopSessionActivity('tool_exec') for tracking active session state.

Progress events during tool execution are delivered via a Stream object (restored-src/src/services/tools/toolExecution.ts:509). streamedCheckPermissionsAndCallTool merges the checkPermissionsAndCallTool Promise result with real-time progress events into the same async iterable, allowing callers to receive both progress updates and the final result.

4.4.6 Phase 6: PostToolUse Hooks and Result Processing

After successful tool execution, the system sequentially performs:

1. Result mapping: Converts tool output to API format via tool.mapToolResultToToolResultBlockParam() (restored-src/src/services/tools/toolExecution.ts:1292-1293)
2. Large result persistence: If the result exceeds the threshold, writes it to disk and replaces with a summary (see Section 4.6)
3. PostToolUse Hooks: Executes post-hooks, which can modify MCP tool output or prevent subsequent loop continuation (restored-src/src/services/tools/toolExecution.ts:1483-1531)

For MCP tools, hooks can modify tool output by returning updatedMCPToolOutput. This modification takes effect before the addToolResult call, ensuring the modified version is what gets stored in message history. For non-MCP tools, result mapping completes before hooks, so hooks can only append information, not modify results.

If tool execution fails, the system instead executes PostToolUseFailure hooks (restored-src/src/services/tools/toolExecution.ts:1700-1713), allowing hooks to inspect the error and inject additional context.

4.5 StreamingToolExecutor: The Streaming Concurrent Executor

The runTools described above operates in batch mode — it waits for all tool_use blocks to arrive before starting partitioning and execution. But in streaming response scenarios, tool call blocks are parsed one by one from the API stream. StreamingToolExecutor (restored-src/src/services/tools/StreamingToolExecutor.ts) implements a different strategy: start executing tool calls as they arrive, without waiting for all to be ready.

4.5.1 State Machine Model

StreamingToolExecutor maintains a four-state lifecycle for each tool:

queued ──→ executing ──→ completed ──→ yielded

• queued: Tool registered but not yet started
• executing: Tool currently running
• completed: Tool finished, result buffered
• yielded: Result consumed by caller

State transitions are driven by processQueue() (restored-src/src/services/tools/StreamingToolExecutor.ts:140-151). Each time a tool completes or a new tool is enqueued, the queue processor is woken up to attempt starting the next executable tool.

4.5.2 Concurrency Control

The canExecuteTool method (restored-src/src/services/tools/StreamingToolExecutor.ts:129-135) implements the core concurrency strategy:

private canExecuteTool(isConcurrencySafe: boolean): boolean {
  const executingTools = this.tools.filter(t => t.status === 'executing')
  return (
    executingTools.length === 0 ||
    (isConcurrencySafe && executingTools.every(t => t.isConcurrencySafe))
  )
}

The rules are concise:

• If no tools are executing, any tool can start
• If tools are executing, a new tool can only start if both itself and all currently executing tools are concurrency-safe
• Non-concurrency-safe tools require exclusive access

4.5.3 Bash Error Cascade Abort

StreamingToolExecutor implements an elegant error handling mechanism: when a Bash tool errors, all sibling parallel Bash tools are cancelled (restored-src/src/services/tools/StreamingToolExecutor.ts:357-363).

if (tool.block.name === BASH_TOOL_NAME) {
  this.hasErrored = true
  this.erroredToolDescription = this.getToolDescription(tool)
  this.siblingAbortController.abort('sibling_error')
}

This design is based on a practical observation: Bash commands typically have implicit dependency chains. If mkdir fails, a subsequent cp command is destined to fail too — rather than letting them each report errors independently, it's better to cancel preemptively. But this strategy only applies to Bash tools — Read, WebFetch, and similar tools are independent; one's failure shouldn't affect others.

The error cascade uses a siblingAbortController, which is a child controller of toolUseContext.abortController. Aborting the sibling controller cancels running subprocesses but does not abort the parent controller — meaning the Agent Loop itself won't terminate the current turn due to a single Bash error.

4.5.4 Interrupt Behavior

Each tool can declare its own interrupt behavior: 'cancel' or 'block' (restored-src/src/Tool.ts:416). When the user sends an interrupt signal:

• cancel tools: Immediately receive a cancellation message; results are replaced with a synthesized REJECT_MESSAGE
• block tools: Continue running to completion (don't respond to interrupt)

StreamingToolExecutor tracks whether all currently executing tools are interruptible via updateInterruptibleState() (restored-src/src/services/tools/StreamingToolExecutor.ts:254-259). This information is passed to the UI layer, determining whether to show "Press ESC to cancel."

4.5.5 Immediate Delivery of Progress Messages

Regular tool results must be delivered in order (preserving order semantics), but progress messages can be delivered immediately (restored-src/src/services/tools/StreamingToolExecutor.ts:417-420). StreamingToolExecutor stores progress messages in a separate pendingProgress queue; getCompletedResults() yields progress messages first when scanning the tool list, unconstrained by tool completion order.

When there are no completed results but tools are executing, getRemainingResults() uses Promise.race to wait for either any tool to complete or new progress messages to arrive (restored-src/src/services/tools/StreamingToolExecutor.ts:476-481), avoiding unnecessary polling.

4.6 Tool Result Management: Budgets and Persistence

4.6.1 Large Result Persistence

A Bash tool's cat command might return hundreds of thousands of characters. Stuffing such an enormous result directly into the context window not only wastes token budget but may cause the model's attention to scatter. toolResultStorage.ts implements the large result persistence mechanism.

Persistence threshold determination follows this priority (restored-src/src/utils/toolResultStorage.ts:55-78):

1. GrowthBook override: The operations team can set custom thresholds for specific tools via Feature Flags (tengu_satin_quoll)
2. Tool-declared value: Each tool's maxResultSizeChars property
3. Global ceiling: DEFAULT_MAX_RESULT_SIZE_CHARS = 50,000 characters (restored-src/src/constants/toolLimits.ts:13)

The final threshold is the lesser of the tool-declared value and the global ceiling. But if a tool declares Infinity, persistence is skipped — for example, the Read tool manages its own output boundaries, and persisting its output to a file only to have the model Read it back would be a circular reference.

When a result exceeds the threshold, persistToolResult (restored-src/src/utils/toolResultStorage.ts:137) writes the full content to a tool-results/ subdirectory under the session directory, then generates a summary message with a preview:

<persisted-output>
Output too large (245.0 KB). Full output saved to: /path/to/tool-results/abc123.txt

Preview (first 2.0 KB):
[First 2000 bytes of content...]
...
</persisted-output>

Preview generation (restored-src/src/utils/toolResultStorage.ts:339-356) attempts to truncate at newline boundaries to avoid cutting in the middle of a line. The truncation point search range is the last newline between 50% and 100% of the threshold.

4.6.2 Per-Message Aggregate Budget

Beyond single-tool size limits, the system also maintains a per-message aggregate budget. When multiple parallel tools in a single turn each return results near the threshold, their sum can far exceed reasonable limits (e.g., 10 tools each returning 40K = 400K characters).

The aggregate budget defaults to 200,000 characters (restored-src/src/constants/toolLimits.ts:49), overridable via GrowthBook Flag (tengu_hawthorn_window). When exceeded, the system persists results starting from the largest tool result until the total drops back within budget.

To maintain prompt cache stability, the aggregate budget system maintains a ContentReplacementState (restored-src/src/utils/toolResultStorage.ts:390-393), recording which tool results have been persisted. Once a result is persisted in one evaluation, it uses the same persisted version in all subsequent evaluations — even if the total doesn't exceed budget in subsequent turns. This avoids "cache thrashing": the same message having different content across API calls, causing prefix cache invalidation.

4.6.3 Empty Result Padding

An easily overlooked detail: empty tool_result content can cause some models (especially Capybara) to misinterpret it as a turn boundary, outputting the \n\nHuman: stop sequence and terminating the response (restored-src/src/utils/toolResultStorage.ts:280-295). The system prevents this by detecting empty results and injecting placeholder text (e.g., (Bash completed with no output)).

4.7 Stop Hooks: Interruption Points After Tool Execution

Both PreToolUse and PostToolUse hooks can request stopping subsequent loop continuation (prevent continuation). This is implemented via the preventContinuation flag.

When a PreToolUse hook sets this flag (restored-src/src/services/tools/toolHooks.ts:500-508), the tool still executes (unless a deny decision is also returned), but after execution completes, the system appends a hook_stopped_continuation type attachment message to the message list (restored-src/src/services/tools/toolExecution.ts:1572-1582). The Agent Loop detects this message type and terminates the current iteration, no longer sending results to the model for the next reasoning round.

PostToolUse hooks can similarly prevent continuation (restored-src/src/services/tools/toolHooks.ts:118-129) and are the more common use case — for example, a hook might decide to interrupt the Agent loop after detecting the results of a dangerous operation.

4.8 Pattern Extraction

Pattern 1: Greedy-Merge Pipeline Partitioning

Tool call partitioning uses a "greedy merge" strategy: consecutive same-type tools are merged into the same batch, with type-switch points becoming batch boundaries. The core insight of this pattern is — between order guarantees and parallel efficiency, choose a simple middle ground. Full parallelism (ignoring order) could cause inconsistency; full serialization (ignoring type) wastes performance. Greedy merging achieves near-optimal parallelism while maintaining relative order.

Pattern 2: Fail-Closed Safety Defaults

isConcurrencySafe defaults to false on parse failure or exception; the Tool interface's default implementation is also false. Permission hooks' allow can't override deny rules. These are all manifestations of the "fail-closed" pattern — when the system can't determine safety, choose the more conservative behavior. In AI Agent systems, this principle is especially important: model output is unpredictable, and any optimistic design assuming "this normally won't happen" could become a security vulnerability.

Pattern 3: Layered Error Cascade

Bash errors cancel sibling Bash tools but don't affect Read/Grep and other independent tools; sibling abort controllers cancel subprocesses but don't abort the parent Agent Loop. This selective cascading avoids two extremes: either complete isolation (errors ignored) or global abort (one small error kills the entire session).

Pattern 4: Cache-Stable Result Management

The large result persistence system uses ContentReplacementState to ensure the same result always uses the same replacement content across different API calls. This is key to prompt cache optimization — for performance, sacrifice a bit of logical simplicity to maintain determinism. Similar cache stability designs will recur throughout Chapters 13-15's caching architecture.

What You Can Do

Here are actionable recommendations extracted from Claude Code's tool execution orchestration, applicable to any AI Agent system that needs to orchestrate multi-tool calls:

• Implement input-based concurrency partitioning. Don't simply serialize all tool calls. Judge whether each tool call is read-only/concurrency-safe based on its actual input, merge consecutive safe calls into concurrent batches, and maximize throughput.
• Set "fail-closed" defaults for concurrency safety. If input parsing fails or isConcurrencySafe throws an exception, default to serial execution. Never assume concurrency is safe when uncertain.
• Implement selective cascade abort for Bash errors. When a shell command fails, cancel sibling shell commands (they likely have implicit dependencies), but don't cancel independent read-only tools (like Read, Grep). Use child AbortControllers to avoid aborting the entire Agent Loop.
• Implement two-level budget control for large results. Single tool results have a character limit; all tool results in a single message also have an aggregate limit. When exceeding budget, persist to disk and return previews, starting from the largest results.
• Maintain determinism in result replacement. Once a tool result is persisted and replaced, use the same replacement version in all subsequent API calls, even if the aggregate budget is currently not exceeded. This is critical for prompt cache hit rates.
• Inject placeholder text for empty tool results. Empty tool_result may be misinterpreted by the model as a turn boundary. Inject text like (Bash completed with no output) to prevent the model from unexpectedly terminating its response.
• Design permission checking as defense in depth. A Hook's allow decision should not bypass user-configured deny rules. Multi-layer permission checking (hook -> tool's own -> rule matching -> user interaction) ensures security boundaries are always effective.

This chapter revealed how the tool execution orchestration layer balances concurrent efficiency, safety control, and context management. The next chapter enters Part 2, analyzing the system prompt architecture — another key control surface for harnessing model behavior.

Version Evolution: v2.1.92 Changes

The following analysis is based on v2.1.92 bundle string signal inference, without complete source code evidence. Changes already documented for v2.1.91 (staleReadFileStateHint file state tracking, etc.) are not repeated here.

AdvisorTool — The First Non-Execution Tool

A brand new name appears in v2.1.92's tool list: AdvisorTool. Together with event signals in the bundle (tengu_advisor_command, tengu_advisor_dialog_shown, tengu_advisor_tool_call, tengu_advisor_result), and associated identifiers advisor_model, advisor_redacted_result, advisor_tool_token_usage, it can be inferred that this is an embedded advisor Agent — it has its own independent model call chain (advisor_model implies a separate model or configuration), produces tool calls (advisor_tool_call), and results may undergo redaction (advisor_redacted_result).

This has no precedent in v2.1.88's 40+ tool system (see Chapter 2). All tools in v2.1.88 are execution-type — Read reads files, Bash executes commands, Edit modifies files, Grep searches content. Their common trait is directly changing environment state or returning environment data. AdvisorTool breaks this pattern: it doesn't execute any external operation, but rather provides suggestions to the user or Agent.

This design choice reflects an evolutionary direction for Agent systems: from "only doing things" to "suggesting first, then doing things." This aligns with the philosophy of plan mode (see Chapter 20c) — aligning intent before execution. The difference is that plan mode is a user-initiated workflow, while AdvisorTool may trigger automatically during Agent operation (advisor_dialog_shown suggests it pops up a dialog).

The existence of the CLAUDE_CODE_DISABLE_ADVISOR_TOOL environment variable indicates this feature can be disabled — consistent with Claude Code's established "progressive autonomy" principle (see Chapter 27): new capabilities are enabled by default but opt-out.

Tool Result Deduplication — A New Defense Line for Context Hygiene

The tengu_tool_result_dedup event reveals a deduplication mechanism at the tool result layer. In v2.1.88, context hygiene relied primarily on two defense lines: single-tool result truncation (DEFAULT_MAX_RESULT_SIZE_CHARS = 50,000, see restored-src/src/constants/toolLimits.ts:13) and compaction (see Chapter 11). v2.1.92 adds a third: tool result deduplication.

This forms a complete chain with v2.1.91's newly added tengu_file_read_reread (detecting repeated file reads): file_read_reread detects on the input side "you read the same file again," while tool_result_dedup handles on the output side "this result is the same as before, no need to redundantly occupy context window."

Design philosophy: context is an Agent's most precious resource, and every layer should have deduplication and cleanup mechanisms — input dedup, output dedup, compaction. These three defense lines each guard a different stage, collectively maintaining context hygiene.

Version Evolution: v2.1.91 Changes

The following analysis is based on v2.1.91 bundle signal comparison.

v2.1.91's sdk-tools.d.ts added a new staleReadFileStateHint field to tool result metadata — when tool execution causes the mtime of a previously read file to change, the system automatically generates a staleness hint. This is a new output channel for the tool execution orchestration layer, enabling the model to perceive the side effects of its own operations on the file system.

Chapter 4b: Plan Mode — From "Act First, Ask Later" to "Look Before You Leap"

Positioning: This chapter analyzes Claude Code's Plan Mode — a complete "plan first, execute second" state machine. Prerequisites: Chapter 3 (Agent Loop), Chapter 4 (Tool Execution Orchestration). Use when: you want to understand how CC implements a human-aligned planning approval mechanism, or want to implement a similar "plan before act" workflow in your own AI Agent.

Why This Matters

One of the biggest risks with AI coding agents isn't writing incorrect code — it's writing correct code for the wrong thing. When a user says "refactor the auth module," the agent might choose JWT while the user had OAuth2 in mind. If the agent starts implementing immediately, by the time the user discovers the direction is wrong, dozens of files have already been modified.

Plan Mode solves the intent alignment problem: before the agent modifies any code, it first explores the codebase, creates a plan, and obtains user approval. This isn't a simple "ask before doing" — it's a complete state machine involving permission mode switching, plan file persistence, workflow prompt injection, inter-team approval protocols, and complex interactions with Auto Mode.

From an engineering perspective, Plan Mode demonstrates three key design decisions:

1. Permission modes as behavioral constraints: After entering plan mode, the model's toolset is restricted to read-only — not through a prompt saying "please don't modify files," but through the permission system intercepting write operations before tool execution.
2. Plan files as alignment vehicles: Plans don't stay in conversation context as text — they're written to disk as Markdown files that users can edit in external editors and that CCR remote sessions can transmit back to the local terminal.
3. A state machine, not a boolean flag: Plan Mode isn't a simple isPlanMode flag — it's a complete state transition chain encompassing entry, exploration, approval, exit, and restoration, where each transition has side effects to manage.

4b.1 The Plan Mode State Machine: Entry and Exit

At the core of Plan Mode are two tools — EnterPlanMode and ExitPlanMode — and the permission mode transitions they trigger.

Entering Plan Mode

There are two paths to enter Plan Mode:

1. The model proactively calls the EnterPlanMode tool — requires user confirmation
2. The user manually types the /plan command — takes effect immediately

Both paths ultimately call the same core function, prepareContextForPlanMode:

// restored-src/src/utils/permissions/permissionSetup.ts:1462-1492
export function prepareContextForPlanMode(
  context: ToolPermissionContext,
): ToolPermissionContext {
  const currentMode = context.mode
  if (currentMode === 'plan') return context
  if (feature('TRANSCRIPT_CLASSIFIER')) {
    const planAutoMode = shouldPlanUseAutoMode()
    if (currentMode === 'auto') {
      if (planAutoMode) {
        return { ...context, prePlanMode: 'auto' }
      }
      // ... deactivate auto mode and restore permissions stripped by auto
    }
    if (planAutoMode && currentMode !== 'bypassPermissions') {
      autoModeStateModule?.setAutoModeActive(true)
      return {
        ...stripDangerousPermissionsForAutoMode(context),
        prePlanMode: currentMode,
      }
    }
  }
  return { ...context, prePlanMode: currentMode }
}

Key design: The prePlanMode field saves the mode before entry. This is a classic "save/restore" pattern — when entering plan mode, the current mode (which could be default, auto, or acceptEdits) is stored in prePlanMode, and restored on exit. This ensures Plan Mode is a reversible operation that doesn't lose the user's previous permission configuration.

The EnterPlanMode tool definition itself reveals several important constraints:

// restored-src/src/tools/EnterPlanModeTool/EnterPlanModeTool.ts:36-102
export const EnterPlanModeTool: Tool<InputSchema, Output> = buildTool({
  name: ENTER_PLAN_MODE_TOOL_NAME,
  shouldDefer: true,
  isEnabled() {
    // Disabled when --channels is active, preventing plan mode from becoming a trap
    if ((feature('KAIROS') || feature('KAIROS_CHANNELS')) &&
        getAllowedChannels().length > 0) {
      return false
    }
    return true
  },
  isConcurrencySafe() { return true },
  isReadOnly() { return true },
  async call(_input, context) {
    if (context.agentId) {
      throw new Error('EnterPlanMode tool cannot be used in agent contexts')
    }
    // ... execute mode switch
  },
})

Three constraints worth noting:

Exiting Plan Mode

Exiting is far more complex than entering. ExitPlanModeV2Tool has three execution paths:

flowchart TD
    A[ExitPlanMode called] --> B{Caller identity?}
    B -->|Non-teammate| C{Current mode is plan?}
    C -->|No| D[Reject: not in plan mode]
    C -->|Yes| E[Show approval dialog]
    E --> F{User choice?}
    F -->|Approve| G[Restore prePlanMode]
    F -->|Reject| H[Stay in plan mode]
    G --> I[Return plan content]
    
    B -->|Teammate + planModeRequired| J{Plan file exists?}
    J -->|No| K[Throw error]
    J -->|Yes| L[Send plan_approval_request to team-lead mailbox]
    L --> M[Wait for leader approval]
    
    B -->|Teammate voluntary plan| N[Exit directly, no approval needed]

The most complex part of exiting is permission restoration:

// restored-src/src/tools/ExitPlanModeTool/ExitPlanModeV2Tool.ts:357-403
context.setAppState(prev => {
  if (prev.toolPermissionContext.mode !== 'plan') return prev
  setHasExitedPlanMode(true)
  setNeedsPlanModeExitAttachment(true)
  let restoreMode = prev.toolPermissionContext.prePlanMode ?? 'default'
  
  if (feature('TRANSCRIPT_CLASSIFIER')) {
    // Circuit breaker defense: if auto mode gate is disabled, fall back to default
    if (restoreMode === 'auto' &&
        !(permissionSetupModule?.isAutoModeGateEnabled() ?? false)) {
      restoreMode = 'default'
    }
    // ... sync auto mode activation state
  }
  
  // Non-auto mode: restore dangerous permissions that were stripped
  const restoringToAuto = restoreMode === 'auto'
  if (restoringToAuto) {
    baseContext = permissionSetupModule?.stripDangerousPermissionsForAutoMode(baseContext)
  } else if (prev.toolPermissionContext.strippedDangerousRules) {
    baseContext = permissionSetupModule?.restoreDangerousPermissions(baseContext)
  }
  
  return {
    ...prev,
    toolPermissionContext: {
      ...baseContext,
      mode: restoreMode,
      prePlanMode: undefined, // clear the saved mode
    },
  }
})

This code demonstrates a circuit breaker defense pattern: if the user entered plan from auto mode, but during the plan the auto mode circuit breaker tripped (e.g., consecutive rejections exceeded the limit), exiting plan won't restore to auto — it falls back to default instead. This prevents a dangerous scenario: Plan Mode exit bypassing the circuit breaker to restore auto mode directly.

State Transition Debouncing

Users might rapidly toggle plan mode (enter → immediately exit → enter again). handlePlanModeTransition handles this edge case:

// restored-src/src/bootstrap/state.ts:1349-1363
export function handlePlanModeTransition(fromMode: string, toMode: string): void {
  // When switching TO plan, clear any pending exit attachment — prevents sending both enter and exit notifications
  if (toMode === 'plan' && fromMode !== 'plan') {
    STATE.needsPlanModeExitAttachment = false
  }
  // When leaving plan, mark that an exit attachment needs to be sent
  if (fromMode === 'plan' && toMode !== 'plan') {
    STATE.needsPlanModeExitAttachment = true
  }
}

This is a classic one-shot notification design — the attachment flag is cleared immediately after consumption, preventing duplicate sends.

4b.2 Plan Files: Persistent Intent Alignment

A key design decision in Plan Mode is: plans don't stay in conversation context — they're written to disk files. This brings three benefits:

1. Users can modify plans in an external editor (/plan open)
2. Plans survive context compaction without loss (see Chapter 10)
3. Plans from CCR remote sessions can be transmitted back to the local terminal

File Naming and Storage

// restored-src/src/utils/plans.ts:79-128
export const getPlansDirectory = memoize(function getPlansDirectory(): string {
  const settings = getInitialSettings()
  const settingsDir = settings.plansDirectory
  let plansPath: string

  if (settingsDir) {
    const cwd = getCwd()
    const resolved = resolve(cwd, settingsDir)
    // Path traversal defense
    if (!resolved.startsWith(cwd + sep) && resolved !== cwd) {
      logError(new Error(`plansDirectory must be within project root: ${settingsDir}`))
      plansPath = join(getClaudeConfigHomeDir(), 'plans')
    } else {
      plansPath = resolved
    }
  } else {
    plansPath = join(getClaudeConfigHomeDir(), 'plans')
  }
  // ...
})

export function getPlanFilePath(agentId?: AgentId): string {
  const planSlug = getPlanSlug(getSessionId())
  if (!agentId) {
    return join(getPlansDirectory(), `${planSlug}.md`)  // main session
  }
  return join(getPlansDirectory(), `${planSlug}-agent-${agentId}.md`)  // sub-agent
}

Plan Slug Generation

Each session generates a unique word slug, cached in planSlugCache:

// restored-src/src/utils/plans.ts:32-49
export function getPlanSlug(sessionId?: SessionId): string {
  const id = sessionId ?? getSessionId()
  const cache = getPlanSlugCache()
  let slug = cache.get(id)
  if (!slug) {
    const plansDir = getPlansDirectory()
    for (let i = 0; i < MAX_SLUG_RETRIES; i++) {
      slug = generateWordSlug()
      const filePath = join(plansDir, `${slug}.md`)
      if (!getFsImplementation().existsSync(filePath)) {
        break  // found a non-conflicting slug
      }
    }
    cache.set(id, slug!)
  }
  return slug!
}

Conflict detection retries up to 10 times (MAX_SLUG_RETRIES = 10). Since generateWordSlug() uses adjective-noun combinations (vocabulary sizes typically in the thousands for each word type, yielding millions of possible combinations), collision probability is extremely low even in frequently-used directories.

The /plan Command

Users interact with plans through the /plan command:

// restored-src/src/commands/plan/plan.tsx:64-121
export async function call(onDone, context, args) {
  const currentMode = appState.toolPermissionContext.mode
  
  // If not in plan mode, enable it
  if (currentMode !== 'plan') {
    handlePlanModeTransition(currentMode, 'plan')
    setAppState(prev => ({
      ...prev,
      toolPermissionContext: applyPermissionUpdate(
        prepareContextForPlanMode(prev.toolPermissionContext),
        { type: 'setMode', mode: 'plan', destination: 'session' },
      ),
    }))
    const description = args.trim()
    if (description && description !== 'open') {
      onDone('Enabled plan mode', { shouldQuery: true })  // with description → trigger query
    } else {
      onDone('Enabled plan mode')
    }
    return null
  }
  
  // Already in plan mode — show current plan or open in editor
  if (argList[0] === 'open') {
    const result = await editFileInEditor(planPath)
    // ...
  }
}

The /plan command has four behaviors:

• /plan — Enable plan mode (if not already in plan mode)
• /plan <description> — Enable plan mode with a description (shouldQuery: true triggers the model to start planning)
• /plan (already in plan mode) — Display current plan content and file path; shows "No plan written yet" if no plan exists
• /plan open — Open the plan file in an external editor

4b.3 Plan Prompt Injection: The 5-Phase Workflow

After entering Plan Mode, the system injects workflow instructions into the model via attachment messages. This is the core behavioral constraint of Plan Mode — rather than using tool restrictions to tell the model "what it can't do," prompts tell the model "what it should do."

Attachment Types

Plan Mode uses three attachment types:

Full vs. Sparse Throttling

// restored-src/src/utils/attachments.ts:1195-1241
function getPlanModeAttachments(messages, toolUseContext) {
  // Check how many human turns since the last plan_mode attachment
  const { turnCount, foundPlanModeAttachment } = 
    getPlanModeAttachmentTurnCount(messages)
  
  // Already have an attachment and interval too short → skip
  if (foundPlanModeAttachment &&
      turnCount < PLAN_MODE_ATTACHMENT_CONFIG.TURNS_BETWEEN_ATTACHMENTS) {
    return []
  }
  
  // Decide full or sparse
  const attachmentCount = countPlanModeAttachmentsSinceLastExit(messages)
  const reminderType = attachmentCount %
    PLAN_MODE_ATTACHMENT_CONFIG.FULL_REMINDER_EVERY_N_ATTACHMENTS === 1
    ? 'full' : 'sparse'
  
  attachments.push({ type: 'plan_mode', reminderType, isSubAgent, planFilePath, planExists })
  return attachments
}

Full attachments contain the complete 5-phase workflow instructions (~2,000+ characters). Sparse attachments are a single-line reminder:

Plan mode still active (see full instructions earlier in conversation). 
Read-only except plan file ({planFilePath}). Follow 5-phase workflow.

This is a token cost optimization — full instructions are only injected on the 1st, 6th, 11th... occurrence; all other turns use sparse. The counter resets each time plan mode is exited.

The 5-Phase Workflow (Standard Mode)

When isPlanModeInterviewPhaseEnabled() returns false, the model receives 5-phase instructions:

flowchart LR
    P1["Phase 1<br/>Initial Understanding<br/>Launch Explore agents"] --> P2["Phase 2<br/>Design<br/>Launch Plan agents"]
    P2 --> P3["Phase 3<br/>Review<br/>Read critical files"]
    P3 --> P4["Phase 4<br/>Final Plan<br/>Write to plan file"]
    P4 --> P5["Phase 5<br/>ExitPlanMode<br/>Submit for approval"]

// restored-src/src/utils/messages.ts:3227-3292 (core instructions, simplified)
const content = `Plan mode is active. The user indicated that they do not want 
you to execute yet -- you MUST NOT make any edits (with the exception of the 
plan file mentioned below)...

## Plan Workflow

### Phase 1: Initial Understanding
Goal: Gain a comprehensive understanding of the user's request...
Launch up to ${exploreAgentCount} Explore agents IN PARALLEL...

### Phase 2: Design
Launch Plan agent(s) to design the implementation...
You can launch up to ${agentCount} agent(s) in parallel.

### Phase 3: Review
Read the critical files identified by agents...
Use AskUserQuestion to clarify any remaining questions.

### Phase 4: Final Plan
Write your final plan to the plan file (the only file you can edit).

### Phase 5: Call ExitPlanMode
Once you are happy with your final plan file - call ExitPlanMode.
This is critical - your turn should only end with either AskUserQuestion OR ExitPlanMode.`

Agent counts are dynamically adjusted based on subscription tier:

// restored-src/src/utils/planModeV2.ts:5-29
export function getPlanModeV2AgentCount(): number {
  // Environment variable override
  if (process.env.CLAUDE_CODE_PLAN_V2_AGENT_COUNT) { /* ... */ }
  // Max 20x subscription → 3 agents
  if (subscriptionType === 'max' && rateLimitTier === 'default_claude_max_20x') return 3
  // Enterprise/Team → 3 agents
  if (subscriptionType === 'enterprise' || subscriptionType === 'team') return 3
  // Others → 1 agent
  return 1
}

Interview Workflow (Iterative Mode)

When isPlanModeInterviewPhaseEnabled() returns true (always true for Anthropic internal users), a different workflow is used:

// restored-src/src/utils/messages.ts:3323-3378
const content = `Plan mode is active...

## Iterative Planning Workflow

You are pair-planning with the user. Explore the code to build context, 
ask the user questions when you hit decisions you can't make alone, and 
write your findings into the plan file as you go.

### The Loop
Repeat this cycle until the plan is complete:
1. **Explore** — Use Read, Glob, Grep to read code...
2. **Update the plan file** — After each discovery, immediately capture what you learned.
3. **Ask the user** — When you hit an ambiguity, use AskUserQuestion. Then go back to step 1.

### First Turn
Start by quickly scanning a few key files... Then write a skeleton plan and 
ask the user your first round of questions. Don't explore exhaustively before engaging the user.

### Asking Good Questions
- Never ask what you could find out by reading the code
- Batch related questions together
- Focus on things only the user can answer: requirements, preferences, tradeoffs`

Core differences between interview mode and the standard 5-phase mode:

Pewter Ledger Experiment: Plan File Length Optimization

An interesting A/B experiment in Plan Mode is tengu_pewter_ledger — optimizing plan file structure and length:

// restored-src/src/utils/planModeV2.ts:66-95
// Baseline (control, 14d ending 2026-03-02, N=26.3M):
//   p50 4,906 chars | p90 11,617 | mean 6,207 | 82% Opus 4.6
//   Reject rate monotonic with size: 20% at <2K → 50% at 20K+
//
// Primary: session-level Avg Cost
export function getPewterLedgerVariant(): PewterLedgerVariant {
  const raw = getFeatureValue_CACHED_MAY_BE_STALE('tengu_pewter_ledger', null)
  if (raw === 'trim' || raw === 'cut' || raw === 'cap') return raw
  return null
}

Four experiment arms progressively tighten Phase 4 instructions:

The baseline data recorded in comments reveals a key finding: rejection rate is monotonically correlated with plan length — plans under 2K characters have a 20% rejection rate, while 20K+ plans have a 50% rejection rate. Longer plans don't mean better plans.

Different Trigger Thresholds for Internal vs. External Users

The EnterPlanMode tool prompt has two versions:

// restored-src/src/tools/EnterPlanModeTool/prompt.ts:166-170
export function getEnterPlanModeToolPrompt(): string {
  return process.env.USER_TYPE === 'ant'
    ? getEnterPlanModeToolPromptAnt()
    : getEnterPlanModeToolPromptExternal()
}

This internal/external difference reflects a product strategy: external users need more alignment protection (avoiding costly rework when the agent diverges), while internal users are more familiar with tool behavior and prefer fast execution.

4b.4 The Approval Flow: The Critical Human-AI Collaboration Point

User Approval (Standard Flow)

When the model calls ExitPlanMode, the user approval dialog is triggered for non-teammate scenarios:

// restored-src/src/tools/ExitPlanModeTool/ExitPlanModeV2Tool.ts:221-238
async checkPermissions(input, context) {
  if (isTeammate()) {
    return { behavior: 'allow' as const, updatedInput: input }
  }
  return {
    behavior: 'ask' as const,
    message: 'Exit plan mode?',
    updatedInput: input,
  }
}

After approval, mapToolResultToToolResultBlockParam injects the approved plan into the tool_result:

// restored-src/src/tools/ExitPlanModeTool/ExitPlanModeV2Tool.ts:481-492
return {
  type: 'tool_result',
  content: `User has approved your plan. You can now start coding. Start with updating your todo list if applicable

Your plan has been saved to: ${filePath}
You can refer back to it if needed during implementation.${teamHint}

## ${planLabel}:
${plan}`,
  tool_use_id: toolUseID,
}

If the user edited the plan in the CCR Web UI, the planWasEdited flag ensures the model knows the content was modified:

// restored-src/src/tools/ExitPlanModeTool/ExitPlanModeV2Tool.ts:477-478
const planLabel = planWasEdited
  ? 'Approved Plan (edited by user)'
  : 'Approved Plan'

Team Leader Approval

In Teams mode, teammate agents' plans require team lead approval (see Chapter 20b). ExitPlanModeV2Tool sends approval requests through the mailbox system:

// restored-src/src/tools/ExitPlanModeTool/ExitPlanModeV2Tool.ts:264-312
if (isTeammate() && isPlanModeRequired()) {
  const approvalRequest = {
    type: 'plan_approval_request',
    from: agentName,
    timestamp: new Date().toISOString(),
    planFilePath: filePath,
    planContent: plan,
    requestId,
  }
  
  await writeToMailbox('team-lead', {
    from: agentName,
    text: jsonStringify(approvalRequest),
    timestamp: new Date().toISOString(),
  }, teamName)
  
  return {
    data: {
      plan, isAgent: true, filePath,
      awaitingLeaderApproval: true,
      requestId,
    },
  }
}

The approval request is a JSON message written to the team lead's mailbox file (~/.claude/teams/{team}/inboxes/team-lead.json). Messages use proper-lockfile for concurrency safety.

Plan Execution Verification

The ExitPlanMode return value includes a hasTaskTool flag:

// restored-src/src/tools/ExitPlanModeTool/ExitPlanModeV2Tool.ts:405-408
const hasTaskTool =
  isAgentSwarmsEnabled() &&
  context.options.tools.some(t => toolMatchesName(t, AGENT_TOOL_NAME))

When Agent Swarms are available, a hint is appended to the tool_result:

If this plan can be broken down into multiple independent tasks, consider using the TeamCreate tool to create a team and parallelize the work.

This seamlessly connects Plan Mode output to multi-agent execution (see Chapter 20b).

4b.5 Auto Mode and Plan Mode Interaction

Auto Mode (YOLO classifier, see Chapter 17) and Plan Mode interaction is one of the most complex parts of CC's permission system.

Permission Saving on Entry

When a user enters plan mode from auto mode, there are two strategies:

// restored-src/src/utils/permissions/permissionSetup.ts:1469-1486
if (currentMode === 'auto') {
  if (planAutoMode) {
    // Keep auto active → classifier continues working during plan
    return { ...context, prePlanMode: 'auto' }
  }
  // Deactivate auto → strip dangerous permissions
  // ...
}

shouldPlanUseAutoMode() determines based on user settings whether to keep the classifier active during plan mode. If kept active, the model's read-only operations in plan mode are still auto-approved by the classifier; if deactivated, all operations require user confirmation.

Circuit Breaker Check on Exit

// restored-src/src/tools/ExitPlanModeTool/ExitPlanModeV2Tool.ts:328-346
if (feature('TRANSCRIPT_CLASSIFIER')) {
  const prePlanRaw = appState.toolPermissionContext.prePlanMode ?? 'default'
  if (prePlanRaw === 'auto' &&
      !(permissionSetupModule?.isAutoModeGateEnabled() ?? false)) {
    const reason = permissionSetupModule?.getAutoModeUnavailableReason() ?? 'circuit-breaker'
    gateFallbackNotification = 
      permissionSetupModule?.getAutoModeUnavailableNotification(reason) ??
      'auto mode unavailable'
  }
}

This logic ensures: if the auto mode circuit breaker tripped during plan mode (e.g., the classifier exceeded consecutive rejection limits), exiting plan won't restore to auto — it degrades to default instead. The user sees a notification:

plan exit → default · auto mode unavailable

Mid-Session Settings Changes

If the user modifies the useAutoModeDuringPlan setting while in plan mode, transitionPlanAutoMode takes effect immediately:

// restored-src/src/utils/permissions/permissionSetup.ts:1502-1517
export function transitionPlanAutoMode(
  context: ToolPermissionContext,
): ToolPermissionContext {
  if (context.mode !== 'plan') return context
  // Plan entered from bypassPermissions doesn't allow auto activation
  if (context.prePlanMode === 'bypassPermissions') return context
  
  const want = shouldPlanUseAutoMode()
  const have = autoModeStateModule?.isAutoModeActive() ?? false
  // Activate or deactivate auto based on want/have
}

4b.6 The Plan Agent: A Read-Only Architect

Plan Mode's 5-phase workflow uses the built-in Plan agent in Phase 2 (see Chapter 20 for the agent system). This agent's definition shows how read-only behavior is enforced through tool restrictions:

// restored-src/src/tools/AgentTool/built-in/planAgent.ts:73-92
export const PLAN_AGENT: BuiltInAgentDefinition = {
  agentType: 'Plan',
  disallowedTools: [
    AGENT_TOOL_NAME,      // cannot spawn sub-agents
    EXIT_PLAN_MODE_TOOL_NAME,  // cannot exit plan mode
    FILE_EDIT_TOOL_NAME,  // cannot edit files
    FILE_WRITE_TOOL_NAME, // cannot write files
    NOTEBOOK_EDIT_TOOL_NAME,
  ],
  tools: EXPLORE_AGENT.tools,
  omitClaudeMd: true,     // don't inject CLAUDE.md, saves tokens
  getSystemPrompt: () => getPlanV2SystemPrompt(),
}

The Plan agent's system prompt further reinforces the read-only constraint:

=== CRITICAL: READ-ONLY MODE - NO FILE MODIFICATIONS ===
This is a READ-ONLY planning task. You are STRICTLY PROHIBITED from:
- Creating new files (no Write, touch, or file creation of any kind)
- Modifying existing files (no Edit operations)
- Using redirect operators (>, >>, |) or heredocs to write to files
- Running ANY commands that change system state

The dual constraint (tool blocklist + prompt prohibition) ensures that even if the model "forgets" the tool restrictions, the prompt will prevent it from attempting write operations.

Pattern Extraction

From Plan Mode's implementation, the following reusable AI Agent design patterns can be extracted:

Pattern 1: Save/Restore Permission Mode

Problem: After temporarily entering a restricted mode, you need to precisely restore the previous state.

Solution: Add a prePlanMode field to the permission context — save on entry, restore on exit.

Entry: context.prePlanMode = context.mode; context.mode = 'plan'
Exit:  context.mode = context.prePlanMode; context.prePlanMode = undefined

Precondition: On exit, you must check whether external conditions (like circuit breakers) still permit restoration to the original mode. If not, degrade to a safe default.

Pattern 2: Plan File as Alignment Vehicle

Problem: Plans in conversation context get lost during compaction; users can't view or edit them outside the agent.

Solution: Write plans to disk files with human-readable naming (word slugs), supporting external editing and cross-session recovery.

Precondition: Requires path traversal defense, conflict detection, and snapshot persistence for remote sessions.

Pattern 3: Full/Sparse Throttling

Problem: Injecting full workflow instructions every turn wastes tokens, but not reminding the model at all causes workflow drift.

Solution: Inject full instructions on first occurrence, use sparse reminders subsequently, re-inject full every N times. Reset counter on state transitions.

Precondition: Count by human turns (not tool call turns), otherwise 10 tool calls would trigger repeated reminders.

Pattern 4: Internal/External Behavioral Calibration

Problem: Different user populations have different expectations for agent autonomy. External users need more alignment protection; internal users need more execution efficiency.

Solution: Differentiate prompt variants via USER_TYPE. External version lowers the trigger threshold ("if unsure, plan"); internal version raises it ("start working, ask specific questions").

Precondition: Requires A/B testing infrastructure to validate how different thresholds affect user satisfaction and rework rates.

Pattern 5: State Transition Debouncing

Problem: Rapid mode toggles (plan → normal → plan) can cause duplicate or contradictory notifications.

Solution: Use single-consumption flags (needsPlanModeExitAttachment); on entry, clear any pending exit notifications; on exit, set new notifications.

Precondition: Flags must be cleared immediately after consumption (attachment sent), and entry/exit operations must operate on flags mutually exclusively.

What Users Can Do

Basic Usage

Configuration Options

Usage Recommendations

1. Prefer Plan Mode for large refactors: For changes touching 3+ files, start with /plan refactor the auth system to let the model create an approach, then confirm before execution.
2. Edit plans rather than re-planning: If the plan is mostly right but needs adjustments, use /plan open to edit directly in your editor — more efficient than having the model re-plan.
3. Specify mode: 'plan' when launching agents: Through the Agent tool's mode parameter, you can have sub-agents work in plan mode, ensuring large tasks go through approval before execution.

Version Evolution Note

The core analysis in this chapter is based on Claude Code v2.1.88. Plan Mode is an actively evolving subsystem — the interview workflow (tengu_plan_mode_interview_phase) and plan length experiment (tengu_pewter_ledger) were still undergoing A/B testing at the time of analysis. Ultraplan (remote plan mode) as a remote extension of Plan Mode is covered in Chapter 20c.

Chapter 5: System Prompt Architecture

Positioning: This chapter analyzes how CC dynamically assembles the system prompt — section registration and memoization, cache boundary markers, and multi-source priority synthesis. Prerequisites: Chapter 3 (Agent Loop). Target audience: readers wanting to understand how CC dynamically assembles the system prompt, or developers looking to design a prompt architecture for their own Agent.

Chapter 4 dissected the entire orchestration process of tool execution. Before the model can make any tool call, it needs to first "know who it is" -- and that is precisely the role of the system prompt. This chapter dives deep into the assembly architecture of the system prompt: how sections are registered and memoized, how static and dynamic content are separated by boundary markers, how cache optimization contracts are honored at the API layer, and how multi-source prompts are synthesized by priority into the final instruction set sent to the model.

5.1 Why the System Prompt Needs "Architecture"

A naive implementation could hardcode the system prompt as a single string constant. But Claude Code's system prompt faces three engineering challenges:

1. Volume and Cost: The complete system prompt includes identity introduction, behavioral guidelines, tool usage instructions, environment information, memory files, MCP instructions, and over ten other sections, totaling tens of thousands of tokens. Retransmitting all of this on every API call means enormous prompt caching costs.
2. Varying Change Frequencies: Identity introduction and coding guidelines are identical across all users and all sessions, while environment information (working directory, OS version) varies by session, and MCP server instructions can even change mid-conversation.
3. Multi-Source Overrides: Users can customize the prompt via --system-prompt, Agent mode has its own dedicated prompt, coordinator mode has an independent prompt, and Loop mode can completely override everything -- the priority between these sources must be unambiguous.

Claude Code's solution is a sectioned composition architecture: splitting the system prompt into independent, memoizable sections, managing their lifecycle through a registry, using boundary markers to delineate cache tiers, and ultimately transforming them at the API layer into request blocks with cache_control.

Interactive Version: Click to view the prompt assembly animation -- watch 7 sections stack layer by layer as the cache ratio is calculated in real time.

5.2 Section Registry: Memoization and Cache Awareness of systemPromptSection

5.2.1 Core Abstraction

The minimal unit of the system prompt is a section. Each section consists of a name, a compute function, and a cache strategy. This abstraction is defined in systemPromptSections.ts:

type SystemPromptSection = {
  name: string
  compute: ComputeFn        // () => string | null | Promise<string | null>
  cacheBreak: boolean       // false = memoizable, true = recomputed each turn
}

Source Reference: restored-src/src/constants/systemPromptSections.ts:10-14

Two factory functions create sections:

• systemPromptSection(name, compute) -- Creates a memoized section. The compute function executes only on the first invocation; the result is cached in global state, and subsequent turns directly return the cached value. The cache resets on /clear or /compact.
• DANGEROUS_uncachedSystemPromptSection(name, compute, reason) -- Creates a volatile section. The compute function is re-executed on every resolve. The DANGEROUS_ prefix and mandatory reason parameter are intentional API friction, reminding developers that this type of section breaks prompt caching.

┌───────────────────────────────────────────────────────────────────────┐
│                      Section Registry                                 │
│                                                                       │
│  ┌─────────────────────┐   ┌──────────────────────────────────────┐  │
│  │ systemPromptSection │   │ DANGEROUS_uncachedSystemPromptSection│  │
│  │   cacheBreak=false  │   │         cacheBreak=true              │  │
│  └────────┬────────────┘   └────────────┬─────────────────────────┘  │
│           │                              │                            │
│           ▼                              ▼                            │
│  ┌─────────────────────────────────────────────────────────────────┐  │
│  │            resolveSystemPromptSections(sections)                │  │
│  │                                                                 │  │
│  │  for each section:                                              │  │
│  │    if (!cacheBreak && cache.has(name)):                         │  │
│  │      return cache.get(name)    ← memoization hit               │  │
│  │    else:                                                        │  │
│  │      value = await compute()                                    │  │
│  │      cache.set(name, value)    ← write to cache                │  │
│  │      return value                                               │  │
│  └─────────────────────────────────────────────────────────────────┘  │
│                                                                       │
│  Cache storage: STATE.systemPromptSectionCache (Map<string, string|null>) │
│  Reset timing: /clear, /compact → clearSystemPromptSections()        │
└───────────────────────────────────────────────────────────────────────┘

Figure 5-1: Memoization flow of the Section Registry. Memoized sections (cacheBreak=false) are cached in a global Map after first computation; volatile sections (cacheBreak=true) are recomputed every time.

5.2.2 Resolution Flow

resolveSystemPromptSections is the core function that transforms section definitions into actual strings (restored-src/src/constants/systemPromptSections.ts:43-58):

export async function resolveSystemPromptSections(
  sections: SystemPromptSection[],
): Promise<(string | null)[]> {
  const cache = getSystemPromptSectionCache()
  return Promise.all(
    sections.map(async s => {
      if (!s.cacheBreak && cache.has(s.name)) {
        return cache.get(s.name) ?? null
      }
      const value = await s.compute()
      setSystemPromptSectionCacheEntry(s.name, value)
      return value
    }),
  )
}

Several key design decisions:

• Parallel Resolution: Uses Promise.all to execute all section compute functions in parallel. This is especially important for sections requiring I/O operations (e.g., loadMemoryPrompt reading CLAUDE.md files).
• null is Valid: A compute function returning null indicates that the section does not need to be included in the final prompt. null values are also cached, avoiding repeated condition checks on subsequent turns.
• Cache Storage Location: The cache is stored in STATE.systemPromptSectionCache (restored-src/src/bootstrap/state.ts:203), a Map<string, string | null>. Choosing global state over module-level variables allows the /clear and /compact commands to uniformly reset all state.

5.2.3 Cache Lifecycle

Cache clearing is handled by the clearSystemPromptSections function (restored-src/src/constants/systemPromptSections.ts:65-68):

export function clearSystemPromptSections(): void {
  clearSystemPromptSectionState()   // clear the Map
  clearBetaHeaderLatches()          // reset beta header latches
}

This function is called at two points:

1. /clear command -- When the user explicitly clears conversation history, all section caches are invalidated, and the next API call will recompute all sections.
2. /compact command -- When the conversation is compacted, section caches are likewise invalidated. This is because compaction may change context state (e.g., available tool list), and section values computed from old state may no longer be correct.

The accompanying clearBetaHeaderLatches() ensures that a new conversation can re-evaluate AFK, fast-mode, and other beta feature headers, rather than carrying over latch values from the previous turn.

5.3 When to Use DANGEROUS_uncachedSystemPromptSection

The DANGEROUS_ prefix is not decorative -- it marks a real engineering trade-off. Let's look at the only usage in the source code:

DANGEROUS_uncachedSystemPromptSection(
  'mcp_instructions',
  () =>
    isMcpInstructionsDeltaEnabled()
      ? null
      : getMcpInstructionsSection(mcpClients),
  'MCP servers connect/disconnect between turns',
),

Source Reference: restored-src/src/constants/prompts.ts:513-520

MCP servers can connect or disconnect between two turns of a conversation. If the MCP instructions section were memoized, it would compute with only server A connected on turn 1, caching instructions for A; by turn 3, server B might also be connected, but the cache would still return the old value containing only A -- the model would never learn about B's existence.

This is the use case for DANGEROUS_uncachedSystemPromptSection: when a section's content may change within the conversation's lifecycle, and using stale values would cause functional errors.

The reason parameter in the code comment ('MCP servers connect/disconnect between turns') is not just documentation but also a code review constraint -- any PR introducing a new DANGEROUS_ section must explain why cache invalidation is necessary.

It's worth noting that the source code also records a case of "downgrading from DANGEROUS to regular caching." The token_budget section was once a DANGEROUS_uncachedSystemPromptSection that dynamically switched based on getCurrentTurnTokenBudget(), but this broke approximately 20K tokens of cache on every budget switch. The solution was to reword the prompt text so it naturally becomes a no-op when there's no budget, thereby downgrading to a regular systemPromptSection (restored-src/src/constants/prompts.ts:540-550).

5.4 Static vs. Dynamic Boundary: SYSTEM_PROMPT_DYNAMIC_BOUNDARY

5.4.1 Boundary Marker Definition

An explicit dividing line exists within the system prompt, partitioning content into a "static zone" and a "dynamic zone":

export const SYSTEM_PROMPT_DYNAMIC_BOUNDARY =
  '__SYSTEM_PROMPT_DYNAMIC_BOUNDARY__'

Source Reference: restored-src/src/constants/prompts.ts:114-115

This string constant does not appear in the text ultimately sent to the model -- it is an in-band signal that exists only within the system prompt array, for the downstream splitSysPromptPrefix function to identify and process.

5.4.2 Boundary Position and Meaning

In the return array of the getSystemPrompt function, the boundary marker is precisely placed between static and dynamic content (restored-src/src/constants/prompts.ts:560-576):

Return array structure:
[
  getSimpleIntroSection(...)          ─┐
  getSimpleSystemSection()             │ Static zone: identical for all users/sessions
  getSimpleDoingTasksSection()         │ → cacheScope: 'global'
  getActionsSection()                  │
  getUsingYourToolsSection(...)        │
  getSimpleToneAndStyleSection()       │
  getOutputEfficiencySection()        ─┘
  SYSTEM_PROMPT_DYNAMIC_BOUNDARY      ← boundary marker
  session_guidance                    ─┐
  memory (CLAUDE.md)                   │ Dynamic zone: varies by session/user
  env_info_simple                      │ → cacheScope: null (not cached)
  language                             │
  output_style                         │
  mcp_instructions (DANGEROUS)         │
  scratchpad                           │
  ...                                 ─┘
]

Figure 5-2: Static/Dynamic boundary diagram. The boundary marker divides the system prompt array into two zones, each corresponding to a different cache scope.

The key rule: All content before the boundary marker is completely identical across all organizations, all users, and all sessions. This means they can use scope: 'global' for cross-organization caching -- a cache prefix computed by one user's API call can be directly hit by any other user's call.

The boundary marker is only inserted when the first-party API provider has global caching enabled:

...(shouldUseGlobalCacheScope() ? [SYSTEM_PROMPT_DYNAMIC_BOUNDARY] : []),

shouldUseGlobalCacheScope() (restored-src/src/utils/betas.ts:227-231) checks that the API provider is 'firstParty' (i.e., directly using the Anthropic API) and that experimental beta features are not disabled via environment variables. Third-party providers (e.g., access via Foundry) do not use global caching.

5.4.3 Pushing Session Variations Past the Boundary

The source code contains a carefully written comment explaining why getSessionSpecificGuidanceSection exists (restored-src/src/constants/prompts.ts:343-347):

Session-variant guidance that would fragment the cacheScope:'global' prefix if placed before SYSTEM_PROMPT_DYNAMIC_BOUNDARY. Each conditional here is a runtime bit that would otherwise multiply the Blake2b prefix hash variants (2^N).

This reveals a subtle but critical design constraint: the static zone cannot contain any conditional branches that vary by session. If the available tool list, Skill commands, Agent tools, or other runtime information appeared before the boundary, each tool combination would produce a different Blake2b prefix hash, causing the number of global cache variants to grow exponentially (2^N, where N is the number of conditional bits), effectively reducing the hit rate to zero.

Therefore, all content depending on runtime state -- tool guidance (session guidance), memory files, environment information, language preferences -- is placed in the dynamic zone after the boundary, as memoized sections (systemPromptSection) rather than static strings.

5.5 The Three Code Paths of splitSysPromptPrefix

splitSysPromptPrefix (restored-src/src/utils/api.ts:321-435) is the bridge that transforms the logical system prompt array into SystemPromptBlock[] with cache control for the API request. It selects among three different code paths based on runtime conditions.

flowchart TD
    A["splitSysPromptPrefix(systemPrompt, options)"] --> B{"shouldUseGlobalCacheScope()\n&&\nskipGlobalCacheForSystemPrompt?"}
    B -->|"Yes (MCP tools present)"| C["Path 1: MCP Downgrade"]
    B -->|"No"| D{"shouldUseGlobalCacheScope()?"}
    D -->|"Yes"| E{"Boundary marker\nexists?"}
    D -->|"No"| G["Path 3: Default org cache"]
    E -->|"Yes"| F["Path 2: Global cache + boundary"]
    E -->|"No"| G

    C --> C1["attribution → null\nprefix → org\nrest → org"]
    C1 --> C2["Up to 3 blocks\nskip boundary marker"]

    F --> F1["attribution → null\nprefix → null\nstatic → global\ndynamic → null"]
    F1 --> F2["Up to 4 blocks"]

    G --> G1["attribution → null\nprefix → org\nrest → org"]
    G1 --> G2["Up to 3 blocks"]

    style C fill:#f9d,stroke:#333
    style F fill:#9df,stroke:#333
    style G fill:#dfd,stroke:#333

Figure 5-3: splitSysPromptPrefix three-path flowchart. Based on global cache features and MCP tool presence, the function selects different cache strategies.

5.5.1 Path 1: MCP Downgrade Path

Trigger Condition: shouldUseGlobalCacheScope() === true and options.skipGlobalCacheForSystemPrompt === true

When MCP tools are present in the session, the tool schemas themselves are user-level dynamic content that cannot be globally cached. In this case, even though the static zone of the system prompt could be globally cached, the presence of tool schemas greatly diminishes the actual benefit of global caching. Therefore, splitSysPromptPrefix chooses to downgrade to org-level caching.

// Path 1 core logic (restored-src/src/utils/api.ts:332-359)
for (const prompt of systemPrompt) {
  if (!prompt) continue
  if (prompt === SYSTEM_PROMPT_DYNAMIC_BOUNDARY) continue // skip boundary
  if (prompt.startsWith('x-anthropic-billing-header')) {
    attributionHeader = prompt
  } else if (CLI_SYSPROMPT_PREFIXES.has(prompt)) {
    systemPromptPrefix = prompt
  } else {
    rest.push(prompt)
  }
}
// Result: [attribution:null, prefix:org, rest:org]

The boundary marker is skipped directly (continue), and all non-special blocks are merged into a single org-level cache block. The skipGlobalCacheForSystemPrompt value comes from a check in claude.ts (restored-src/src/services/api/claude.ts:1210-1214): the downgrade is triggered only when MCP tools are actually rendered into the request (rather than defer_loading).

5.5.2 Path 2: Global Cache + Boundary Path

Trigger Condition: shouldUseGlobalCacheScope() === true, not downgraded by MCP, and the boundary marker exists in the system prompt

This is the primary path for first-party users without MCP tools, and it offers the highest cache efficiency:

// Path 2 core logic (restored-src/src/utils/api.ts:362-409)
const boundaryIndex = systemPrompt.findIndex(
  s => s === SYSTEM_PROMPT_DYNAMIC_BOUNDARY,
)
if (boundaryIndex !== -1) {
  for (let i = 0; i < systemPrompt.length; i++) {
    const block = systemPrompt[i]
    if (!block || block === SYSTEM_PROMPT_DYNAMIC_BOUNDARY) continue
    if (block.startsWith('x-anthropic-billing-header')) {
      attributionHeader = block
    } else if (CLI_SYSPROMPT_PREFIXES.has(block)) {
      systemPromptPrefix = block
    } else if (i < boundaryIndex) {
      staticBlocks.push(block)        // before boundary → static
    } else {
      dynamicBlocks.push(block)       // after boundary → dynamic
    }
  }
  // Result: [attribution:null, prefix:null, static:global, dynamic:null]
}

This path produces up to 4 text blocks:

The static block using scope: 'global' means the Anthropic API backend can share this cache prefix across all Claude Code users. Given that the static zone typically contains tens of thousands of tokens of identity introduction and behavioral guidelines, the computational savings from this cache under high concurrency are enormous.

5.5.3 Path 3: Default Org Cache Path

Trigger Condition: Global cache feature is not enabled (third-party providers), or the boundary marker does not exist

This is the simplest fallback path:

// Path 3 core logic (restored-src/src/utils/api.ts:411-434)
for (const block of systemPrompt) {
  if (!block) continue
  if (block.startsWith('x-anthropic-billing-header')) {
    attributionHeader = block
  } else if (CLI_SYSPROMPT_PREFIXES.has(block)) {
    systemPromptPrefix = block
  } else {
    rest.push(block)
  }
}
// Result: [attribution:null, prefix:org, rest:org]

All non-special content is merged into a single block using org-level caching. This is sufficient for third-party providers -- users within the same organization share the same system prompt prefix and can still achieve organization-level cache hits.

5.5.4 From splitSysPromptPrefix to API Request

buildSystemPromptBlocks (restored-src/src/services/api/claude.ts:3213-3237) is the direct consumer of splitSysPromptPrefix. It transforms SystemPromptBlock[] into the TextBlockParam[] format expected by the Anthropic API:

export function buildSystemPromptBlocks(
  systemPrompt: SystemPrompt,
  enablePromptCaching: boolean,
  options?: { skipGlobalCacheForSystemPrompt?: boolean; querySource?: QuerySource },
): TextBlockParam[] {
  return splitSysPromptPrefix(systemPrompt, {
    skipGlobalCacheForSystemPrompt: options?.skipGlobalCacheForSystemPrompt,
  }).map(block => ({
    type: 'text' as const,
    text: block.text,
    ...(enablePromptCaching && block.cacheScope !== null && {
      cache_control: getCacheControl({
        scope: block.cacheScope,
        querySource: options?.querySource,
      }),
    }),
  }))
}

The mapping rule is straightforward: blocks with a non-null cacheScope receive a cache_control property; null blocks do not. The API backend uses the value of cache_control.scope ('global' or 'org') to determine the caching sharing scope.

5.6 System Prompt Build Flow

5.6.1 The Complete Flow of getSystemPrompt

getSystemPrompt (restored-src/src/constants/prompts.ts:444-577) is the main entry point for building the system prompt. It accepts a tool list, model name, additional working directories, and MCP client list, returning a string[] array.

flowchart TD
    A["getSystemPrompt(tools, model, dirs, mcpClients)"] --> B{"CLAUDE_CODE_SIMPLE?"}
    B -->|"Yes"| C["Return minimal prompt\n(identity + CWD + date only)"]
    B -->|"No"| D["Parallel computation:\nskillToolCommands\noutputStyleConfig\nenvInfo"]
    D --> E{"Proactive mode?"}
    E -->|"Yes"| F["Return autonomous agent prompt\n(slimmed, no section registry)"]
    E -->|"No"| G["Build dynamic section array\n(systemPromptSection ×N)"]
    G --> H["resolveSystemPromptSections\n(parallel resolution, memoization)"]
    H --> I["Assemble final array"]

    I --> J["Static zone:\nintro, system, tasks,\nactions, tools, tone,\nefficiency"]
    J --> K["BOUNDARY MARKER\n(conditionally inserted)"]
    K --> L["Dynamic zone:\nsession_guidance, memory,\nenv_info, language,\noutput_style, mcp, ..."]
    L --> M["filter(s => s !== null)"]
    M --> N["Return string[]"]

Figure 5-4: System prompt build flowchart. The complete data flow from entry point to final return.

The build process has three fast paths:

1. CLAUDE_CODE_SIMPLE mode: When the CLAUDE_CODE_SIMPLE environment variable is true, it directly returns a minimal prompt containing only identity, working directory, and date. This is primarily for testing and debugging scenarios.
2. Proactive mode: When the PROACTIVE or KAIROS feature flags are enabled and active, it returns a slimmed autonomous agent prompt. Note that this path bypasses the section registry and directly assembles a string array.
3. Standard path: Goes through the full section registration, resolution, and static/dynamic partitioning flow.

5.6.2 Section Registry Overview

The dynamic sections registered in the standard path (restored-src/src/constants/prompts.ts:491-555) constitute all content in the dynamic zone:

The only DANGEROUS_uncachedSystemPromptSection is mcp_instructions -- consistent with the analysis in Section 5.3. All other sections are memoized, computed once within the session lifecycle and unchanged thereafter.

5.7 Priority of buildEffectiveSystemPrompt

getSystemPrompt builds the "default system prompt." But in actual invocations, multiple sources may override or supplement this default. buildEffectiveSystemPrompt (restored-src/src/utils/systemPrompt.ts:41-123) is responsible for synthesizing the final effective prompt by priority.

5.7.1 Priority Chain

Priority 0 (highest): overrideSystemPrompt
  ↓ when absent
Priority 1: coordinator system prompt
  ↓ when absent
Priority 2: agent system prompt
  ↓ when absent
Priority 3: customSystemPrompt (--system-prompt)
  ↓ when absent
Priority 4 (lowest): defaultSystemPrompt (output of getSystemPrompt)

+ appendSystemPrompt is always appended at the end (except for override)

5.7.2 Behavior at Each Priority Level

Override: When overrideSystemPrompt exists (e.g., loop instructions set by Loop mode), it directly returns an array containing only that string, ignoring all other sources, including appendSystemPrompt (restored-src/src/utils/systemPrompt.ts:56-58):

if (overrideSystemPrompt) {
  return asSystemPrompt([overrideSystemPrompt])
}

Coordinator: When the COORDINATOR_MODE feature flag is enabled and the CLAUDE_CODE_COORDINATOR_MODE environment variable is true, the coordinator-specific system prompt replaces the default. Note the lazy import of the coordinatorMode module to avoid circular dependencies (restored-src/src/utils/systemPrompt.ts:62-75).

Agent: When mainThreadAgentDefinition is set, behavior depends on whether Proactive mode is active:

• In Proactive mode: Agent instructions are appended to the end of the default prompt, rather than replacing it. This is because the default prompt in Proactive mode is already a slimmed autonomous agent identity; the Agent definition merely adds domain instructions on top -- consistent with behavior in teammates mode.
• In normal mode: Agent instructions replace the default prompt.

Custom: The prompt specified by the --system-prompt command-line argument replaces the default prompt.

Default: The complete output of getSystemPrompt.

Append: If appendSystemPrompt is set, it is appended to the end of the final array. This provides a mechanism for injecting additional instructions without completely overriding the system prompt.

5.7.3 Final Synthesis Logic

When there is no override or coordinator, the core three-way selection logic is as follows (restored-src/src/utils/systemPrompt.ts:115-122):

return asSystemPrompt([
  ...(agentSystemPrompt
    ? [agentSystemPrompt]
    : customSystemPrompt
      ? [customSystemPrompt]
      : defaultSystemPrompt),
  ...(appendSystemPrompt ? [appendSystemPrompt] : []),
])

This is a clean ternary chain: Agent > Custom > Default, plus an optional append. asSystemPrompt is a branded type conversion ensuring type safety of the return value (see Chapter 8 for discussion on the type system).

5.8 Cache Optimization Contract: Design Constraints and Pitfalls

The system prompt architecture establishes an implicit cache optimization contract. Violating this contract causes cache hit rates to plummet. Here are the key constraints distilled from the source code:

Constraint 1: The Static Zone Must Not Contain Session Variables

As discussed in Section 5.4.3, any conditional branch before the boundary exponentially increases the number of hash variants. PRs #24490 and #24171 documented this type of bug: a developer inadvertently placed an if (hasAgentTool) condition in the static zone, causing the global cache hit rate to plummet from 95% to below 10%.

Constraint 2: DANGEROUS Sections Must Have Sufficient Justification

Every use of DANGEROUS_uncachedSystemPromptSection is scrutinized in code review. The reason parameter, while not used at runtime (note the _ prefix on the parameter name: _reason), serves as an anchor for PR review -- reviewers check whether the justification is sufficient and whether alternatives exist to downgrade to a memoized section.

Constraint 3: MCP Tools Trigger Global Cache Downgrade

When MCP tools are present, splitSysPromptPrefix automatically downgrades to org-level caching. This decision is based on an engineering judgment: MCP tool schemas are user-level dynamic content, and even though the static zone of the system prompt could be globally cached, the presence of tool schema blocks means the API request already contains large blocks that cannot be globally cached. The marginal benefit of global caching for the system prompt is not sufficient to justify the additional complexity.

Constraint 4: The Boundary Marker Position Is an Architectural Invariant

The source code comments are blunt (restored-src/src/constants/prompts.ts:572):

// === BOUNDARY MARKER - DO NOT MOVE OR REMOVE ===

Moving or deleting the boundary marker is not a code change -- it is an architectural change that alters the caching behavior for all first-party users.

5.8 Pattern Extraction

From the system prompt architecture, the following reusable engineering patterns can be extracted:

Pattern 1: Sectioned Memoization

• Problem Solved: In large prompts, some content is static and some is dynamic; recomputing everything wastes resources.
• Solution: Split the prompt into independent sections, each with a clear cache strategy (memoized vs. volatile). Distinguish the two types through factory functions, adding API friction for the volatile type (DANGEROUS_ prefix + mandatory reason).
• Prerequisites: Requires a global state manager holding a cache Map, and well-defined cache invalidation timings (e.g., /clear, /compact).
• Code Template:

  memoizedSection(name, computeFn)        → cached after first computation
  volatileSection(name, computeFn, reason) → recomputed each turn, reason required
  resolveAll(sections)                     → Promise.all parallel resolution
  

Pattern 2: Cache Boundary Partitioning

• Problem Solved: Prompt prefixes shared across multiple users need global caching, but session-specific content destroys cache hit rates.
• Solution: Insert an explicit boundary marker in the prompt array, dividing content into a "globally cacheable static zone" and a "per-session dynamic zone." Downstream functions assign different cacheScope values based on boundary position.
• Prerequisites: The API backend supports multi-level cache scopes (e.g., global / org / null).
• Key Constraint: The static zone before the boundary must not contain any conditional branches that vary by session; otherwise, the number of hash variants grows exponentially.

Pattern 3: Priority Chain Composition

• Problem Solved: Multiple sources (user-customized, Agent mode, coordinator mode, default) may all provide system prompts, requiring clear priorities.
• Solution: Define a linear priority chain (override > coordinator > agent > custom > default), plus an always-appended append mechanism. Use a ternary chain to maintain linear readability.
• Prerequisites: Unified input interfaces for all priority sources (all as string | string[]).

5.9 What Users Can Do

Based on the system prompt architecture analyzed in this chapter, here are recommendations that readers can directly apply in their own AI Agent projects:

1. Build a section registry for your prompts. Don't hardcode the system prompt as a single string. Split it into independent, named sections, each annotated with whether it's cacheable. The benefit is not just cache efficiency but also maintainability -- when you need to modify a behavioral directive, you can precisely locate the corresponding section rather than searching through a massive string.

2. Add API friction for volatile sections. If parts of your prompt content need to be recomputed each turn (e.g., dynamic tool lists, real-time status information), follow the design of DANGEROUS_uncachedSystemPromptSection: require callers to provide a reason for why per-turn recomputation is necessary. This friction is especially valuable in code reviews -- it forces developers to explicitly weigh cache efficiency against content freshness.

3. Push session variables past the cache boundary. If the API you use supports prompt caching, ensure the prefix portion of the prompt (the range over which the cache key is computed) does not contain content that varies by user, session, or runtime state. Claude Code's SYSTEM_PROMPT_DYNAMIC_BOUNDARY marker is a direct implementation of this strategy.

4. Define a clear prompt priority chain. When your system supports multiple operating modes (autonomous Agent, coordinator, user-customized, etc.), define explicit priorities for prompt sources of each mode. Avoid "merging" prompts from different sources -- using "replace" semantics is safer and more predictable.

5. Monitor cache hit rates. The value of the system prompt architecture is fully reflected in cache hit rates. If your cache hit rate suddenly drops, check whether a new conditional branch has been introduced into the static zone -- this is a pitfall the Claude Code team encountered in PR #24490.

5.10 Summary

The system prompt architecture is the "invisible but omnipresent" infrastructure of Claude Code. Its design embodies three core principles:

1. Sectioned Composition: Through the systemPromptSection registry, the prompt is decomposed into independent, memoizable sections, each with a clear name, compute function, and cache strategy.
2. Boundary Partitioning: The SYSTEM_PROMPT_DYNAMIC_BOUNDARY marker divides content into a globally cacheable static zone and a per-session dynamic zone, with splitSysPromptPrefix's three paths selecting the optimal cache strategy based on runtime conditions.
3. Priority Synthesis: buildEffectiveSystemPrompt supports multiple operating modes through a clear five-level priority chain (override > coordinator > agent > custom > default + append), while maintaining linear code readability.

The "success criterion" for this architecture is not functional correctness -- even hardcoding the entire system prompt as a single string would work perfectly fine functionally. Its value lies in cost efficiency: through careful cache tier design, enormous prompt processing overhead is saved across millions of daily API calls. The next chapter will discuss a key input to the system prompt architecture -- how CLAUDE.md memory files are loaded and injected (see Chapter 6).

Chapter 6: Steering Behavior Through Prompts

Chapter 5 dissected the assembly architecture of the system prompt -- section registration, cache boundaries, multi-source synthesis. But architecture is merely the skeleton; what truly makes Claude Code behave "like an experienced engineer" is the muscle attached to that skeleton: carefully worded behavioral directives. This chapter distills 6 reusable behavior steering patterns, each with source code examples, the principles behind their effectiveness, and templates you can directly adopt in your own prompts.

6.1 The Nature of Behavior Steering: Setting Boundaries in the Generation Probability Space

The output of a large language model is a sampling process over a probability distribution. Behavioral directives in the system prompt are essentially fences erected in this probability space -- raising the probability of desired behavior and suppressing undesired behavior. But the wording of those fences determines whether they function as a solid wall or a blurry line.

Reading through Claude Code's system prompt source code (restored-src/src/constants/prompts.ts and restored-src/src/tools/BashTool/prompt.ts), one discovers that Anthropic's engineers did not pile up directives haphazardly but formed an implicit pattern language. These patterns work not just because they "say the right things," but because their wording structure aligns with the model's attention mechanisms and instruction-following characteristics.

This chapter makes these patterns explicit, naming them as 6 behavior steering patterns:

1. Minimalism Directive
2. Progressive Escalation
3. Reversibility Awareness
4. Tool Preference Steering
5. Agent Delegation Protocol
6. Numeric Anchoring

6.2 Pattern 1: Minimalism Directive

6.2.1 Pattern Definition

Core Idea: Constrain the model's "helpfulness" tendency to the actual scope of the task by explicitly prohibiting over-engineering.

Large language models naturally tend to "do a little extra" -- adding additional error handling, supplementing doc comments, introducing abstraction layers. This is a virtue in conversational scenarios but a disaster in code generation. The Minimalism Directive uses specific counter-examples to teach the model that "what not to do" is more important than "what to do."

6.2.2 Source Code Examples

Example 1: Three Lines of Code Over Premature Abstraction

Don't create helpers, utilities, or abstractions for one-time operations.
Don't design for hypothetical future requirements. The right amount of
complexity is what the task actually requires — no speculative abstractions,
but no half-finished implementations either. Three similar lines of code
is better than a premature abstraction.

Source Location: restored-src/src/constants/prompts.ts:203

The last sentence -- "Three similar lines of code is better than a premature abstraction" -- is the most brilliant stroke in the entire Minimalism Directive. It provides a concrete numerical threshold -- three lines -- giving the model a clear benchmark when facing the "should I extract a common function" decision. Without this anchor, the model would default to DRY (Don't Repeat Yourself), and DRY in the context of AI-assisted programming often leads to over-abstraction.

Example 2: Don't Add Features Beyond What Was Asked

Don't add features, refactor code, or make "improvements" beyond what was
asked. A bug fix doesn't need surrounding code cleaned up. A simple feature
doesn't need extra configurability. Don't add docstrings, comments, or type
annotations to code you didn't change. Only add comments where the logic
isn't self-evident.

Source Location: restored-src/src/constants/prompts.ts:201

Note the structure of this directive: first a general principle ("don't add features beyond what was asked"), then three specific counter-examples (a bug fix doesn't need surrounding code cleaned up, a simple feature doesn't need extra configurability, don't add comments to unchanged code). This "general rule + counter-examples" structure is very effective because the model needs to map abstract principles to concrete scenarios when following instructions, and counter-examples provide anchoring points for this mapping.

Example 3: Don't Add Defenses for Impossible Scenarios (ant-only)

Don't add error handling, fallbacks, or validation for scenarios that can't
happen. Trust internal code and framework guarantees. Only validate at system
boundaries (user input, external APIs). Don't use feature flags or
backwards-compatibility shims when you can just change the code.

Source Location: restored-src/src/constants/prompts.ts:202

This directive strikes directly at a common LLM behavioral pattern: overly defensive programming. The model has seen extensive "best practice" articles in its training data that emphasize handling every possible error. But in actual internal code, many error paths will never be triggered. This directive provides a new judgment framework through the phrase "Trust internal code and framework guarantees": distinguish between system boundaries and internal calls.

6.2.3 Why It Works

The Minimalism Directive works because of three mechanisms:

1. Counter-examples are easier to follow than positive rules. "Don't do X" is more precise than "only do Y," because the boundaries of X are clearer than the boundaries of Y. The model can check each generated token against "is this doing X."
2. Specific numbers override default heuristics. A numerical anchor like "three lines of repeated code" overrides the model's built-in DRY heuristic. Without a specific number, the model falls back to the most common pattern in its training data.
3. Scenario classification reduces ambiguity. Directives like "a bug fix doesn't need surrounding code cleaned up" transform the fuzzy question of "when should I do a little extra" into a clear classification task: "is the current task a bug fix or a refactor?"

6.2.4 Reusable Template

[Minimalism Directive Template]

Don't add {features/refactoring/improvements} beyond the task scope.
{Task type A} doesn't need {common over-engineering behavior A}.
{Task type B} doesn't need {common over-engineering behavior B}.
{N} lines of repeated code is better than a premature abstraction.
Only {take extra action} when {clear boundary condition}.

6.3 Pattern 2: Progressive Escalation

6.3.1 Pattern Definition

Core Idea: Define a middle path between "giving up" and "infinite loops," guiding the model to first diagnose, then adjust, and finally ask for help.

LLMs have two extreme tendencies when facing failure: either immediately giving up and asking the user for help, or endlessly retrying the exact same operation. The Progressive Escalation pattern locks the model's failure response into a reasonable range by defining a clear three-stage protocol -- diagnose, adjust, escalate.

6.3.2 Source Code Examples

Example 1: Three-Stage Failure Handling

If an approach fails, diagnose why before switching tactics — read the error,
check your assumptions, try a focused fix. Don't retry the identical action
blindly, but don't abandon a viable approach after a single failure either.
Escalate to the user with ask_user_question only when you're genuinely stuck
after investigation, not as a first response to friction.

Source Location: restored-src/src/constants/prompts.ts:233

This directive defines a complete failure handling protocol in a single paragraph:

• Stage 1 (Diagnose): "read the error, check your assumptions" -- first understand what happened
• Stage 2 (Adjust): "try a focused fix" -- make a targeted modification based on the diagnosis
• Stage 3 (Escalate): "Escalate to the user... only when you're genuinely stuck" -- request help only at genuine dead ends

The key design lies in the tension between two "don'ts": "Don't retry the identical action blindly" (prohibits infinite loops) and "don't abandon a viable approach after a single failure" (prohibits premature giving up). This dual-sided constraint forces the model to find a middle path between the two extremes.

Example 2: Diagnosis-First for Git Operations

Before running destructive operations (e.g., git reset --hard, git push
--force, git checkout --), consider whether there is a safer alternative
that achieves the same goal. Only use destructive operations when they are
truly the best approach.

Source Location: restored-src/src/tools/BashTool/prompt.ts:306

This directive requires a "is there a safer alternative" evaluation before executing high-risk operations. It doesn't simply prohibit these operations but requires the model to complete a reasoning step before making a choice.

Example 3: Diagnostic Alternative to Sleep Commands

Do not retry failing commands in a sleep loop — diagnose the root cause.

Source Location: restored-src/src/tools/BashTool/prompt.ts:318

This is the most minimal form of the Progressive Escalation pattern: a single sentence simultaneously containing a prohibition ("don't retry in a sleep loop") and an alternative ("diagnose the root cause"). It specifically targets a common LLM behavior pattern -- when a command fails, the model may sleep && retry in a loop, which is disastrous in an interactive environment.

6.3.3 Why It Works

The effectiveness of Progressive Escalation comes from:

1. Dual-sided constraints create tension. Simultaneously defining "don't give up too quickly" and "don't retry infinitely" forces the model to perform an explicit reasoning step after each failure: "am I retrying blindly, or making an informed adjustment?"
2. Stage ordering maps to Chain-of-Thought. The diagnose -> adjust -> escalate sequence naturally aligns with the model's chain of thought. The model can directly encode this protocol as steps in its reasoning chain.
3. Escalation as last resort. Setting "ask the user" as the final option reduces unnecessary interaction interruptions and improves autonomous completion rates.

6.3.4 Reusable Template

[Progressive Escalation Template]

When {operation} fails, first {diagnostic action} ({specific diagnostic steps}).
Don't blindly retry the same operation, but don't abandon a viable approach
after a single failure either.
Only {escalate action} when {escalation condition}, not as a first response
to friction.

6.4 Pattern 3: Reversibility Awareness

6.4.1 Pattern Definition

Core Idea: Classify operations by their reversibility and blast radius, establishing a confirmation framework for high-risk operations.

This is the most complex and most carefully designed pattern in Claude Code's prompt engineering. It doesn't simply list "dangerous operations" but establishes a complete risk assessment framework, teaching the model to "measure twice, cut once."

6.4.2 Source Code Examples

Example 1: Reversibility Analysis Framework

Carefully consider the reversibility and blast radius of actions. Generally
you can freely take local, reversible actions like editing files or running
tests. But for actions that are hard to reverse, affect shared systems beyond
your local environment, or could otherwise be risky or destructive, check
with the user before proceeding.

Source Location: restored-src/src/constants/prompts.ts:258

This directive introduces two key dimensions: reversibility and blast radius. These two dimensions form a 2x2 decision matrix:

quadrantChart
    title Reversibility vs. Blast Radius Decision Matrix
    x-axis "Small Blast Radius" --> "Large Blast Radius"
    y-axis "Irreversible (hard to reverse)" --> "Reversible"
    quadrant-1 "Inform then execute"
    quadrant-2 "Execute freely"
    quadrant-3 "Confirm then execute"
    quadrant-4 "Mandatory confirmation"
    "Edit files": [0.25, 0.8]
    "Run tests": [0.3, 0.85]
    "Create temp branch": [0.7, 0.75]
    "Delete local files": [0.25, 0.25]
    "force push": [0.8, 0.15]
    "Close PR/issue": [0.75, 0.2]

Figure 6-1: Reversibility vs. Blast Radius decision matrix. Claude Code classifies operations into four categories using these two dimensions, from "execute freely" to "mandatory confirmation."

Example 2: Exhaustive List of High-Risk Operations

The source code provides four major categories of operations requiring confirmation, each with specific examples (restored-src/src/constants/prompts.ts:261-264):

Example 3: Git Safety Protocol

Git Safety Protocol:
- NEVER update the git config
- NEVER run destructive git commands (push --force, reset --hard, checkout .,
  restore ., clean -f, branch -D) unless the user explicitly requests these
  actions.
- NEVER skip hooks (--no-verify, --no-gpg-sign, etc) unless the user
  explicitly requests it
- NEVER run force push to main/master, warn the user if they request it
- CRITICAL: Always create NEW commits rather than amending, unless the user
  explicitly requests a git amend. When a pre-commit hook fails, the commit
  did NOT happen — so --amend would modify the PREVIOUS commit, which may
  result in destroying work or losing previous changes.

Source Location: restored-src/src/tools/BashTool/prompt.ts:87-94

The Git Safety Protocol is the most refined implementation of the Reversibility Awareness pattern. Note several design points:

1. NEVER in uppercase -- not "avoid" or "try not to," but absolute prohibition. Uppercase letters function similarly to "increasing attention weight" in prompts.
2. "unless the user explicitly requests" -- Each NEVER rule comes with an explicit exemption condition, preventing the model from refusing when the user explicitly asks.
3. CRITICAL marker + causal explanation -- For the most subtle rule about amend vs. new commit, not only is it marked CRITICAL, but it explains why the rule exists (when a hook fails, the commit hasn't happened yet, and amend would modify the previous commit). Causal explanations enable the model to generalize the spirit of the rule to new scenarios, rather than merely following the literal text mechanically.

Example 4: One-Time Authorization Does Not Equal Permanent Authorization

A user approving an action (like a git push) once does NOT mean that they
approve it in all contexts, so unless actions are authorized in advance in
durable instructions like CLAUDE.md files, always confirm first.
Authorization stands for the scope specified, not beyond. Match the scope
of your actions to what was actually requested.

Source Location: restored-src/src/constants/prompts.ts:258

This directive strikes at a dangerous LLM tendency: generalizing from a single permission to universal permission. The model might see in context that the user previously agreed to git push and then execute push without confirmation in subsequent different scenarios. This rule establishes a precise concept of authorization scope through the phrase "scope specified, not beyond."

6.4.3 Why It Works

The effectiveness of Reversibility Awareness comes from:

1. Dimensional analysis replaces enumeration. Rather than listing all dangerous operations (impossible to be exhaustive), it teaches the model to autonomously evaluate using the two dimensions of "reversibility" and "blast radius." The specific example list serves as supplementary calibration, not comprehensive coverage.
2. NEVER + unless creates precise exemptions. The combination of absolute prohibition + explicit exception prevents the model's "creative interpretation" in gray areas.
3. Causal explanations promote generalization. Explaining "why" a rule exists (like the causal chain of amend) enables the model to derive correct behavior in unseen scenarios.
4. "Measure twice, cut once" as a mnemonic. This English idiom at the end serves as a cognitive anchor for the entire framework, helping the model recall the full risk assessment protocol when facing edge cases.

6.4.4 Reusable Template

[Reversibility Awareness Template]

Before executing actions, evaluate their reversibility and blast radius.
You may freely execute {list of reversible local operations}.
For {irreversible/shared system} operations, confirm with the user before executing.

NEVER:
- {Dangerous operation 1}, unless the user explicitly requests
- {Dangerous operation 2}, unless the user explicitly requests
- [CRITICAL] {Most subtle dangerous operation}, because {causal explanation}

A user approving {operation} once does NOT mean approval in all contexts.
Authorization is limited to the scope specified.

6.5 Pattern 4: Tool Preference Steering

6.5.1 Pattern Definition

Core Idea: Redirect the model's tool selection from generic Bash commands to specialized tools through tool description text.

Claude Code provides rich specialized tools (Read, Edit, Write, Glob, Grep), but the model's training data is full of cat, grep, sed, find, and other Unix commands. Without guidance, the model naturally tends to execute these commands through the Bash tool. The Tool Preference Steering pattern inserts redirection instructions at the earliest position in tool descriptions, intercepting the model's default tool selection path.

6.5.2 Source Code Examples

Example 1: Front-loaded Interception in Bash Tool Description

IMPORTANT: Avoid using this tool to run find, grep, cat, head, tail, sed,
awk, or echo commands, unless explicitly instructed or after you have
verified that a dedicated tool cannot accomplish your task. Instead, use the
appropriate dedicated tool as this will provide a much better experience for
the user:

 - File search: Use Glob (NOT find or ls)
 - Content search: Use Grep (NOT grep or rg)
 - Read files: Use Read (NOT cat/head/tail)
 - Edit files: Use Edit (NOT sed/awk)
 - Write files: Use Write (NOT echo >/cat <<EOF)
 - Communication: Output text directly (NOT echo/printf)

Source Location: restored-src/src/tools/BashTool/prompt.ts:280-291 (assembled by getSimplePrompt())

The design of this directive has three layers of sophistication:

1. Positional priority. This text appears at the beginning of the Bash tool description, immediately following the basic functionality explanation. When the model begins considering calling the Bash tool, this redirection directive is the first constraint it encounters.
2. NOT parenthetical comparison. Each mapping rule lists both "what to use" and "what not to use." The format Use Grep (NOT grep or rg) creates a direct binary comparison, reducing the model's decision hesitation.
3. User experience justification. "this will provide a much better experience for the user" provides a reason for following this rule, rather than merely issuing an unconditional command.

Example 2: Redundant Reinforcement in System Prompt

Do NOT use the Bash to run commands when a relevant dedicated tool is
provided. Using dedicated tools allows the user to better understand and
review your work. This is CRITICAL to assisting the user:
  - To read files use Read instead of cat, head, tail, or sed
  - To edit files use Edit instead of sed or awk
  - To create files use Write instead of cat with heredoc or echo redirection
  - To search for files use Glob instead of find or ls
  - To search the content of files, use Grep instead of grep or rg
  - Reserve using the Bash exclusively for system commands and terminal
    operations that require shell execution.

Source Location: restored-src/src/constants/prompts.ts:291-302

Note that this content nearly duplicates the mapping table in the Bash tool description. This is not an oversight but intentional redundant reinforcement. Placing the same directive in both the system prompt and tool description locations ensures that regardless of which path the model's attention takes, it encounters the constraint.

Example 3: Conditional Adaptation for Embedded Tools

const embedded = hasEmbeddedSearchTools()

const toolPreferenceItems = [
  ...(embedded
    ? []
    : [
        `File search: Use ${GLOB_TOOL_NAME} (NOT find or ls)`,
        `Content search: Use ${GREP_TOOL_NAME} (NOT grep or rg)`,
      ]),
  `Read files: Use ${FILE_READ_TOOL_NAME} (NOT cat/head/tail)`,
  // ...
]

Source Location: restored-src/src/tools/BashTool/prompt.ts:280-291

When Ant internal builds (ant-native builds) map find and grep through shell aliases to embedded bfs and ugrep, the redirections to the standalone Glob/Grep tools become unnecessary. The source code skips these two mappings via the hasEmbeddedSearchTools() condition. This conditional adaptation ensures the prompt never contains self-contradictory instructions.

6.5.3 Why It Works

The effectiveness of Tool Preference Steering comes from:

1. Intercepting the decision path at the earliest point. The model reads tool descriptions first when selecting tools. Inserting "don't use me for X, use Y instead" in the Bash tool's description is equivalent to intervening before the model makes its choice.
2. Binary comparison eliminates ambiguity. The format Use Grep (NOT grep or rg) transforms an open-ended choice ("which tool to search with") into a binary judgment ("Grep tool or grep command"), reducing decision complexity.
3. Redundant reinforcement covers attention blind spots. The model's attention decays in long contexts. Placing the same constraint at two different locations increases the probability of the constraint being "seen."

6.5.4 Reusable Template

[Tool Preference Steering Template]

When {operation category} is needed, use {specialized tool name} (NOT {generic alternative commands}).
Using the specialized tool provides {user experience benefit}.

{Generic tool name} should only be used for {explicit list of legitimate uses}.
When unsure, default to the specialized tool and only fall back to {generic tool} when {fallback condition}.

6.6 Pattern 5: Agent Delegation Protocol

6.6.1 Pattern Definition

Core Idea: Define precise delegation rules for multi-agent collaboration, preventing recursive spawning, context pollution, and result fabrication.

When an AI system can spawn sub-agents, new failure modes emerge: agents may recursively spawn themselves infinitely, may peek at sub-agent intermediate output (polluting their own context), or may fabricate results before the sub-agent returns. The Agent Delegation Protocol prevents these failure modes through a set of precise rules.

6.6.2 Source Code Examples

Example 1: Fork vs. Fresh Agent Selection Framework

Fork yourself (omit subagent_type) when the intermediate tool output isn't
worth keeping in your context. The criterion is qualitative — "will I need
this output again" — not task size.
- Research: fork open-ended questions. If research can be broken into
  independent questions, launch parallel forks in one message. A fork beats
  a fresh subagent for this — it inherits context and shares your cache.
- Implementation: prefer to fork implementation work that requires more than
  a couple of edits.

Source Location: restored-src/src/tools/AgentTool/prompt.ts:83-88

This directive establishes the selection criteria between fork (context-inheriting branch) and fresh agent (entirely new agent). The key insight is that the criterion is not task size but "will I need to see this output again later." While this qualitative criterion is somewhat fuzzy, combined with the two concrete scenarios below (research and implementation), it provides sufficient anchoring for the model.

Example 2: "Don't Peek" -- Context Hygiene Rules

Don't peek. The tool result includes an output_file path — do not Read or
tail it unless the user explicitly asks for a progress check. You get a
completion notification; trust it. Reading the transcript mid-flight pulls
the fork's tool noise into your context, which defeats the point of forking.

Source Location: restored-src/src/tools/AgentTool/prompt.ts:91

"Don't peek" may be one of the most creative phrases in all of Claude Code's prompts. It uses two everyday words to precisely describe a complex technical constraint: do not read the sub-agent's intermediate output file. The subsequent explanation gives the reason -- doing so would pull the sub-agent's tool noise into the main agent's context, defeating the purpose of forking (keeping the main context clean).

The engineering problem this rule corresponds to is: the fork sub-agent's results are written to a file that the main agent has the ability to read via the Read tool. If the main agent reads intermediate results before the sub-agent completes, those half-finished tool call outputs would enter the main agent's context window, wasting precious token budget.

Example 3: "Don't Race" -- Result Fabrication Protection

Don't race. After launching, you know nothing about what the fork found.
Never fabricate or predict fork results in any format — not as prose,
summary, or structured output. The notification arrives as a user-role
message in a later turn; it is never something you write yourself. If the
user asks a follow-up before the notification lands, tell them the fork is
still running — give status, not a guess.

Source Location: restored-src/src/tools/AgentTool/prompt.ts:93

"Don't race" prevents a subtle but dangerous failure mode: the main agent, after dispatching a fork, may "predict" the fork's results and generate a reply prematurely. This behavior might appear to the user as "smart anticipation," but it is pure hallucination -- the main agent has absolutely no idea what the fork found.

The design of this directive is particularly strict: it not only prohibits "fabricating results" but explicitly forbids all possible variant forms -- "not as prose, summary, or structured output." This exhaustive format prohibition exists because the model might attempt to circumvent the literal prohibition through different output forms.

Example 4: Fork Sub-Agent Identity Anchoring

STOP. READ THIS FIRST.

You are a forked worker process. You are NOT the main agent.

RULES (non-negotiable):
1. Your system prompt says "default to forking." IGNORE IT — that's for the
   parent. You ARE the fork. Do NOT spawn sub-agents; execute directly.
2. Do NOT converse, ask questions, or suggest next steps
3. Do NOT editorialize or add meta-commentary
...
6. Do NOT emit text between tool calls. Use tools silently, then report
   once at the end.

Source Location: restored-src/src/tools/AgentTool/forkSubagent.ts:172-194

This is the most dramatic fragment in the delegation protocol. The fork sub-agent inherits the parent agent's complete system prompt, which contains the "default to forking" directive. Without intervention, the sub-agent would read this directive and attempt to fork again -- causing infinite recursion.

The solution is to insert an "identity override" directive at the beginning of the fork sub-agent's messages: first seize attention with the all-caps "STOP. READ THIS FIRST.", then explicitly declare "You ARE the fork," and finally directly point out "Your system prompt says 'default to forking.' IGNORE IT." This technique of "acknowledging the existence of contradictory instructions and explicitly overriding them" is far more reliable than simply hoping the model ignores a certain passage.

6.6.3 Why It Works

The effectiveness of the Agent Delegation Protocol comes from:

1. Anthropomorphic verbs establish intuition. "Don't peek" and "Don't race" are easier to remember and follow than "don't read sub-agent output files" and "don't generate results before receiving notifications." Anthropomorphization turns abstract technical constraints into social intuition.
2. Exhaustive format prohibition. "not as prose, summary, or structured output" blocks potential evasion paths the model might take.
3. Explicit contradiction resolution. Acknowledging that the sub-agent will see the parent agent's "fork" directive and then explicitly overriding it is more reliable than assuming the model will correctly handle contradictory instructions.
4. Identity anchoring + output format constraints. The fork sub-agent's "STOP. READ THIS FIRST." combined with strict output format (Scope: / Result: / Key files: / Files changed: / Issues:) confines the sub-agent's behavior to a very narrow channel.

6.6.4 Reusable Template

[Agent Delegation Protocol Template]

## When to fork
Fork yourself when {intermediate output isn't worth keeping in context}.
The criterion is {qualitative criterion}, not {commonly misjudged criterion}.

## Post-fork behavior
- Don't peek: Do not read {sub-agent}'s intermediate output; wait for
  the completion notification.
  Reason: {specific consequences of context pollution}.
- Don't race: Before {sub-agent} returns, do not predict or fabricate its
  results in any form ({format list}).
  If the user asks a follow-up, reply with {status info}, not a guess.

## Fork sub-agent identity
You are a forked worker process, not the main agent.
{Directive in parent prompt that could cause recursion} does not apply to
you -- execute directly, do not delegate further.

6.7 Pattern 6: Numeric Anchoring

6.7.1 Pattern Definition

Core Idea: Replace vague qualitative descriptions with precise numbers, giving the model a directly measurable output ruler.

"Be more concise," "keep it short," "don't be too verbose" -- these qualitative directives have almost no constraining power, because the model's understanding of "concise" depends on distributions in training data that vary by domain and style. Numeric Anchoring converts a subjective judgment into a measurable constraint by providing specific numbers.

6.7.2 Source Code Examples

Example 1: Word Limit Between Tool Calls

Length limits: keep text between tool calls to ≤25 words. Keep final
responses to ≤100 words unless the task requires more detail.

Source Location: restored-src/src/constants/prompts.ts:534

This directive is currently enabled only for Anthropic internal users (ant-only), with the following annotation:

// Numeric length anchors — research shows ~1.2% output token reduction vs
// qualitative "be concise". Ant-only to measure quality impact first.

Source Location: restored-src/src/constants/prompts.ts:527-528

A 1.2% output token reduction may not sound like much, but considering the volume of requests Claude Code processes daily, the absolute value of this percentage in cost savings is considerable. More importantly, this 1.2% was achieved merely by replacing "be concise" with "≤25 words" -- zero code changes, pure prompt optimization.

Note the different designs of the two numeric anchors:

• ≤25 words (between tool calls): This is a hard constraint, because text between tool calls is typically unnecessary -- the model should directly call the next tool rather than explaining to the user what it's doing.
• ≤100 words (final response): This comes with an exemption condition ("unless the task requires more detail"), because final response length genuinely depends on task complexity.

Example 2: Report Length Limit for Fork Sub-Agents

8. Keep your report under 500 words unless the directive specifies otherwise.
   Be factual and concise.

Source Location: restored-src/src/tools/AgentTool/forkSubagent.ts:186

The 500-word limit for fork sub-agents serves a clear engineering goal: the sub-agent's report is injected into the main agent's context, and an overly long report wastes the main agent's context window. 500 words corresponds to roughly 600-700 tokens, a balance point between "providing enough information" and "conserving context space."

Example 3: Commit Message Length Guidance

Draft a concise (1-2 sentences) commit message that focuses on the "why"
rather than the "what"

Source Location: restored-src/src/tools/BashTool/prompt.ts:103

"1-2 sentences" is another form of numeric anchoring -- not word count but sentence count. This anchor combined with the content guidance "focuses on the 'why' rather than the 'what'" simultaneously constrains both length and quality.

6.7.3 Ant-Only Experiment Results

The Numeric Anchoring pattern is one of the few prompt optimizations in Claude Code with explicit quantified effect data:

Table 6-1: Ant-only experiment results for Numeric Anchoring. Currently enabled only for internal users to measure quality impact before expanding deployment.

The gradual rollout strategy of ant-only is itself noteworthy. The conditional check in the source code:

...(process.env.USER_TYPE === 'ant'
  ? [
      systemPromptSection(
        'numeric_length_anchors',
        () => 'Length limits: keep text between tool calls to ≤25 words...',
      ),
    ]
  : []),

This pattern appears repeatedly throughout Claude Code's prompts: new behavioral directives are first opened to internal users, data is collected, and then a decision is made whether to roll out to external users. This is A/B testing methodology in prompt engineering.

6.7.4 Why It Works

The effectiveness of Numeric Anchoring comes from:

1. Eliminates subjective interpretation. "25 words" is unambiguous; "concise" is not. The model can count after generating each token to judge whether it's approaching the threshold.
2. Anchoring Effect. Cognitive psychology research shows that humans are anchored by prior numbers when making quantity estimates. LLM behavior is similar -- numbers appearing in prompts become reference points for output length.
3. Hard constraint + soft exemption combination. "≤25 words" is a hard constraint; "unless the task requires more detail" is a soft exemption. This combination makes the model default to the numeric limit while allowing breakthroughs in reasonable situations.

6.7.5 Reusable Template

[Numeric Anchoring Template]

Length limits:
- {Output type A}: keep to ≤{N} words/sentences/lines.
- {Output type B}: keep to ≤{M} words/sentences/lines, unless {exemption condition}.
Be factual and concise.

6.8 Pattern Summary

The following table summarizes the 6 behavior steering patterns distilled in this chapter, each with a representative source code quote and a directly reusable prompt template:

Table 6-2: Summary of the 6 behavior steering patterns. Each pattern has clear applicable scenarios and a reusable template structure.

6.9 Cross-Pattern Design Principles

Reviewing these 6 patterns, several underlying cross-pattern design principles emerge:

Principle 1: Negative definitions outperform positive descriptions. "Don't do X" is easier for the model to follow than "do Y," because the boundaries of prohibition are clearer than the boundaries of permission. Five of the 6 patterns make extensive use of negation forms like "Don't" / "NEVER" / "NOT."

Principle 2: Concrete examples are calibrators for abstract rules. Every abstract rule ("consider reversibility") is paired with a list of concrete examples ("git reset --hard, push --force..."). Examples are not substitutes for rules but calibration points -- helping the model understand the rule's applicability scope and granularity.

Principle 3: Causal explanations promote generalization. When rules are accompanied by "because..." explanations (like the causal chain of amend vs. new commit), the model can derive the spirit of the rule in unseen scenarios. Purely imperative rules only work within the training distribution; causal explanations allow rules to transcend their literal text.

Principle 4: Redundancy is intentional. Tool Preference Steering places the same mapping table at two locations; Reversibility Awareness defines Git safety rules in both the system prompt and Bash tool description. This redundancy is not negligence but an engineering measure against attention decay.

Principle 5: Gradual rollout is part of prompt engineering. The ant-only experiment of Numeric Anchoring demonstrates that prompt modifications also need A/B testing and gradual rollout -- just like code changes. The USER_TYPE === 'ant' conditional check is the embodiment of this methodology in code.

6.10 What Users Can Do

Based on the 6 behavior steering patterns distilled in this chapter, here are practical recommendations that readers can directly incorporate into their own prompts:

1. Replace "do Y" with "don't do X." Review your existing prompts and transform positive descriptions into negative constraints. "Generate concise code" is less effective than "Don't add features beyond what was asked. A bug fix doesn't need surrounding code cleaned up." Specific counter-examples are easier for the model to follow than abstract positive goals.

2. Define a three-stage protocol for failure scenarios. If your agent needs to handle potentially failing operations (API calls, command execution, file operations), explicitly define a "diagnose -> adjust -> escalate" path in the prompt. Simultaneously prohibit both extremes: blind retrying and giving up after a single failure.

3. Replace adjectives with numbers. Replace "keep it concise" with "≤25 words" or "1-2 sentences." Claude Code's data shows that this single change alone achieved a 1.2% output token reduction. In your own scenarios, set specific quantity limits for each output type.

4. Insert redirection tables in tool descriptions. If your tool set contains a "universal tool" (like Bash), place a "which scenario should use which alternative tool" mapping table at the earliest position in its description. Simultaneously declare exclusivity in specialized tool descriptions. Bidirectional closed loops are far more effective than unidirectional constraints.

5. Build a reversibility evaluation framework for high-risk operations. Don't simply list "dangerous operations" (impossible to be exhaustive); instead, teach the model to autonomously evaluate using the two dimensions of "reversibility" and "blast radius." Combined with the NEVER + unless precise exemption structure, give the model an executable decision framework.

6. Validate in small-scale gradual rollouts first. New behavioral directives should first be opened to a small subset of users or scenarios, with effect data collected before rolling out broadly. Claude Code's USER_TYPE === 'ant' gradual rollout mechanism is a referenceable pattern -- prompt modifications also need A/B testing.

6.11 Summary

This chapter distilled 6 named behavior steering patterns from Claude Code's source code. These patterns are not arbitrary wording choices but experimentally validated engineering practices -- from the "three lines of code" anchor in the Minimalism Directive to the 1.2% token reduction of Numeric Anchoring, each pattern has a clear design intent and measurable effect.

The common characteristic of these patterns is precision: replacing vague adjectives with specific numbers, replacing positive descriptions with counter-examples, replacing unconditional commands with causal explanations. This precision is not coincidental -- it reflects a fundamental truth: the reliability with which a large language model follows instructions is positively correlated with the precision of those instructions.

The next chapter will turn to runtime behavior observation and debugging: when these carefully designed prompts encounter unexpected situations in actual conversations, how the system detects, records, and responds.

Version Evolution: v2.1.91 Changes

The following analysis is based on v2.1.91 bundle signal comparison.

v2.1.91 introduced a new tengu_rate_limit_lever_hint event, suggesting a new rate-limit steering mechanism -- when the model approaches rate limits, the system steers the model's behavior through prompt-level "lever hints" (such as reducing tool call frequency or using lighter operations), rather than simply waiting for rate limits to lift.

Chapter 6b: API Communication Layer — Retry, Streaming, and Degradation Engineering

The services/api/ directory is not an SDK wrapper layer — it is the Agent's Control Plane. Model degradation, cache protection, file transfer, and Prompt Replay debugging all happen at this layer. This chapter focuses on its most critical resilience subsystems: retry, streaming, and degradation. The file transfer channel (Files API) is covered at the end of this chapter, and the Prompt Replay debugging tool is analyzed in Chapter 29.

Why This Matters

The reliability of an Agent system depends not on how intelligent the model is, but on whether it can still function under the worst network conditions. Imagine a developer using Claude Code on a train to handle an urgent bug: WiFi cuts in and out, the API occasionally returns 529 overload errors, and a streaming response abruptly terminates halfway through. Without sufficient resilience design in the communication layer, this developer either sees an inexplicable crash or must manually retry repeatedly, wasting precious context window space.

Claude Code's communication layer solves exactly these kinds of problems. It is not a simple "retry on failure" wrapper, but a multi-layered defense system: exponential backoff prevents avalanche effects, a 529 counter triggers model degradation, dual watchdogs detect stream interruptions, Fast Mode cache-aware retry protects costs, and persistent mode supports unattended scenarios. Together, these mechanisms embody a core engineering philosophy: communication failure is the norm, not the exception, and the system must have a contingency plan at every layer.

What's equally noteworthy is the observability design of this system. Every API call emits three telemetry events — tengu_api_query (request sent), tengu_api_success (successful response), tengu_api_error (failed response) — combined with 25 error classifications and gateway fingerprint detection, making every communication failure traceable and diagnosable. This is a system forged by real production traffic, where every line of code maps to a failure scenario that actually occurred.

Source Code Analysis

Interactive version: Click to view the retry and degradation animation — Timeline animations for 4 scenarios (normal / 429 rate limit / 529 overload / Fast Mode degradation).

6b.1 Retry Strategy: From Exponential Backoff to Model Degradation

Claude Code's retry system is implemented in withRetry.ts. The core is an AsyncGenerator function withRetry() that uses yield during retry waits to pass SystemAPIErrorMessage to the upper layer, allowing the UI to display retry status in real time.

Constants and Configuration

The retry system's behavior is governed by a carefully tuned set of constants:

The 10-retry budget may seem generous, but combined with exponential backoff (500ms -> 1s -> 2s -> 4s -> 8s -> 16s -> 32s x 4), the total wait is approximately 2.5-3 minutes. The actual implementation also adds 0-25% random jitter on each backoff interval (withRetry.ts:542-547), preventing multiple clients from retrying simultaneously and causing a Thundering Herd effect. This is a carefully calibrated design: enough retries to handle brief network hiccups, but not so many that users wait too long when the API is truly unavailable.

Retry Decisions: The shouldRetry Function

The shouldRetry() function is the core decision-maker of the retry system, defined at withRetry.ts:696-787. It receives an APIError and returns a boolean. Analyzing all its return paths reveals three categories:

Never retry:

Always retry:

Conditional retry:

There is a notable design decision here: for ClaudeAI subscribers (Max/Pro), even when the x-should-retry header is true, 429 errors are not retried. The reason is clearly stated in the source comments:

// restored-src/src/services/api/withRetry.ts:735-736
// For Max and Pro users, should-retry is true, but in several hours, so we shouldn't.
// Enterprise users can retry because they typically use PAYG instead of rate limits.

Max/Pro user rate limit windows are on the order of hours — retrying just wastes time, and it's better to inform the user directly. This is a differentiated decision based on understanding user scenarios, rather than a one-size-fits-all retry policy.

The Three-Layer Error Classification Funnel

Claude Code's error handling is not a flat switch-case but a three-layer funnel structure:

classifyAPIError()  — 19+ specific types (for telemetry and diagnostics)
    ↓ mapping
categorizeRetryableAPIError()  — 4 SDK categories (for upper-layer error display)
    ↓ decision
shouldRetry()  — boolean (for the retry loop)

The first layer, classifyAPIError() (errors.ts:965-1161), subdivides errors into 25+ specific types, including aborted, api_timeout, repeated_529, capacity_off_switch, rate_limit, server_overload, prompt_too_long, pdf_too_large, pdf_password_protected, image_too_large, tool_use_mismatch, unexpected_tool_result, duplicate_tool_use_id, invalid_model, credit_balance_low, invalid_api_key, token_revoked, oauth_org_not_allowed, auth_error, bedrock_model_access, server_error, client_error, ssl_cert_error, connection_error, and unknown. These classifications are written directly into the errorType field of the tengu_api_error telemetry event, enabling precise categorization of production issues.

The second layer, categorizeRetryableAPIError() (errors.ts:1163-1182), merges these fine-grained types into 4 SDK-level categories: rate_limit (429 and 529), authentication_failed (401 and 403), server_error (408+), and unknown. This layer provides simplified error display for the upper-layer UI.

The third layer is shouldRetry() itself, making the final boolean decision.

The benefit of this three-layer design is that diagnostic information can be very detailed (25 classifications) while decision logic remains concise (true/false). The two concerns are completely decoupled.

Special Handling of 529 Overload

The 529 error holds a special position in Claude Code's retry system. A 529 means the API backend has insufficient capacity — unlike a 429 (user rate limiting), this is a system-level overload.

First, not all query sources retry on 529. FOREGROUND_529_RETRY_SOURCES (withRetry.ts:62-82) defines an allowlist where only foreground requests (requests the user is actively waiting for) are retried:

// restored-src/src/services/api/withRetry.ts:57-61
// Foreground query sources where the user IS blocking on the result — these
// retry on 529. Everything else (summaries, titles, suggestions, classifiers)
// bails immediately: during a capacity cascade each retry is 3-10× gateway
// amplification, and the user never sees those fail anyway.

This is a system-level load shedding strategy: when the backend is overloaded, background tasks (summary generation, title generation, suggestion generation) immediately give up rather than joining the retry queue. Each retry amplifies load on the overloaded backend by 3-10x — reducing unnecessary retries is key to mitigating cascading failures.

Second, three consecutive 529 errors trigger model degradation. This logic is at withRetry.ts:327-364:

// restored-src/src/services/api/withRetry.ts:327-351
if (is529Error(error) &&
    (process.env.FALLBACK_FOR_ALL_PRIMARY_MODELS ||
     (!isClaudeAISubscriber() && isNonCustomOpusModel(options.model)))
) {
  consecutive529Errors++
  if (consecutive529Errors >= MAX_529_RETRIES) {
    if (options.fallbackModel) {
      logEvent('tengu_api_opus_fallback_triggered', {
        original_model: options.model,
        fallback_model: options.fallbackModel,
        provider: getAPIProviderForStatsig(),
      })
      throw new FallbackTriggeredError(
        options.model,
        options.fallbackModel,
      )
    }
    // ...
  }
}

FallbackTriggeredError (withRetry.ts:160-168) is a dedicated error class. It is not an ordinary exception — it is a control flow signal that, when caught by the upper-layer Agent Loop, triggers a model switch (typically from Opus to Sonnet). Using exceptions for control flow is an anti-pattern in many contexts, but it is justified here: the degradation event needs to propagate through multiple call stack layers to reach the Agent Loop, and exceptions are the most natural upward propagation mechanism.

Equally important is CannotRetryError (withRetry.ts:144-158), which carries retryContext (including the current model, thinking configuration, max_tokens override, etc.), giving the upper layer sufficient context to decide how to handle the failure.

6b.2 Streaming: Dual Watchdogs

Streaming responses are core to the Claude Code user experience — users see text appear gradually rather than waiting through a long blank page. But streaming connections are far more fragile than regular HTTP requests: TCP connections may be silently closed by intermediary proxies, the server may hang during generation, and the SDK's timeout mechanism only covers the initial connection, not the data stream phase.

Claude Code solves this problem in claude.ts with two layers of watchdogs.

Idle Timeout Watchdog (Interrupting)

// restored-src/src/services/api/claude.ts:1877-1878
const STREAM_IDLE_TIMEOUT_MS =
  parseInt(process.env.CLAUDE_STREAM_IDLE_TIMEOUT_MS || '', 10) || 90_000
const STREAM_IDLE_WARNING_MS = STREAM_IDLE_TIMEOUT_MS / 2

The Idle watchdog follows a classic two-phase alert pattern:

1. Warning phase (45 seconds): If no streaming events (chunks) are received for 45 seconds, a warning log and diagnostic event cli_streaming_idle_warning are recorded. The stream may just be slow at this point — it's not necessarily dead.
2. Timeout phase (90 seconds): If 90 seconds pass with no events at all, the stream is declared dead. It sets streamIdleAborted = true, records a performance.now() snapshot (for measuring abort propagation delay later), sends a tengu_streaming_idle_timeout telemetry event, then calls releaseStreamResources() to forcibly terminate the stream.

Each time a new streaming event arrives, resetStreamIdleTimer() resets both timers. This ensures that as long as the stream is alive — even if slow — the watchdog won't kill it prematurely.

// restored-src/src/services/api/claude.ts:1895-1928
function resetStreamIdleTimer(): void {
  clearStreamIdleTimers()
  if (!streamWatchdogEnabled) { return }
  streamIdleWarningTimer = setTimeout(/* warning */, STREAM_IDLE_WARNING_MS)
  streamIdleTimer = setTimeout(() => {
    streamIdleAborted = true
    streamWatchdogFiredAt = performance.now()
    // ... logging and telemetry
    releaseStreamResources()
  }, STREAM_IDLE_TIMEOUT_MS)
}

Note that the watchdog must be explicitly enabled via the CLAUDE_ENABLE_STREAM_WATCHDOG environment variable. This indicates the feature is still in a gradual rollout phase — validated first with internal and limited users before being extended to all users.

Stall Detection (Logging Only)

// restored-src/src/services/api/claude.ts:1936
const STALL_THRESHOLD_MS = 30_000 // 30 seconds

Stall detection addresses a different problem than the Idle watchdog:

• Idle = "no events received at all" (the connection may already be dead)
• Stall = "events are received, but the gap between them is too large" (the connection is alive, but the server is slow)

Stall detection only logs — it does not interrupt. When the interval between two streaming events exceeds 30 seconds, it increments stallCount and totalStallTime, and sends a tengu_streaming_stall telemetry event:

// restored-src/src/services/api/claude.ts:1944-1965
if (lastEventTime !== null) {
  const timeSinceLastEvent = now - lastEventTime
  if (timeSinceLastEvent > STALL_THRESHOLD_MS) {
    stallCount++
    totalStallTime += timeSinceLastEvent
    logForDebugging(
      `Streaming stall detected: ${(timeSinceLastEvent / 1000).toFixed(1)}s gap between events (stall #${stallCount})`,
      { level: 'warn' },
    )
    logEvent('tengu_streaming_stall', { /* ... */ })
  }
}
lastEventTime = now

A key detail: lastEventTime is only set after the first chunk arrives, avoiding misidentification of TTFB (Time to First Token) as a stall. TTFB can legitimately be high (the model is thinking), but once output begins, subsequent event intervals should be stable.

The collaboration between the two watchdog layers can be illustrated as follows:

graph TD
    A[Stream Connection Established] --> B{Event Received?}
    B -->|Yes| C[resetStreamIdleTimer]
    C --> D{Gap Since Last Event > 30s?}
    D -->|Yes| E[Log Stall<br/>No Interruption]
    D -->|No| F[Process Event Normally]
    E --> F
    B -->|No, Waiting| G{Waited 45s?}
    G -->|Yes| H[Log Idle Warning]
    H --> I{Waited 90s?}
    I -->|Yes| J[Terminate Stream<br/>Trigger Fallback]
    I -->|No| B
    G -->|No| B

Non-Streaming Fallback

When a streaming connection is interrupted by the watchdog or fails for other reasons, Claude Code falls back to non-streaming request mode. This logic is at claude.ts:2464-2569.

Two key pieces of information are recorded during fallback:

1. fallback_cause: 'watchdog' (watchdog timeout) or 'other' (other error), used to distinguish the trigger cause.
2. initialConsecutive529Errors: If the streaming failure itself was a 529 error, the count is passed to the non-streaming retry loop. This ensures that the 529 count is not reset during the streaming-to-non-streaming switch:

// restored-src/src/services/api/claude.ts:2559
initialConsecutive529Errors: is529Error(streamingError) ? 1 : 0,

Non-streaming fallback has its own timeout configuration:

// restored-src/src/services/api/claude.ts:807-811
function getNonstreamingFallbackTimeoutMs(): number {
  const override = parseInt(process.env.API_TIMEOUT_MS || '', 10)
  if (override) return override
  return isEnvTruthy(process.env.CLAUDE_CODE_REMOTE) ? 120_000 : 300_000
}

CCR (Claude Code Remote) environments default to 2 minutes, while local environments default to 5 minutes. CCR's shorter timeout is because remote containers have a ~5-minute idle reclamation mechanism — a 5-minute hang would cause the container to receive SIGKILL, so it's better to timeout gracefully at 2 minutes.

Worth noting is that non-streaming fallback can be disabled via the Feature Flag tengu_disable_streaming_to_non_streaming_fallback or the environment variable CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK. The reason is clearly explained in the source comments:

// restored-src/src/services/api/claude.ts:2464-2468
// When the flag is enabled, skip the non-streaming fallback and let the
// error propagate to withRetry. The mid-stream fallback causes double tool
// execution when streaming tool execution is active: the partial stream
// starts a tool, then the non-streaming retry produces the same tool_use
// and runs it again. See inc-4258.

This fix was born from a real production incident (inc-4258): when a tool has already started executing during streaming, and then the system falls back to non-streaming retry, the same tool gets executed twice. This "partial completion + full retry = duplicate execution" pattern is a classic pitfall of all streaming systems.

6b.3 Fast Mode Cache-Aware Retry

Fast Mode is Claude Code's acceleration mode (see Chapter 21 for details), which uses a separate model name to achieve higher throughput. The retry strategy under Fast Mode has a unique consideration: Prompt Cache.

When Fast Mode encounters a 429 (rate limit) or 529 (overload), the core of the retry decision lies in the wait time indicated by the Retry-After header (withRetry.ts:267-305):

// restored-src/src/services/api/withRetry.ts:284-304
const retryAfterMs = getRetryAfterMs(error)
if (retryAfterMs !== null && retryAfterMs < SHORT_RETRY_THRESHOLD_MS) {
  // Short retry-after: wait and retry with fast mode still active
  // to preserve prompt cache (same model name on retry).
  await sleep(retryAfterMs, options.signal, { abortError })
  continue
}
// Long or unknown retry-after: enter cooldown (switches to standard
// speed model), with a minimum floor to avoid flip-flopping.
const cooldownMs = Math.max(
  retryAfterMs ?? DEFAULT_FAST_MODE_FALLBACK_HOLD_MS,
  MIN_COOLDOWN_MS,
)
const cooldownReason: CooldownReason = is529Error(error)
  ? 'overloaded'
  : 'rate_limit'
triggerFastModeCooldown(Date.now() + cooldownMs, cooldownReason)

The cost tradeoff behind this design is:

The cooldown floor is 10 minutes (MIN_COOLDOWN_MS), with a default of 30 minutes (DEFAULT_FAST_MODE_FALLBACK_HOLD_MS). The floor's purpose is to prevent Fast Mode from flip-flopping at the rate limit boundary, which would create an unstable user experience.

Additionally, if the 429 is because overage usage is not available — i.e., the user's subscription does not support overage — Fast Mode is permanently disabled rather than temporarily cooled down:

// restored-src/src/services/api/withRetry.ts:275-281
const overageReason = error.headers?.get(
  'anthropic-ratelimit-unified-overage-disabled-reason',
)
if (overageReason !== null && overageReason !== undefined) {
  handleFastModeOverageRejection(overageReason)
  retryContext.fastMode = false
  continue
}

6b.4 Persistent Retry Mode

Setting the environment variable CLAUDE_CODE_UNATTENDED_RETRY=1 activates Claude Code's persistent retry mode. This mode is designed for unattended scenarios (CI/CD, batch processing, internal Anthropic automation), and its core behavior is: infinite retry on 429/529.

Three key design aspects of persistent mode:

1. Infinite Loop + Independent Counter

In normal mode, attempt grows from 1 to maxRetries + 1 before the loop terminates. Persistent mode achieves an infinite loop by clamping the attempt value at the end of the loop:

// restored-src/src/services/api/withRetry.ts:505-506
// Clamp so the for-loop never terminates. Backoff uses the separate
// persistentAttempt counter which keeps growing to the 5-min cap.
if (attempt >= maxRetries) attempt = maxRetries

persistentAttempt is an independent counter that only increments in persistent mode, used to calculate backoff delay. It is not bounded by maxRetries, so the backoff time continues growing until reaching the 5-minute cap.

2. Window-Level Rate Limit Awareness

For 429 errors, persistent mode checks the anthropic-ratelimit-unified-reset header for the reset timestamp. If the server indicates "resets in 5 hours," the system waits directly until the reset time rather than mindlessly polling every 5 minutes:

// restored-src/src/services/api/withRetry.ts:436-447
if (persistent && error instanceof APIError && error.status === 429) {
  persistentAttempt++
  const resetDelay = getRateLimitResetDelayMs(error)
  delayMs =
    resetDelay ??
    Math.min(
      getRetryDelay(persistentAttempt, retryAfter, PERSISTENT_MAX_BACKOFF_MS),
      PERSISTENT_RESET_CAP_MS,
    )
}

3. Heartbeat Keepalive

This is the most clever design in persistent mode. When backoff times are long (e.g., 5 minutes), the system doesn't perform a single sleep(300000). Instead, it slices the wait into multiple 30-second segments, yielding a SystemAPIErrorMessage after each segment:

// restored-src/src/services/api/withRetry.ts:489-503
let remaining = delayMs
while (remaining > 0) {
  if (options.signal?.aborted) throw new APIUserAbortError()
  if (error instanceof APIError) {
    yield createSystemAPIErrorMessage(
      error,
      remaining,
      reportedAttempt,
      maxRetries,
    )
  }
  const chunk = Math.min(remaining, HEARTBEAT_INTERVAL_MS)
  await sleep(chunk, options.signal, { abortError })
  remaining -= chunk
}

The heartbeat mechanism solves two problems:

• Container idle reclamation: Remote environments like CCR will identify long-running processes with no output as idle and reclaim them. The 30-second yield produces activity on stdout, preventing false termination.
• User interrupt responsiveness: By checking signal.aborted between each 30-second segment, users can interrupt long waits at any time. With a single sleep(300s), pressing Ctrl-C would require waiting until the sleep completes before taking effect.

A TODO comment in the source reveals the stopgap nature of this design:

// restored-src/src/services/api/withRetry.ts:94-95
// TODO(ANT-344): the keep-alive via SystemAPIErrorMessage yields is a stopgap
// until there's a dedicated keep-alive channel.

6b.5 API Observability

Claude Code's API observability system is implemented in logging.ts, built around three telemetry events:

The Three-Event Model

These three events form a complete request funnel: query -> success/error. By correlating on requestId, the complete lifecycle of a request from dispatch to completion can be traced.

TTFB and Cache Hits

The most critical performance metric in the success event is ttftMs (Time to First Token) — the time from request dispatch to the arrival of the first streaming chunk. This metric directly reflects:

• Network latency (round-trip time from client to API endpoint)
• Queue delay (time the request spends queued on the API backend)
• Model first-token generation time (related to prompt length and model size)

Cache-related fields (cachedInputTokens and uncachedInputTokens, i.e., cache_creation_input_tokens) allow the team to monitor Prompt Cache hit rates, which directly impact cost and TTFB.

Gateway Fingerprint Detection

An easily overlooked feature in logging.ts is gateway detection (detectGateway(), logging.ts:107-139). It identifies whether a request has passed through a third-party AI gateway by examining response header prefixes:

Once a gateway is detected, the gateway field is included in success and error events. This allows the Anthropic team to diagnose "specific error patterns in certain gateway environments" — for example, if the 404 error rate is abnormally high through a LiteLLM proxy, it may be a proxy configuration issue rather than an API issue.

Diagnostic Value of Error Classification

The errorType in error events uses classifyAPIError()'s 25 classifications. Compared to simple HTTP status codes, these classifications provide more precise diagnostic information:

Pattern Extraction

Pattern 1: Finite Retry Budget + Independent Degradation Threshold

• Problem solved: Infinite retries cause user waiting and cost runaway; simultaneously, different error types require different patience thresholds
• Core approach: Set a global retry budget (10 attempts) while establishing an independent sub-budget for specific errors (529 overload, 3 attempts). Exhausting the sub-budget triggers degradation rather than abandonment. The two counters run independently without interfering with each other
• Prerequisites: Must have a clear degradation plan (fallback model); degradation itself should not consume the main budget
• Source reference: restored-src/src/services/api/withRetry.ts:52-54 — DEFAULT_MAX_RETRIES=10, MAX_529_RETRIES=3

Pattern 2: Dual Watchdog (Logging + Interrupting)

• Problem solved: Streaming connections can die silently — TCP keepalive cannot cover application-layer silent hangs
• Core approach: Set up two layers of detection. Stall detection (30 seconds) only logs and emits telemetry when event intervals are too large, without interfering with the stream — because slow doesn't mean dead. The Idle watchdog (90 seconds) terminates the connection and triggers fallback when there are no events at all — because a stream with 90 seconds of inactivity is almost certainly dead
• Prerequisites: Must have a non-streaming fallback path; watchdog thresholds must be configurable (different network environments need different thresholds)
• Source reference: restored-src/src/services/api/claude.ts:1936 — Stall detection, restored-src/src/services/api/claude.ts:1877 — Idle watchdog

Pattern 3: Cache-Aware Retry Decision

• Problem solved: Retries may cause Prompt Cache invalidation, and cache invalidation means higher token costs and longer TTFB
• Core approach: Make differentiated decisions based on expected wait time. Short wait (<20 seconds) -> preserve cache and wait in place, because the cache won't expire within 20 seconds; long wait (>=20 seconds) -> abandon cache and switch modes, because the time cost of waiting exceeds the cost of rebuilding the cache
• Prerequisites: API must provide a Retry-After header; must have an alternative mode to switch to
• Source reference: restored-src/src/services/api/withRetry.ts:284-304

Pattern 4: Heartbeat Keepalive

• Problem solved: During long sleeps, the process produces no output and may be deemed idle by the host environment and reclaimed
• Core approach: Slice a single long sleep into N 30-second segments, yielding a message after each segment to keep the stream active. Also check the interrupt signal between each segment, ensuring users can cancel at any time
• Prerequisites: The caller must be an AsyncGenerator or similar coroutine structure capable of producing intermediate results during the wait
• Source reference: restored-src/src/services/api/withRetry.ts:489-503

6b.5 File Transfer Channel: Files API

The services/api/ directory also contains an often-overlooked subsystem — filesApi.ts, which implements file upload/download functionality with the Anthropic Public Files API. This is not a simple HTTP client but a file transfer channel serving three distinct scenarios:

The design of FilesApiConfig reveals an important constraint — file operations require an OAuth session token (not an API key), because files are bound to sessions:

// restored-src/src/services/api/filesApi.ts:60-67
export type FilesApiConfig = {
  /** OAuth token for authentication (from session JWT) */
  oauthToken: string
  /** Base URL for the API (default: https://api.anthropic.com) */
  baseUrl?: string
  /** Session ID for creating session-specific directories */
  sessionId: string
}

The file size limit is 500MB (MAX_FILE_SIZE_BYTES, line 82). Downloads use independent retry logic (3 attempts with exponential backoff, base 500ms), rather than reusing withRetry.ts's generic retry — because the failure modes of file downloads (oversized files, insufficient disk space) differ from those of API calls (429/529 overload), requiring an independent retry budget.

The beta header files-api-2025-04-14,oauth-2025-04-20 (line 27) indicates this is a still-evolving API — oauth-2025-04-20 enables Bearer OAuth authentication on public API paths.

What You Can Do

1. Understand the relationship between 529 and model degradation. After 3 consecutive 529 overload errors, Claude Code automatically degrades to the fallback model (typically from Opus to Sonnet). If you notice a sudden drop in response quality, it may be because the model was degraded — check for tengu_api_opus_fallback_triggered events in the terminal output. This is not a bug; the system is protecting availability.

2. Leverage Fast Mode's cache window. Brief 429 errors under Fast Mode (Retry-After < 20 seconds) won't cause cache invalidation — Claude Code waits in place to preserve the cache. But waits exceeding 20 seconds trigger at least a 10-minute cooldown period, during which it switches to standard speed. If you frequently see Fast Mode cooldowns, you may need to reduce your request frequency.

3. Persistent retry mode (v2.1.88, Anthropic internal builds only). CLAUDE_CODE_UNATTENDED_RETRY=1 enables infinite retry (with exponential backoff, capped at 5 minutes), supporting waiting until the rate limit resets based on the anthropic-ratelimit-unified-reset header. If you're building your own Agent, this "heartbeat keepalive + rate limit-aware waiting" pattern is worth adopting.

4. TTFB is the most critical latency metric. In --verbose mode, Claude Code reports the TTFB (Time to First Token) for each API call. If this value is abnormally high (>5 seconds), it may indicate API-side overload or network issues. Also watch the cachedInputTokens field — if it's consistently 0, your Prompt Cache isn't hitting, and you're paying full price for every request (see Chapter 13 for details).

5. Customize the streaming timeout threshold. If your network environment has high latency (e.g., accessing the API through a VPN or satellite link), the default 90-second Idle Timeout may be too aggressive. You can adjust the timeout threshold by setting the CLAUDE_STREAM_IDLE_TIMEOUT_MS environment variable (also requires CLAUDE_ENABLE_STREAM_WATCHDOG=1).

6. Adjust the retry budget via CLAUDE_CODE_MAX_RETRIES. The default 10 retries suit most scenarios, but if your API provider frequently returns transient errors, you can increase it; if you want faster failure feedback, you can reduce it to 3-5.

Version Evolution: v2.1.100 — Bedrock/Vertex Setup Wizard and Model Upgrade

The following analysis is based on v2.1.100 bundle signal comparison, combined with v2.1.88 source code inference.

Interactive Cloud Platform Setup Wizard

v2.1.100 introduces complete interactive setup wizards for AWS Bedrock and Google Vertex AI, replacing the manual environment variable configuration required in v2.1.88. Using Bedrock as an example (Vertex flow is symmetric), the complete setup lifecycle is covered by 3 events:

tengu_bedrock_setup_started → tengu_bedrock_setup_complete / tengu_bedrock_setup_cancelled
tengu_vertex_setup_started → tengu_vertex_setup_complete / tengu_vertex_setup_cancelled

The setup wizard launches from a unified platform selection menu — users can choose Bedrock, Vertex, or Microsoft Foundry (oauth_platform_docs_opened opens the corresponding documentation page). Upon completion, the authentication method (auth_method) is recorded in telemetry.

Automatic Model Upgrade Detection

The most interesting addition in v2.1.100 is automatic model upgrade detection. When Anthropic releases new model versions, the system automatically detects whether the user's current configuration can be upgraded:

Detection flow:
  upgrade_check (check for available upgrades)
    → probe_result (probe whether new model is accessible in user's Bedrock/Vertex account)
      → upgrade_accepted / upgrade_declined (user decision)
        → upgrade_relaunch (restart after upgrade) / upgrade_save_failed (save failure)

The probing logic extracted from the bundle reveals an elegant design:

// v2.1.100 bundle reverse engineering — Bedrock upgrade probing
// 1. Check unpinned model tiers
d("tengu_bedrock_default_check", { unpinned_tiers: String(q.length) });

// 2. For each unpinned tier, probe whether new model is accessible
let w = await Za8(O, Y.tier);  // Za8 = probeBedrockModel
d("tengu_bedrock_probe_result", {
  tier: Y.tier,
  model_id: O,
  accessible: String(w)
});

Key design decisions:

• Only checks "unpinned" model tiers — if the user explicitly pinned a model ID via environment variables, the system won't suggest upgrades
• Declined upgrades are persisted in user settings via bedrockDeclinedUpgrades / vertexDeclinedUpgrades, preventing repeated prompting
• When the default model is inaccessible, default_fallback triggers — automatically switching to an alternative model in the same tier

Mantle Authentication Backend

v2.1.100 introduces mantle as the fifth API authentication backend (alongside firstParty, bedrock, vertex, and foundry). Enabled via the CLAUDE_CODE_USE_MANTLE environment variable, skippable with CLAUDE_CODE_SKIP_MANTLE_AUTH. Mantle uses anthropic.-prefixed model IDs (e.g., anthropic.claude-haiku-4-5), suggesting this is an Anthropic-hosted enterprise authentication channel, distinct from direct API calls.

API Retry Enhancement

The new tengu_api_retry_after_too_long event indicates v2.1.100 adds special handling for excessive Retry-After header values — when the API returns a retry wait time exceeding a reasonable threshold, the system may choose to abandon waiting and report an error immediately, preventing users from experiencing prolonged unresponsiveness.

Chapter 7: Model-Specific Tuning and A/B Testing

Chapter 6 explored how the system prompt is assembled into the instruction set sent to the model. But the same prompt does not suit all models -- each model generation has unique behavioral tendencies, and Anthropic's internal users need to test and validate new models earlier than external users. This chapter reveals how Claude Code achieves model-specific prompt tuning, internal A/B testing, and safe public repository contributions through the @[MODEL LAUNCH] annotation system, USER_TYPE === 'ant' gating, GrowthBook Feature Flags, and Undercover mode.

7.1 Model Launch Checklist: @[MODEL LAUNCH] Annotations

Throughout Claude Code's codebase, a special comment marker is scattered:

// @[MODEL LAUNCH]: Update the latest frontier model.
const FRONTIER_MODEL_NAME = 'Claude Opus 4.6'

Source Reference: constants/prompts.ts:117-118

These @[MODEL LAUNCH] annotations are not ordinary comments. They form a distributed checklist -- when a new model is ready for release, engineers simply search globally for @[MODEL LAUNCH] in the codebase to find all locations that need updating. This design embeds release process knowledge into the code itself, rather than relying on external documentation.

In prompts.ts, @[MODEL LAUNCH] marks the following key update points:

In antModels.ts:

The elegance of this pattern lies in its self-documenting nature: the annotation text itself serves as the operation instruction. For example, the annotation at line 204 explicitly states the lift condition: "remove or soften once the model stops over-commenting by default." Engineers don't need to consult an external operations manual -- both the condition and the action are written right beside the code.

7.2 Capybara v8 Behavior Mitigations

Each model generation has its unique "personality flaws." Claude Code's source code documents four known issues with Capybara v8 (one of the internal codenames for the Claude 4.5/4.6 series), along with prompt-level mitigations for each.

7.2.1 Over-Commenting

Problem: Capybara v8 tends to add excessive unnecessary comments to code.

Mitigation (lines 204-209):

// @[MODEL LAUNCH]: Update comment writing for Capybara —
// remove or soften once the model stops over-commenting by default
...(process.env.USER_TYPE === 'ant'
  ? [
      `Default to writing no comments. Only add one when the WHY is
       non-obvious...`,
      `Don't explain WHAT the code does, since well-named identifiers
       already do that...`,
      `Don't remove existing comments unless you're removing the code
       they describe...`,
    ]
  : []),

Source Reference: constants/prompts.ts:204-209

These directives form a refined commenting philosophy: default to writing no comments, only add them when the "why" is non-obvious; don't explain what the code does (identifiers already do that); don't remove existing comments you don't understand. Note the subtlety of the third directive -- it both prevents the model from over-commenting and prevents over-correction by deleting valuable existing comments.

7.2.2 False Claims

Problem: Capybara v8's False Claims rate (FC rate) is 29-30%, significantly higher than v4's 16.7%.

Mitigation (lines 237-241):

// @[MODEL LAUNCH]: False-claims mitigation for Capybara v8
// (29-30% FC rate vs v4's 16.7%)
...(process.env.USER_TYPE === 'ant'
  ? [
      `Report outcomes faithfully: if tests fail, say so with the
       relevant output; if you did not run a verification step, say
       that rather than implying it succeeded. Never claim "all tests
       pass" when output shows failures...`,
    ]
  : []),

Source Reference: constants/prompts.ts:237-241

The design of this mitigation directive embodies symmetrical thinking: it not only requires the model not to falsely report success, but explicitly requires it not to be excessively self-doubting -- "when a check did pass or a task is complete, state it plainly -- do not hedge confirmed results with unnecessary disclaimers." The engineers discovered that simply telling the model "don't lie" causes it to swing to the other extreme, adding unnecessary disclaimers to all results. The mitigation target is accurate reporting, not defensive reporting.

7.2.3 Over-Assertiveness

Problem: Capybara v8 tends to simply execute user instructions without offering its own judgment.

Mitigation (lines 224-228):

// @[MODEL LAUNCH]: capy v8 assertiveness counterweight (PR #24302)
// — un-gate once validated on external via A/B
...(process.env.USER_TYPE === 'ant'
  ? [
      `If you notice the user's request is based on a misconception,
       or spot a bug adjacent to what they asked about, say so.
       You're a collaborator, not just an executor...`,
    ]
  : []),

Source Reference: constants/prompts.ts:224-228

The annotation's "PR #24302" indicates this mitigation was introduced through the code review process, and "un-gate once validated on external via A/B" reveals the complete release strategy: first validate on internal users (ant), then roll out to external users through A/B testing after collecting data.

7.2.4 Lack of Thoroughness

Problem: Capybara v8 tends to claim task completion without verifying results.

Mitigation (lines 210-211):

// @[MODEL LAUNCH]: capy v8 thoroughness counterweight (PR #24302)
// — un-gate once validated on external via A/B
`Before reporting a task complete, verify it actually works: run the
 test, execute the script, check the output. Minimum complexity means
 no gold-plating, not skipping the finish line.`,

Source Reference: constants/prompts.ts:210-211

The last sentence of this directive is particularly subtle: "If you can't verify (no test exists, can't run the code), say so explicitly rather than claiming success." It acknowledges that there are situations where verification isn't possible, but requires the model to explicitly acknowledge this rather than silently pretending everything is fine.

7.2.5 Mitigation Lifecycle

The four mitigations share a unified lifecycle pattern:

flowchart LR
    A["Discover behavioral issue\n(FC rate, etc.)"] --> B["PR introduces mitigation\n(PR #24302)"]
    B --> C["ant-only gating\ninternal validation"]
    C --> D["A/B test validation\nexternal rollout"]
    D --> E{"New model launch\n@[MODEL LAUNCH]\nre-evaluate"}
    E -->|"Issue fixed"| F["Remove mitigation"]
    E -->|"Issue persists"| G["Keep/adjust"]
    E -->|"Lift ant-only"| H["Full rollout"]

    style A fill:#f9d,stroke:#333
    style D fill:#9df,stroke:#333
    style F fill:#dfd,stroke:#333
    style H fill:#dfd,stroke:#333

Figure 7-1: Complete lifecycle of model mitigations. From issue discovery to mitigation introduction, through internal validation and A/B testing, culminating in re-evaluation at the next @[MODEL LAUNCH].

7.3 USER_TYPE === 'ant' Gating: The Internal A/B Testing Staging Area

All four mitigations above are wrapped in the same condition:

process.env.USER_TYPE === 'ant'

This environment variable is not read at runtime -- it is a build-time constant. The source code comments explain this critical compiler contract:

DCE: `process.env.USER_TYPE === 'ant'` is build-time --define.
It MUST be inlined at each callsite (not hoisted to a const) so the
bundler can constant-fold it to `false` in external builds and
eliminate the branch.

Source Reference: constants/prompts.ts:617-619

This comment reveals an elegant Dead Code Elimination (DCE) mechanism:

1. Build-time replacement: The bundler's --define option replaces process.env.USER_TYPE with a string literal at compile time.
2. Constant folding: For external builds, 'external' === 'ant' is folded to false.
3. Branch elimination: Branches with condition false are entirely removed, including all their string content.
4. Inline requirement: Each callsite must directly write process.env.USER_TYPE === 'ant'; it cannot be extracted into a variable, or the bundler cannot perform constant folding.

This means ant-only code physically does not exist in external user build artifacts. This is not a runtime permission check but compile-time code elimination. Even decompiling the external build wouldn't reveal internal codenames like Capybara or the specific wording of mitigations.

7.3.1 Complete ant-only Gating Inventory

The following table lists all content in prompts.ts gated by USER_TYPE === 'ant':

Table 7-1: Complete ant-only gating inventory in prompts.ts. Each gate has a clear lift condition, forming a progressive release pipeline from internal validation to external rollout.

getAntModelOverrideSection (lines 136-139) deserves special attention:

function getAntModelOverrideSection(): string | null {
  if (process.env.USER_TYPE !== 'ant') return null
  if (isUndercover()) return null
  return getAntModelOverrideConfig()?.defaultSystemPromptSuffix || null
}

It has dual gating -- not only must the user be internal, but they must also not be in Undercover mode. This design ensures that even internal users don't leak internal model configurations when contributing to public repositories.

7.4 Undercover Mode: Stealth in Public Repositories

Undercover mode is one of Claude Code's most unique features. It solves a very specific problem: when Anthropic internal engineers use Claude Code to contribute to public/open-source repositories, no internal information should be leaked.

7.4.1 Activation Logic

export function isUndercover(): boolean {
  if (process.env.USER_TYPE === 'ant') {
    if (isEnvTruthy(process.env.CLAUDE_CODE_UNDERCOVER)) return true
    return getRepoClassCached() !== 'internal'
  }
  return false
}

Source Reference: utils/undercover.ts:28-37

The activation rules have three levels:

1. Forced on: Setting the CLAUDE_CODE_UNDERCOVER=1 environment variable forces activation even in internal repositories.
2. Auto-detection: If the current repository's remote address is not in the internal whitelist, it activates automatically. 'external', 'none', and null (check hasn't run yet) all resolve to "on."
3. Cannot be forced off: By design, there is no option to force it off. The source code comment explains: "This guards against model codename leaks -- if we're not confident we're in an internal repo, we stay undercover."

This "safe default is on" design philosophy is worth deep reflection -- better to unnecessarily hide information in internal repositories than risk leaking in public ones.

7.4.2 Suppression Scope

When Undercover mode is activated, the following suppression operations are executed:

┌─────────────────────────────────────────────────────────────────────┐
│                     Undercover Mode Workflow                         │
│                                                                     │
│  ┌─────────────────┐                                                │
│  │  isUndercover()  │──── false ────▶ Normal mode (show model info)  │
│  │    returns true  │                                                │
│  └────────┬────────┘                                                │
│           │ true                                                     │
│           ▼                                                          │
│  ┌─────────────────────────────────────────────────────────────────┐ │
│  │                    Suppression Layer 1: System Prompt            │ │
│  │                                                                 │ │
│  │  computeEnvInfo (L621):                                         │ │
│  │    modelDescription = ''  ← model name/ID fully cleared         │ │
│  │                                                                 │ │
│  │  computeSimpleEnvInfo (L660):                                   │ │
│  │    modelDescription = null  ← removed from env info             │ │
│  │                                                                 │ │
│  │  Model family list (L694-696):                                  │ │
│  │    null  ← Opus/Sonnet/Haiku ID list not shown                  │ │
│  │                                                                 │ │
│  │  Claude Code platform info (L697-699):                          │ │
│  │    null  ← CLI/desktop/Web/IDE info not shown                   │ │
│  │                                                                 │ │
│  │  Fast mode explanation (L700-702):                              │ │
│  │    null  ← explanation about using same model not shown         │ │
│  │                                                                 │ │
│  │  getAntModelOverrideSection (L138):                             │ │
│  │    return null  ← ant model override suffix not injected        │ │
│  └─────────────────────────────────────────────────────────────────┘ │
│           │                                                          │
│           ▼                                                          │
│  ┌─────────────────────────────────────────────────────────────────┐ │
│  │                    Suppression Layer 2: Attribution              │ │
│  │                                                                 │ │
│  │  getAttributionTexts():                                         │ │
│  │    return { commit: '', pr: '' }                                │ │
│  │    ← no Co-Authored-By line generated                           │ │
│  │    ← no AI tool attribution in PR descriptions                  │ │
│  └─────────────────────────────────────────────────────────────────┘ │
│           │                                                          │
│           ▼                                                          │
│  ┌─────────────────────────────────────────────────────────────────┐ │
│  │                    Suppression Layer 3: Behavioral Directives    │ │
│  │                                                                 │ │
│  │  getUndercoverInstructions():                                   │ │
│  │    Injects detailed anti-leak directives:                       │ │
│  │    - Prohibit internal model codenames (Capybara, Tengu, etc.)  │ │
│  │    - Prohibit unreleased model version numbers                  │ │
│  │    - Prohibit internal repo/project names                       │ │
│  │    - Prohibit internal tools, Slack channels, short links       │ │
│  │    - Prohibit "Claude Code" text or AI identity hints           │ │
│  │    - Prohibit Co-Authored-By attribution                        │ │
│  │    - Require commit messages written like a human developer     │ │
│  └─────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘

Figure 7-2: Undercover mode's three-layer suppression workflow. From system prompt to attribution to behavioral directives, forming a complete information leak defense.

The source code comment (lines 612-615) explains why the suppression scope is so broad:

Undercover: keep ALL model names/IDs out of the system prompt so
nothing internal can leak into public commits/PRs. This includes the
public FRONTIER_MODEL_* constants — if those ever point at an
unannounced model, we don't want them in context. Go fully dark.

"Go fully dark" -- even public constants (like FRONTIER_MODEL_NAME) are suppressed, because if these constants point to a not-yet-announced model, they themselves become leak sources.

7.4.3 Undercover Instruction Examples

The getUndercoverInstructions() function (utils/undercover.ts:39-69) injects a detailed anti-leak directive. It teaches the model using both positive and negative examples:

Good commit messages:

• "Fix race condition in file watcher initialization"
• "Add support for custom key bindings"

Must never write:

• "Fix bug found while testing with Claude Capybara"
• "1-shotted by claude-opus-4-6"
• "Generated with Claude Code"

This side-by-side positive/negative example teaching approach is more effective than a simple prohibition list -- it not only tells the model "what not to do" but also demonstrates "what to do."

7.4.4 Auto-Notification Mechanism

When Undercover mode is first auto-activated, Claude Code displays a one-time explanatory dialog (shouldShowUndercoverAutoNotice, lines 80-88). The check logic ensures users aren't repeatedly bothered: users who forced it on (via environment variable) won't see the notification (they already know), and users who've already seen the notification won't see it again. This flag is stored in the global config's hasSeenUndercoverAutoNotice field.

7.5 GrowthBook Integration: The tengu_* Feature Flag System

7.5.1 Architecture Overview

Claude Code uses GrowthBook as its Feature Flag and experimentation platform. All Feature Flags follow the tengu_* naming convention -- "tengu" is Claude Code's internal codename.

GrowthBook client initialization and feature value retrieval follow a carefully designed multi-layer fallback mechanism:

Priority (high to low):
  1. Environment variable override (CLAUDE_INTERNAL_FC_OVERRIDES) — ant-only
  2. Local config override (/config Gates panel)                  — ant-only
  3. In-memory remote evaluation values (remoteEvalFeatureValues)
  4. Disk cache (cachedGrowthBookFeatures)
  5. Default value (defaultValue parameter)

The core value retrieval function is getFeatureValue_CACHED_MAY_BE_STALE (growthbook.ts:734-775). As its name states, the value returned by this function may be stale -- it reads from memory or disk cache first, never blocking to wait for a network request. This is an intentional design decision: on the startup critical path, a stale but available value is better than a UI frozen waiting for the network.

export function getFeatureValue_CACHED_MAY_BE_STALE<T>(
  feature: string,
  defaultValue: T,
): T {
  // 1. Environment variable override
  const overrides = getEnvOverrides()
  if (overrides && feature in overrides) return overrides[feature] as T
  // 2. Local config override
  const configOverrides = getConfigOverrides()
  if (configOverrides && feature in configOverrides)
    return configOverrides[feature] as T
  // 3. In-memory remote evaluation value
  if (remoteEvalFeatureValues.has(feature))
    return remoteEvalFeatureValues.get(feature) as T
  // 4. Disk cache
  const cached = getGlobalConfig().cachedGrowthBookFeatures?.[feature]
  return cached !== undefined ? (cached as T) : defaultValue
}

Source Reference: services/analytics/growthbook.ts:734-775

7.5.2 Remote Evaluation and Local Cache Sync

GrowthBook uses remoteEval: true mode -- feature values are pre-evaluated server-side, and the client only needs to cache results. The processRemoteEvalPayload function (growthbook.ts:327-394) runs on each initialization and periodic refresh, writing server-returned pre-evaluated values to two stores:

1. In-memory Map (remoteEvalFeatureValues): For fast reads during process lifetime.
2. Disk cache (syncRemoteEvalToDisk, lines 407-417): For cross-process persistence.

The disk cache uses a full replacement rather than merge strategy -- features deleted server-side are cleared from disk. This ensures the disk cache is always a complete snapshot of server state, not an ever-accumulating historical sediment.

The source code comment (lines 322-325) records a past failure:

Without this running on refresh, remoteEvalFeatureValues freezes at
its init-time snapshot and getDynamicConfig_BLOCKS_ON_INIT returns
stale values for the entire process lifetime — which broke the
tengu_max_version_config kill switch for long-running sessions.

This kill switch failure illustrates why periodic refresh is critical -- if values are only read once at initialization, long-running sessions cannot respond to urgent remote configuration changes.

7.5.3 Experiment Exposure Tracking

GrowthBook's A/B testing functionality depends on experiment exposure tracking. The logExposureForFeature function (lines 296-314) records exposure events when feature values are accessed, for subsequent experiment analysis. Key designs:

• Session-level deduplication: The loggedExposures Set ensures each feature is recorded at most once per session, preventing duplicate events from frequent calls in hot paths (like render loops).
• Deferred exposure: If a feature is accessed before GrowthBook initialization completes, the pendingExposures Set stores these accesses, recording them retroactively once initialization is done.

7.5.4 Known tengu_* Feature Flags

The following tengu_* Feature Flags can be identified from the codebase:

Note that some Flags use obfuscated names (e.g., tengu_frond_boric). This is a security consideration -- even if the Flag name is externally observed, its purpose cannot be deduced.

7.5.5 Environment Variable Override: The Eval Harness Backdoor

The CLAUDE_INTERNAL_FC_OVERRIDES environment variable (growthbook.ts:161-192) allows overriding any Feature Flag value without connecting to the GrowthBook server. This mechanism is specifically designed for the eval harness -- automated tests need to run under deterministic conditions and cannot depend on the state of remote services.

// Example: CLAUDE_INTERNAL_FC_OVERRIDES='{"my_feature": true}'

Override priority is highest (above disk cache and remote evaluation values), and it's only available in ant builds. This ensures eval harness determinism while not affecting external users.

7.6 tengu_ant_model_override: Model Hot-Switching

tengu_ant_model_override is the most complex of all tengu_* Flags. It configures the complete list of ant-only models via GrowthBook remote configuration, supporting runtime hot-switching without releasing a new version.

7.6.1 Configuration Structure

export type AntModelOverrideConfig = {
  defaultModel?: string               // Default model ID
  defaultModelEffortLevel?: EffortLevel // Default effort level
  defaultSystemPromptSuffix?: string   // Suffix appended to system prompt
  antModels?: AntModel[]              // Available model list
  switchCallout?: AntModelSwitchCalloutConfig // Switch callout configuration
}

Source Reference: utils/model/antModels.ts:24-30

Each AntModel includes alias (for command-line selection), model ID, display label, default effort level, context window size, and other parameters. switchCallout allows displaying model switch suggestions to the user in the UI.

7.6.2 Resolution Flow

resolveAntModel (antModels.ts:51-64) resolves user-input model names to specific AntModel configurations:

export function resolveAntModel(
  model: string | undefined,
): AntModel | undefined {
  if (process.env.USER_TYPE !== 'ant') return undefined
  if (model === undefined) return undefined
  const lower = model.toLowerCase()
  return getAntModels().find(
    m => m.alias === model || lower.includes(m.model.toLowerCase()),
  )
}

The matching logic supports both exact alias matching and fuzzy model ID inclusion matching. For example, if the user specifies --model capybara-fast, alias matching finds the corresponding AntModel; if they specify --model claude-opus-4-6-capybara, the model ID inclusion matching also resolves correctly.

7.6.3 Cold Cache Startup Problem

A comment in main.tsx (lines 2001-2014) documents a tricky startup ordering issue: ant model aliases are resolved through the tengu_ant_model_override Feature Flag, and _CACHED_MAY_BE_STALE can only read the disk cache before GrowthBook initialization completes. If the disk cache is empty (cold cache), resolveAntModel returns undefined, causing the model alias to fail resolution.

The solution is to synchronously wait for GrowthBook initialization to complete when detecting that an ant user specified an explicit model and the disk cache is empty:

if ('external' === 'ant' && explicitModel && ...) {
  await initializeGrowthBook()
}

This is one of the very few scenarios in the entire codebase where a GrowthBook call needs to block and wait.

7.7 Knowledge Cutoff Date Mapping

The getKnowledgeCutoff function (prompts.ts:712-730) maintains a mapping from model IDs to knowledge cutoff dates:

function getKnowledgeCutoff(modelId: string): string | null {
  const canonical = getCanonicalName(modelId)
  if (canonical.includes('claude-sonnet-4-6'))      return 'August 2025'
  else if (canonical.includes('claude-opus-4-6'))    return 'May 2025'
  else if (canonical.includes('claude-opus-4-5'))    return 'May 2025'
  else if (canonical.includes('claude-haiku-4'))     return 'February 2025'
  else if (canonical.includes('claude-opus-4') ||
           canonical.includes('claude-sonnet-4'))    return 'January 2025'
  return null
}

Source Reference: constants/prompts.ts:712-730

This function uses includes rather than exact matching, making it robust against model ID suffixes (like date tags -20251001). The cutoff date is injected into the environment information section of the system prompt (lines 635-638), letting the model know its knowledge boundaries:

const knowledgeCutoffMessage = cutoff
  ? `\n\nAssistant knowledge cutoff is ${cutoff}.`
  : ''

When Undercover mode is active, the model-specific portions of the entire environment information section (including knowledge cutoff date) are suppressed -- but the knowledge cutoff date itself is still retained, as it doesn't leak internal information.

7.8 Engineering Insights

The Three-Stage Progressive Release Pipeline

Claude Code's model tuning reveals a clear three-stage release pipeline:

1. Discovery and introduction: Behavioral issues are discovered through model evaluation (e.g., 29-30% FC rate), and mitigations are introduced through PRs.
2. Internal validation: Restricted to internal users through USER_TYPE === 'ant' gating, collecting real usage data.
3. Progressive rollout: After validating effects through GrowthBook A/B testing, ant-only gating is lifted and rolled out to all users.

Compile-Time Safety Over Runtime Checks

The USER_TYPE build-time replacement + Dead Code Elimination mechanism ensures that internal code physically does not exist in external builds, not merely "inaccessible." This compile-time safety is stronger than runtime permission checks -- no code means no attack surface.

The Philosophy of Safe Defaults

Undercover mode's "cannot be forced off" design, the DANGEROUS_ prefix's API friction, and the "block and wait on cold cache" startup logic all embody the same philosophy: when security and convenience conflict, choose security. This isn't paranoia -- it's a reasonable tradeoff between "leaking internal model information" and "waiting a few hundred milliseconds."

Feature Flags as Control Plane

The tengu_* Feature Flag system transforms Claude Code from a single software product into a remotely controllable platform. Through GrowthBook, engineers can, without releasing a new version: switch the default model, adjust event sampling rates, enable/disable experimental features, and even urgently shut down problematic features through kill switches. This "control plane / data plane separation" architecture is a hallmark of SaaS product maturity.

7.9 What Users Can Do

Based on this chapter's analysis of model-specific tuning and the A/B testing system, here are recommendations readers can apply in their own AI Agent projects:

1. Embed distributed checklists in your code. If your system needs to update multiple locations during model upgrades (model name, knowledge cutoff date, behavior mitigations, etc.), adopt @[MODEL LAUNCH]-style annotation markers. Write the update action and lift condition directly in the annotation text, letting the checklist coexist with the code rather than relying on external documentation.

2. Maintain a behavior mitigation archive for each model generation. When you discover a new model's behavioral tendency (e.g., over-commenting, false claims), correct it through prompt-level mitigations rather than code logic. Document each mitigation's introduction reason, quantified metrics like FC rate, and lift conditions. This archive is invaluable reference for the next model upgrade.

3. Use build-time constants instead of runtime checks to protect internal code. If your product distinguishes between internal and external versions, don't rely on runtime if checks to hide internal functionality. Reference Claude Code's USER_TYPE + bundler --define + Dead Code Elimination (DCE) mechanism to ensure internal code physically doesn't exist in external builds.

4. Establish a Feature Flag system for remote control of prompts. Gate experimental content in prompts (new behavioral directives, numeric anchors, etc.) through Feature Flags rather than hardcoding. This lets you adjust model behavior without releasing a new version, run A/B tests, and roll back changes through kill switches in emergencies.

5. Default to safe, not convenient. When choosing between security and convenience, reference Undercover mode's design: security mode on by default, cannot be forced off, better to false-positive than to miss. For AI Agents, the cost of information leakage far exceeds the cost of occasional extra restrictions.

Chapter 8: Tool Prompts as Micro-Harnesses

Chapter 5 dissected the macro architecture of the system prompt -- section registration, cache layering, dynamic assembly. But the system prompt is only the "top-level strategy." At the micro level of each tool call, a parallel harness system operates: tool prompts (tool description / tool prompt). They are injected as the description field in the API request's tools array, directly shaping how the model uses each tool. This chapter dissects the prompt design of Claude Code's six core tools one by one, revealing the steering strategies and reusable patterns within.

8.1 The Harness Nature of Tool Prompts

A tool's description field in the Anthropic API is positioned as "telling the model what this tool does." But Claude Code extends this field from a simple functional description into a complete behavioral constraint protocol. Each tool's prompt is effectively a micro-harness, containing:

• Functional description: What the tool does
• Positive guidance: How it should be used
• Negative prohibitions: How it must not be used
• Conditional branches: What to do in specific scenarios
• Format templates: What the output should look like

The core insight behind this design is: the behavioral quality of the model with each tool is directly constrained by that tool's prompt quality. The system prompt sets the global persona; tool prompts shape local behavior. Together they form Claude Code's "dual-layer harness architecture."

Let's analyze the six tools in order of decreasing functional complexity.

8.2 BashTool: The Most Complex Micro-Harness

BashTool is the tool with the longest prompt and densest constraints in Claude Code. Its prompt is dynamically generated by the getSimplePrompt() function, potentially reaching thousands of words.

Source Location: tools/BashTool/prompt.ts:275-369

8.2.1 Tool Preference Matrix: Routing Traffic to Specialized Tools

The first part of the prompt establishes an explicit tool preference matrix:

IMPORTANT: Avoid using this tool to run find, grep, cat, head, tail,
sed, awk, or echo commands, unless explicitly instructed or after you
have verified that a dedicated tool cannot accomplish your task.

Immediately followed by a mapping table (lines 281-291):

const toolPreferenceItems = [
  `File search: Use ${GLOB_TOOL_NAME} (NOT find or ls)`,
  `Content search: Use ${GREP_TOOL_NAME} (NOT grep or rg)`,
  `Read files: Use ${FILE_READ_TOOL_NAME} (NOT cat/head/tail)`,
  `Edit files: Use ${FILE_EDIT_TOOL_NAME} (NOT sed/awk)`,
  `Write files: Use ${FILE_WRITE_TOOL_NAME} (NOT echo >/cat <<EOF)`,
  'Communication: Output text directly (NOT echo/printf)',
]

This design embodies an important harness pattern: traffic steering. Bash is a "universal tool" -- theoretically capable of performing all file reading/writing, searching, and editing operations. But having the model perform these operations through Bash causes two problems:

1. Poor user experience: Specialized tools (like FileEditTool) have structured input, visual diffs, permission checks, and other capabilities; Bash commands are opaque strings.
2. Permission control bypass: Specialized tools have fine-grained permission verification; Bash commands bypass these checks.

Note the conditional branch at lines 276-278: when the system detects embedded search tools (hasEmbeddedSearchTools()), find and grep are removed from the prohibited list. This adapts for Anthropic's internal builds (ant-native builds), which alias find/grep to embedded bfs/ugrep while removing the standalone Glob/Grep tools.

Reusable Pattern -- "Universal Tool Demotion": When your tool set contains a tool with extremely broad functional coverage, explicitly list "which scenarios should use which alternative tools" in its prompt, preventing the model from over-relying on a single tool.

8.2.2 Command Execution Guidelines: From Timeouts to Concurrency

The second part of the prompt is a detailed command execution specification (lines 331-352), covering:

• Directory verification: "If your command will create new directories or files, first use this tool to run ls to verify the parent directory exists"
• Path quoting: "Always quote file paths that contain spaces with double quotes"
• Working directory persistence: "Try to maintain your current working directory throughout the session by using absolute paths"
• Timeout control: Default 120,000ms (2 minutes), maximum 600,000ms (10 minutes)
• Background execution: run_in_background parameter, with explicit usage conditions

The most sophisticated is the multi-command concurrency guide (lines 297-303):

const multipleCommandsSubitems = [
  `If the commands are independent and can run in parallel, make multiple
   ${BASH_TOOL_NAME} tool calls in a single message.`,
  `If the commands depend on each other and must run sequentially, use
   a single ${BASH_TOOL_NAME} call with '&&' to chain them together.`,
  "Use ';' only when you need to run commands sequentially but don't
   care if earlier commands fail.",
  'DO NOT use newlines to separate commands.',
]

This is not simple "best practice advice" but a concurrency decision tree: independent tasks use parallel tool calls -> dependencies use && -> tolerate failure use ; -> prohibit newlines. Each rule corresponds to a specific failure mode.

8.2.3 Git Safety Protocol: Defense in Depth

Git operations are the most important security domain in BashTool's prompt. The complete Git Safety Protocol is defined in the getCommitAndPRInstructions() function (lines 42-161), with its core prohibition list (lines 88-95) forming a six-layer defense:

Git Safety Protocol:
- NEVER update the git config
- NEVER run destructive git commands (push --force, reset --hard,
  checkout ., restore ., clean -f, branch -D) unless the user
  explicitly requests these actions
- NEVER skip hooks (--no-verify, --no-gpg-sign, etc) unless the
  user explicitly requests it
- NEVER run force push to main/master, warn the user if they request it
- CRITICAL: Always create NEW commits rather than amending
- When staging files, prefer adding specific files by name rather
  than using "git add -A" or "git add ."
- NEVER commit changes unless the user explicitly asks you to

Each prohibition corresponds to a real data loss scenario:

The "CRITICAL" marker is reserved for the most subtle scenario: the --amend trap after pre-commit hook failure. This rule requires understanding Git's internal mechanics -- hook failure means the commit didn't happen, and at that point --amend would modify the previous existing commit, not "retry the current commit."

The prompt also includes a complete commit workflow template (lines 96-125), using numbered steps to explicitly specify which operations can run in parallel and which must be sequential, even providing a HEREDOC-format commit message template. This is a workflow scaffolding pattern -- not telling the model "what to do," but telling it "in what order to do it."

8.2.4 Sandbox Configuration as Inline JSON

When the sandbox is enabled, the getSimpleSandboxSection() function (lines 172-273) inlines the complete sandbox configuration as JSON into the prompt:

const filesystemConfig = {
  read: {
    denyOnly: dedup(fsReadConfig.denyOnly),
    allowWithinDeny: dedup(fsReadConfig.allowWithinDeny),
  },
  write: {
    allowOnly: normalizeAllowOnly(fsWriteConfig.allowOnly),
    denyWithinAllow: dedup(fsWriteConfig.denyWithinAllow),
  },
}

Source Reference: tools/BashTool/prompt.ts:195-203

This is a design decision worth deep reflection: exposing machine-readable security policies directly to the model. The model needs to "understand" which paths it can access and which network hosts it can connect to, so it can proactively avoid violations when generating commands. JSON format guarantees precision and unambiguity.

Note the dedup function at lines 167-170 and normalizeAllowOnly at lines 188-191: the former removes duplicate paths (because SandboxManager doesn't deduplicate when merging multi-layer configs), the latter replaces user-specific temporary directory paths with $TMPDIR placeholders. These two optimizations respectively save ~150-200 tokens and ensure cross-user prompt cache consistency.

Reusable Pattern -- "Policy Transparency": When security policies require model cooperation to enforce, inline the complete rule set in a structured format (JSON/YAML) into the prompt, letting the model self-check compliance during generation.

8.2.5 Sleep Anti-Pattern Suppression

The prompt dedicates a section (lines 310-327) to suppressing sleep abuse:

const sleepSubitems = [
  'Do not sleep between commands that can run immediately — just run them.',
  'If your command is long running... use `run_in_background`.',
  'Do not retry failing commands in a sleep loop — diagnose the root cause.',
  'If waiting for a background task... do not poll.',
  'If you must sleep, keep the duration short (1-5 seconds)...',
]

This is a typical anti-pattern suppression strategy. LLMs tend to use sleep + polling to handle asynchronous waits in code generation scenarios, because this is the most common pattern in training data. The prompt "overwrites" this default behavior by enumerating alternatives one by one (background execution, event notification, root cause diagnosis).

8.3 FileEditTool: The "Must Read Before Edit" Enforcement

FileEditTool's prompt is much more concise than BashTool's, but every sentence carries critical engineering constraints.

Source Location: tools/FileEditTool/prompt.ts:1-28

8.3.1 Pre-Read Enforcement

The first rule of the prompt (lines 4-6):

function getPreReadInstruction(): string {
  return `You must use your \`${FILE_READ_TOOL_NAME}\` tool at least once
  in the conversation before editing. This tool will error if you
  attempt an edit without reading the file.`
}

This is not a "suggestion" but a hard constraint -- the tool's runtime implementation checks the conversation history for a Read call on the file, returning an error if none exists. The prompt's explanation lets the model know in advance about this constraint, avoiding wasting a tool call.

This design solves a core problem: model hallucination. If the model attempts to edit a file without reading it first, its assumptions about file content may be completely wrong. Forcing a prior read ensures edit operations are based on the actual file state, not the model's "memory" or "guess."

Reusable Pattern -- "Precondition Enforcement": When tool B's correctness depends on tool A being called first, declare this dependency in B's prompt and enforce it in B's runtime. Double insurance -- the prompt layer prevents wasted calls, the runtime layer backstops against incorrect operations.

8.3.2 Minimal Unique old_string

The prompt's requirements for the old_string parameter (lines 20-27) embody a delicate balance:

- The edit will FAIL if `old_string` is not unique in the file. Either
  provide a larger string with more surrounding context to make it unique
  or use `replace_all` to change every instance of `old_string`.

For Anthropic internal users (USER_TYPE === 'ant'), there's an additional optimization hint (lines 17-19):

const minimalUniquenessHint =
  process.env.USER_TYPE === 'ant'
    ? `Use the smallest old_string that's clearly unique — usually 2-4
       adjacent lines is sufficient. Avoid including 10+ lines of context
       when less uniquely identifies the target.`
    : ''

This reveals a token economics issue: when using FileEditTool, the model needs to provide the original text to replace in the old_string parameter. If the model habitually includes large blocks of context to "ensure uniqueness," the token consumption of each edit operation skyrockets. The "2-4 lines" guidance helps the model find the sweet spot between uniqueness and brevity.

8.3.3 Indentation Preservation and Line Number Prefix

The most easily overlooked but most critical technical detail in the prompt (lines 13-16, line 23):

const prefixFormat = isCompactLinePrefixEnabled()
  ? 'line number + tab'
  : 'spaces + line number + arrow'

// In the description:
`When editing text from Read tool output, ensure you preserve the exact
indentation (tabs/spaces) as it appears AFTER the line number prefix.
The line number prefix format is: ${prefixFormat}. Everything after that
is the actual file content to match. Never include any part of the line
number prefix in the old_string or new_string.`

Read tool output comes with line number prefixes (like 42 →), and the model needs to strip this prefix during editing, extracting only actual file content as old_string. This is the interface contract between the Read tool and the Edit tool -- the prompt serves as "interface documentation."

Reusable Pattern -- "Inter-Tool Interface Declaration": When two tools' output/input have a format transformation relationship, explicitly describe the upstream tool's output format in the downstream tool's prompt, preventing format conversion errors by the model.

8.4 FileReadTool: Resource-Aware Reading Strategy

FileReadTool's prompt appears simple but contains carefully designed resource management strategies.

Source Location: tools/FileReadTool/prompt.ts:1-49

8.4.1 The 2000-Line Default Limit

export const MAX_LINES_TO_READ = 2000

// In the prompt template:
`By default, it reads up to ${MAX_LINES_TO_READ} lines starting from
the beginning of the file`

Source Reference: tools/FileReadTool/prompt.ts:10,37

2000 lines is a carefully balanced number. Anthropic's model has a 200K token context window, but the larger the context, the more attention disperses and the higher the reasoning cost. 2000 lines corresponds to roughly 8000-16000 tokens (depending on code density), occupying 4-8% of the context window. This budget is sufficient to cover the vast majority of single-file scenarios while leaving room for multi-file operations.

8.4.2 Progressive Guidance for offset/limit

The prompt provides two wording modes for the offset/limit parameters (lines 17-21):

export const OFFSET_INSTRUCTION_DEFAULT =
  "You can optionally specify a line offset and limit (especially handy
   for long files), but it's recommended to read the whole file by not
   providing these parameters"

export const OFFSET_INSTRUCTION_TARGETED =
  'When you already know which part of the file you need, only read
   that part. This can be important for larger files.'

The two modes serve different usage stages:

• DEFAULT mode encourages full reading -- suitable for when the model first encounters a file and needs global understanding.
• TARGETED mode encourages precise reading -- suitable for when the model already knows the target location, saving token budget.

Which mode is used depends on runtime context (decided by the FileReadTool caller), but the prompt predefines two "guidance tones," letting the model exhibit different reading behavior in different scenarios.

8.4.3 Multimedia Capability Declarations

The prompt uses a series of declarative statements to expand the Read tool's capability boundaries (lines 40-48):

- This tool allows Claude Code to read images (eg PNG, JPG, etc).
  When reading an image file the contents are presented visually
  as Claude Code is a multimodal LLM.
- This tool can read PDF files (.pdf). For large PDFs (more than 10
  pages), you MUST provide the pages parameter to read specific page
  ranges. Maximum 20 pages per request.
- This tool can read Jupyter notebooks (.ipynb files) and returns all
  cells with their outputs.

The PDF pagination limit ("more than 10 pages...MUST provide the pages parameter") is a progressive resource limit: small files are read directly, large files require mandatory pagination. This is more reasonable than both "all files must be paginated" and "no pagination limit" -- the former adds unnecessary tool call rounds, the latter may inject too much content at once.

Note that PDF support is conditional (line 41): isPDFSupported() checks whether the runtime environment supports PDF parsing. When unsupported, the entire PDF explanation section disappears from the prompt. This avoids the common trap of "the prompt promises a capability the runtime can't deliver."

Reusable Pattern -- "Capability Declaration Aligned with Runtime": Tool prompt capability descriptions should be dynamically determined by runtime capability. If a feature is unavailable in a specific environment, don't mention it in the prompt -- this would cause the model to repeatedly attempt a nonexistent feature, producing confusion and waste.

8.5 GrepTool: "Always Use Grep, Never bash grep"

GrepTool's prompt is distilled to the extreme, yet every line is a hard constraint.

Source Location: tools/GrepTool/prompt.ts:1-18

8.5.1 Exclusivity Declaration

The first usage rule in the prompt (line 10):

ALWAYS use Grep for search tasks. NEVER invoke `grep` or `rg` as a
Bash command. The Grep tool has been optimized for correct permissions
and access.

This is a design that works in bidirectional coordination with BashTool's tool preference matrix: BashTool says "don't use bash for searching," GrepTool says "searching must use me." Constraints from both directions form a closed loop, maximally reducing the probability of the model "taking the wrong path."

"has been optimized for correct permissions and access" provides a reason, rather than merely issuing a prohibition. The reason matters -- GrepTool's underlying call is the same ripgrep, but it wraps permission checking (checkReadPermissionForTool, GrepTool.ts:233-239), ignore pattern application (getFileReadIgnorePatterns, GrepTool.ts:413-427), and version control directory exclusion (VCS_DIRECTORIES_TO_EXCLUDE, GrepTool.ts:95-102). Calling rg directly through Bash bypasses these safety layers.

8.5.2 ripgrep Syntax Hints

The prompt provides three critical syntax difference notes (lines 11-16):

- Supports full regex syntax (e.g., "log.*Error", "function\s+\w+")
- Pattern syntax: Uses ripgrep (not grep) - literal braces need
  escaping (use `interface\{\}` to find `interface{}` in Go code)
- Multiline matching: By default patterns match within single lines only.
  For cross-line patterns like `struct \{[\s\S]*?field`, use
  `multiline: true`

The first clarifies the syntax family (ripgrep's Rust regex), the second provides the most common pitfall (braces need escaping -- different from GNU grep), and the third explains the multiline parameter's use case.

Looking at the code implementation, multiline: true corresponds to ripgrep parameters -U --multiline-dotall (GrepTool.ts:341-343). The prompt chooses to explain this feature with "use case + example" rather than exposing underlying parameter details -- the model doesn't need to know what -U is, only when to set multiline: true.

8.5.3 Output Modes and head_limit

GrepTool's input schema (GrepTool.ts:33-89) defines rich parameters, but the prompt only briefly mentions three output modes:

Output modes: "content" shows matching lines, "files_with_matches"
shows only file paths (default), "count" shows match counts

The head_limit parameter design (GrepTool.ts:81,107) deserves special attention:

const DEFAULT_HEAD_LIMIT = 250

// In schema description:
'Defaults to 250 when unspecified. Pass 0 for unlimited
(use sparingly — large result sets waste context).'

The default 250-result cap is a context protection mechanism -- the comments explain (lines 104-108) that unlimited content-mode searches can fill the 20KB tool result persistence threshold. The "use sparingly" wording gives the model a gentle warning, while 0 as the "unlimited" escape hatch preserves flexibility.

Reusable Pattern -- "Safe Default + Escape Hatch": For tools that may produce large outputs, set conservative default limits while providing an explicit way to lift the limit. Explain both their existence and applicable scenarios in the prompt.

8.6 AgentTool: Dynamic Agent List and Fork Guidance

AgentTool has the most complex prompt generation logic among the six tools, because it needs to dynamically compose content based on runtime state (available agent definitions, whether fork is enabled, coordinator mode, subscription type).

Source Location: tools/AgentTool/prompt.ts:1-287

8.6.1 Inline vs. Attachment: Two Injection Methods for Agent Lists

The agent list in the prompt can be injected through two methods (lines 58-64, lines 196-199):

export function shouldInjectAgentListInMessages(): boolean {
  if (isEnvTruthy(process.env.CLAUDE_CODE_AGENT_LIST_IN_MESSAGES)) return true
  if (isEnvDefinedFalsy(process.env.CLAUDE_CODE_AGENT_LIST_IN_MESSAGES))
    return false
  return getFeatureValue_CACHED_MAY_BE_STALE('tengu_agent_list_attach', false)
}

Method 1 (inline): The agent list is embedded directly in the tool description.

`Available agent types and the tools they have access to:
${effectiveAgents.map(agent => formatAgentLine(agent)).join('\n')}`

Method 2 (attachment): The tool description only contains static text "Available agent types are listed in <system-reminder> messages in the conversation," with the actual list injected separately via an agent_listing_delta attachment message.

The source code comment (lines 50-57) explains the motivation: the dynamic agent list accounts for approximately 10.2% of global cache_creation tokens. Whenever MCP servers connect asynchronously, plugins reload, or permission modes change, the agent list changes, causing the tool schema containing the list to be entirely invalidated, triggering expensive cache rebuilds. Moving the list to an attachment message makes the tool description static text, thereby protecting the tool schema layer's prompt cache.

Each agent's description format (lines 43-46):

export function formatAgentLine(agent: AgentDefinition): string {
  const toolsDescription = getToolsDescription(agent)
  return `- ${agent.agentType}: ${agent.whenToUse} (Tools: ${toolsDescription})`
}

The getToolsDescription function (lines 15-37) handles the cross-filtering of tool whitelists and blacklists, ultimately generating descriptions like "All tools except Bash, Agent" or "Read, Grep, Glob." This lets the model know what tools each agent type can use, enabling reasonable delegation decisions.

Reusable Pattern -- "Externalize Dynamic Content": When a frequently changing part of a tool's prompt has a large cache impact, move it from the tool description to the message stream (e.g., attachment, system-reminder), keeping the tool description stable.

8.6.2 Fork Sub-Agent: Lightweight Delegation with Context Inheritance

When isForkSubagentEnabled() is true, the prompt adds a "When to fork" section (lines 81-96), guiding the model to choose between two delegation modes:

1. Fork (omit subagent_type): Inherits the parent agent's complete conversation context, suitable for research and implementation tasks.
2. Fresh agent (specify subagent_type): Starts from scratch, requires complete context passing.

The fork usage guide includes three core disciplines:

Don't peek. The tool result includes an output_file path — do not
Read or tail it unless the user explicitly asks for a progress check.

Don't race. After launching, you know nothing about what the fork found.
Never fabricate or predict fork results in any format.

Writing a fork prompt. Since the fork inherits your context, the prompt
is a directive — what to do, not what the situation is.

"Don't peek" prevents the parent agent from reading the fork's intermediate output, which would pull the fork's tool noise into the parent agent's context, defeating the purpose of forking. "Don't race" prevents the parent agent from "guessing" the fork's conclusions before results are returned -- a known LLM tendency.

8.6.3 Prompt Writing Guide: Preventing Shallow Delegation

The most unique part of the prompt is a section on "how to write a good agent prompt" (lines 99-113):

Brief the agent like a smart colleague who just walked into the room —
it hasn't seen this conversation, doesn't know what you've tried,
doesn't understand why this task matters.

...

**Never delegate understanding.** Don't write "based on your findings,
fix the bug" or "based on the research, implement it." Those phrases
push synthesis onto the agent instead of doing it yourself.

"Never delegate understanding" is a profound meta-cognitive constraint. It prevents the model from tossing thinking work that requires synthesis and judgment to sub-agents -- sub-agents should be executors, not decision-makers. This rule anchors "understanding" in the parent agent, ensuring knowledge isn't lost in the delegation chain.

Reusable Pattern -- "Delegation Quality Assurance": When tools involve passing tasks to subsystems, constrain the completeness and specificity of task descriptions in the prompt, preventing the model from generating vague, incomplete delegation instructions.

8.7 SkillTool: Budget Constraints and Three-Level Truncation

SkillTool's unique characteristic is that it not only harnesses the model's behavior but also manages its own prompt's volume.

Source Location: tools/SkillTool/prompt.ts:1-242

8.7.1 The 1% Context Window Budget

export const SKILL_BUDGET_CONTEXT_PERCENT = 0.01
export const CHARS_PER_TOKEN = 4
export const DEFAULT_CHAR_BUDGET = 8_000 // Fallback: 1% of 200k * 4

Source Reference: tools/SkillTool/prompt.ts:21-23

The total character budget for the skill list is hard-limited to 1% of the context window. For a 200K token context window, this is 200K * 4 chars/token * 1% = 8000 characters. This budget constraint ensures the skill discovery feature doesn't encroach on the model's working context -- the skill list is a "directory," not "content." The model only needs to see enough information to decide whether to call a skill; the actual skill content is loaded on invocation.

8.7.2 Three-Level Truncation Strategy

The formatCommandsWithinBudget function (lines 70-171) implements a progressive truncation strategy:

Level 1: Full retention. If all skills' complete descriptions fit within budget, keep everything.

if (fullTotal <= budget) {
  return fullEntries.map(e => e.full).join('\n')
}

Level 2: Description trimming. When over budget, trim non-bundled skill descriptions to the average available length. Bundled skills always retain full descriptions.

const maxDescLen = Math.floor(availableForDescs / restCommands.length)
// ...
return `- ${cmd.name}: ${truncate(description, maxDescLen)}`

Level 3: Name only. If the post-trim average description length is less than 20 characters (MIN_DESC_LENGTH), non-bundled skills degrade to showing only their names.

if (maxDescLen < MIN_DESC_LENGTH) {
  return commands
    .map((cmd, i) =>
      bundledIndices.has(i) ? fullEntries[i]!.full : `- ${cmd.name}`,
    )
    .join('\n')
}

The priority ordering of this three-level strategy is: bundled skills > non-bundled skill descriptions > non-bundled skill names. Bundled skills, as Claude Code's core functionality, are never truncated. Third-party plugin skills degrade as needed, ensuring token costs are controlled regardless of the skill ecosystem's scale.

8.7.3 Single-Entry Hard Cap

Beyond the total budget, each skill entry also has an independent hard cap (line 29):

export const MAX_LISTING_DESC_CHARS = 250

The getCommandDescription function (lines 43-49) pre-truncates each entry to 250 characters before total budget truncation:

function getCommandDescription(cmd: Command): string {
  const desc = cmd.whenToUse
    ? `${cmd.description} - ${cmd.whenToUse}`
    : cmd.description
  return desc.length > MAX_LISTING_DESC_CHARS
    ? desc.slice(0, MAX_LISTING_DESC_CHARS - 1) + '\u2026'
    : desc
}

The comment explains the rationale: the skill list serves discovery purposes, not usage purposes. Verbose whenToUse strings waste turn-1 cache_creation tokens without improving skill matching rates.

8.7.4 Invocation Protocol

SkillTool's core prompt (lines 173-196) is relatively short but contains one critical blocking requirement:

When a skill matches the user's request, this is a BLOCKING REQUIREMENT:
invoke the relevant Skill tool BEFORE generating any other response
about the task

"BLOCKING REQUIREMENT" is one of the strongest constraint phrasings in Claude Code's prompt system. It requires the model to immediately call the Skill tool upon identifying a matching skill, without first generating text responses. This prevents a common anti-pattern: the model first outputs analysis text, then calls the skill -- this text often conflicts with the actual instructions loaded after the skill.

Another defensive rule (line 194):

`If you see a <${COMMAND_NAME_TAG}> tag in the current conversation turn,
the skill has ALREADY been loaded - follow the instructions directly
instead of calling this tool again`

This prevents duplicate loading: if the skill has already been injected via a <command-name> tag into the current turn, the model should not call SkillTool again but should directly execute the skill instructions.

Reusable Pattern -- "Budget-Aware Directory Generation": When tools need to present a dynamically growing list (plugins, skills, API endpoints, etc.) to the model, allocate a fixed token budget for the list and implement multi-level degradation strategies. Prioritize preserving the completeness of high-value entries; lower-priority entries progressively degrade.

8.8 Six-Tool Comparative Summary

The following table compares the prompt design of the six tools across five dimensions:

block-beta
    columns 2
    block:behavior["Behavioral Constraint"]:1
        BT1["BashTool ← Safety Protocol"]
        ET1["EditTool ← Preconditions"]
        GT1["GrepTool ← Exclusivity"]
    end
    block:resource["Resource Management"]:1
        SK1["SkillTool ← Budget Truncation"]
        RT1["ReadTool ← Line/Page Limits"]
        GT2["GrepTool ← head_limit"]
    end
    block:collab["Collaboration Orchestration"]:1
        AT1["AgentTool ← Delegation Guide"]
        BT2["BashTool ← Concurrency Tree"]
        ET2["EditTool ← Interface Contract"]
    end
    block:cache["Cache Optimization"]:1
        AT2["AgentTool ← List Externalization"]
        BT3["BashTool ← $TMPDIR Normalization"]
        SK2["SkillTool ← Description Trimming"]
    end

Figure 8-1: Four-quadrant distribution of tool prompt steering patterns. Each tool typically spans multiple quadrants -- BashTool simultaneously exhibits behavioral constraint, collaboration orchestration, and cache optimization characteristics; GrepTool combines behavioral constraint and resource management.

8.9 Seven Principles for Designing Tool Prompts

From the analysis of six tools, we can distill a set of general tool prompt design principles:

1. Bidirectional closed loop: When tool A should not handle a certain type of task, simultaneously say "don't do X, use B" in A, and "doing X must use me" in B. Unidirectional constraints leave loopholes.

2. Reasons before prohibitions: Follow every "NEVER" with a "because." The model is less likely to violate constraints when it understands the reason. GrepTool's "has been optimized for correct permissions" is more effective than a bare "NEVER use bash grep."

3. Capabilities aligned with runtime: Capabilities declared in the prompt must be guaranteed by the runtime. FileReadTool's PDF support is conditionally injected based on isPDFSupported(), rather than unconditionally declared.

4. Safe defaults + escape hatch: Set conservative defaults for all parameters that may produce large outputs or side effects, while providing an explicit way to lift them. GrepTool's head_limit=250/0 is a textbook case.

5. Budget awareness: Tool prompts themselves consume tokens. SkillTool's 1% budget constraint and three-level truncation is extreme but correct. BashTool's $TMPDIR normalization and dedup are more subtle optimizations.

6. Precondition declarations: If correct tool usage depends on specific prerequisites (reading a file first, checking a directory first), declare it in the prompt and enforce it in the runtime. Double insurance beats single-layer defense.

7. Delegation quality standards: When tools involve passing tasks to subsystems, constrain the completeness and specificity of task descriptions. AgentTool's "Never delegate understanding" prevents knowledge from being lost in the delegation chain.

8.10 What Users Can Do

Based on this chapter's analysis of the six tool prompts, here are recommendations readers can directly apply when designing their own tool prompts:

1. Build a traffic routing table for "universal tools." If your tool set contains a tool with extremely broad functional coverage (like Bash, a generic API caller), place a "scenario -> specialized tool" mapping table at the very front of its description. Simultaneously declare exclusivity in each specialized tool. This bidirectional closed loop is the most effective means of preventing the model from over-relying on a single tool.

2. Enforce preconditions between tools. When tool B's correctness depends on tool A being called first (like "must read before edit"), declare this dependency in B's prompt and enforce it with code in B's runtime. The prompt layer prevents wasted calls, the runtime layer backstops against incorrect operations -- dual-layer defense beats single-layer.

3. Inline security policies as JSON into prompts. If the model needs to "understand" its permission boundaries (accessible paths, connectable hosts, etc.), inject the complete policy rule set in a structured format into the prompt. This lets the model self-check compliance during generation, rather than relying on runtime rejection followed by retry.

4. Set conservative defaults for high-output tools. For all tool parameters that may produce large output (search result counts, file line counts, PDF page counts), set conservative default limits. Simultaneously provide an explicit "lift limit" option (like head_limit=0), and note "use sparingly" in the prompt.

5. Control the token cost of tool descriptions themselves. Reference SkillTool's 1% context window budget and three-level truncation strategy. As your tool set grows, the total token overhead of tool descriptions also grows. Allocate a fixed budget for tool descriptions, prioritize preserving core tool completeness, and progressively degrade edge tools.

6. Use dynamic conditions to control capability declarations. Don't declare capabilities in the prompt that the runtime may not always deliver. Reference FileReadTool's isPDFSupported() condition check -- if PDF parsing is unavailable, don't mention PDF support in the prompt. A prompt that promises what the runtime can't deliver causes the model to repeatedly attempt and fail, wasting context window.

8.11 Summary

Tool prompts are the most "grounded" layer in Claude Code's harness system. The system prompt sets the persona; tool prompts shape the actions. The prompt design of the six tools reveals a core principle: excellent tool prompts are not functional documentation but behavioral contracts. They don't just tell the model "what this tool can do," but also "under what conditions to use this tool," "how to use it safely," and "when to use a different tool."

The next chapter will ascend from the micro-level harness of individual tools to the macro-level orchestration of tool collaboration -- exploring how tools coordinate as a whole through permission systems, state passing, and concurrency control.

Chapter 9: Auto-Compaction — When and How Context Gets Compressed

"The best compression is the one the user never notices."

Every long-session user of Claude Code has experienced this moment: you're having the model incrementally refactor a complex module, when suddenly you notice its responses becoming "forgetful" — it forgets an interface signature you explicitly asked to preserve five minutes ago, or it re-suggests an approach you already rejected. The model didn't get dumber — the context window filled up, and auto-compaction just fired.

Compaction is the core mechanism of Claude Code's context management. It determines at what point and in what manner your conversation history gets condensed into a summary. Understanding this mechanism means you can predict when it triggers, control what it preserves, and know what to do when it "goes wrong."

This chapter will fully dissect auto-compaction from the source code level across three phases: threshold determination (when it triggers), summary generation (how it compresses), and failure recovery (what happens when it fails).

9.1 Threshold Calculation: When Auto-Compaction Triggers

9.1.1 The Core Formula

The trigger condition for auto-compaction can be expressed as a simple inequality:

current token count >= autoCompactThreshold

Computing autoCompactThreshold involves three constants and two layers of subtraction. Let's derive it step by step from the source code.

Layer 1: Effective Context Window

// services/compact/autoCompact.ts:30
const MAX_OUTPUT_TOKENS_FOR_SUMMARY = 20_000

// services/compact/autoCompact.ts:33-48
export function getEffectiveContextWindowSize(model: string): number {
  const reservedTokensForSummary = Math.min(
    getMaxOutputTokensForModel(model),
    MAX_OUTPUT_TOKENS_FOR_SUMMARY,
  )
  let contextWindow = getContextWindowForModel(model, getSdkBetas())

  const autoCompactWindow = process.env.CLAUDE_CODE_AUTO_COMPACT_WINDOW
  if (autoCompactWindow) {
    const parsed = parseInt(autoCompactWindow, 10)
    if (!isNaN(parsed) && parsed > 0) {
      contextWindow = Math.min(contextWindow, parsed)
    }
  }

  return contextWindow - reservedTokensForSummary
}

The logic here is: subtract a "compaction output reservation" from the model's raw context window. MAX_OUTPUT_TOKENS_FOR_SUMMARY = 20_000 comes from actual p99.99 compaction output statistics — 99.99% of compaction summaries fit within 17,387 tokens, and 20K is the upper bound with a safety margin.

Note the Math.min(getMaxOutputTokensForModel(model), MAX_OUTPUT_TOKENS_FOR_SUMMARY) operation: if a model's maximum output limit is itself below 20K (e.g., certain Bedrock configurations), the model's own limit is used instead.

Layer 2: Auto-Compaction Buffer

// services/compact/autoCompact.ts:62
export const AUTOCOMPACT_BUFFER_TOKENS = 13_000

// services/compact/autoCompact.ts:72-91
export function getAutoCompactThreshold(model: string): number {
  const effectiveContextWindow = getEffectiveContextWindowSize(model)
  const autocompactThreshold =
    effectiveContextWindow - AUTOCOMPACT_BUFFER_TOKENS

  const envPercent = process.env.CLAUDE_AUTOCOMPACT_PCT_OVERRIDE
  if (envPercent) {
    const parsed = parseFloat(envPercent)
    if (!isNaN(parsed) && parsed > 0 && parsed <= 100) {
      const percentageThreshold = Math.floor(
        effectiveContextWindow * (parsed / 100),
      )
      return Math.min(percentageThreshold, autocompactThreshold)
    }
  }

  return autocompactThreshold
}

AUTOCOMPACT_BUFFER_TOKENS = 13_000 is an additional safety buffer — it ensures that between threshold triggering and actual compaction execution, there's still enough room for extra tokens the current turn might produce (tool call results, system messages, etc.).

9.1.2 Threshold Calculation Table

Using Claude Sonnet 4 (200K context window) as an example:

Interactive version: Click to view the Token Dashboard animation — watch how a 200K window gets progressively filled, when compaction triggers, and how old messages get replaced by a summary.

Expressed more visually:

|<------------ 200K context window ------------>|
|<---- 167K usable ---->|<- 13K buffer ->|<- 20K compaction output reservation ->|
                        ^                ^
                 Auto-compaction    Effective window
                  trigger point       boundary

This means that under default configuration, auto-compaction triggers when your conversation has consumed approximately 83.5% of the context window.

9.1.3 Environment Variable Overrides

Claude Code provides two environment variables for users (or test environments) to override the default thresholds:

CLAUDE_CODE_AUTO_COMPACT_WINDOW — Override context window size

// services/compact/autoCompact.ts:40-46
const autoCompactWindow = process.env.CLAUDE_CODE_AUTO_COMPACT_WINDOW
if (autoCompactWindow) {
  const parsed = parseInt(autoCompactWindow, 10)
  if (!isNaN(parsed) && parsed > 0) {
    contextWindow = Math.min(contextWindow, parsed)
  }
}

This variable takes Math.min(actual window, configured value) — you can only shrink the window, not expand it. Typical use case: setting a smaller window value in CI environments to force more frequent compaction triggering for stability testing.

CLAUDE_AUTOCOMPACT_PCT_OVERRIDE — Override threshold by percentage

// services/compact/autoCompact.ts:79-87
const envPercent = process.env.CLAUDE_AUTOCOMPACT_PCT_OVERRIDE
if (envPercent) {
  const parsed = parseFloat(envPercent)
  if (!isNaN(parsed) && parsed > 0 && parsed <= 100) {
    const percentageThreshold = Math.floor(
      effectiveContextWindow * (parsed / 100),
    )
    return Math.min(percentageThreshold, autocompactThreshold)
  }
}

For example, setting CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=50 makes the threshold 50% of the effective window (90,000 tokens), but again using Math.min — this override cannot be higher than the default threshold, it can only make compaction trigger earlier.

9.1.4 Complete Determination Flow

The shouldAutoCompact() function (autoCompact.ts:160-239) has a series of guard conditions before comparing token counts:

shouldAutoCompact(messages, model, querySource)
  |
  +- querySource is 'session_memory' or 'compact'? -> false (prevent recursion)
  +- querySource is 'marble_origami' (ctx-agent)? -> false (prevent shared state pollution)
  +- isAutoCompactEnabled() returns false? -> false
  |   +- DISABLE_COMPACT env var is truthy? -> false
  |   +- DISABLE_AUTO_COMPACT env var is truthy? -> false
  |   +- User config autoCompactEnabled = false? -> false
  +- REACTIVE_COMPACT experiment mode active? -> false (let reactive compact take over)
  +- Context Collapse active? -> false (collapse owns its own context management)
  |
  +- tokenCount >= autoCompactThreshold? -> true/false

Note the detailed source comments on Context Collapse (autoCompact.ts:199-222): autocompact triggers at roughly 93% of the effective window, while Context Collapse starts committing at 90% and blocks at 95% — if both run simultaneously, autocompact would "jump the gun" and destroy the fine-grained context that Collapse is preparing to save. Therefore, when Collapse is enabled, proactive autocompact is disabled, with only reactive compact retained as a fallback for 413 errors.

9.2 Circuit Breaker: Consecutive Failure Protection

9.2.1 Problem Background

In the ideal case, context shrinks significantly after compaction, and the next turn doesn't trigger again. But in practice there's a class of "unrecoverable" scenarios: the context contains large amounts of incompressible system messages, attachments, or encoded data, and the post-compaction result still exceeds the threshold, causing immediate re-triggering on the next turn — forming an infinite loop.

Source comments document a real-world scale data point (autoCompact.ts:68-69):

BQ 2026-03-10: 1,279 sessions had 50+ consecutive failures (up to 3,272) in a single session, wasting ~250K API calls/day globally.

1,279 sessions experienced consecutive failures, with one reaching 3,272 failures, wasting approximately 250,000 API calls per day globally. This isn't an edge case — it's a systemic problem requiring hard protection.

9.2.2 Circuit Breaker Implementation

// services/compact/autoCompact.ts:70
const MAX_CONSECUTIVE_AUTOCOMPACT_FAILURES = 3

The circuit breaker logic is extremely concise — the entire mechanism is under 20 lines of code:

// services/compact/autoCompact.ts:257-265
if (
  tracking?.consecutiveFailures !== undefined &&
  tracking.consecutiveFailures >= MAX_CONSECUTIVE_AUTOCOMPACT_FAILURES
) {
  return { wasCompacted: false }
}

State tracking is passed between queryLoop iterations via the AutoCompactTrackingState type:

// services/compact/autoCompact.ts:51-60
export type AutoCompactTrackingState = {
  compacted: boolean
  turnCounter: number
  turnId: string
  consecutiveFailures?: number  // Circuit breaker counter
}

• On success (autoCompact.ts:332): consecutiveFailures resets to 0
• On failure (autoCompact.ts:341-349): Counter increments; after reaching 3, a warning is logged and no further attempts are made
• After tripping: All subsequent autocompact requests for the session immediately return { wasCompacted: false }

This design embodies an important principle: it's better to let users manually run /compact than to waste API budget on retries doomed to fail. The circuit breaker only blocks automatic compaction — users can still trigger it manually via the /compact command.

9.3 Compaction Prompt Dissection: The 9-Section Template

When the threshold triggers, Claude Code needs to send a special prompt to the model asking it to condense the entire conversation into a structured summary. The design of this prompt is critical to compaction quality — it directly determines what's preserved and what's lost in the summary.

9.3.1 Three Prompt Variants

The source code defines three compaction prompt variants, each corresponding to a different compaction scenario:

The core difference between the three lies in the "scope of vision" for the summary:

• BASE tells the model: "Your task is to create a detailed summary of the conversation so far" — summarize everything
• PARTIAL tells the model: "Your task is to create a detailed summary of the RECENT portion of the conversation — the messages that follow earlier retained context" — only summarize the new portion
• PARTIAL_UP_TO tells the model: "This summary will be placed at the start of a continuing session; newer messages that build on this context will follow after your summary" — summarize the prefix, providing context for subsequent messages

9.3.2 Template Structure Analysis

Taking BASE_COMPACT_PROMPT as an example (prompt.ts:61-143), the entire prompt consists of 9 structured sections. Below is a section-by-section analysis of the design intent:

9.3.3 The <analysis> Draft Block: A Hidden Quality Assurance Mechanism

Before the 9-section summary, the template requires the model to first generate an <analysis> block:

// prompt.ts:31-44
const DETAILED_ANALYSIS_INSTRUCTION_BASE = `Before providing your final summary,
wrap your analysis in <analysis> tags to organize your thoughts and ensure
you've covered all necessary points. In your analysis process:

1. Chronologically analyze each message and section of the conversation.
   For each section thoroughly identify:
   - The user's explicit requests and intents
   - Your approach to addressing the user's requests
   - Key decisions, technical concepts and code patterns
   - Specific details like:
     - file names
     - full code snippets
     - function signatures
     - file edits
   - Errors that you ran into and how you fixed them
   - Pay special attention to specific user feedback...
2. Double-check for technical accuracy and completeness...`

This <analysis> block is a drafting scratchpad — the model traverses the entire conversation chronologically before generating the final summary. The key phrase is "Chronologically analyze each message", which forces the model to process sequentially rather than jumping around, reducing omissions.

But this draft block does not appear in the final context. The formatCompactSummary() function (prompt.ts:311-335) strips it out completely:

// prompt.ts:316-319
formattedSummary = formattedSummary.replace(
  /<analysis>[\s\S]*?<\/analysis>/,
  '',
)

This is a clever application of chain-of-thought: leverage the <analysis> block to improve summary quality, but don't let it consume post-compaction context space. The draft block's tokens are only generated in the compaction API call's output and don't become a context burden for subsequent conversations.

9.3.4 NO_TOOLS_PREAMBLE: Preventing Tool Calls

All three variants inject a strong "no tool calls" preamble at the very beginning:

// prompt.ts:19-26
const NO_TOOLS_PREAMBLE = `CRITICAL: Respond with TEXT ONLY. Do NOT call any tools.

- Do NOT use Read, Bash, Grep, Glob, Edit, Write, or ANY other tool.
- You already have all the context you need in the conversation above.
- Tool calls will be REJECTED and will waste your only turn — you will fail the task.
- Your entire response must be plain text: an <analysis> block followed by a <summary> block.
`

And there's a matching trailer at the end (prompt.ts:269-272):

const NO_TOOLS_TRAILER =
  '\n\nREMINDER: Do NOT call any tools. Respond with plain text only — ' +
  'an <analysis> block followed by a <summary> block. ' +
  'Tool calls will be rejected and you will fail the task.'

Source comments explain why such an "aggressive" prohibition is needed (prompt.ts:12-18): compaction requests execute with maxTurns: 1 (only one response turn allowed). If the model attempts a tool call during this turn, the tool call gets rejected, resulting in no text output — the entire compaction fails, falling back to the streaming fallback path. On Sonnet 4.6, this issue occurs at a rate of 2.79%. The dual prohibition at both start and end reduces this problem to negligible levels.

9.3.5 PARTIAL Variant Differences

The main differences between PARTIAL_COMPACT_PROMPT and BASE_COMPACT_PROMPT are:

1. Scope limitation: "Focus your summary on what was discussed, learned, and accomplished in the recent messages only"
2. Analysis instruction: DETAILED_ANALYSIS_INSTRUCTION_PARTIAL replaces the BASE version's "Chronologically analyze each message and section of the conversation" with "Analyze the recent messages chronologically"

PARTIAL_COMPACT_UP_TO_PROMPT is more distinctive — its section 8 changes from "Current Work" to "Work Completed", and section 9 changes from "Optional Next Step" to "Context for Continuing Work". This is because in UP_TO mode, the model only sees the first half of the conversation (the second half will be appended as-is as preserved messages), so the summary needs to provide context for a "continuation" rather than plan next steps.

9.4 Compaction Execution Flow

9.4.1 compactConversation() Main Flow

The compactConversation() function (compact.ts:387-704) is the core orchestrator of compaction. Its main flow can be summarized as:

flowchart TD
    A[Start compaction] --> B[Execute PreCompact Hooks]
    B --> C[Build compaction prompt]
    C --> D[Send compaction request]
    D --> E{Is response<br/>prompt_too_long?}
    E -->|Yes| F[PTL retry loop]
    E -->|No| G{Is summary valid?}
    F --> D
    G -->|No| H[Throw error]
    G -->|Yes| I[Clear file state cache]
    I --> J[Generate attachments in parallel:<br/>files/plan/skills/tools/MCP]
    J --> K[Execute SessionStart Hooks]
    K --> L[Build CompactionResult]
    L --> M[Record telemetry event]
    M --> N[Return result]

Several noteworthy details:

Pre-clear and post-restore (compact.ts:518-561): After compaction completes, the code first clears the readFileState cache and loadedNestedMemoryPaths, then restores the most important file context via createPostCompactFileAttachments(). This is a "forget then recall" strategy — rather than preserving all file contents in the summary (unreliable), it re-reads the most critical files after compaction (highly deterministic). File restoration budget: up to 5 files, total of 50,000 tokens, per-file limit of 5,000 tokens.

Attachment re-injection (compact.ts:566-585): Compaction consumed the previous delta attachments (deferred tool declarations, agent listings, MCP instructions). The code regenerates these attachments after compaction using an "empty message history" as baseline, ensuring the model has complete tool and instruction context on the first post-compaction turn.

9.4.2 Post-Compaction Message Structure

The CompactionResult produced by compaction is assembled into the final message array via buildPostCompactMessages() (compact.ts:330-338):

[boundaryMarker, ...summaryMessages, ...messagesToKeep, ...attachments, ...hookResults]

Where:

• boundaryMarker: A SystemCompactBoundaryMessage marking where compaction occurred
• summaryMessages: The summary in user message format, containing the preamble generated by getCompactUserSummaryMessage() ("This session is being continued from a previous conversation that ran out of context")
• messagesToKeep: Recent messages preserved during partial compaction
• attachments: File, plan, skill, tool, and other attachments
• hookResults: Results from SessionStart hooks

9.5 PTL Retry: When Compaction Itself Is Too Long

9.5.1 Problem Scenario

This is a "recursive" dilemma: your conversation is too long and needs compaction, but the compaction request itself exceeds the API's input limit (prompt_too_long). In extremely long sessions (e.g., those consuming 190K+ tokens), sending the entire conversation history to the compaction model may push the compaction request's input tokens to or beyond the context window.

9.5.2 Retry Mechanism

The truncateHeadForPTLRetry() function (compact.ts:243-291) implements a "discard oldest content" retry strategy:

flowchart TD
    A[Compaction request] --> B{Does response start<br/>with PROMPT_TOO_LONG?}
    B -->|No| C[Compaction succeeds]
    B -->|Yes| D{ptlAttempts <= 3?}
    D -->|No| E[Throw error:<br/>Conversation too long]
    D -->|Yes| F[truncateHeadForPTLRetry]
    F --> G[Parse tokenGap]
    G --> H{Is tokenGap<br/>parseable?}
    H -->|Yes| I[Discard oldest<br/>API round groups<br/>by tokenGap]
    H -->|No| J[Fallback: discard<br/>20% of round groups]
    I --> K{At least 1<br/>group remains?}
    J --> K
    K -->|No| L[Return null -> failure]
    K -->|Yes| M[Prepend PTL_RETRY_MARKER]
    M --> N[Resend compaction request<br/>with truncated messages]
    N --> B

The core logic has three steps:

Step 1: Group by API rounds

// compact.ts:257
const groups = groupMessagesByApiRound(input)

groupMessagesByApiRound() (grouping.ts:22-60) groups messages by API round boundaries — a new group starts whenever a new assistant message ID appears. This ensures the discard operation doesn't split a tool_use from its corresponding tool_result.

Step 2: Calculate discard count

// compact.ts:260-272
const tokenGap = getPromptTooLongTokenGap(ptlResponse)
let dropCount: number
if (tokenGap !== undefined) {
  let acc = 0
  dropCount = 0
  for (const g of groups) {
    acc += roughTokenCountEstimationForMessages(g)
    dropCount++
    if (acc >= tokenGap) break
  }
} else {
  dropCount = Math.max(1, Math.floor(groups.length * 0.2))
}

If the API's prompt_too_long response includes a specific token gap, the code precisely accumulates from the oldest groups until covering this gap. If the gap isn't parseable (some Vertex/Bedrock error formats differ), it falls back to discarding 20% of groups — a conservative but effective heuristic.

Step 3: Fix message sequence

// compact.ts:278-291
const sliced = groups.slice(dropCount).flat()
if (sliced[0]?.type === 'assistant') {
  return [
    createUserMessage({ content: PTL_RETRY_MARKER, isMeta: true }),
    ...sliced,
  ]
}
return sliced

After discarding the oldest groups, the remaining messages' first entry might be an assistant message (because the original conversation's user preamble was in group 0, which got discarded). The API requires the first message to be a user role, so the code inserts a synthetic user marker message PTL_RETRY_MARKER.

9.5.3 Preventing Marker Accumulation

Note a subtle handling at the beginning of truncateHeadForPTLRetry() (compact.ts:250-255):

const input =
  messages[0]?.type === 'user' &&
  messages[0].isMeta &&
  messages[0].message.content === PTL_RETRY_MARKER
    ? messages.slice(1)
    : messages

Before grouping, if the first message in the sequence is a PTL_RETRY_MARKER inserted by a previous retry, the code strips it first. Otherwise, this marker would be grouped into group 0, and the 20% fallback strategy might "only discard this marker" — zero progress, and the second retry enters an infinite loop.

9.5.4 Retry Limit and Cache Passthrough

// compact.ts:227
const MAX_PTL_RETRIES = 3

Maximum 3 retries. Each retry not only truncates messages but also updates cacheSafeParams (compact.ts:487-490) to ensure forked-agent paths also use the truncated messages:

retryCacheSafeParams = {
  ...retryCacheSafeParams,
  forkContextMessages: truncated,
}

If all 3 retries still fail, it throws ERROR_MESSAGE_PROMPT_TOO_LONG, and the user sees: "Conversation too long. Press esc twice to go up a few messages and try again."

9.6 Complete Orchestration of autoCompactIfNeeded()

Chaining all the above mechanisms together, autoCompactIfNeeded() (autoCompact.ts:241-351) is the entry point called by queryLoop on each iteration. Its complete flow:

flowchart TD
    A["queryLoop each iteration"] --> B{"DISABLE_COMPACT?"}
    B -->|Yes| Z["Return wasCompacted: false"]
    B -->|No| C{"consecutiveFailures >= 3?<br/>(circuit breaker)"}
    C -->|Yes| Z
    C -->|No| D["shouldAutoCompact()"]
    D -->|Not needed| Z
    D -->|Needed| E["Try Session Memory compaction"]
    E -->|Success| F["Cleanup + return result"]
    E -->|Failure/not applicable| G["compactConversation()"]
    G -->|Success| H["Reset consecutiveFailures = 0<br/>Return result"]
    G -->|Failure| I{"Is user abort?"}
    I -->|Yes| J["Log error"]
    I -->|No| J
    J --> K["consecutiveFailures++"]
    K --> L{">= 3?"}
    L -->|Yes| M["Log circuit breaker warning"]
    L -->|No| N["Return wasCompacted: false"]
    M --> N

Note an interesting priority: the code first attempts Session Memory compaction (autoCompact.ts:287-310), and only falls back to traditional compactConversation() when Session Memory is unavailable or can't free sufficient space. Session Memory compaction is a more fine-grained strategy (pruning messages rather than full summarization), which will be discussed in detail in later chapters.

9.7 What Users Can Do

Having understood the inner mechanics of auto-compaction, here are concrete actions you can take as a user:

9.7.1 Observe Compaction Timing

When you see a brief "compacting..." status indicator during a long session, auto-compaction is in progress. Based on the threshold formula, with a 200K context window, this happens at roughly 167K tokens (about 83.5% usage).

9.7.2 Manually Compact Ahead of Time

Don't wait for auto-compaction to trigger. Before finishing one subtask and starting the next, proactively run /compact. Manual compaction allows you to pass custom instructions:

/compact Focus on preserving file modification history and error fix records, keep code snippets complete

These custom instructions get appended to the end of the compaction prompt, directly influencing summary content.

9.7.3 Leverage Compaction Instructions in CLAUDE.md

You can add a compaction instructions section to your project's CLAUDE.md, which will be automatically injected during every compaction:

## Compact Instructions
When summarizing the conversation focus on typescript code changes
and also remember the mistakes you made and how you fixed them.

9.7.4 Adjust Thresholds with Environment Variables

If you find auto-compaction triggers too early (causing unnecessary context loss) or too late (causing frequent prompt_too_long errors), you can fine-tune with environment variables:

# Trigger compaction at 70% (more conservative, fewer PTL errors)
export CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=70

# Or directly limit the "visible window" to 100K (for slow networks/tight budgets)
export CLAUDE_CODE_AUTO_COMPACT_WINDOW=100000

9.7.5 Disable Auto-Compaction (Not Recommended)

# Only disable auto-compaction, keep manual /compact
export DISABLE_AUTO_COMPACT=1

# Completely disable all compaction (including manual)
export DISABLE_COMPACT=1

Fully disabling means you must manage context manually, otherwise you'll encounter unrecoverable prompt_too_long errors when the context window is exhausted.

9.7.6 Understanding Post-Compaction "Forgetting"

What the model "forgets" after compaction depends entirely on what the 9-section summary template covers. The types of information most easily lost:

1. Precise code diffs: While the template requests "full code snippets," extremely long diff lists get truncated
2. Specific reasons for rejected approaches: The template focuses on "what was done," with weaker coverage of "why something wasn't done"
3. Subtle preferences from early conversation: If you mentioned "don't use lodash" once at the start, this may disappear after multiple compactions

Mitigation strategy: Write critical constraints into CLAUDE.md (unaffected by compaction), or explicitly list information to preserve in compaction instructions.

9.7.7 Recovery After Circuit Breaker Trips

If you notice the model no longer auto-compacts (circuit breaker tripped after 3 consecutive failures), you can:

1. Manually run /compact to attempt compaction
2. If that still fails, start a new session — in some cases the context is beyond recovery

9.8 Summary

Auto-compaction is one of Claude Code's most critical context management mechanisms, and its design reflects several important engineering principles:

1. Multi-layer buffering: 20K output reservation + 13K buffer + 3K blocking hard limit — three lines of defense ensure the system never overflows under any race condition
2. Progressive degradation: Session Memory compaction -> traditional compaction -> PTL retry -> circuit breaker — each layer is a fallback for the one above
3. Observability: tengu_compact, tengu_compact_failed, tengu_compact_ptl_retry — three telemetry events covering success, failure, and retry paths
4. User controllability: Environment variable overrides, custom compaction instructions, manual /compact command — giving advanced users sufficient control

The next chapter will explore the post-compaction file state preservation mechanism — compaction can "forget" conversation history, but it shouldn't "forget" which files it's editing.

Version Evolution: v2.1.91 Changes

The following analysis is based on v2.1.91 bundle signal comparison, combined with v2.1.88 source code inference.

File State Staleness Detection

v2.1.91's sdk-tools.d.ts adds a new staleReadFileStateHint field:

staleReadFileStateHint?: string;
// Model-facing note listing readFileState entries whose mtime bumped
// during this command (set when WRITE_COMMAND_MARKERS matches)

This means that during tool execution, if a Bash command modifies a previously read file, the system attaches a staleness hint to the tool result, informing the model that "file A you previously read has been modified." This complements the post-compaction file state preservation mechanism described in this chapter — compaction addresses "long-term memory," while staleness hints address "single-turn immediacy."

Version Evolution: v2.1.100 Changes

The following analysis is based on v2.1.100 bundle signal comparison, combined with v2.1.88 source code inference.

Cold Compact: Deferred Strategy with Feature Flag Control

The tengu_cold_compact event in v2.1.100 indicates cold compact has moved from experiment to controlled deployment. Trigger logic extracted from the bundle:

// v2.1.100 bundle reverse engineering
let M = GPY() && S8("tengu_cold_compact", !1);
// GPY() — Feature Flag gate (server-side control switch)
// S8("tengu_cold_compact", false) — GrowthBook config, default off
try {
  let P = await QS6(q, K, _, !0, void 0, !0, J, M);
  // M passed as 8th parameter to the core compaction function

The distinction between cold and hot compact:

Rapid Refill Circuit Breaker

The tengu_auto_compact_rapid_refill_breaker event addresses an edge case in the compaction system: if compaction just completed and the user immediately resumes high-density input causing rapid context refill, the system could enter a "compact → refill → compact again" death loop. The circuit breaker tracks consecutive rapid refills via the consecutiveRapidRefills counter: if context refills to the compact threshold within 3 turns of the previous compact, the counter increments; 3 consecutive rapid refills trip the breaker, halting compaction and showing the user "Autocompact is thrashing" — sacrificing one compaction opportunity for system stability.

User-Triggerable /compact Command

v2.1.100 adds tengu_autocompact_command and tengu_autocompact_dialog_opened events, indicating users can now trigger compaction via the /compact command and decide whether to proceed through a confirmation dialog. This changes the v2.1.88 model where compaction was entirely system-automated — users gain active control over context management.

MAX_CONTEXT_TOKENS Override

The new CLAUDE_CODE_MAX_CONTEXT_TOKENS environment variable allows users to override the maximum context token count. From bundle reverse engineering:

// v2.1.100 bundle reverse engineering
if (B6(process.env.DISABLE_COMPACT) && process.env.CLAUDE_CODE_MAX_CONTEXT_TOKENS) {
  let _ = parseInt(process.env.CLAUDE_CODE_MAX_CONTEXT_TOKENS, 10);
  if (!isNaN(_) && _ > 0) // Override context window size

Note this override only takes effect when DISABLE_COMPACT is also enabled — the design intent is to let advanced users manually control the context budget when auto-compaction is disabled, not to bypass compaction safety thresholds.

Chapter 10: Post-Compaction File State Preservation

"Compression without restoration is just data loss with extra steps."

Chapter 9 covered when compaction triggers and how summaries are generated. But the compaction story doesn't end after summary generation. When a long conversation gets condensed into a single summary message, the model loses all original context — it no longer knows which files it just read, doesn't remember the plan it was executing, and doesn't even know what tools are available. If the first turn after compaction asks the model to continue editing a file it "just" read, and the model blankly Reads it again, this not only wastes tokens but also interrupts the user's workflow.

This chapter's topic is post-compaction state restoration — how Claude Code, after compaction completes, injects key context the model "needs but has lost" back into the conversation flow through a series of carefully designed attachments. We'll dissect five restoration dimensions one by one: file state, skill content, plan state, delta tool declarations, and content deliberately not restored.

10.1 Pre-Compaction Snapshot: Save Before Clearing

The first step of compaction restoration isn't what you do after compaction, but saving the scene before compaction.

10.1.1 cacheToObject + clear: The Snapshot-Clear Pattern

// services/compact/compact.ts:517-522
// Store the current file state before clearing
const preCompactReadFileState = cacheToObject(context.readFileState)

// Clear the cache
context.readFileState.clear()
context.loadedNestedMemoryPaths?.clear()

These three lines implement a classic snapshot-clear pattern:

1. Snapshot: cacheToObject(context.readFileState) serializes the in-memory FileStateCache (a Map structure) into a plain Record<string, { content: string; timestamp: number }> object. This object records every file the model read before compaction — filename, content, and the timestamp of the last read.

2. Clear: context.readFileState.clear() clears the file state cache, and context.loadedNestedMemoryPaths?.clear() clears the loaded nested memory paths.

Why clear first? Because compaction replaces conversation history with a single summary message. From the model's perspective, it's about to "forget" ever reading any files. If the cache isn't cleared, the system would falsely believe the model still "knows" the contents of these files, causing the subsequent file deduplication logic to malfunction. After clearing, the system enters a clean state, then selectively restores the most important files — rather than restoring everything.

10.1.2 Why Not Restore Everything?

This question touches the core design philosophy of compaction restoration. During a long session, the model may have read dozens or even hundreds of files. If all of them were injected back after compaction, it would create an absurd cycle: the token space just freed by compaction would be immediately filled by restored file contents.

Therefore, the restoration strategy is fundamentally a budget allocation problem — selectively restoring the most valuable state within a limited token budget.

10.2 File Restoration: Most Recent 5 Files, 5K Per File, 50K Total Budget

10.2.1 The Five-Constant Budget Framework

// services/compact/compact.ts:122-130
export const POST_COMPACT_MAX_FILES_TO_RESTORE = 5
export const POST_COMPACT_TOKEN_BUDGET = 50_000
export const POST_COMPACT_MAX_TOKENS_PER_FILE = 5_000
export const POST_COMPACT_MAX_TOKENS_PER_SKILL = 5_000
export const POST_COMPACT_SKILLS_TOKEN_BUDGET = 25_000

These five constants form the complete budget framework for post-compaction restoration. The table below shows their allocation logic:

Table 10-1: Post-Compaction Token Budget Allocation

Using a 200K context window as an example, the post-compaction summary occupies approximately 10K-20K tokens. File restoration consumes at most 50K, skill restoration at most 25K, totaling roughly 75K-95K — still leaving 100K+ space for subsequent conversation. This is a carefully considered balance: restore enough context for the model to seamlessly continue working, but not so much that compaction becomes meaningless.

10.2.2 Restoration Logic in Detail

// services/compact/compact.ts:1415-1464
export async function createPostCompactFileAttachments(
  readFileState: Record<string, { content: string; timestamp: number }>,
  toolUseContext: ToolUseContext,
  maxFiles: number,
  preservedMessages: Message[] = [],
): Promise<AttachmentMessage[]> {
  const preservedReadPaths = collectReadToolFilePaths(preservedMessages)
  const recentFiles = Object.entries(readFileState)
    .map(([filename, state]) => ({ filename, ...state }))
    .filter(
      file =>
        !shouldExcludeFromPostCompactRestore(
          file.filename,
          toolUseContext.agentId,
        ) && !preservedReadPaths.has(expandPath(file.filename)),
    )
    .sort((a, b) => b.timestamp - a.timestamp)
    .slice(0, maxFiles)
  // ...
}

This function's logic breaks down into four steps:

Step 1: Exclude files that don't need restoration. shouldExcludeFromPostCompactRestore (lines 1674-1705) excludes two types of files:

• Plan files — they have their own independent restoration channel (see Section 10.4)
• CLAUDE.md memory files — these are injected via system prompts and don't need to be duplicated through the file restoration channel

Additionally, if a file path already appears in the preserved message tail (preservedReadPaths), it doesn't need redundant restoration — the model can already see it in context.

Step 2: Sort by timestamp. .sort((a, b) => b.timestamp - a.timestamp) arranges files in descending order of last read time. The most recently read files are most likely the ones the model needs to operate on next.

Step 3: Take the top N. .slice(0, maxFiles) takes the 5 most recent files. Note this truncation happens after exclusion filtering — if 3 out of 20 files are excluded, only 17 files participate in sorting, and the top 5 are taken from those.

Step 4: Generate attachments in parallel. For selected files, generateFileAttachment re-reads file contents in parallel, with each file subject to POST_COMPACT_MAX_TOKENS_PER_FILE (5K token) limits. An important detail here: restoration reads the current content on disk, not the cached content from the snapshot. If a file was modified externally during compaction (e.g., the user manually edited it in their editor), the restored content is the modified version.

Step 5: Budget control. After generating file attachments, there's one more budget gate:

// services/compact/compact.ts:1452-1463
let usedTokens = 0
return results.filter((result): result is AttachmentMessage => {
  if (result === null) {
    return false
  }
  const attachmentTokens = roughTokenCountEstimation(jsonStringify(result))
  if (usedTokens + attachmentTokens <= POST_COMPACT_TOKEN_BUDGET) {
    usedTokens += attachmentTokens
    return true
  }
  return false
})

Even with only 5 files, if they're all large (each approaching 5K tokens), the total might exceed the 50K budget. This filter acts as the final gatekeeper — accumulating each file's token count in order, discarding remaining files once the total exceeds POST_COMPACT_TOKEN_BUDGET (50K).

10.2.3 "Preserve vs. Discard" Decision Tree

The following decision tree describes the complete logic for determining whether each file will be restored after compaction:

flowchart TD
    A["Was the file read before compaction?"] -->|No| B["Not restored: file not in readFileState"]
    A -->|Yes| C{"Is it a plan file?"}
    C -->|Yes| D["Excluded: restored independently via Plan attachment (see 10.4)"]
    C -->|No| E{"Is it a CLAUDE.md memory file?"}
    E -->|Yes| F["Excluded: injected via system prompt"]
    E -->|No| G{"Already in preserved message tail?"}
    G -->|Yes| H["Excluded: model can already see it, no duplication needed"]
    G -->|No| I{"In top 5 after timestamp sorting?"}
    I -->|No| J["Discarded: exceeds file count limit"]
    I -->|Yes| K{"Single file exceeds 5K tokens?"}
    K -->|Yes| L["Truncated to 5K tokens, then continue"]
    K -->|No| M{"Cumulative total exceeds 50K?"}
    L --> M
    M -->|Yes| N["Discarded: exceeds total budget"]
    M -->|No| O["Restored - injected as attachment"]

This decision tree reveals an important design: restoration is not a simple "most recent N" algorithm, but a multi-layer filtering pipeline. Exclusion rules, count limits, per-file truncation, and total budget caps — four layers of protection ensure restored content is both valuable and not excessively bloated.

10.3 Skill Re-injection: Selective Restoration of invokedSkills

10.3.1 Why Skills Need Independent Restoration

Skills are Claude Code's extensibility system. When a user invokes a skill during a session (such as code-review or commit), the skill's instructions are injected into the conversation. After compaction, these instructions disappear along with the rest of the context. But skills often contain critical behavioral constraints — like "must run tests before committing" or "focus on security issues during code review." If they aren't restored, the model may violate these constraints post-compaction.

10.3.2 Skill Restoration Mechanism

// services/compact/compact.ts:1494-1534
export function createSkillAttachmentIfNeeded(
  agentId?: string,
): AttachmentMessage | null {
  const invokedSkills = getInvokedSkillsForAgent(agentId)

  if (invokedSkills.size === 0) {
    return null
  }

  // Sorted most-recent-first so budget pressure drops the least-relevant skills.
  let usedTokens = 0
  const skills = Array.from(invokedSkills.values())
    .sort((a, b) => b.invokedAt - a.invokedAt)
    .map(skill => ({
      name: skill.skillName,
      path: skill.skillPath,
      content: truncateToTokens(
        skill.content,
        POST_COMPACT_MAX_TOKENS_PER_SKILL,
      ),
    }))
    .filter(skill => {
      const tokens = roughTokenCountEstimation(skill.content)
      if (usedTokens + tokens > POST_COMPACT_SKILLS_TOKEN_BUDGET) {
        return false
      }
      usedTokens += tokens
      return true
    })

  if (skills.length === 0) {
    return null
  }

  return createAttachmentMessage({
    type: 'invoked_skills',
    skills,
  })
}

The skill restoration strategy is highly similar to file restoration, but with two key differences:

Difference 1: Truncate rather than discard. Source comments (lines 125-128) explain the design intent:

Skills can be large (verify=18.7KB, claude-api=20.1KB). Previously re-injected unbounded on every compact -> 5-10K tok/compact. Per-skill truncation beats dropping -- instructions at the top of a skill file are usually the critical part.

Skill files can be large (the verify skill is 18.7KB, claude-api is 20.1KB), but the instructions at the beginning of a skill file are usually the most critical part. The truncateToTokens function truncates each skill to 5K tokens, preserving the top instructions and discarding the detailed reference content at the tail. This is more refined than a binary "keep all or drop all" strategy.

Difference 2: Isolation by agent. getInvokedSkillsForAgent(agentId) only returns skills belonging to the current agent. This prevents the main session's skills from leaking into a sub-agent's context, and vice versa.

10.3.3 Budget Arithmetic

How many skills can the 25K total budget restore? At 5K tokens per skill, theoretically at most 5 skills. Source comments also confirm this: "Budget sized to hold ~5 skills at the per-skill cap."

But in practice, many skills are under 5K tokens after truncation, so the 25K budget typically covers all invoked skills in a session. Only when a user invokes numerous large skills in a single long session does the budget become a bottleneck — in which case the oldest skills are dropped first.

10.4 Content Deliberately Not Restored: sentSkillNames

Not all cleared state needs to be restored. One of the most interesting design decisions in the source code is:

// services/compact/compact.ts:524-529
// Intentionally NOT resetting sentSkillNames: re-injecting the full
// skill_listing (~4K tokens) post-compact is pure cache_creation with
// marginal benefit. The model still has SkillTool in its schema and
// invoked_skills attachment (below) preserves used-skill content. Ants
// with EXPERIMENTAL_SKILL_SEARCH already skip re-injection via the
// early-return in getSkillListingAttachments.

sentSkillNames is a module-level Map<string, Set<string>> that records which skill name listings have already been sent to the model. If it were reset after compaction, the system would re-inject the full skill listing attachment on the next request — approximately 4K tokens.

But the code intentionally does not reset it. The reasons are:

1. Cost asymmetry: The 4K token skill listing would be entirely cache_creation tokens (new content that needs to be written to cache), but the benefit is marginal — the model can still know about the skill tool's existence through the SkillTool schema.
2. Already-invoked skills are already restored: The invoked_skills attachment from the previous section already restores the content of actually used skills, so the model doesn't need to see the full name listing again.
3. Experimental skill search: Environments with EXPERIMENTAL_SKILL_SEARCH enabled already skip skill listing injection.

This is a textbook token-saving engineering decision — choosing "token cost" over "restoration completeness." 4K tokens may seem small, but they accumulate with each compaction. For long sessions that compact frequently, this represents significant savings.

10.5 Plan and PlanMode Attachment Preservation

Claude Code's plan mode allows the model to create a detailed plan before executing any operations. After compaction, the plan state must be fully preserved; otherwise, the model will "forget" the plan it was executing.

10.5.1 Plan Attachment

// services/compact/compact.ts:545-548
const planAttachment = createPlanAttachmentIfNeeded(context.agentId)
if (planAttachment) {
  postCompactFileAttachments.push(planAttachment)
}

createPlanAttachmentIfNeeded (lines 1470-1486) checks whether the current agent has an active plan file. If so, the plan content is injected as a plan_file_reference type attachment. Note that plan files are explicitly excluded from file restoration by shouldExcludeFromPostCompactRestore, precisely because they have this independent restoration channel — avoiding the same file being restored twice and wasting budget.

10.5.2 PlanMode Attachment

// services/compact/compact.ts:552-555
const planModeAttachment = await createPlanModeAttachmentIfNeeded(context)
if (planModeAttachment) {
  postCompactFileAttachments.push(planModeAttachment)
}

The Plan attachment restores plan content, while the PlanMode attachment restores mode state. createPlanModeAttachmentIfNeeded (lines 1542-1560) checks whether the user is currently in plan mode (mode === 'plan'). If so, it injects a plan_mode type attachment containing a reminderType: 'full' flag — ensuring the model continues operating in plan mode after compaction rather than reverting to normal execution mode.

These two attachments work in concert: the Plan attachment tells the model "you're executing this plan," and the PlanMode attachment tells the model "you must continue working in plan mode." Missing either one would cause behavioral deviation.

10.6 Delta Attachments: Re-announcing Tools and Instructions

Compaction doesn't just clear file state — it also clears all previous delta attachments. Delta attachments are "incremental information" the system progressively informs the model about during conversation — newly registered deferred tools, newly discovered agents, newly loaded MCP instructions. After compaction, this information disappears along with the old messages.

10.6.1 Full Replay of Three Delta Types

// services/compact/compact.ts:563-585
// Compaction ate prior delta attachments. Re-announce from the current
// state so the model has tool/instruction context on the first
// post-compact turn. Empty message history -> diff against nothing ->
// announces the full set.
for (const att of getDeferredToolsDeltaAttachment(
  context.options.tools,
  context.options.mainLoopModel,
  [],
  { callSite: 'compact_full' },
)) {
  postCompactFileAttachments.push(createAttachmentMessage(att))
}
for (const att of getAgentListingDeltaAttachment(context, [])) {
  postCompactFileAttachments.push(createAttachmentMessage(att))
}
for (const att of getMcpInstructionsDeltaAttachment(
  context.options.mcpClients,
  context.options.tools,
  context.options.mainLoopModel,
  [],
)) {
  postCompactFileAttachments.push(createAttachmentMessage(att))
}

The source comment reveals this code's clever design: passing an empty array [] as the message history.

During normal conversation turns, delta attachment functions compare current state against what has already appeared in message history, sending only the "delta." But after compaction there's no message history to compare against — passing an empty array means the diff baseline is empty, so the functions generate complete tool and instruction declarations.

The three delta attachment types and their purposes:

The callSite: 'compact_full' tag is used for telemetry analysis, distinguishing normal incremental declarations from post-compaction full replays.

10.6.2 Async Agent Attachments

// services/compact/compact.ts:532-539
const [fileAttachments, asyncAgentAttachments] = await Promise.all([
  createPostCompactFileAttachments(
    preCompactReadFileState,
    context,
    POST_COMPACT_MAX_FILES_TO_RESTORE,
  ),
  createAsyncAgentAttachmentsIfNeeded(context),
])

createAsyncAgentAttachmentsIfNeeded (lines 1568-1599) checks whether there are async agents running in the background or completed agents whose results haven't been retrieved. If so, it generates a task_status type attachment for each agent, including the agent's description, status, and progress summary. This prevents the model from "forgetting" about background tasks post-compaction and redundantly launching the same tasks.

Note that file restoration and async agent attachment generation are executed in parallel (Promise.all) — a performance optimization since the two are independent and there's no reason to wait sequentially.

10.7 The Complete Restoration Orchestration

Now let's put all restoration steps together and see the complete orchestration of post-compaction state restoration (compact.ts lines 517-585):

flowchart TD
    subgraph Step1["Step 1: Snapshot and Clear"]
        S1A["cacheToObject(readFileState)<br/>Save file state snapshot"]
        S1B["readFileState.clear()<br/>Clear file cache"]
        S1C["loadedNestedMemoryPaths.clear()<br/>Clear memory paths"]
        S1A --> S1B --> S1C
    end

    subgraph Step2["Step 2: Generate Attachments in Parallel"]
        S2A["createPostCompactFileAttachments<br/>File restoration attachments"]
        S2B["createAsyncAgentAttachmentsIfNeeded<br/>Async agent attachments"]
    end

    subgraph Step3["Step 3: Generate Attachments Sequentially"]
        S3A["createPlanAttachmentIfNeeded<br/>Plan content attachment"]
        S3B["createPlanModeAttachmentIfNeeded<br/>Plan mode attachment"]
        S3C["createSkillAttachmentIfNeeded<br/>Invoked skills attachment"]
        S3A --> S3B --> S3C
    end

    subgraph Step4["Step 4: Delta Full Replay"]
        S4A["getDeferredToolsDeltaAttachment<br/>Deferred tools"]
        S4B["getAgentListingDeltaAttachment<br/>Agent listing"]
        S4C["getMcpInstructionsDeltaAttachment<br/>MCP instructions"]
    end

    Step1 --> Step2
    Step2 --> Step3
    Step3 --> Step4
    Step4 --> Step5["Step 5: Merge into postCompactFileAttachments<br/>Sent with the first post-compaction message to the model"]

The key characteristic of this orchestration is layered and selective. Not all state is restored, and the restoration methods differ — files are restored by re-reading from disk, skills are restored through truncated re-injection, plans are restored via dedicated attachments, and tool declarations are restored through delta replay. Each type of state has the restoration channel best suited to it.

10.8 What Users Can Do

Understanding the post-compaction restoration mechanism, you can adopt the following strategies to optimize your long-session experience:

10.8.1 Keep File Reads Focused

Only the 5 most recently read files are restored after compaction. If you had the model read 20 files in one conversation, only the last 5 will be automatically restored. This means the "reference files" you had the model read in the first half of the conversation — test cases, type definitions, config files — will likely all be lost after compaction.

Strategy: When executing complex tasks, prioritize having the model read files it needs to edit next, rather than "reading all related files first." The last files read are most likely to be preserved after compaction. If a file is critical to the task but hasn't been read in a while, consider having the model re-read it when you sense compaction is approaching (e.g., when the conversation has gone 30+ turns), refreshing its timestamp.

10.8.2 Truncation Expectations for Large Files

Each file restoration is capped at 5K tokens (approximately 2,000-2,500 lines of code, depending on language). If you're editing an oversized file, the model will only see the beginning of the file after compaction.

Strategy: At points where compaction might occur (when you notice the conversation has become very long), explicitly remind the model to focus on specific regions of large files. Or better yet, write key constraints into CLAUDE.md — it's never affected by compaction.

10.8.3 Post-Compaction Skill Behavior Changes

After skills are truncated to 5K tokens, reference content at the tail of the file may be lost. If a skill's behavior changes after compaction, this may be due to truncation.

Strategy: Place the most critical skill instructions at the beginning of the skill file, not the end. Claude Code's truncation strategy preserves the head — meaning skill files should be structured as "critical instructions first, supplementary reference after."

10.8.4 Using Plan Mode to Survive Compaction

If you're executing a multi-step task, using plan mode ensures the plan is fully preserved after compaction. Plan attachments are not subject to the 50K file budget — they have their own independent restoration channel.

Strategy: For complex tasks that might span a compaction boundary, have the model create a plan first (/plan), then execute step by step. Even if compaction occurs mid-execution, the model can restore the plan context and continue working.

10.8.5 Watch for "Post-Compaction Amnesia" Patterns

If the model suddenly, after compaction:

• Re-reads a file it "just" read — this file may have ranked 6th or lower and wasn't restored
• Forgets about a background agent — check if the agent was marked as retrieved or pending
• No longer follows an MCP tool's constraints — delta replay usually covers this, but edge cases may have gaps
• Re-proposes a previously rejected approach — summaries tend to preserve "what was done" rather than "what was rejected"

These are all normal engineering trade-offs. Budget is limited, and 100% restoration is neither possible nor necessary. Understanding which information "survives" compaction and which gets lost is a key skill for navigating long sessions.

10.8.6 Cumulative Effects of Multiple Compactions

An extremely long session may undergo multiple compactions. Each compaction:

• Clears and rebuilds all file state cache (up to 5 files)
• Re-truncates skill content (each time from original content, no "truncation of truncation")
• Regenerates delta attachments (full replay)

But summaries are irreversible. The second compaction's summary is generated from "the first summary + subsequent conversation," with information density decreasing with each pass. After three or four compactions, details from the beginning of the conversation are virtually impossible to preserve.

Strategy: For anticipated ultra-long tasks, proactively use /compact at key intermediate milestones with custom instructions explicitly listing critical information to preserve. Don't wait for the system to auto-compact — at that point you can't control the summary's focus.

10.9 Summary

Post-compaction state restoration reflects the fine balance Claude Code strikes between "information completeness" and "token economy":

1. Snapshot-clear pattern: Save the scene before clearing, ensuring restoration has a basis and cache state is consistent
2. Layered budgets: 50K for file restoration, 25K for skill restoration, an independent plan channel — different types of state have different restoration budgets and strategies
3. Selective restoration: Timestamp sorting + exclusion rules + budget control — three filtering layers ensure only the most valuable content is restored
4. Deliberate non-restoration: The preservation of sentSkillNames is a counter-intuitive but correct decision — the 4K token skill listing injection cost exceeds its benefit
5. Delta full replay: Passing empty message history to trigger a full replay is a clever reuse of existing incremental mechanisms

Core insight: Compaction is not "forgetting" — it's "selectively remembering." Understanding the logic of this selection allows you to predict what the model will remember and what it will forget post-compaction, and adjust your workflow accordingly.

Version Evolution: v2.1.91 Changes

The following analysis is based on v2.1.91 bundle signal comparison, combined with v2.1.88 source code inference.

staleReadFileStateHint and File State Tracking

v2.1.91 adds a new staleReadFileStateHint field in tool result metadata. When tool execution (such as a Bash command) causes the mtime of a previously read file to change, the system sends a staleness hint to the model. This extends the file state tracking system described in this chapter — from "restoring file context post-compaction" to "detecting file changes within a single turn."

In v2.1.88, the readFileState cache (cli/print.ts:1147-1177) already existed in the source code; v2.1.91 exposes it as a model-perceivable output field.

Version Evolution: v2.1.100 Changes

The following analysis is based on v2.1.100 bundle signal comparison, combined with v2.1.88 source code inference.

Tool Result Dedup

v2.1.100 introduces a tool result deduplication mechanism (tengu_tool_result_dedup) — a significant optimization for context budget. When the model makes consecutive tool calls returning identical content (e.g., reading the same file multiple times), the system no longer injects the full result repeatedly, but replaces it with a short reference ID:

// v2.1.100 bundle reverse engineering — replacement on dedup hit
let H = `<identical to result [r${j}] from your ${$.toolName} call earlier — refer to that output>`;
d("tengu_tool_result_dedup", {
  hit: true,
  toolName: OK(K),
  originalBytes: A,
  savedBytes: A - H.length  // Track bytes saved
});
return { ...q, content: H };

// On dedup miss — register new result
r += 1;
let j = `r${_.counter}`;   // Short ID: r1, r2, r3...
_.seen.set(w, { shortId: j, toolName: K });

How it works: The system maintains a seen Map keyed by djb2 hash of tool result content, storing short IDs and tool names. Dedup only applies to string results between 256 bytes and 50,000 bytes — too short isn't worth deduplicating, too long may already be truncated. First occurrences are injected normally with a [result-id: rN] tag appended; subsequent identical results are replaced with the <identical to result [rN]...> reference.

Context budget impact: Dedup directly reduces token consumption in conversation history. A typical file read result may be thousands of tokens; replacing it with a reference costs only ~20 tokens. The savedBytes field provides precise savings tracking, adding a new dimension to context management observability (see Chapter 29).

This complements the post-compaction file restoration mechanism described in this chapter: post-compaction restoration of "most recent 5 files" ensures the model knows what it's been editing, while dedup ensures that before reaching the compaction threshold, duplicate content doesn't unnecessarily consume context budget.

sdk-tools.d.ts Changes

v2.1.100 makes two minor adjustments to tool type definitions:

1. originalFile: string → string | null: The Edit tool's originalFile field relaxed to nullable, supporting new file creation (no original file to reference)
2. toolStats statistics field: New 7-dimensional session-level tool usage statistics for cost analysis and behavioral insights (full field definitions and Dream system correlation analysis in Chapter 24)

Chapter 11: Micro-Compaction — Precise Context Pruning

"The cheapest token is the one you never send."

In the previous chapter (Chapter 9), we thoroughly analyzed auto-compaction — when context approaches the window limit, Claude Code condenses the entire conversation into a structured summary. This is a "nuclear option": effective but costly. It loses the original details of the conversation and requires a full LLM call to generate the summary.

This chapter's protagonist is micro-compaction — a lightweight context pruning strategy. It doesn't generate summaries, doesn't call the LLM, but instead directly clears or deletes old tool call results. The 200 lines of grep output from three minutes ago, the config file cat'd half an hour ago, the Bash command logs from an hour ago — this information is "stale" for the model's current reasoning task. Micro-compaction's core philosophy is: rather than letting this stale content occupy precious context space, remove it precisely at the right moment.

Claude Code implements three micro-compaction mechanisms, which differ fundamentally in trigger conditions, execution approach, and cache impact:

The priority relationship between these three mechanisms is also clear: time-based triggers execute first and short-circuit, cached micro-compaction comes next, and API Context Management exists as an independent declarative layer that's always present.

Interactive version: Click to view the micro-compaction animation — evaluate messages one by one: preserve key conclusions, prune redundant details, remove stale content.

11.1 Time-Based Micro-Compaction: Batch Cleanup After Cache Expiry

11.1.1 Design Intuition

Imagine this scenario: at 10 AM you use Claude Code to complete a complex refactor, then you go to lunch. You come back at 1 PM to continue working — a 3-hour gap.

What happened during those 3 hours? The server-side prompt cache has expired. Anthropic's prompt cache has two TTL tiers: 5 minutes (standard) and 1 hour (extended). Regardless of the tier, both have expired after 3 hours. This means your next API call will rewrite the entire conversation history into the cache — every single token will be re-billed as cache creation.

The logic of time-based micro-compaction is therefore very natural: since the cache has expired and the entire prefix needs to be rewritten anyway, you might as well clean out unneeded old content first, making the rewrite smaller and cheaper.

11.1.2 Configuration Parameters

Configuration is delivered via the GrowthBook feature flag tengu_slate_heron, typed as TimeBasedMCConfig:

// services/compact/timeBasedMCConfig.ts:18-28
export type TimeBasedMCConfig = {
  /** Master switch. When false, time-based microcompact is a no-op. */
  enabled: boolean
  /** Trigger when (now - last assistant timestamp) exceeds this many minutes. */
  gapThresholdMinutes: number
  /** Keep this many most-recent compactable tool results. */
  keepRecent: number
}

const TIME_BASED_MC_CONFIG_DEFAULTS: TimeBasedMCConfig = {
  enabled: false,
  gapThresholdMinutes: 60,
  keepRecent: 5,
}

Each of the three parameters has its own rationale:

• enabled defaults to off — this is a gradual rollout feature, enabled incrementally via GrowthBook
• gapThresholdMinutes: 60 aligns with the server's 1-hour cache TTL — this is the "safe choice." Source comments (line 23) explicitly state: "the server's 1h cache TTL is guaranteed expired for all users, so we never force a miss that wouldn't have happened"
• keepRecent: 5 retains the 5 most recent tool results, providing the model with minimal working context

11.1.3 Trigger Determination

The evaluateTimeBasedTrigger() function (microCompact.ts:422-444) is a pure determination function with no side effects:

// microCompact.ts:422-444
export function evaluateTimeBasedTrigger(
  messages: Message[],
  querySource: QuerySource | undefined,
): { gapMinutes: number; config: TimeBasedMCConfig } | null {
  const config = getTimeBasedMCConfig()
  if (!config.enabled || !querySource || !isMainThreadSource(querySource)) {
    return null
  }
  const lastAssistant = messages.findLast(m => m.type === 'assistant')
  if (!lastAssistant) {
    return null
  }
  const gapMinutes =
    (Date.now() - new Date(lastAssistant.timestamp).getTime()) / 60_000
  if (!Number.isFinite(gapMinutes) || gapMinutes < config.gapThresholdMinutes) {
    return null
  }
  return { gapMinutes, config }
}

Note the guard condition at line 428: !querySource immediately returns null. This differs from cached micro-compaction's behavior — isMainThreadSource() (lines 249-251) treats undefined as the main thread (for cached MC backward compatibility), but time-based triggering explicitly requires querySource to be present. Source comments (lines 429-431) explain: /context, /compact, and other analytical calls invoke microcompactMessages() without a source, and they shouldn't trigger time-based cleanup.

11.1.4 Execution Logic

When trigger conditions are met, maybeTimeBasedMicrocompact() executes the following steps:

flowchart TD
    A["maybeTimeBasedMicrocompact(messages, querySource)"] --> B{"evaluateTimeBasedTrigger()"}
    B -->|null| C["Return null (don't trigger)"]
    B -->|Triggered| D["collectCompactableToolIds(messages)<br/>Collect all compactable tool IDs"]
    D --> E["keepRecent = Math.max(1, config.keepRecent)<br/>Keep at least 1<br/>(slice(-0) returns entire array)"]
    E --> F["keepSet = compactableIds.slice(-keepRecent)<br/>Keep most recent N"]
    F --> G["clearSet = all remaining to clear"]
    G --> H["Iterate messages, replace clearSet<br/>tool_result.content with placeholder text"]
    H --> I["suppressCompactWarning()<br/>Suppress context pressure warning"]
    I --> J["resetMicrocompactState()<br/>Reset cached MC state"]
    J --> K["notifyCacheDeletion()<br/>Notify cache break detector"]

The key implementation detail is in microCompact.ts:470-492 — message modification uses an immutable style:

// microCompact.ts:470-492
let tokensSaved = 0
const result: Message[] = messages.map(message => {
  if (message.type !== 'user' || !Array.isArray(message.message.content)) {
    return message
  }
  let touched = false
  const newContent = message.message.content.map(block => {
    if (
      block.type === 'tool_result' &&
      clearSet.has(block.tool_use_id) &&
      block.content !== TIME_BASED_MC_CLEARED_MESSAGE
    ) {
      tokensSaved += calculateToolResultTokens(block)
      touched = true
      return { ...block, content: TIME_BASED_MC_CLEARED_MESSAGE }
    }
    return block
  })
  if (!touched) return message
  return {
    ...message,
    message: { ...message.message, content: newContent },
  }
})

Note the guard at line 479: block.content !== TIME_BASED_MC_CLEARED_MESSAGE — this prevents double-counting tokensSaved for already-cleared content. This is an idempotency guarantee: multiple executions won't alter the tokensSaved statistics.

11.1.5 Side Effect Chain

After time-based trigger execution completes, three important side effects are produced:

1. suppressCompactWarning() (line 511): Micro-compaction freed context space, suppressing the user-visible "context about to fill" warning
2. resetMicrocompactState() (line 517): Clears the cached MC's tool registration state — since we just modified message content and broke the server cache, all of cached MC's old state (which tools were registered, which were deleted) is invalidated
3. notifyCacheDeletion(querySource) (line 526): Notifies the promptCacheBreakDetection module that the next API response's cache_read_tokens will drop — this is expected behavior, not a cache break bug

The third side effect is particularly subtle. Source comments (lines 520-522) explain why notifyCacheDeletion is used instead of notifyCompaction: "notifyCacheDeletion (not notifyCompaction) because it's already imported here and achieves the same false-positive suppression — adding the second symbol to the import was flagged by the circular-deps check." This is a pragmatic choice under circular dependency constraints: both functions have the same effect (both prevent false positives), but importing the additional symbol would trigger the circular dependency detector.

11.2 Cached Micro-Compaction: Precise Surgery Without Breaking the Cache

11.2.1 The Core Challenge

Time-based micro-compaction has a fundamental limitation: it must modify message content, which means the cache prefix changes, and the next API call incurs full cache creation costs. When the cache has already expired, this doesn't matter (it's being rewritten anyway). But during an active session, this is unacceptable — the cache prefix you just accumulated may represent tens of thousands of tokens in cache creation costs.

Cached micro-compaction solves this problem through Anthropic's API cache_edits feature: it doesn't modify local message content, but instead sends "delete the specified tool results from the server-side cache" directives to the API. The server removes this content in-place within the cache prefix, maintaining prefix continuity — the next request can still hit the existing cache.

11.2.2 How cache_edits Works

The following sequence diagram shows the complete lifecycle of cached micro-compaction:

sequenceDiagram
    participant MC as microCompact.ts
    participant API as claude.ts (API layer)
    participant Server as Anthropic API Server

    MC->>MC: 1. registerToolResult()<br/>Register tool_results
    MC->>MC: 2. getToolResultsToDelete()<br/>Check if threshold reached
    MC->>MC: 3. createCacheEditsBlock()<br/>Create cache_edits block
    MC->>API: 4. Store in pendingCacheEdits

    API->>API: 5. consumePendingCacheEdits()
    API->>API: 6. getPinnedCacheEdits()
    API->>API: 7. addCacheBreakpoints()<br/>Insert cache_edits block in user message<br/>Add cache_reference to tool_result

    API->>Server: 8. API Request: messages contain cache_edits
    Server->>Server: 9. Delete corresponding tool_result in cache<br/>Cache prefix remains continuous
    Server-->>API: 10. Response: cache_deleted_input_tokens (cumulative)

    API->>API: 11. pinCacheEdits()
    API->>API: 12. markToolsSentToAPIState()

Let's dissect this flow step by step.

11.2.3 Tool Registration and Threshold Determination

The cachedMicrocompactPath() function (microCompact.ts:305-399) first scans all messages, registering compactable tool results:

// microCompact.ts:313-329
const compactableToolIds = new Set(collectCompactableToolIds(messages))
// Second pass: register tool results grouped by user message
for (const message of messages) {
  if (message.type === 'user' && Array.isArray(message.message.content)) {
    const groupIds: string[] = []
    for (const block of message.message.content) {
      if (
        block.type === 'tool_result' &&
        compactableToolIds.has(block.tool_use_id) &&
        !state.registeredTools.has(block.tool_use_id)
      ) {
        mod.registerToolResult(state, block.tool_use_id)
        groupIds.push(block.tool_use_id)
      }
    }
    mod.registerToolMessage(state, groupIds)
  }
}

Registration happens in two steps: collectCompactableToolIds() first collects all tool_use IDs from assistant messages that belong to the compactable tool set, then finds the corresponding tool_result entries in user messages, registering them grouped by message. Grouping is necessary because cache_edits deletion granularity is per individual tool_result, but trigger determination is based on total tool count.

After registration, mod.getToolResultsToDelete(state) is called to get the list of tools to delete. This function's logic is controlled by GrowthBook-configured triggerThreshold and keepRecent — when the total registered tool count exceeds triggerThreshold, keep the most recent keepRecent, and mark the rest for deletion.

11.2.4 cache_edits Block Lifecycle

When tools need to be deleted, the code creates a CacheEditsBlock and stores it in the module-level variable pendingCacheEdits:

// microCompact.ts:334-339
const toolsToDelete = mod.getToolResultsToDelete(state)

if (toolsToDelete.length > 0) {
  const cacheEdits = mod.createCacheEditsBlock(state, toolsToDelete)
  if (cacheEdits) {
    pendingCacheEdits = cacheEdits
  }

The consumer of this pendingCacheEdits variable is the API layer's claude.ts. Before building API request parameters (line 1531), the code calls consumePendingCacheEdits() to retrieve pending edit directives in one shot:

// claude.ts:1531-1532
const consumedCacheEdits = cachedMCEnabled ? consumePendingCacheEdits() : null
const consumedPinnedEdits = cachedMCEnabled ? getPinnedCacheEdits() : []

The design of consumePendingCacheEdits() is single-consumption (microCompact.ts:88-94): it immediately clears pendingCacheEdits after being called. Source comments (lines 1528-1530) explain why consumption can't happen inside paramsFromContext: "paramsFromContext is called multiple times (logging, retries), so consuming inside it would cause the first call to steal edits from subsequent calls."

11.2.5 Inserting cache_edits into the API Request

The addCacheBreakpoints() function (claude.ts:3063-3162) is responsible for weaving cache_edits directives into the message array. The core logic has three steps:

Step 1: Re-insert pinned edits (lines 3128-3139)

// claude.ts:3128-3139
for (const pinned of pinnedEdits ?? []) {
  const msg = result[pinned.userMessageIndex]
  if (msg && msg.role === 'user') {
    if (!Array.isArray(msg.content)) {
      msg.content = [{ type: 'text', text: msg.content as string }]
    }
    const dedupedBlock = deduplicateEdits(pinned.block)
    if (dedupedBlock.edits.length > 0) {
      insertBlockAfterToolResults(msg.content, dedupedBlock)
    }
  }
}

On each API call, previously sent cache_edits must be re-sent at the same positions — the server needs to see a complete, consistent edit history to correctly rebuild the cache prefix. This is the purpose of pinnedEdits.

Step 2: Insert new edits (lines 3142-3162)

The new cache_edits block is inserted into the last user message, then the position index is pinned via pinCacheEdits(i, newCacheEdits), ensuring subsequent calls re-send at the same position.

Step 3: Deduplication

The deduplicateEdits() helper function (lines 3116-3125) uses a seenDeleteRefs Set to ensure the same cache_reference doesn't appear in multiple blocks. This prevents an edge case: the same tool result being marked for deletion in different turns.

11.2.6 cache_edits Data Structure

At the API layer, the cache_edits block type definition (claude.ts:3052-3055) is quite concise:

type CachedMCEditsBlock = {
  type: 'cache_edits'
  edits: { type: 'delete'; cache_reference: string }[]
}

Each edit is a delete operation pointing to a cache_reference — a unique identifier the server assigns to each tool_result. The client obtains these references from previous API responses, then references them in subsequent requests to specify which content to delete.

11.2.7 Baseline and Delta Tracking

cachedMicrocompactPath() records a baselineCacheDeletedTokens value when returning results (lines 374-383):

// microCompact.ts:374-383
const lastAsst = messages.findLast(m => m.type === 'assistant')
const baseline =
  lastAsst?.type === 'assistant'
    ? ((
        lastAsst.message.usage as unknown as Record<
          string,
          number | undefined
        >
      )?.cache_deleted_input_tokens ?? 0)
    : 0

The API-returned cache_deleted_input_tokens is a cumulative value — it includes the total tokens deleted by all cache_edits operations in the current session. To calculate the actual delta from the current operation, the baseline before the operation must be recorded, then subtracted from the new cumulative value in the API response. This design avoids imprecise token estimation on the client side.

11.2.8 Mutual Exclusion with Time-Based Trigger

The entry function microcompactMessages() (lines 253-293) defines strict priority:

// microCompact.ts:267-270
const timeBasedResult = maybeTimeBasedMicrocompact(messages, querySource)
if (timeBasedResult) {
  return timeBasedResult
}

Time-based trigger executes first and short-circuits. Source comments (lines 261-266) explain why: "If the gap since the last assistant message exceeds the threshold, the server cache has expired and the full prefix will be rewritten regardless — so content-clear old tool results now ... Cached MC (cache-editing) is skipped when this fires: editing assumes a warm cache, and we just established it's cold."

This is an elegant mutual exclusion design:

• Warm cache: Use cache_edits to delete content without breaking the cache
• Cold cache: Use time-based trigger to directly modify content, since the cache has already expired

The two mechanisms never execute simultaneously.

11.3 API Context Management: Declarative Context Management

11.3.1 From Imperative to Declarative

The previous two micro-compaction mechanisms are both imperative — the client decides which tools to delete, when, and how. API Context Management is declarative: the client only needs to describe "when context exceeds X tokens, clear Y type of content, keep the most recent Z," and the API server executes automatically.

This logic is located in apiMicrocompact.ts. The getAPIContextManagement() function builds a ContextManagementConfig object that's sent with the API request:

// apiMicrocompact.ts:59-62
export type ContextManagementConfig = {
  edits: ContextEditStrategy[]
}

11.3.2 Two Strategy Types

The ContextEditStrategy union type defines two server-executable edit strategies:

Strategy 1: clear_tool_uses_20250919

// apiMicrocompact.ts:36-53
| {
    type: 'clear_tool_uses_20250919'
    trigger?: {
      type: 'input_tokens'
      value: number        // Trigger when input tokens exceed this value
    }
    keep?: {
      type: 'tool_uses'
      value: number        // Keep the most recent N tool uses
    }
    clear_tool_inputs?: boolean | string[]  // Which tools' inputs to clear
    exclude_tools?: string[]                // Which tools to exclude
    clear_at_least?: {
      type: 'input_tokens'
      value: number        // Clear at least this many tokens
    }
  }

Strategy 2: clear_thinking_20251015

// apiMicrocompact.ts:54-56
| {
    type: 'clear_thinking_20251015'
    keep: { type: 'thinking_turns'; value: number } | 'all'
  }

This strategy specifically handles thinking blocks — extended thinking models (like Claude Sonnet 4 with thinking) generate large amounts of thinking process, whose value in subsequent turns decays rapidly.

11.3.3 Strategy Composition Logic

getAPIContextManagement() composes multiple strategies based on runtime conditions:

// apiMicrocompact.ts:64-88
export function getAPIContextManagement(options?: {
  hasThinking?: boolean
  isRedactThinkingActive?: boolean
  clearAllThinking?: boolean
}): ContextManagementConfig | undefined {
  const {
    hasThinking = false,
    isRedactThinkingActive = false,
    clearAllThinking = false,
  } = options ?? {}

  const strategies: ContextEditStrategy[] = []

  // Strategy 1: thinking management
  if (hasThinking && !isRedactThinkingActive) {
    strategies.push({
      type: 'clear_thinking_20251015',
      keep: clearAllThinking
        ? { type: 'thinking_turns', value: 1 }
        : 'all',
    })
  }
  // ...
}

The three branches for thinking strategy:

Note that clearAllThinking sets value to 1 instead of 0 — source comments (line 81) explain: "the API schema requires value >= 1, and omitting the edit falls back to the model-policy default (often 'all'), which wouldn't clear."

11.3.4 Two Modes of Tool Clearing

Within the clear_tool_uses_20250919 strategy, tool clearing has two complementary modes:

Mode 1: Clear tool results (clear_tool_inputs)

// apiMicrocompact.ts:104-124
if (useClearToolResults) {
  const strategy: ContextEditStrategy = {
    type: 'clear_tool_uses_20250919',
    trigger: { type: 'input_tokens', value: triggerThreshold },
    clear_at_least: {
      type: 'input_tokens',
      value: triggerThreshold - keepTarget,
    },
    clear_tool_inputs: TOOLS_CLEARABLE_RESULTS,
  }
  strategies.push(strategy)
}

TOOLS_CLEARABLE_RESULTS (lines 19-26) contains tools whose outputs are large but disposable: Shell commands, Glob, Grep, FileRead, WebFetch, WebSearch. These tools' results are typically search outputs or file contents — the model has already processed them, and clearing them doesn't affect subsequent reasoning.

Mode 2: Clear tool uses (exclude_tools)

// apiMicrocompact.ts:128-149
if (useClearToolUses) {
  const strategy: ContextEditStrategy = {
    type: 'clear_tool_uses_20250919',
    trigger: { type: 'input_tokens', value: triggerThreshold },
    clear_at_least: {
      type: 'input_tokens',
      value: triggerThreshold - keepTarget,
    },
    exclude_tools: TOOLS_CLEARABLE_USES,
  }
  strategies.push(strategy)
}

TOOLS_CLEARABLE_USES (lines 28-32) contains FileEdit, FileWrite, and NotebookEdit — tools whose inputs (i.e., the edit instructions the model sends) are typically larger than their outputs. The semantics of exclude_tools is "clear all tool uses except these tools," allowing the API side to clean up more aggressively.

The default parameters for both modes are identical: triggerThreshold = 180,000 (roughly equal to the auto-compaction warning threshold), keepTarget = 40,000 (keep the last 40K tokens), clear_at_least = triggerThreshold - keepTarget = 140,000 (free at least 140K tokens). These values can be overridden via API_MAX_INPUT_TOKENS and API_TARGET_INPUT_TOKENS environment variables.

11.4 Compactable Tool Set Inventory

The three micro-compaction mechanisms each define different compactable tool sets. Understanding these differences is crucial for predicting which tool results will be cleared.

11.4.1 COMPACTABLE_TOOLS (Shared by Time-Based + Cached Micro-Compaction)

// microCompact.ts:41-50
const COMPACTABLE_TOOLS = new Set<string>([
  FILE_READ_TOOL_NAME,      // Read
  ...SHELL_TOOL_NAMES,       // Bash (multiple shell variants)
  GREP_TOOL_NAME,            // Grep
  GLOB_TOOL_NAME,            // Glob
  WEB_SEARCH_TOOL_NAME,      // WebSearch
  WEB_FETCH_TOOL_NAME,       // WebFetch
  FILE_EDIT_TOOL_NAME,       // Edit
  FILE_WRITE_TOOL_NAME,      // Write
])

11.4.2 TOOLS_CLEARABLE_RESULTS (API clear_tool_inputs)

// apiMicrocompact.ts:19-26
const TOOLS_CLEARABLE_RESULTS = [
  ...SHELL_TOOL_NAMES,
  GLOB_TOOL_NAME,
  GREP_TOOL_NAME,
  FILE_READ_TOOL_NAME,
  WEB_FETCH_TOOL_NAME,
  WEB_SEARCH_TOOL_NAME,
]

11.4.3 TOOLS_CLEARABLE_USES (API exclude_tools)

// apiMicrocompact.ts:28-32
const TOOLS_CLEARABLE_USES = [
  FILE_EDIT_TOOL_NAME,       // Edit
  FILE_WRITE_TOOL_NAME,      // Write
  NOTEBOOK_EDIT_TOOL_NAME,   // NotebookEdit
]

Key differences:

NotebookEdit only appears in the API's TOOLS_CLEARABLE_USES — client-side micro-compaction doesn't handle it. FileEdit and FileWrite clear results (tool_result) on the client side, but in API mode they're excluded from clear_tool_inputs and handled in exclude_tools instead. This layered design lets the client and server each handle the parts best suited to them.

11.5 Coordinating with Cache Break Detection

11.5.1 The Problem: Micro-Compaction Triggers False Positives

The promptCacheBreakDetection.ts module continuously monitors cache_read_tokens in API responses. When this value drops by more than 5% compared to the last request and the absolute decrease exceeds 2,000 tokens, it reports a "cache break" — this typically means some change (system prompt modification, tool list change) has invalidated the cache prefix.

But micro-compaction intentionally reduces cached content. Without coordination, every micro-compaction would trigger a false positive. Claude Code solves this through two notification functions:

11.5.2 notifyCacheDeletion()

// promptCacheBreakDetection.ts:673-682
export function notifyCacheDeletion(
  querySource: QuerySource,
  agentId?: AgentId,
): void {
  const key = getTrackingKey(querySource, agentId)
  const state = key ? previousStateBySource.get(key) : undefined
  if (state) {
    state.cacheDeletionsPending = true
  }
}

When called: After cached micro-compaction sends cache_edits (microCompact.ts:366), and after time-based trigger modifies message content (microCompact.ts:526).

Effect: Sets cacheDeletionsPending = true. When the next API response arrives, checkResponseForCacheBreak() (lines 472-481) sees this flag and skips break detection entirely:

// promptCacheBreakDetection.ts:472-481
if (state.cacheDeletionsPending) {
  state.cacheDeletionsPending = false
  logForDebugging(
    `[PROMPT CACHE] cache deletion applied, cache read: ${prevCacheRead}
     -> ${cacheReadTokens} (expected drop)`,
  )
  state.pendingChanges = null
  return
}

11.5.3 notifyCompaction()

// promptCacheBreakDetection.ts:689-698
export function notifyCompaction(
  querySource: QuerySource,
  agentId?: AgentId,
): void {
  const key = getTrackingKey(querySource, agentId)
  const state = key ? previousStateBySource.get(key) : undefined
  if (state) {
    state.prevCacheReadTokens = null
  }
}

When called: After full compaction (compact.ts:699) and auto-compaction (autoCompact.ts:303) complete.

Effect: Resets prevCacheReadTokens to null, meaning there's no "previous value" for comparison on the next API response — the detector treats it as a "first call" and doesn't report a break.

The difference between the two functions:

11.6 Sub-Agent Isolation

An important scenario the micro-compaction system must handle is sub-agents. Claude Code's main thread can fork multiple sub-agents (session_memory, prompt_suggestion, etc.), each with an independent conversation history.

cachedMicrocompactPath only executes on the main thread (microCompact.ts:275-285):

// microCompact.ts:275-285
if (feature('CACHED_MICROCOMPACT')) {
  const mod = await getCachedMCModule()
  const model = toolUseContext?.options.mainLoopModel ?? getMainLoopModel()
  if (
    mod.isCachedMicrocompactEnabled() &&
    mod.isModelSupportedForCacheEditing(model) &&
    isMainThreadSource(querySource)
  ) {
    return await cachedMicrocompactPath(messages, querySource)
  }
}

Source comments (lines 272-276) explain the reason: "Only run cached MC for the main thread to prevent forked agents from registering their tool_results in the global cachedMCState, which would cause the main thread to try deleting tools that don't exist in its own conversation."

cachedMCState is a module-level global variable. If sub-agents registered their own tool IDs, the main thread would attempt to delete those IDs on its next execution — but they don't exist in the main thread's messages, resulting in invalid cache_edits directives. The isMainThreadSource(querySource) guard completely excludes sub-agents from cached micro-compaction.

The implementation of isMainThreadSource() (lines 249-251) uses prefix matching rather than exact matching:

// microCompact.ts:249-251
function isMainThreadSource(querySource: QuerySource | undefined): boolean {
  return !querySource || querySource.startsWith('repl_main_thread')
}

This is because promptCategory.ts sets querySource to 'repl_main_thread:outputStyle:<style>' — if strict === 'repl_main_thread' checking were used, users with non-default output styles would be silently excluded from cached micro-compaction. Source comments (lines 246-248) flag the old exact matching as a "latent bug."

11.7 What Users Can Do

Understanding the three micro-compaction mechanisms, you can adopt the following strategies to optimize your daily experience:

11.7.1 Understanding Why "Tool Results Disappear"

When you notice the model "forgetting" a previous grep or cat result later in the conversation, this is likely not model hallucination but micro-compaction actively clearing old tool results. Cleared tool results are replaced with [Old tool result content cleared] placeholder text. If you need the model to re-reference a search result, simply ask it to re-execute the search — this is more reliable than trying to make the model "recall" cleared content.

11.7.2 Expectation Management After Long Breaks

If you leave for more than 1 hour and return to continue a conversation, time-based micro-compaction may have cleared most old tool results (keeping only the 5 most recent). This is by design — since the server cache has expired, clearing old content can significantly reduce the cache creation cost of the next API call. Returning and having the model re-read key files is normal and efficient behavior.

11.7.3 Using CLAUDE.md to Preserve Key Context

Micro-compaction only clears tool call results — it doesn't affect CLAUDE.md content injected via system prompts. If certain information (such as project conventions, architectural decisions, key file paths) needs to remain effective throughout the entire session, writing them into CLAUDE.md is the most reliable approach — they're unaffected by any compaction or micro-compaction mechanism.

11.7.4 Cost Awareness for Parallel Tool Calls

When the model simultaneously initiates multiple search or read operations, the aggregate size of these results is limited by the 200K character per-message budget. If you observe some parallel tools' results being persisted to disk (the model will indicate "Output too large, saved to file"), this is the budget mechanism preventing context bloat. You can reduce individual tool output size through more precise search criteria.

11.7.5 Awareness of Non-Compactable Tools

Not all tool results are cleared by micro-compaction. FileEdit, FileWrite, and other write-type tools' results are clearable in client-side micro-compaction, but tools like ToolSearch, SendMessage, etc. are not in the compactable set. Knowing which tool results will be cleared (see the comparison table in Section 11.4) helps you understand the model's behavioral changes during long sessions.

11.8 Design Pattern Summary

The micro-compaction system showcases several engineering patterns worth studying:

Layered degradation: The three mechanisms form a hierarchy — API Context Management serves as a declarative baseline that's always present; cached micro-compaction provides precise surgery in environments supporting cache_edits; time-based trigger serves as the fallback after cache expiry. Each layer has clear preconditions and degradation paths.

Side effect coordination: Micro-compaction is not an isolated operation — it must notify the cache break detector (prevent false positives), reset related state (prevent dirty data), and suppress user warnings (prevent confusion). These three side effects are coordinated through explicit function calls (notifyCacheDeletion, resetMicrocompactState, suppressCompactWarning) rather than an event system, maintaining the traceability of the causal chain.

Single-consumption semantics: consumePendingCacheEdits() immediately clears data after returning it — preventing duplicate consumption during API retry scenarios. This pattern is very practical when one-time state needs to be passed across modules.

Immutable message modification: The time-based trigger path uses map + spread operators to create new message arrays rather than modifying in place. This ensures that if the micro-compaction logic has a bug, the original messages aren't polluted. Cached micro-compaction goes even further — it completely avoids modifying local messages, with all modifications happening server-side.

Circular dependency avoidance: notifyCacheDeletion is reused in place of notifyCompaction solely because importing the latter would trigger the circular dependency detector. This kind of pragmatic compromise is common in large codebases — perfect module boundaries yield to build system constraints. The source comments candidly document this trade-off rather than trying to hide it.

Version Evolution: v2.1.91 Changes

The following analysis is based on v2.1.91 bundle signal comparison, combined with v2.1.88 source code inference.

Cold Compact

v2.1.91 introduces the tengu_cold_compact event, suggesting a new "cold compact" strategy alongside the existing "hot compact" (urgent, triggered automatically when context is about to fill):

Compaction Dialog

The new tengu_autocompact_dialog_opened event indicates v2.1.91 introduces a compaction confirmation UI — users can see a notification before compaction occurs and choose whether to proceed. This improves compaction operation transparency, contrasting with v2.1.88's completely silent compaction.

Rapid Refill Circuit Breaker

tengu_auto_compact_rapid_refill_breaker addresses an edge case: after compaction, if large numbers of tool results quickly refill the context (e.g., reading multiple large files), the system may enter a "compact -> refill -> re-compact" loop. This circuit breaker interrupts the loop when it detects a rapid refill pattern, avoiding pointless API overhead.

Manual Compaction Tracking

tengu_autocompact_command distinguishes user-initiated /compact commands from system-triggered auto-compaction, enabling telemetry data to accurately reflect user intent vs. system behavior.

Chapter 12: Token Budgeting Strategies

Why This Matters

In Chapters 9-11, we analyzed how Claude Code compresses and prunes after the context window "fills up." But there's an even more fundamental question: before content enters the context window, how do you control its size?

A single grep returns 80KB of search results, a single cat reads a 200KB log file, five parallel tool calls each return 50KB — these are real scenarios. Without control, a single tool result could consume a quarter of the context window, and a set of parallel tool calls could push the context straight to the compaction threshold.

Token budgeting strategies are Claude Code's "entry gate" for context management. They operate at three levels:

1. Per-tool-result level: Results exceeding a threshold are persisted to disk, with only a preview shown to the model
2. Per-message level: Total results from one round of parallel tool calls cannot exceed 200K characters
3. Token counting level: Context window usage is tracked via canonical API or rough estimation

This chapter will dive deep into these three levels of implementation, revealing the engineering trade-offs involved — particularly the token counting pitfalls in parallel tool call scenarios.

12.1 Tool Result Persistence: The 50K Character Entry Gate

Core Constants

Tool result size control revolves around two core constants defined in constants/toolLimits.ts:

// constants/toolLimits.ts:13
export const DEFAULT_MAX_RESULT_SIZE_CHARS = 50_000

// constants/toolLimits.ts:49
export const MAX_TOOL_RESULTS_PER_MESSAGE_CHARS = 200_000

The first constant is the global ceiling for a single tool result — when a tool's output exceeds 50,000 characters, the full content is written to a disk file, and the model receives only a substitute message containing the file path and a 2,000-byte preview. The second constant is the aggregate ceiling for all tool results within a single message, designed to guard against the cumulative effect of parallel tool calls.

The relationship between these two constants is worth noting: 200K / 50K = 4, meaning even if four tools each reach the per-tool ceiling, they're still safe within a single message. But if five or more parallel tools simultaneously return results near the ceiling, the message-level budget enforcement kicks in.

Persistence Threshold Calculation

The per-tool persistence threshold isn't simply equal to 50K — it's a multi-layer decision:

// utils/toolResultStorage.ts:55-78
export function getPersistenceThreshold(
  toolName: string,
  declaredMaxResultSizeChars: number,
): number {
  // Infinity = hard opt-out
  if (!Number.isFinite(declaredMaxResultSizeChars)) {
    return declaredMaxResultSizeChars
  }
  const overrides = getFeatureValue_CACHED_MAY_BE_STALE<Record<
    string, number
  > | null>(PERSIST_THRESHOLD_OVERRIDE_FLAG, {})
  const override = overrides?.[toolName]
  if (
    typeof override === 'number' &&
    Number.isFinite(override) &&
    override > 0
  ) {
    return override
  }
  return Math.min(declaredMaxResultSizeChars, DEFAULT_MAX_RESULT_SIZE_CHARS)
}

This function's decision logic forms a priority chain:

Table 12-1: Per-Tool Persistence Threshold Priority Chain

The first priority is particularly interesting: the Read tool sets its maxResultSizeChars to Infinity, meaning it's never persisted. Source comments (lines 59-61) explain the reason — if the Read tool's output were persisted to a file, the model would need to call Read again to read that file, creating a loop. The Read tool controls output size through its own maxTokens parameter and doesn't rely on the general persistence mechanism.

Persistence Flow

When a tool result exceeds the threshold, the maybePersistLargeToolResult function executes the following flow:

flowchart TD
    A["Tool execution completes, produces result"] --> B{"Is result content empty?"}
    B -->|Yes| C["Inject placeholder text<br/>(toolName completed with no output)"]
    B -->|No| D{"Contains image blocks?"}
    D -->|Yes| E["Return as-is<br/>(images must be sent to the model)"]
    D -->|No| F{"size <= threshold?"}
    F -->|Yes| G["Return as-is"]
    F -->|No| H["persistToolResult()<br/>Write to disk file, generate 2KB preview"]
    H --> I["buildLargeToolResultMessage()<br/>Build substitute message:<br/>persisted-output file path + preview"]

Figure 12-1: Tool Result Persistence Decision Flow

Two implementation details worth noting:

Empty result handling (lines 280-295): Empty tool_result content causes certain models (the comments mention "capybara") to mistakenly identify a conversation turn boundary, erroneously ending output. This is because the server-side renderer doesn't insert an \n\nAssistant: marker after tool_result, and empty content matches the \n\nHuman: stop sequence pattern. The solution is injecting a brief placeholder string (toolName completed with no output).

File write idempotency (lines 161-172): persistToolResult uses flag: 'wx' to write files, meaning it throws an EEXIST error if the file already exists — the function catches and ignores this error. This design handles the duplicate persistence problem when microcompact replays original messages: tool_use_id is unique per invocation, content for the same ID is deterministic, so skipping existing files is safe.

Post-Persistence Message Format

After persistence, the message the model actually sees looks like this:

<persisted-output>
Output too large (82.3 KB). Full output saved to:
  /path/to/session/tool-results/toolu_01XYZ.txt

Preview (first 2.0 KB):
[First 2000 bytes of content, truncated at newline boundary]
...
</persisted-output>

The preview generation logic (lines 339-356) tries to truncate at newline boundaries to avoid cutting a line in the middle. If the last newline position is before 50% of the limit (meaning either there's only one line or lines are very long), it falls back to the exact byte limit.

12.2 Per-Message Budget: The 200K Aggregate Ceiling

Why Message-Level Budget Is Needed

The per-tool 50K ceiling is insufficient for parallel tool call scenarios. Consider this situation: the model simultaneously initiates 10 Grep calls searching for different keywords, each returning 40K characters — individually all under the 50K threshold, but totaling 400K characters that would be sent in a single user message to the API. This would immediately consume a large chunk of the context window and potentially trigger unnecessary compaction.

MAX_TOOL_RESULTS_PER_MESSAGE_CHARS = 200_000 (line 49) is the aggregate budget designed for this scenario. Comments (lines 40-48) clearly state the core design principle: messages are evaluated independently — 150K of results in one round and 150K in another are each within budget and don't affect each other.

Message Grouping Complexity

Parallel tool calls are not trivially represented in Claude Code's internal message format. When the model initiates multiple parallel tool calls, the streaming handler produces a separate AssistantMessage record for each content_block_stop event, then each tool_result follows as an independent user message. So the internal message array looks like:

[..., assistant(id=A), user(result_1), assistant(id=A), user(result_2), ...]

Note that multiple assistant records share the same message.id. But before sending to the API, normalizeMessagesForAPI merges consecutive user messages into one. The message-level budget must work according to the grouping the API sees, not the scattered internal representation.

The collectCandidatesByMessage function (lines 600-638) implements this grouping logic. It groups messages by "assistant message boundaries" — only previously unseen assistant message.ids create new group boundaries:

// utils/toolResultStorage.ts:624-635
const seenAsstIds = new Set<string>()
for (const message of messages) {
  if (message.type === 'user') {
    current.push(...collectCandidatesFromMessage(message))
  } else if (message.type === 'assistant') {
    if (!seenAsstIds.has(message.message.id)) {
      flush()
      seenAsstIds.add(message.message.id)
    }
  }
}

There's a subtle edge case here: when parallel tool execution encounters an abort, agent_progress messages may be inserted between tool_result messages. If group boundaries were created at progress messages, those tool_results would be split into different sub-budget groups, bypassing the aggregate budget check — but normalizeMessagesForAPI would merge them into a single over-budget message on the wire. The code avoids this by only creating groups at assistant messages (ignoring progress, attachment, and other types).

Budget Enforcement and State Freezing

The core mechanism of message-level budget enforcement is the enforceToolResultBudget function (lines 769-908). Its design revolves around a key constraint: prompt cache stability. Once the model has seen a tool result (whether full content or substitute preview), this decision must remain consistent across all subsequent API calls. Otherwise, prefix changes would invalidate the prompt cache.

This leads to the "tri-state partition" mechanism:

flowchart LR
    subgraph CRS["ContentReplacementState"]
        direction TB
        S["seenIds: Set &lt; string &gt;<br/>replacements: Map &lt; string, string &gt;"]
        subgraph States["Three States"]
            direction LR
            MA["mustReapply<br/>In seenIds with replacement<br/>-> Re-apply cached replacement"]
            FR["frozen<br/>In seenIds without replacement<br/>-> Immutable, keep as-is"]
            FH["fresh<br/>Not in seenIds<br/>-> Can be selected for replacement"]
        end
        S --> States
    end

Figure 12-2: Tool Result Tri-State Partition and State Transitions

The execution flow before each API call:

1. For each message group, partition candidate tool_results into the above three states
2. mustReapply: Retrieve the previously cached substitute string from the Map and re-apply it identically — zero I/O, byte-level consistency
3. frozen: Previously seen but not replaced results — can no longer be replaced (doing so would break the prompt cache prefix)
4. fresh: New results from this turn — check the aggregate budget; when over budget, select the largest results for persistence in descending size order

The logic for selecting which fresh results to replace is in selectFreshToReplace (lines 675-692): sort in descending size, select one by one until the remaining total (frozen + unselected fresh) drops below the budget limit. If frozen results alone exceed the budget, accept the overage — microcompact will eventually clean them up.

State Marking Timing

There's a carefully designed timing constraint in the code (lines 833-842). Candidates not selected for persistence are immediately synchronously marked as seen (added to seenIds), while candidates selected for persistence are only marked after await persistToolResult() completes — ensuring consistency between seenIds.has(id) and replacements.has(id). The comments explain: if an ID appears in seenIds but not in replacements, it gets classified as frozen (unreplaceable), causing full content to be sent; meanwhile the main thread may be sending the preview — inconsistency would cause prompt cache invalidation.

12.3 Token Counting: Canonical vs. Rough Estimation

Two Counting Mechanisms

Claude Code maintains two token counting mechanisms for different scenarios:

Table 12-2: Comparison of Two Token Counting Mechanisms

Canonical Count: From API Usage to Context Size

The API response's usage object contains multiple fields. The getTokenCountFromUsage function (utils/tokens.ts:46-53) combines them into the full context window size:

// utils/tokens.ts:46-53
export function getTokenCountFromUsage(usage: Usage): number {
  return (
    usage.input_tokens +
    (usage.cache_creation_input_tokens ?? 0) +
    (usage.cache_read_input_tokens ?? 0) +
    usage.output_tokens
  )
}

This calculation includes four components: input_tokens (non-cached input for this request), cache_creation_input_tokens (tokens newly written to cache), cache_read_input_tokens (tokens read from cache), and output_tokens (model-generated output). Note the cache-related fields are optional (?? 0), since not all API providers return them.

Rough Estimation: The 4 Bytes/Token Rule

When API usage is unavailable — for example, when new messages are added between two API calls — Claude Code uses character length divided by an empirical factor to estimate token count. The core estimation function is in services/tokenEstimation.ts:203-208:

// services/tokenEstimation.ts:203-208
export function roughTokenCountEstimation(
  content: string,
  bytesPerToken: number = 4,
): number {
  return Math.round(content.length / bytesPerToken)
}

The default of 4 bytes/token is a conservative estimate. Claude's tokenizer has an actual ratio of roughly 3.5-4.5 for English text, with 4 as the empirical median. But actual ratios vary significantly across content types:

Table 12-3: File-Type-Aware Token Estimation Rules Summary

JSON files use 2 instead of 4 for a reason clearly explained in the comments (lines 213-215): dense JSON contains many single-character tokens ({, }, :, ,, "), which means each token corresponds to roughly 2 bytes on average. If 4 were still used, a 100KB JSON file would be estimated at 25K tokens, while it's actually closer to 50K — this underestimate could cause oversized tool results to slip past persistence, quietly entering the context.

bytesPerTokenForFileType (lines 215-224) returns different factors based on file extension:

// services/tokenEstimation.ts:215-224
export function bytesPerTokenForFileType(fileExtension: string): number {
  switch (fileExtension) {
    case 'json':
    case 'jsonl':
    case 'jsonc':
      return 2
    default:
      return 4
  }
}

Fixed Estimation for Images and Documents

Images and PDF documents are special cases. The API's actual token billing for images is (width x height) / 750, with images scaled to a maximum of 2000x2000 pixels (approximately 5,333 tokens). But in rough estimation, Claude Code uniformly uses a fixed 2,000 tokens (lines 400-412).

There's an important engineering consideration here: if an image or PDF's source.data (base64 encoded) were fed into the general JSON serialization path, a 1MB PDF would produce roughly 1.33M base64 characters, estimated at about 325K tokens at 4 bytes/token — far exceeding the API's actual charge of ~2,000 tokens. Therefore, the code explicitly checks block.type === 'image' || block.type === 'document' before general estimation and returns the fixed value early, avoiding catastrophic overestimation.

12.4 The Token Counting Pitfall of Parallel Tool Calls

The Message Interleaving Problem

Parallel tool calls introduce a subtle but serious token counting problem. tokenCountWithEstimation — Claude Code's canonical function for threshold decisions — has a detailed analysis of this problem in its implementation (utils/tokens.ts:226-261).

The root cause lies in the interleaved structure of the message array. When the model initiates two parallel tool calls, the internal message array takes this form:

Index:  ... i-3       i-2         i-1          i
Message:... asst(A)   user(tr_1)  asst(A)      user(tr_2)
             ^ usage              ^ same usage

The two assistant records share the same message.id and identical usage (since they come from different content blocks of the same API response). If you simply find the last assistant message with usage from the end (index i-1), then estimate the messages after it (only user(tr_2) at index i), you'll miss user(tr_1) at index i-2.

But in the next API request, both user(tr_1) and user(tr_2) will appear in the input. This means tokenCountWithEstimation would systematically underestimate context size.

             Content actually in context
    +--------------------------------------+
    | asst(A) user(tr_1) asst(A) user(tr_2)|
    +--------------------------------------+
              ^                   ^
              Missed!              Only this one estimated

             Corrected estimation range
    +--------------------------------------+
    | asst(A) user(tr_1) asst(A) user(tr_2)|
    +--------------------------------------+
    ^ Backtrack to first assistant with same ID ^
    Estimate all subsequent messages from here

Figure 12-3: Token Count Backtracking Correction for Parallel Tool Calls

Same-ID Backtracking Correction

The solution in tokenCountWithEstimation is to, after finding the last assistant record with usage, backtrack to the first assistant record sharing the same message.id:

// utils/tokens.ts:235-250
const responseId = getAssistantMessageId(message)
if (responseId) {
  let j = i - 1
  while (j >= 0) {
    const prior = messages[j]
    const priorId = prior ? getAssistantMessageId(prior) : undefined
    if (priorId === responseId) {
      i = j  // Anchor to the earlier same-ID record
    } else if (priorId !== undefined) {
      break  // Hit a different API response, stop backtracking
    }
    j--
  }
}

Note three cases in the backtracking logic:

1. priorId === responseId: An earlier fragment of the same API response — move the anchor here
2. priorId !== undefined (and different ID): Hit another API response — stop backtracking
3. priorId === undefined: This is a user/tool_result/attachment message — possibly a tool result interleaved between fragments, continue backtracking

After backtracking completes, all messages after the anchor (including all interleaved tool_results) are included in the rough estimation:

// utils/tokens.ts:253-256
return (
  getTokenCountFromUsage(usage) +
  roughTokenCountEstimationForMessages(messages.slice(i + 1))
)

The final context size = exact usage from the last API response + rough estimation of all subsequently added messages. This "exact baseline + incremental estimation" hybrid approach balances precision and performance.

When Not to Use Which Function

Source comments (lines 118-121, lines 207-212) repeatedly emphasize the importance of function selection:

• tokenCountWithEstimation: The canonical function, used for all threshold comparisons (auto-compaction triggering, session memory initialization, etc.)
• tokenCountFromLastAPIResponse: Only returns the exact token total from the last API call, excluding newly added messages' estimation — not suitable for threshold decisions
• messageTokenCountFromLastAPIResponse: Only returns output_tokens — used solely to measure how many tokens the model generated in a single response, doesn't reflect context window usage

Misusing these functions has real consequences: if messageTokenCountFromLastAPIResponse were used to decide whether compaction is needed, the return value might be only a few thousand (one assistant reply's output), while the actual context is already over 180K — compaction would never trigger, ultimately causing API calls to fail by exceeding the window limit.

12.5 Auxiliary Counting: API Token Counting and Haiku Fallback

countTokens API

Beyond rough estimation, Claude Code can also obtain precise token counts through the API. countMessagesTokensWithAPI (services/tokenEstimation.ts:140-201) calls the anthropic.beta.messages.countTokens endpoint, passing the complete message list and tool definitions to get an exact input_tokens value.

This API is used for scenarios requiring precise counts (such as evaluating tool definition token overhead), but has latency overhead — it requires an additional HTTP round-trip. Therefore, daily threshold decisions use tokenCountWithEstimation's hybrid approach, with API counting reserved for specific scenarios.

Haiku Fallback

When the countTokens API is unavailable (e.g., certain Bedrock configurations), countTokensViaHaikuFallback (lines 251-325) uses a clever alternative: send a max_tokens: 1 request to Haiku (a small model), using the returned usage to obtain the precise input token count. The cost is one small model API call, but it achieves precision.

The function considers multiple platform constraints when selecting the fallback model:

• Vertex global regions: Haiku is unavailable, fall back to Sonnet
• Bedrock + thinking blocks: Haiku 3.5 doesn't support thinking, fall back to Sonnet
• Other cases: Use Haiku (lowest cost)

12.6 End-to-End Token Budget System

Combining all the above mechanisms, Claude Code's token budget forms a multi-layer defense system:

flowchart TB
    subgraph L1["Layer 1: Per-Tool Result Persistence"]
        L1D["Tool executes -> result > threshold? -> Persist to disk + 2KB preview<br/>Threshold = min(tool declared value, 50K) or GrowthBook override<br/>Special cases: Read (Infinity), images (skip)"]
    end
    subgraph L2["Layer 2: Per-Message Aggregate Budget"]
        L2D["Before API call -> tool_result total > 200K?<br/>-> Persist fresh results by descending size until total <= 200K<br/>-> State freeze: seen results' fate never changes (prompt cache stability)"]
    end
    subgraph L3["Layer 3: Context Window Tracking"]
        L3D["tokenCountWithEstimation() = exact usage + incremental rough estimation<br/>-> Drives auto-compaction, micro-compaction decisions<br/>-> Parallel tool calls: same-ID backtracking correction avoids systematic underestimation"]
    end
    subgraph L4["Layer 4: Auto-Compaction / Micro-Compaction (see Chapters 9-11)"]
        L4D["Context approaching window limit -> compress message history / clean old tool results"]
    end
    L1 -->|"If not intercepted"| L2
    L2 -->|"If not intercepted"| L3
    L3 -->|"Threshold exceeded triggers"| L4

Figure 12-4: The Four-Layer Token Budget Defense System

Each layer has clear responsibility boundaries and degradation paths on failure:

• Layer 1 fails (disk persistence error) -> Full result returned as-is, Layers 2 and 4 catch it
• Layer 2's frozen results can't be replaced -> Accept overage, Layer 4's microcompact eventually cleans up
• Layer 3's rough estimation is inaccurate -> May cause compaction to trigger too early or too late, but won't cause data loss

GrowthBook Dynamic Parameter Tuning

Two core thresholds can be adjusted at runtime via GrowthBook feature flags, without releasing a new version:

• tengu_satin_quoll: Per-tool persistence threshold override map
• tengu_hawthorn_window: Per-message aggregate budget global override

getPerMessageBudgetLimit (lines 421-434) demonstrates defensive coding for override values — performing typeof, isFinite, and > 0 triple checks on GrowthBook-returned values, because the cache layer may leak null, NaN, or string-typed values.

12.7 What Users Can Do

12.7.1 Control Tool Output Size

When your grep or bash command returns large output (over 50K characters), results are persisted to disk and the model can only see the first 2KB preview. To avoid this information loss, use more precise search criteria — for example, use grep -l (list filenames only) instead of full-text search, or use head -n 100 to limit command output. This way the model sees complete results rather than a truncated preview.

12.7.2 Watch for Parallel Tool Call Accumulation

When the model simultaneously initiates multiple searches, the aggregate size of all results is limited to 200K characters. If you ask the model to "search for these 10 keywords at once," some results may be persisted due to budget overflow. Consider splitting large-scale searches into several smaller rounds, or let the model search incrementally to keep each round's results within budget.

12.7.3 Special Considerations for JSON Files

JSON files have 2x the token density of regular code (about 2 bytes per token vs. 4). This means a 100KB JSON file actually consumes about 50K tokens, while a TypeScript file of the same size only consumes about 25K tokens. When having the model read large JSON configs or data files, be aware they put more pressure on the context window.

12.7.4 Leverage the Read Tool's Special Status

The Read tool's output is never persisted to disk — it controls size through its own maxTokens parameter. This means file contents read via Read are always presented directly to the model, never truncated to a 2KB preview. If you need the model to see a file's complete contents, using Read is more reliable than the cat command.

12.7.5 Be Aware of Rough Estimation Deviation

Between API calls, Claude Code uses rough estimation (character count / 4) to track context size, with deviation up to +/-50%. This means auto-compaction trigger timing may be earlier or later than expected. If you observe compaction happening at unexpected times, this is typically normal behavior caused by estimation deviation, not a bug.

12.8 Design Insights

Conservative vs. Aggressive Estimation

A recurring design trade-off throughout the token budget system is: it's better to overestimate token count than to underestimate.

• JSON uses 2 bytes/token instead of 4, because underestimating would cause oversized results to slip past persistence
• Images use a fixed 2,000 tokens instead of base64 length estimation, because the latter would cause catastrophic overestimation (context appears "full" when it actually isn't)
• Parallel tool call backtracking correction exists because missing tool_results would cause systematic underestimation

These choices reflect a principle: the token budget is a safety mechanism, not an optimization mechanism. The cost of overestimation is triggering compaction prematurely (minor performance loss); the cost of underestimation is context window overflow (API call failure).

Prompt Cache's Deep Impact on Budget Design

Most of the message-level budget's complexity — tri-state partition, state freezing, byte-level-consistent re-application — stems from a single external constraint: prompt cache requires prefix stability. Without prompt cache, every API call could freely re-evaluate whether all tool results need persistence. But prompt cache's existence means once the model has "seen" a tool result's full content, subsequent calls must continue sending the full content (otherwise prefix changes invalidate the cache).

This constraint transforms what could be a stateless function ("check size, replace if over") into a stateful state machine (ContentReplacementState), and the state must survive across session resumes — which is why ContentReplacementRecord is persisted to the transcript.

This is a textbook example: in AI Agent systems, performance optimizations (prompt cache) can retroactively constrain functional design (budget enforcement), creating unexpected architectural coupling.

Version Evolution: v2.1.91 Changes

The following analysis is based on v2.1.91 bundle signal comparison.

v2.1.91 adds tengu_memory_toggled and tengu_extract_memories_skipped_no_prose events. The former tracks memory feature toggle state; the latter indicates that memory extraction is skipped when messages contain no prose content — a budget-aware optimization that avoids performing pointless memory extraction on pure code/tool-result messages.

Chapter 13: Cache Architecture and Breakpoint Design

Why This Matters

In Chapter 12, we discussed how token budget strategies control the size of content entering the context window. But there is a more insidious cost issue: even when the content within the context window is completely identical, every API call still pays for the system prompt and tool definitions.

For a typical Claude Code session, the system prompt is about 11,000 tokens, and the schema definitions for 40+ tools contribute another ~20,000 tokens — these "fixed overheads" alone consume 30,000+ tokens per call. Over a 50-turn session, that means 1,500,000 tokens are processed repeatedly. At Anthropic's pricing, this is a non-trivial cost.

Anthropic's Prompt Caching mechanism was designed to solve exactly this problem: if the prefix of an API request matches a previous request, the server can reuse the cached KV state, reducing costs for the cached portion by 90%. But cache hits have a strict requirement — the prefix must match byte-for-byte. A single character change causes a cache miss, i.e., a "cache break."

Claude Code builds a sophisticated cache architecture around this constraint, featuring three cache scope levels, two TTL tiers, and a set of "latching" mechanisms to prevent cache breaks. This chapter dives deep into the design and implementation of this architecture.

13.1 Anthropic API Prompt Caching Fundamentals

Prefix Matching Model

Anthropic's prompt caching is based on the prefix matching principle. The server treats an API request as a serialized byte stream, comparing byte-by-byte from the beginning. Once a mismatch is found, the cache "breaks" at that point — everything before can be reused, everything after must be recomputed.

This means cache effectiveness depends entirely on the stability of the request prefix. The serialization order of an API request is roughly:

[System Prompt] → [Tool Definitions] → [Message History]

The system prompt and tool definitions sit at the front of the sequence — any changes to them invalidate the entire cache. Message history is appended at the end, so new messages only incur costs for the incremental portion.

cache_control Markers

To enable caching, you add cache_control markers to content blocks in the API request:

// Basic form of cache_control
{
  type: 'ephemeral'
}

// Extended form (1P exclusive)
{
  type: 'ephemeral',
  scope: 'global' | 'org',   // Cache scope
  ttl: '5m' | '1h'           // Cache time-to-live
}

type: 'ephemeral' is the only supported cache type, indicating a temporary cache breakpoint. Claude Code defines an extended tool schema type in utils/api.ts (lines 68–78) that includes the full cache_control options:

// utils/api.ts:68-78
type BetaToolWithExtras = BetaTool & {
  strict?: boolean
  defer_loading?: boolean
  cache_control?: {
    type: 'ephemeral'
    scope?: 'global' | 'org'
    ttl?: '5m' | '1h'
  }
  eager_input_streaming?: boolean
}

Cache Breakpoint Placement

Claude Code carefully places cache breakpoints in requests, generating a unified cache_control object through the getCacheControl() function (services/api/claude.ts, lines 358–374):

// services/api/claude.ts:358-374
export function getCacheControl({
  scope,
  querySource,
}: {
  scope?: CacheScope
  querySource?: QuerySource
} = {}): {
  type: 'ephemeral'
  ttl?: '1h'
  scope?: CacheScope
} {
  return {
    type: 'ephemeral',
    ...(should1hCacheTTL(querySource) && { ttl: '1h' }),
    ...(scope === 'global' && { scope }),
  }
}

This function appears simple, but every conditional branch embodies a carefully considered caching strategy.

13.2 Three Cache Scope Levels

Claude Code uses three cache scopes, each corresponding to a different reuse granularity. These scopes are assigned to different parts of the system prompt through the splitSysPromptPrefix() function (utils/api.ts, lines 321–435).

Scope Definitions

Table 13-1: Three Cache Scope Levels Compared

Interactive version: Click to view cache hit animation — step-by-step demonstration of the API request cache matching process, supporting 3 scenario switches (first call / same user / different user), with real-time hit rate and cost savings calculations.

Global Cache Scope (global)

Global caching is the most aggressive optimization — content marked as global can share KV cache across all Claude Code users. This means when User A initiates a request and caches the static portion of the system prompt, User B's next request can directly hit that cache.

The eligibility criteria for global caching are very strict: content must be completely invariant, containing no user-specific, organization-specific, or even time-specific information. Claude Code splits the system prompt into static and dynamic parts using a "dynamic boundary marker" (SYSTEM_PROMPT_DYNAMIC_BOUNDARY):

// utils/api.ts:362-404 (simplified)
if (useGlobalCacheFeature) {
  const boundaryIndex = systemPrompt.findIndex(
    s => s === SYSTEM_PROMPT_DYNAMIC_BOUNDARY,
  )
  if (boundaryIndex !== -1) {
    // Content before the boundary → cacheScope: 'global'
    // Content after the boundary → cacheScope: null
    for (let i = 0; i < systemPrompt.length; i++) {
      if (i < boundaryIndex) {
        staticBlocks.push(block)
      } else {
        dynamicBlocks.push(block)
      }
    }
    // ...
    if (staticJoined)
      result.push({ text: staticJoined, cacheScope: 'global' })
    if (dynamicJoined)
      result.push({ text: dynamicJoined, cacheScope: null })
  }
}

Note that dynamic content after the boundary is marked as cacheScope: null — it doesn't even use org-level caching, because the change frequency of dynamic content is too high, cache hit rates would be extremely low, and marking cache breakpoints would only add complexity to the API request.

Organization Cache Scope (org)

When global caching is unavailable (e.g., the global cache feature is not enabled, or content contains organization-specific information), Claude Code falls back to the org level:

// utils/api.ts:411-435 (default mode)
let attributionHeader: string | undefined
let systemPromptPrefix: string | undefined
const rest: string[] = []

for (const block of systemPrompt) {
  if (block.startsWith('x-anthropic-billing-header')) {
    attributionHeader = block
  } else if (CLI_SYSPROMPT_PREFIXES.has(block)) {
    systemPromptPrefix = block
  } else {
    rest.push(block)
  }
}

const result: SystemPromptBlock[] = []
if (attributionHeader)
  result.push({ text: attributionHeader, cacheScope: null })
if (systemPromptPrefix)
  result.push({ text: systemPromptPrefix, cacheScope: 'org' })
const restJoined = rest.join('\n\n')
if (restJoined)
  result.push({ text: restJoined, cacheScope: 'org' })

The chunking strategy here reveals an important detail: the billing attribution header (x-anthropic-billing-header) is marked as null and excluded from caching. This is because the attribution header contains user identity information that cannot be shared even at the org level. The CLI system prompt prefix (CLI_SYSPROMPT_PREFIXES) and remaining system prompt content are both marked as org, shared within the same organization.

Special Handling for MCP Tools

When users configure MCP tools, the global caching strategy changes. Because MCP tool definitions are provided by external servers and their content is unpredictable, including them in global cache would reduce hit rates. Claude Code handles this through the skipGlobalCacheForSystemPrompt flag:

// utils/api.ts:326-360
if (useGlobalCacheFeature && options?.skipGlobalCacheForSystemPrompt) {
  logEvent('tengu_sysprompt_using_tool_based_cache', {
    promptBlockCount: systemPrompt.length,
  })
  // All content downgraded to org scope, skipping boundary markers
  // ...
}

This downgrade is conservative but reasonable — rather than risking frequent global cache misses, it falls back to the more stable org level hit rate.

13.3 Cache TTL Tiers

Default 5 Minutes vs 1 Hour

Anthropic's prompt caching has a default TTL of 5 minutes. This means if a user doesn't initiate a new API request within 5 minutes, the cache expires. For active coding sessions, 5 minutes is usually sufficient. But for scenarios requiring extended thinking or documentation review, 5 minutes may not be enough.

Claude Code supports upgrading the TTL to 1 hour, decided by the should1hCacheTTL() function (services/api/claude.ts, lines 393–434):

// services/api/claude.ts:393-434
function should1hCacheTTL(querySource?: QuerySource): boolean {
  // 3P Bedrock users opt-in via environment variable
  if (
    getAPIProvider() === 'bedrock' &&
    isEnvTruthy(process.env.ENABLE_PROMPT_CACHING_1H_BEDROCK)
  ) {
    return true
  }

  // Latched eligibility check — prevents mid-session overage flips from changing TTL
  let userEligible = getPromptCache1hEligible()
  if (userEligible === null) {
    userEligible =
      process.env.USER_TYPE === 'ant' ||
      (isClaudeAISubscriber() && !currentLimits.isUsingOverage)
    setPromptCache1hEligible(userEligible)
  }
  if (!userEligible) return false

  // Cache allowlist — also latched to maintain session stability
  let allowlist = getPromptCache1hAllowlist()
  if (allowlist === null) {
    const config = getFeatureValue_CACHED_MAY_BE_STALE(
      'tengu_prompt_cache_1h_config', {}
    )
    allowlist = config.allowlist ?? []
    setPromptCache1hAllowlist(allowlist)
  }

  return (
    querySource !== undefined &&
    allowlist.some(pattern =>
      pattern.endsWith('*')
        ? querySource.startsWith(pattern.slice(0, -1))
        : querySource === pattern,
    )
  )
}

The Latching Mechanism for Eligibility Checks

The most critical design in should1hCacheTTL() is latching. On the first call, the function evaluates whether the user is eligible for 1-hour TTL, then stores the result in the global STATE (bootstrap/state.ts):

// bootstrap/state.ts:1700-1706
export function getPromptCache1hEligible(): boolean | null {
  return STATE.promptCache1hEligible
}

export function setPromptCache1hEligible(eligible: boolean | null): void {
  STATE.promptCache1hEligible = eligible
}

Why is latching necessary? Consider the following scenario:

1. At session start, the user is within their subscription quota (isUsingOverage === false), getting 1-hour TTL
2. By turn 30, the user exceeds quota (isUsingOverage === true)
3. If TTL drops from 1 hour back to 5 minutes, the serialization of the cache_control object changes
4. This change causes the API request prefix to no longer match — cache break

A single overage state flip invalidating ~20,000 tokens of system prompt and tool definition cache is clearly unacceptable. The latching mechanism ensures that once the TTL tier is determined at session start, it remains constant throughout the session.

The same latching logic is applied to the GrowthBook allowlist configuration — preventing mid-session GrowthBook disk cache updates from causing TTL behavior changes.

TTL Tier Decision Table

Table 13-2: Cache TTL Decision Matrix

13.4 Beta Header Latching Mechanism

The Problem: Dynamic Headers Causing Cache Busting

Anthropic API requests include a set of "beta headers" identifying experimental features the client uses. These headers are part of the server-side cache key — adding or removing a header changes the cache key, causing a cache break.

Claude Code has multiple features that can dynamically activate or deactivate mid-session:

• AFK Mode (Auto Mode): Automatically executes tasks when the user is away
• Fast Mode: Uses a faster but potentially more expensive model
• Cache Editing (Cached Microcompact): Performs incremental edits within the cache

Each time one of these features changes state, the corresponding beta header is added or removed, triggering a cache break. The code comment (services/api/claude.ts, lines 1405–1410) explicitly describes this problem:

// services/api/claude.ts:1405-1410
// Sticky-on latches for dynamic beta headers. Each header, once first
// sent, keeps being sent for the rest of the session so mid-session
// toggles don't change the server-side cache key and bust ~50-70K tokens.
// Latches are cleared on /clear and /compact via clearBetaHeaderLatches().
// Per-call gates (isAgenticQuery, querySource===repl_main_thread) stay
// per-call so non-agentic queries keep their own stable header set.

Latching Implementation

Claude Code's solution is "sticky-on" latching — once a beta header has been sent in a session, it continues to be sent for the remainder of the session, even if the feature that triggered it has been deactivated.

Here is the latching code for three beta headers (services/api/claude.ts, lines 1412–1442):

AFK Mode Header:

// services/api/claude.ts:1412-1423
let afkHeaderLatched = getAfkModeHeaderLatched() === true
if (feature('TRANSCRIPT_CLASSIFIER')) {
  if (
    !afkHeaderLatched &&
    isAgenticQuery &&
    shouldIncludeFirstPartyOnlyBetas() &&
    (autoModeStateModule?.isAutoModeActive() ?? false)
  ) {
    afkHeaderLatched = true
    setAfkModeHeaderLatched(true)
  }
}

Fast Mode Header:

// services/api/claude.ts:1425-1429
let fastModeHeaderLatched = getFastModeHeaderLatched() === true
if (!fastModeHeaderLatched && isFastMode) {
  fastModeHeaderLatched = true
  setFastModeHeaderLatched(true)
}