Claude Code Architecture, in Full

512,000 lines of TypeScript · 1,902 files · a single-system deep dive · no comparisons

0 · The Project at a Glance, and a Map of the Code

0.1 What this software is

Claude Code is a coding assistant that runs in your terminal. You type claude at the command line, land in an interface where you can hold an ongoing conversation, and then ask it in plain language to read code, change code, run tests, and commit to git for you.

What sets it apart from an ordinary chatbot: it actually operates your computer — reading files, writing files, running shell commands. That ability is also the source of every bit of its engineering complexity.

Why are there two file extensions, .ts and .tsx? A .tsx file is TypeScript that contains JSX syntax (HTML-style tags written directly in code) and is used for UI components. A .ts file is pure logic.

0.2 The source tree, directory by directory

Below is everything under src/. File counts are in parentheses, so you can see at a glance how the bulk is distributed:

0.3 Three things you can read off this map

First: the core is tiny, the periphery is huge

This is not an oversight; it is a conscious trade-off: the core abstractions must be small enough for one person to read and test in full; the code at the edges is allowed to be messy, because it changes often, branches heavily, and the cost of a mistake there is bounded.

Second: what 331 files in utils/ tells you

A utils (utility functions) directory is usually a project’s junk drawer. 331 files is a startling number — but open it up and you find it is not actually a mess; there is clear second-level grouping inside:

• utils/permissions/ — 21 files, a complete permission subsystem
• utils/bash/ — a lexer and abstract syntax tree for shell commands (bashParser.ts 128 KB + ast.ts 109 KB)
• utils/plugins/ — a 107 KB plugin loader + 91 KB marketplace management

These could have been standalone top-level directories. That they ended up inside utils/ is most likely historical (they started as small helper functions, grew up, and never moved out). This is what a real project looks like — and what is worth noting is that internally they remain clearly grouped.

Third: tools/ versus commands/ is the most important dividing line

0.4 The journey of one complete request (a map of the whole book)

The path below strings all 14 chapters together. Skim it once to build an overall picture, then dig into the chapters one at a time.

0.5 Chapter index

1 · The Entry Layer and Startup

This chapter covers what the program does between the moment you type claude in the terminal and the moment the interface appears.

1.1 Four launch modes

The same executable enters one of four completely different run modes depending on its arguments:

1.2 The first design decision at startup: fast-path dispatch

entrypoints/cli.tsx is the real program entry point, and it is only 302 lines. Its header comment gets straight to the point:

Why this matters

First, a bit of background: when a JavaScript program “imports” a module, that module’s top-level code runs immediately. If a program statically imports several hundred modules, then merely starting up means executing all several hundred of them, even if this particular run never uses them.

Bundled, Claude Code is a 300 MB single-file program with an enormous number of modules. If every run loaded all of it, even claude --version — a command that just wants to glance at the version number — would take several seconds.

So the entry file uses dynamic imports — a branch’s modules are loaded only when execution actually reaches that branch:

async function main(): Promise<void> {
  const args = process.argv.slice(2);          // grab the command-line arguments

  // Fast path 1: --version, zero modules loaded
  if (args.length === 1 && (args[0] === '--version' || args[0] === '-v')) {
    console.log(`${MACRO.VERSION} (Claude Code)`);   // the version is baked in at compile time
    return;                                     // return immediately; nothing was loaded
  }

  // Only the remaining paths load the startup profiler
  const { profileCheckpoint } = await import('../utils/startupProfiler.js');
  profileCheckpoint('cli_entry');               // record a timestamp

  // Fast path 2: --dump-system-prompt (export the system prompt, for evals)
  if (feature('DUMP_SYSTEM_PROMPT') && args[0] === '--dump-system-prompt') {
    const { enableConfigs } = await import('../utils/config.js');
    ...
    return;
  }

  // Fast path 3: the local host process for the browser extension
  if (process.argv[2] === '--claude-in-chrome-mcp') { ... return; }

  // Fast path 4: daemon worker (spawned by the main process; performance-sensitive)
  if (feature('DAEMON') && args[0] === '--daemon-worker') {
    const { runDaemonWorker } = await import('../daemon/workerRegistry.js');
    await runDaemonWorker(args[1]);
    return;
  }
  ...
  // No fast path matched → load the full CLI
}

claude-code/src/entrypoints/cli.tsx

The MACRO in MACRO.VERSION is a compile-time macro — it is replaced with a literal string at bundle time. So getting the version number does not even require reading a config file.

1.3 Command-line arguments: 60-plus options

The full command-line interface is defined in main.tsx using the Commander.js library. There are a great many options; below they are grouped by purpose:

Mode and I/O

Permissions and safety

Model and budget

Sessions and resume

Extensions and integrations

1.4 --bare: a minimal mode worth its own section

This option’s official description is long, and it is worth taking apart item by item, because it amounts to a list of “how much extra work a normal startup actually does”:

Read in reverse, that sentence says a normal startup does all of the following:

--bare mode has one more key behavior change, stated plainly in the description:

1.5 Startup sequence

Once fast-path dispatch is out of the way, the full startup runs roughly in this order:

1.6 The three-part structure of the system prompt

The three parts returned in step ⑦ are not an arbitrary split; they correspond to three different levels of cache stability:

The corresponding code in the main loop calls it like this:

// query.ts
const fullSystemPrompt = asSystemPrompt(
  appendSystemContext(systemPrompt, systemContext)     // system prompt + system context
)
...
messages: prependUserContext(messagesForQuery, userContext)   // user context + messages

2 · The Session Layer: QueryEngine

This chapter covers how “a conversation” is represented and managed inside the program.

2.1 The problem it solves

A large language model has no memory — every call has to resend the entire history. So something must hold all the state of the conversation and stay alive between one user question and the next.

That something is QueryEngine. The class comment in the source puts it plainly:

2.2 What state it holds

export class QueryEngine {
  private config: QueryEngineConfig       // immutable configuration (tools, commands, model, etc.)
  private mutableMessages: Message[]      // ★ the full message history; grows forever
  private abortController: AbortController // the abort switch, threaded through the entire call chain
  private permissionDenials: SDKPermissionDenial[]  // record of operations that were denied
  private totalUsage: NonNullableUsage    // cumulative token usage
  private hasHandledOrphanedPermission = false
  private readFileState: FileStateCache   // ★ which files have been read, and which version

  // The two below are "per-turn tracking," cleared at the start of each turn
  private discoveredSkillNames = new Set<string>()   // skills discovered this turn
  private loadedNestedMemoryPaths = new Set<string>() // memory files loaded this turn
}

claude-code/src/QueryEngine.ts

Two of these fields deserve a closer look

readFileState (the file-read state cache) records “which files the model has read, and which version.” It serves three purposes:

1. Preventing duplicate injection. When the memory system prefetches a file, and the model has already read it on its own, it is not injected again as “memory.”
2. Detecting external modification. The model read a.ts; later the user changed it in their editor; now the content the model is holding is stale. The system detects this and injects a notice.
3. A safety check before editing. When the model tries to modify a file it has never read, the tool refuses and tells it to read first — because editing blind is a recipe for mistakes.

abortController is the “cancel switch.” It is passed into every tool call and every network request. When the user presses Ctrl+C, it is pulled, and the whole chain can feel it. Chapter 3 covers how to handle it correctly.

2.3 The full flow of one submitMessage

submitMessage() is the core method of this class. It is an async generator — meaning it does not “finish computing, then return”; it emits messages while it works, and the caller can consume them in real time.

async *submitMessage(
  prompt: string | ContentBlockParam[],
  options?: { uuid?: string; isMeta?: boolean },
): AsyncGenerator<SDKMessage, void, unknown>

(async * is JavaScript’s async generator syntax. To yield a value means “hand this out first; once the caller has it, I continue.” This is the foundation that lets a streaming interface update live.)

The full flow:

2.4 Why the user message must hit disk first

Step ⑤ carries a long comment describing a real production issue:

In plain English: if the program is killed during the few seconds between the user sending a message and the model replying, that conversation is gone for good. Because the write to disk happened only after the model’s reply.

The fix is to move the write forward to the moment “the user message is accepted.” But that surfaces a performance trade-off:

if (persistSession && messagesFromUserInput.length > 0) {
  const transcriptPromise = recordTranscript(messages)
  if (isBareMode()) {
    void transcriptPromise          // ★ bare mode: fire and forget; don't wait for the write
  } else {
    await transcriptPromise         // normal mode: wait for the write before continuing
    ...
  }
}

The comment explains why bare mode gets special treatment:

2.5 Consuming the main loop’s output: one big switch

Once inside the main loop, QueryEngine uses a for await loop to consume each message the main loop emits, handling each type differently:

Why model messages are fire-and-forget while user messages wait synchronously

There is a subtle mechanism in here that is worth unpacking:

The progress message’s “write immediately” also has a dedicated comment:

2.6 The compact boundary: proactively releasing memory

When the main loop emits a “compact boundary” message, QueryEngine does something important:

if (message.subtype === 'compact_boundary' && message.compactMetadata) {
  // Messages before the boundary have been replaced by a summary; release them to the garbage collector
  const mutableBoundaryIdx = this.mutableMessages.length - 1
  if (mutableBoundaryIdx > 0) {
    this.mutableMessages.splice(0, mutableBoundaryIdx)   // ★ delete them from the array outright
  }
  const localBoundaryIdx = messages.length - 1
  if (localBoundaryIdx > 0) {
    messages.splice(0, localBoundaryIdx)
  }
  yield { type:'system', subtype:'compact_boundary', ... }
}

Comment: “Release pre-compaction messages for GC. query.ts already uses getMessagesAfterCompactBoundary() internally, so only post-boundary messages are needed going forward.” (Release the pre-compaction messages to the garbage collector. The main loop already only uses messages after the boundary internally, so only those need to be kept from here on.)

Why go out of the way to do this? Because the message history of a long session can run to hundreds of MB. After compaction, the earlier messages are logically useless, but as long as the array still references them, the garbage collector will not reclaim them — memory keeps climbing until the OS kills the process.

But the disk write must finish before the release

And the order cannot be wrong. Right before the deletion, there is a dedicated piece of disk-write logic:

if (persistSession && message.type === 'system' &&
    message.subtype === 'compact_boundary') {
  const tailUuid = message.compactMetadata?.preservedSegment?.tailUuid
  if (tailUuid) {
    const tailIdx = this.mutableMessages.findLastIndex(m => m.uuid === tailUuid)
    if (tailIdx !== -1) {
      await recordTranscript(this.mutableMessages.slice(0, tailIdx + 1))
    }
  }
}

The comment explains the consequence of not doing this: “If the SDK subprocess restarts before then (claude-desktop kills between turns), tailUuid points to a never-written message → applyPreservedSegmentRelinks fails its tail→head walk → returns without pruning → resume loads full pre-compact history.”

In other words: if the subprocess restarts before then (the desktop app kills the process between turns), the tail node of the preserved segment points to a message that was never written → the relinking function’s tail-to-head walk fails → it returns without pruning → and resume loads the full pre-compaction history.

The symptom: a session the user had compacted comes back after resume looking the way it did before compaction, and the context blows up immediately.

2.7 Three kinds of exit result

submitMessage ends by emitting a result message indicating how the turn finished:

That last error type carries a dedicated diagnostic prefix

errors: (() => {
  const all = getInMemoryErrors()
  const start = errorLogWatermark ? all.lastIndexOf(errorLogWatermark) + 1 : 0
  return [
    // ★ Diagnostic prefix: states outright what the three "failure verdict" conditions each evaluated to
    `[ede_diagnostic] result_type=${edeResultType} ` +
    `last_content_type=${edeLastContentType} stop_reason=${lastStopReason}`,
    ...all.slice(start).map(_ => _.error),
  ]
})()

And the error list is sliced to the range of this turn — using a “watermark”:

// Use a reference, not an index, as the watermark, so the errors array for error_during_execution
// is scoped to this turn. A length index breaks when the 100-entry ring buffer shifts — the index slides away.
// If the marker itself has been rotated out, lastIndexOf returns -1 and we include everything (safe fallback).
const errorLogWatermark = getInMemoryErrors().at(-1)

2.8 ask(): a convenience wrapper for one-shot calls

The end of the file also exports an ask() function, a one-shot wrapper around QueryEngine — create an instance, run one round, hand the file cache back to the caller:

export async function* ask({...}) {
  const engine = new QueryEngine({
    ...,
    readFileCache: cloneFileStateCache(getReadFileCache()),   // ★ what gets passed in is a clone
  })
  try {
    yield* engine.submitMessage(prompt, { uuid: promptUuid, isMeta })
  } finally {
    setReadFileCache(engine.getReadFileState())   // ★ hand it back no matter what
  }
}

Two details:

• The file cache passed in is a clone. So this call’s changes to the cache do not affect the outside world right away — not until it is explicitly handed back at the end.
• The finally block guarantees the hand-back. Even if an exception is thrown or the call is interrupted midway, the knowledge of “which files the model has read” is not lost. Losing it would cause the next turn to inject memory twice or misjudge file freshness.

3 · The Agent Main Loop ★

query.ts, 1,730 lines. This is the single most important file in the whole system.

3.1 The skeleton of the loop

Start by peeling out the outermost structure, with every detail stripped away:

async function* queryLoop(params, consumedCommandUuids) {
  // —— Immutable parameters; never reassigned for the life of the loop ——
  const { systemPrompt, userContext, systemContext, canUseTool,
          fallbackModel, querySource, maxTurns, skipCacheWrite } = params

  // —— Mutable cross-iteration state, gathered into one struct ——
  let state: State = { messages: params.messages, ... }

  // —— One-time setup ——
  const config = buildQueryConfig()               // snapshot the environment and feature flags
  using pendingMemoryPrefetch = startRelevantMemoryPrefetch(...)  // memory prefetch

  while (true) {
    // 1. Destructure what this iteration needs out of state
    // 2. The five-tier context management pipeline   → Chapter 6
    // 3. Call the model (streaming)
    //    └─ execute tools while streaming            → Chapter 5
    // 4. Error recovery decisions → may continue back to the top of the loop
    // 5. No tool calls → return (done)
    // 6. Execute the remaining tools                  → Chapter 5
    // 7. Collect attachments, process queued messages
    // 8. state = {...new state}; on to the next iteration
  }
}

(using is JavaScript’s newer “explicit resource management” syntax: no matter which path the function exits through — normal return, thrown exception, closed from outside — the resource gets cleaned up. Generator functions have many exit paths, and missing any one of them means a resource leak.)

3.2 State: centralizing cross-iteration state

type State = {
  messages: Message[]                    // the current full message history
  toolUseContext: ToolUseContext         // the context object tool execution needs

  // —— Recovery bookkeeping ——
  autoCompactTracking: AutoCompactTrackingState | undefined
  maxOutputTokensRecoveryCount: number   // how many times output truncation has been retried
  hasAttemptedReactiveCompact: boolean   // whether reactive compaction already ran this turn (idempotency guard)
  maxOutputTokensOverride: number | undefined  // whether the output cap has already been escalated
  stopHookActive: boolean | undefined
  pendingToolUseSummary: Promise<ToolUseSummaryMessage | null> | undefined
  turnCount: number

  transition: Continue | undefined       // ★ "why" the previous iteration continued
}

claude-code/src/query.ts

A comment in the source explains why it is centralized:

3.3 transition: a field that exists purely for testability

transition takes part in no business logic. Its sole purpose is to record “why the previous loop iteration continued.” The comment says so directly:

3.4 The seven transition edges, one by one

① next_turn — normal progress

const next: State = {
  messages: [...messagesForQuery, ...assistantMessages, ...toolResults],
  toolUseContext: toolUseContextWithQueryTracking,
  autoCompactTracking: tracking,
  turnCount: nextTurnCount,
  maxOutputTokensRecoveryCount: 0,      // ★ reset
  hasAttemptedReactiveCompact: false,   // ★ reset
  pendingToolUseSummary: nextPendingToolUseSummary,
  maxOutputTokensOverride: undefined,   // ★ reset
  stopHookActive,
  transition: { reason: 'next_turn' },
}
state = next

Note that this is the only path that resets the recovery counters. None of the six that follow do. That rule is the heart of the defense against infinite loops.

② collapse_drain_retry — context too long; drain the collapse first

if (isWithheld413) {
  if (feature('CONTEXT_COLLAPSE') && contextCollapse &&
      state.transition?.reason !== 'collapse_drain_retry') {   // ★ only try if the last iteration wasn't this path
    const drained = contextCollapse.recoverFromOverflow(messagesForQuery, querySource)
    if (drained.committed > 0) {                                // something was actually drained
      state = { messages: drained.messages, ...,
                transition: { reason: 'collapse_drain_retry', committed: drained.committed } }
      continue
    }
  }
}

The way it limits retries is interesting: instead of a boolean lock, it checks “was the previous iteration’s transition this very path?” If the last iteration already drained once and this one is still a 413, draining is not going to solve the problem, so skip straight to the next tier.

③ reactive_compact_retry — reactive full summarization

if ((isWithheld413 || isWithheldMedia) && reactiveCompact) {
  const compacted = await reactiveCompact.tryReactiveCompact({
    hasAttempted: hasAttemptedReactiveCompact,   // ★ the idempotency guard is passed in
    querySource, aborted: ..., messages: messagesForQuery,
    cacheSafeParams: { systemPrompt, userContext, systemContext,
                       toolUseContext, forkContextMessages: messagesForQuery },
  })
  if (compacted) {
    const postCompactMessages = buildPostCompactMessages(compacted)
    for (const msg of postCompactMessages) yield msg
    state = { messages: postCompactMessages, ...,
              hasAttemptedReactiveCompact: true,     // ★ lock it
              transition: { reason: 'reactive_compact_retry' } }
    continue
  }
  // Recovery failed — emit the withheld error and finish
  yield lastMessage
  void executeStopFailureHooks(lastMessage, toolUseContext)
  return { reason: isWithheldMedia ? 'image_error' : 'prompt_too_long' }
}

Note cacheSafeParams — compaction itself makes a model call, and that call reuses the current session’s cache prefix, so the system prompt and the other parameters must be passed through unchanged. Chapter 6 goes into detail.

④ max_output_tokens_escalate — a one-time bump of the output cap

const capEnabled = getFeatureValue_CACHED_MAY_BE_STALE('tengu_otk_slot_v1', false)
if (capEnabled &&
    maxOutputTokensOverride === undefined &&         // ★ hasn't been escalated yet
    !process.env.CLAUDE_CODE_MAX_OUTPUT_TOKENS) {    // ★ the user hasn't set it manually
  logEvent('tengu_max_tokens_escalate', { escalatedTo: ESCALATED_MAX_TOKENS })
  state = { ..., maxOutputTokensOverride: ESCALATED_MAX_TOKENS,
            transition: { reason: 'max_output_tokens_escalate' } }
  continue
}

The logic: the default output cap is 8,000 tokens (to control cost). If the output gets truncated, first resend the request unchanged, raising only the cap to 64,000 — no extra prompt message, nothing to disturb the model’s train of thought. This step happens at most once per turn.

⑤ max_output_tokens_recovery — multi-round continuation

if (maxOutputTokensRecoveryCount < MAX_OUTPUT_TOKENS_RECOVERY_LIMIT) {   // limit is 3
  const recoveryMessage = createUserMessage({
    content:
      `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.`,
    isMeta: true,        // ★ sent to the model only; not shown to the user
  })
  state = { messages: [...messagesForQuery, ...assistantMessages, recoveryMessage],
            maxOutputTokensRecoveryCount: maxOutputTokensRecoveryCount + 1,
            maxOutputTokensOverride: undefined,     // clear the escalation flag so it can escalate again next time
            transition: { reason: 'max_output_tokens_recovery',
                          attempt: maxOutputTokensRecoveryCount + 1 } }
  continue
}
// All 3 attempts used up — emit the withheld error
yield lastMessage

Each of the three sentences in that continuation instruction solves a specific problem:

⑥ stop_hook_blocking — a pre-finish check fails

const stopHookResult = yield* handleStopHooks(...)

if (stopHookResult.preventContinuation) return { reason: 'stop_hook_prevented' }

if (stopHookResult.blockingErrors.length > 0) {
  state = {
    messages: [...messagesForQuery, ...assistantMessages, ...stopHookResult.blockingErrors],
    maxOutputTokensRecoveryCount: 0,
    // ★★★ This line is where the most important comment in the whole book lives
    hasAttemptedReactiveCompact,     // Preserve it! Do NOT reset!
    stopHookActive: true,
    transition: { reason: 'stop_hook_blocking' },
  }
  continue
}

⑦ token_budget_continuation — budget not exhausted; keep digging

if (feature('TOKEN_BUDGET')) {
  const decision = checkTokenBudget(budgetTracker!, toolUseContext.agentId,
                                    getCurrentTurnTokenBudget(), getTurnOutputTokens())
  if (decision.action === 'continue') {
    incrementBudgetContinuationCount()
    state = { messages: [...messagesForQuery, ...assistantMessages,
                createUserMessage({ content: decision.nudgeMessage, isMeta: true })],
              transition: { reason: 'token_budget_continuation' } }
    continue
  }
  if (decision.completionEvent?.diminishingReturns) {
    logForDebugging(`Token budget early stop: diminishing returns at ${...}%`)
  }
}

This mechanism runs in the opposite direction: not “prevent using too much,” but “the user explicitly gave a budget, so use it fully.” And it has “diminishing returns” detection — if continuing to dig is no longer producing anything new, it stops early instead of burning through the budget.

3.5 The error-withholding mechanism

Inside the streaming loop, three kinds of recoverable error are never emitted to the external caller:

let withheld = false                      // withheld = held back

if (feature('CONTEXT_COLLAPSE')) {
  if (contextCollapse?.isWithheldPromptTooLong(message, isPromptTooLongMessage, querySource))
    withheld = true
}
if (reactiveCompact?.isWithheldPromptTooLong(message))          withheld = true
if (mediaRecoveryEnabled &&
    reactiveCompact?.isWithheldMediaSizeError(message))          withheld = true
if (isWithheldMaxOutputTokens(message))                          withheld = true

if (!withheld) { yield yieldMessage }     // only messages that weren't withheld get emitted

// ★ But withheld or not, it goes into the internal array so the recovery logic below can find it
if (message.type === 'assistant') assistantMessages.push(message)

Only when every recovery option is exhausted is it emitted: yield lastMessage.

3.6 Interrupt handling

This is the part that home-grown agents most often miss, and the part most likely to blow up in production.

The shape of the problem

The fix

if (toolUseContext.abortController.signal.aborted) {
  if (streamingToolExecutor) {
    // Streaming executor in use: consume getRemainingResults()
    // It generates synthetic (fabricated) results for tools that are "queued" or "executing"
    for await (const update of streamingToolExecutor.getRemainingResults()) {
      if (update.message) yield update.message
    }
  } else {
    // No streaming executor: fabricate a fallback result marked as an error for every tool_use
    yield* yieldMissingToolResultBlocks(assistantMessages, 'Interrupted by user')
  }
  ...
  // Interruption message: skip it if this is a "submit interrupt" (caused by the user sending a new message),
  // because the user message that follows immediately explains the situation on its own
  if (toolUseContext.abortController.signal.reason !== 'interrupt') {
    yield createUserInterruptionMessage({ toolUse: false })
  }
  return { reason: 'aborted_streaming' }
}

That fallback function is short, but it is the safety net for the entire system:

function* yieldMissingToolResultBlocks(assistantMessages, errorMessage) {
  for (const assistantMessage of assistantMessages) {
    const toolUseBlocks = assistantMessage.message.content
        .filter(content => content.type === 'tool_use')
    for (const toolUse of toolUseBlocks) {
      yield createUserMessage({
        content: [{ type:'tool_result', content: errorMessage,
                    is_error: true,
                    tool_use_id: toolUse.id }],      // ★ the id must match
        toolUseResult: errorMessage,
        sourceToolAssistantUUID: assistantMessage.uuid,
      })
    }
  }
}

It is called from four places: on user interrupt, on switching to the fallback model, on falling back after a streaming request fails, and in the outermost exception handler.

3.7 Model fallback: three actions

When the primary model is overloaded (the server reports insufficient capacity), the loop switches to the fallback model. Claude Code does three things:

catch (innerError) {
  if (innerError instanceof FallbackTriggeredError && fallbackModel) {
    currentModel = fallbackModel
    attemptWithFallback = true

    // Action 1: fill in synthetic results for every tool call already issued
    yield* yieldMissingToolResultBlocks(assistantMessages, 'Model fallback triggered')
    assistantMessages.length = 0
    toolResults.length = 0
    toolUseBlocks.length = 0
    needsFollowUp = false

    // Action 2: discard the pending results in the streaming executor and build a fresh one
    //           so orphaned results carrying old tool_use_ids don't leak into the retried request
    if (streamingToolExecutor) {
      streamingToolExecutor.discard()
      streamingToolExecutor = new StreamingToolExecutor(...)
    }

    toolUseContext.options.mainLoopModel = fallbackModel

    // Action 3: ★ strip thinking-block signatures
    if (process.env.USER_TYPE === 'ant') {
      messagesForQuery = stripSignatureBlocks(messagesForQuery)
    }
    ...
    yield createSystemMessage(
      `Switched to ${renderModelName(innerError.fallbackModel)} due to high demand for ...`,
      'warning')
    continue
  }
  throw innerError
}

The comment on the third action:

3.8 The three laws of thinking blocks

Near the top of the file is a comment written like a spellbook, but its content is a set of real hard constraints:

Rule 3 directly constrains every context compaction implementation in Chapter 6: compaction, truncation, and replay — if any one of them cuts through the middle of a “thinking-block trajectory,” the API rejects the entire request.

That means you cannot simply say “keep the last 6 messages and compact everything before them” — if message 7 is a thinking block and message 6 is its corresponding tool result, you have chopped a complete trajectory in half. The boundary of the protected window must fall in a gap between trajectories.

3.9 Other mechanisms in the loop

Query chain tracing

const queryTracking = toolUseContext.queryTracking
  ? { chainId: toolUseContext.queryTracking.chainId,
      depth:   toolUseContext.queryTracking.depth + 1 }   // subagent depth +1
  : { chainId: deps.uuid(), depth: 0 }                    // top level: start a new chain

Every model call carries a “chain ID + depth.” The main agent is depth 0, a subagent it spawns is depth 1, and so on. Every telemetry event carries these two fields — so when analyzing the data, every model call triggered by a single user request (including all the subagents’) can be strung together into a tree.

Queued messages: mid-turn injection

const sleepRan = toolUseBlocks.some(b => b.name === SLEEP_TOOL_NAME)
const isMainThread = querySource.startsWith('repl_main_thread') || querySource === 'sdk'
const currentAgentId = toolUseContext.agentId

const queuedCommandsSnapshot = getCommandsByMaxPriority(sleepRan ? 'later' : 'next')
  .filter(cmd => {
    if (isSlashCommand(cmd)) return false            // slash commands can't be injected mid-turn
    if (isMainThread) return cmd.agentId === undefined
    // ★ Subagents only take task notifications addressed to them; they never get user prompts
    return cmd.mode === 'task-notification' && cmd.agentId === currentAgentId
  })

This handles the case where the user sends another message while the model is thinking, or a background task finishes and needs to notify the model.

The key isolation rule is in the comment:

Tool summaries: generated asynchronously by a cheap small model

if (config.gates.emitToolUseSummaries && toolUseBlocks.length > 0 &&
    !toolUseContext.abortController.signal.aborted &&
    !toolUseContext.agentId) {          // ★ subagents don't generate them (they're not shown in the UI)
  ...
  // Kick off summary generation but don't wait for it — the result is passed to the next iteration
  nextPendingToolUseSummary = generateToolUseSummary({...})
    .then(summary => summary ? createToolUseSummaryMessage(summary, toolUseIds) : null)
    .catch(() => null)
}

This summary uses Haiku (a smaller, cheaper model) and takes about 1 second. It is kicked off in one iteration and consumed in the next:

// At the top of the next iteration
if (pendingToolUseSummary) {
  const summary = await pendingToolUseSummary
  if (summary) yield summary
}

Comment: “Yield tool use summary from previous turn — haiku (~1s) resolved during model streaming (5-30s)” (emit the previous turn’s tool summary — Haiku takes about 1 second, and it finishes during the 5 to 30 seconds the model spends streaming).

How the memory prefetch is consumed

if (pendingMemoryPrefetch &&
    pendingMemoryPrefetch.settledAt !== null &&        // ★ consume only once settled
    pendingMemoryPrefetch.consumedOnIteration === -1) { // ★ and not yet consumed
  const memoryAttachments = filterDuplicateMemoryAttachments(
    await pendingMemoryPrefetch.promise,
    toolUseContext.readFileState,      // ★ filter by already-read file state to avoid duplicate injection
  )
  for (const memAttachment of memoryAttachments) { ... }
  pendingMemoryPrefetch.consumedOnIteration = turnCount - 1
}

Comment: “only if settled and not already consumed on an earlier iteration. If not settled yet, skip (zero-wait) and retry next iteration — the prefetch gets as many chances as there are loop iterations before the turn ends.”

In other words: consume it only if it has settled and was not already consumed on an earlier iteration. If it has not settled yet, skip it (zero wait) and try again next iteration — the prefetch gets as many chances as there are iterations before the turn ends.

3.10 Every exit point of the loop

Ten named exit points. Each one can be counted separately in data analysis — the foundation of observability (Chapter 12).

4 · The Tool Model

This chapter covers how “a tool” is modeled inside the program, and how the 40 built-in tools are organized and served to the model.

4.1 The Tool interface: seven orthogonal capability groups

Tool.ts is 793 lines in total, of which the type definition Tool<Input, Output, Progress> takes up 330. It slices “every question a tool needs to answer” into seven non-overlapping capability groups:

4.2 Why the “safety predicates” deserve their own group

Because this group is not for humans; it is for the scheduler. The scheduler knows nothing about any concrete tool — it has no idea what Bash is or what Read is. It only asks these few yes/no questions and arranges execution accordingly:

An easily overlooked detail: the predicates take arguments

isConcurrencySafe(input) is a method that takes the input, not a static flag.

Same Bash tool: running ls (list files) is concurrency-safe; running rm -rf (delete) is not. Safety depends on what this particular call is going to do, not on the tool type. Modeled as a static flag, the Bash tool could only ever declare “I am unsafe,” giving up every opportunity for parallelism.

4.3 Fail-safe defaults

Every tool is created through a factory function:

const TOOL_DEFAULTS = {
  isEnabled:          () => true,
  isConcurrencySafe:  () => false,   // ← default: "cannot run in parallel"
  isReadOnly:         () => false,   // ← default: "writes"
  isDestructive:      () => false,
  checkPermissions:   (input) => ({ behavior:'allow', updatedInput: input }),
  toAutoClassifierInput: () => '',   // ← default: "skip the safety classifier"
  userFacingName:     () => '',
}

export function buildTool<D>(def: D): BuiltTool<D> {
  return { ...TOOL_DEFAULTS,               // lay down the defaults first
           userFacingName: () => def.name,
           ...def }                        // then override with the tool's own definition
}

claude-code/src/Tool.ts

A source comment sums up the design principle: “Defaults (fail-closed where it matters)”.

The one default that looks like it breaks the rule

toAutoClassifierInput defaults to returning an empty string, meaning “this tool stays out of the safety classifier’s view.” The comment explains why:

4.4 The 40 built-in tools, by category

The tool list is assembled conditionally

export function getAllBaseTools(): Tools {
  return [
    AgentTool,
    TaskOutputTool,
    BashTool,
    // The internal native build embeds fast search programs in the executable, and
    // find/grep in the shell are aliased to them, so standalone Glob/Grep tools aren't needed
    ...(hasEmbeddedSearchTools() ? [] : [GlobTool, GrepTool]),
    ExitPlanModeV2Tool,
    FileReadTool, FileEditTool, FileWriteTool, NotebookEditTool,
    WebFetchTool, TodoWriteTool, WebSearchTool, TaskStopTool,
    AskUserQuestionTool, SkillTool, EnterPlanModeTool,
    ...(process.env.USER_TYPE === 'ant' ? [ConfigTool] : []),      // internal users only
    ...(isTodoV2Enabled() ? [TaskCreateTool, TaskGetTool, ...] : []),
    ...(isEnvTruthy(process.env.ENABLE_LSP_TOOL) ? [LSPTool] : []),
    ...(isWorktreeModeEnabled() ? [EnterWorktreeTool, ExitWorktreeTool] : []),
    ...(isAgentSwarmsEnabled() ? [getTeamCreateTool(), getTeamDeleteTool()] : []),
    ...cronTools,
    ...(isToolSearchEnabledOptimistic() ? [ToolSearchTool] : []),
  ]
}

Three dimensions of condition: compile-time feature flags (feature('XXX')), runtime environment variables, and user type (internal / external). Chapter 13 explains how compile-time flags achieve “this code does not even exist in the external build.”

4.5 Progressive tool loading

The problem

Every tool’s full description goes into the system prompt, and the system prompt is resent every turn. When a user has connected a dozen or so MCP external servers, the total tool count can exceed a hundred, and the descriptions add up to tens of thousands of tokens — paid for again every turn.

The fix: defer_loading

The two related fields:

• shouldDefer: true — this tool is lazily loaded
• alwaysLoad: true — never deferred. For tools the model must see on the very first turn. MCP external tools can declare this on the server side via _meta['anthropic/alwaysLoad']

How to write the keywords

Remediation when deferred loading goes wrong

Deferred loading has a side effect: the model may call a tool from memory before its full description has been loaded, and get the parameters wrong. So when parameter validation fails, there is a special hint:

const schemaHint = buildSchemaNotSentHint(tool, toolUseContext.messages,
                                          toolUseContext.options.tools)
if (schemaHint) {
  logEvent('tengu_deferred_tool_schema_not_sent', {
    toolName: sanitizeToolNameForAnalytics(tool.name), isMcp: tool.isMcp ?? false })
  errorContent += schemaHint    // append the hint: "you haven't loaded this tool's description yet; search for it first"
}

And this situation has its own telemetry event (tengu_deferred_tool_schema_not_sent) — which tells you they are monitoring “the rate of call failures caused by deferred loading” to judge the net benefit of this optimization.

4.6 Tool list assembly: a hidden constraint about caching

This code is only 8 lines long, but what it reveals is extremely valuable:

export function assembleToolPool(permissionContext, mcpTools): Tools {
  const builtInTools    = getTools(permissionContext)               // built-in tools
  const allowedMcpTools = filterToolsByDenyRules(mcpTools, permissionContext)

  const byName = (a, b) => a.name.localeCompare(b.name)
  return uniqBy(
    [...builtInTools].sort(byName)             // ★ built-in tools sorted on their own
      .concat(allowedMcpTools.sort(byName)),   // ★ external tools sorted on their own, then appended
    'name',                                    // dedup by name; built-ins win
  )
}

claude-code/src/tools.ts

Note: the two groups are sorted separately and then concatenated, not merged into one big array and sorted together. To someone unfamiliar with the caching mechanism, this looks like needless complication. The source comment gives the answer:

How serious this is

The same file has another comment:

/**
 * NOTE: This MUST stay in sync with
 * https://console.statsig.com/.../claude_code_global_system_caching,
 * in order to cache the system prompt across users.
 */
export function getAllBaseTools(): Tools { ... }

In other words: note: this function must stay in sync with a particular live configuration so that the system prompt’s cache can be shared across all users.

4.7 backfillObservableInput: an extreme example of cache protection

Sometimes a tool needs to add derived fields for logs, hooks, or the SDK (for example, expanding a relative path into an absolute one). But the original parameter object that gets sent back to the API must never be changed — change one byte and the cache is gone.

/**
 * Called on copies of tool_use input before observers see it (SDK stream,
 * transcript, canUseTool, PreToolUse/PostToolUse hooks). Mutate in place
 * to add legacy/derived fields. Must be idempotent. The original API-bound
 * input is never mutated (preserves prompt cache).
 */
backfillObservableInput?(input: Record<string, unknown>): void

The implementation at the call site is even more careful:

const originalInput = block.input as Record<string, unknown>
const inputCopy = { ...originalInput }        // clone
tool.backfillObservableInput(inputCopy)       // mutate only the clone

// ★ Produce a cloned message only when the backfill "added fields";
//   if it merely overwrote existing fields, don't even clone
const addedFields = Object.keys(inputCopy).some(k => !(k in originalInput))
if (addedFields) {
  clonedContent ??= [...message.message.content]
  clonedContent[i] = { ...block, input: inputCopy }
}

Why no clone when it “only overwrites existing fields”? The comment explains:

This level of restraint shows that “protect the cache” is a first-class constraint in this system — even a field overwrite that might affect test fixtures is avoided.

5 · Tool Execution

This chapter covers how the program runs a batch of tool calls to completion once the model has produced them.

5.1 The execution pipeline at a glance

5.2 Concurrency partitioning: a greedy algorithm

function partitionToolCalls(toolUseMessages, 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 {
            // If the predicate throws (e.g. shell quote parsing failed),
            // conservatively treat it as "unsafe"
            return false
          }
        })()
      : false                        // parameters don't even parse → also treated as unsafe

    if (isConcurrencySafe && acc[acc.length - 1]?.isConcurrencySafe) {
      acc[acc.length - 1]!.blocks.push(toolUse)      // merge into the previous parallel batch
    } else {
      acc.push({ isConcurrencySafe, blocks: [toolUse] })   // open a new batch
    }
    return acc
  }, [])
}

claude-code/src/services/tools/toolOrchestration.ts

The effect in practice:

5.3 Context modifications are queued until the batch ends

Some tools modify the shared context object (for instance EnterPlanMode switches the permission mode). If every tool in a parallel batch applied its change immediately, you would have a race.

if (isConcurrencySafe) {
  const queuedContextModifiers: Record<string, ((ctx) => ToolUseContext)[]> = {}

  for await (const update of runToolsConcurrently(blocks, ...)) {
    if (update.contextModifier) {
      const { toolUseID, modifyContext } = update.contextModifier
      if (!queuedContextModifiers[toolUseID]) queuedContextModifiers[toolUseID] = []
      queuedContextModifiers[toolUseID].push(modifyContext)      // ★ queue it first
    }
    yield { message: update.message, newContext: currentContext }  // still using the old context
  }

  // ★ Once the whole batch is done, apply the modifications strictly in the original tool-call order
  for (const block of blocks) {
    const modifiers = queuedContextModifiers[block.id]
    if (!modifiers) continue
    for (const modifier of modifiers) currentContext = modifier(currentContext)
  }
  yield { newContext: currentContext }
}

And Tool.ts has a matching backstop constraint:

5.4 A single execution: the full flow of runToolUse

Step ①: look up the tool by name, with alias support

// First look among the "tools the model can see"
let tool = findToolByName(toolUseContext.options.tools, toolName)

// Not found → check whether it's a deprecated name (old transcripts may still use the old name)
// e.g. an old transcript calls "KillShell", which is now an alias for "TaskStop"
// Fall back only when the name matches an "alias" rather than a "primary name"

The problem this design solves: after a tool is renamed, an old conversation the user resumes with --resume still contains call records under the old name. If that simply produced “tool does not exist,” that historical message could never be processed correctly.

Step ③: parameter shape validation, with an honest comment attached

// Validate input types with zod
// (surprisingly, the model is not great at generating valid input)
const parsedInput = tool.inputSchema.safeParse(input)
if (!parsedInput.success) {
  let errorContent = formatZodValidationError(tool.name, parsedInput.error)
  const schemaHint = buildSchemaNotSentHint(tool, ...)   // see Section 4.5
  if (schemaHint) errorContent += schemaHint
  ...
  return [{ message: createUserMessage({
    content: [{ type:'tool_result',
                content: `<tool_use_error>InputValidationError: ${errorContent}</tool_use_error>`,
                is_error: true, tool_use_id: toolUseID }],
    ... }) }]
}

That parenthetical — “surprisingly, the model is not great at generating valid input” — is a rare bit of candid griping in the source, but it states an important fact: even the strongest model’s tool parameters need strict validation and cannot be trusted.

Note the form of the error result: it is not a thrown exception; it is returned to the model as an ordinary “tool result”, just flagged with is_error: true and wrapped in a <tool_use_error> tag. That way the model can see what it got wrong and correct itself on the next turn.

Step ⑤: speculatively starting the classifier early

// Speculatively start the bash allow classifier check early so it runs in
// parallel with pre-tool hooks, deny/ask classifiers, and permission dialog
// setup. The UI indicator (setClassifierChecking) is NOT set here — it's
// set in interactiveHandler.ts only when the permission check returns `ask`
// with a pendingClassifierCheck. This avoids flashing "classifier running"

In other words: speculatively start the bash allow-classifier check early, so it runs in parallel with the pre-tool hooks, the deny/ask classifiers, and permission dialog setup. The “classifier running” UI indicator is not set here — it is set in the interactive handler only when the permission check returns “ask” along with a pending classifier check. That avoids the indicator flashing on and off.

5.5 The streaming tool executor

The conventional approach is to wait for the model’s entire response to finish streaming before running any tools. Claude Code’s approach: the moment the model finishes writing one tool call, start executing it.

Why this is possible

The model emits one token at a time. If this turn is going to write three tool calls, then when the first one is finished, the second has not yet begun — there is a gap of several seconds in between.

// Inside the streaming loop in query.ts
if (message.type === 'assistant') {
  const msgToolUseBlocks = message.message.content.filter(c => c.type === 'tool_use')
  if (msgToolUseBlocks.length > 0) {
    toolUseBlocks.push(...msgToolUseBlocks)
    needsFollowUp = true
  }
  if (streamingToolExecutor && !toolUseContext.abortController.signal.aborted) {
    for (const toolBlock of msgToolUseBlocks) {
      streamingToolExecutor.addTool(toolBlock, message)     // ★ enqueue the moment it arrives
    }
  }
}
// In the same loop, keep harvesting the ones that have finished
if (streamingToolExecutor && !toolUseContext.abortController.signal.aborted) {
  for (const result of streamingToolExecutor.getCompletedResults()) {
    if (result.message) {
      yield result.message
      toolResults.push(...normalizeMessagesForAPI([result.message], ...))
    }
  }
}

The executor’s internal state machine

type ToolStatus = 'queued' | 'executing' | 'completed' | 'yielded'
//                 waiting    running       finished      emitted

type TrackedTool = {
  id: string
  block: ToolUseBlock
  assistantMessage: AssistantMessage
  status: ToolStatus
  isConcurrencySafe: boolean
  promise?: Promise<void>
  results?: Message[]
  pendingProgress: Message[]      // progress messages stored separately; emitted immediately
  contextModifiers?: Array<(ctx: ToolUseContext) => ToolUseContext>
}

Concurrency rules

private canExecuteTool(isConcurrencySafe: boolean): boolean {
  const executingTools = this.tools.filter(t => t.status === 'executing')
  return (
    executingTools.length === 0                                   // nothing running → go ahead
    || (isConcurrencySafe && executingTools.every(t => t.isConcurrencySafe))
                                        // or: I'm safe AND everything running is safe
  )
}

private async processQueue(): Promise<void> {
  for (const tool of this.tools) {
    if (tool.status !== 'queued') continue
    if (this.canExecuteTool(tool.isConcurrencySafe)) {
      await this.executeTool(tool)
    } else {
      // Can't run this tool. Unsafe tools must preserve order, so stop right here
      // and don't try the tools after it
      if (!tool.isConcurrencySafe) break
    }
  }
}

The class comment sums up three rules:

5.6 The sibling abort controller: the most elegant design in the file

// Child of toolUseContext.abortController. Fires when a Bash tool errors
// so sibling subprocesses die immediately instead of running to completion.
// Aborting this does NOT abort the parent — query.ts won't end the turn.
private siblingAbortController: AbortController

constructor(...) {
  this.siblingAbortController = createChildAbortController(
    toolUseContext.abortController      // ★ the parent controller
  )
}

In other words: this is a child of the main abort controller. It fires when a Bash tool errors, so the sibling subprocesses in the same batch die immediately instead of pointlessly running to completion. Aborting this child does not abort the parent — so the main loop does not end the turn.

5.7 The discard mechanism

/**
 * Discards all pending and in-progress tools. Called when streaming fallback
 * occurs and results from the failed attempt should be abandoned.
 * Queued tools won't start, and in-progress tools will receive synthetic errors.
 */
discard(): void {
  this.discarded = true
}

In other words: discard all pending and in-progress tools. Called when a streaming request fails and falls back, at which point the results of the failed attempt should be abandoned. Queued tools will not start, and in-progress tools will receive synthetic error results.

This method is called from two places, and both handle it identically:

// Scenario 1: the streaming request failed; fall back to a non-streaming retry
if (streamingFallbackOccured) {
  for (const msg of assistantMessages) yield { type:'tombstone', message: msg }
  logEvent('tengu_orphaned_messages_tombstoned', { orphanedMessageCount: ... })
  assistantMessages.length = 0; toolResults.length = 0; toolUseBlocks.length = 0
  if (streamingToolExecutor) {
    streamingToolExecutor.discard()
    streamingToolExecutor = new StreamingToolExecutor(...)    // ★ build a brand-new one
  }
}

// Scenario 2: model fallback to the backup model (see Section 3.7)
// The same four steps: emit tombstones, clear the arrays, discard the executor, rebuild

The comment explains why it rebuilds rather than reuses:

5.8 “Tombstone” messages

A new concept appeared above: tombstone. It is a control-signal message meaning “please remove this message from the UI and the transcript.”

yield { type: 'tombstone' as const, message: msg }

Why is it needed? The comment explains:

The scenario: when a streaming request fails, the model has already emitted part of its content, and the UI has already displayed it. That content cannot stay — it is incomplete and its signatures are invalid. So a tombstone is sent to retract it.

This design matters for a streaming UI: you have already painted something on the screen, and now you need a “retract” mechanism. And the retraction has to apply to both the UI and the record on disk.

5.9 Final processing of results

After a tool finishes, its result goes through two more processing steps before it is returned to the model:

① Spilling oversized results to disk

Every tool declares maxResultSizeChars. A result over the limit is written to disk, and what the model receives is “a preview of the first 2000 bytes + the file path.” See Section 6.2 for details.

② Serialization

mapToolResultToToolResultBlockParam(content: Output, toolUseID: string): ToolResultBlockParam

Each tool decides for itself “how my output should become text for the model.” For instance, the Read tool adds line numbers, and the Bash tool marks standard output and standard error separately.

Note that the Tool interface also has a method dedicated to transcript search:

/**
 * Flattened text of what renderToolResultMessage shows IN TRANSCRIPT MODE.
 * For transcript search indexing: the index counts occurrences in this string,
 * the highlight overlay scans the actual screen buffer. For count ≡ highlight,
 * this must return the text that ends up visible — not the model-facing
 * serialization from mapToolResultToToolResultBlockParam.
 *
 * Phantoms are not fine — text that's claimed here but doesn't render is a
 * count≠highlight bug.
 */
extractSearchText?(out: Output): string

In other words: this method returns a flattened version of “the text actually rendered in transcript mode.” It serves the search index: the index counts occurrences in this string, while the highlight overlay scans the real screen buffer. For the “count” and the “highlights” to be equal, this must return the text that is ultimately visible — not the serialization meant for the model. … Phantom text is not acceptable — text claimed here that does not actually render is a “count ≠ highlight” bug.

6 · Context Management ★

This is the part of the system with the highest engineering density. The problem it solves fits in one sentence: an agent’s context grows on its own, and the context window has a hard ceiling.

6.1 The five-tier pipeline

Before every model call, the message history passes through this pipeline. The tiers are ordered from cheapest to most expensive:

// Inside the query.ts main loop, at the top of each iteration
let messagesForQuery = [...getMessagesAfterCompactBoundary(messages)]
//   First take the messages "after the last compact boundary"; everything before has been replaced by a summary

// ① Tool result budget: a single result / the per-message aggregate over the limit → spill to disk, replace with a reference
messagesForQuery = await applyToolResultBudget(
  messagesForQuery,
  toolUseContext.contentReplacementState,
  persistReplacements ? records => void recordContentReplacement(...) : undefined,
  new Set(toolUseContext.options.tools
    .filter(t => !Number.isFinite(t.maxResultSizeChars))    // exclude tools that declare Infinity
    .map(t => t.name)),
)

// ② Snip: remove zombie messages and stale markers
let snipTokensFreed = 0
if (feature('HISTORY_SNIP')) {
  const snipResult = snipModule!.snipCompactIfNeeded(messagesForQuery)
  messagesForQuery = snipResult.messages
  snipTokensFreed = snipResult.tokensFreed
  if (snipResult.boundaryMessage) yield snipResult.boundaryMessage
}

// ③ Micro-compaction: precisely delete old results by tool-call id
const microcompactResult = await deps.microcompact(messagesForQuery, toolUseContext, querySource)
messagesForQuery = microcompactResult.messages
const pendingCacheEdits = feature('CACHED_MICROCOMPACT')
  ? microcompactResult.compactionInfo?.pendingCacheEdits : undefined

// ④ Context collapse: projection-style, replayable
if (feature('CONTEXT_COLLAPSE') && contextCollapse) {
  const collapseResult = await contextCollapse.applyCollapsesIfNeeded(
    messagesForQuery, toolUseContext, querySource)
  messagesForQuery = collapseResult.messages
}

// ⑤ Auto summary compaction: one full model call
const { compactionResult, consecutiveFailures } = await deps.autocompact(
  messagesForQuery, toolUseContext, { systemPrompt, userContext, systemContext,
  toolUseContext, forkContextMessages: messagesForQuery }, querySource, tracking, snipTokensFreed)

// ⑥ Hard blocking check (only in effect when auto-compaction is turned off)
if (!compactionResult && querySource !== 'compact' && ... ) {
  const { isAtBlockingLimit } = calculateTokenWarningState(
    tokenCountWithEstimation(messagesForQuery) - snipTokensFreed,
    toolUseContext.options.mainLoopModel)
  if (isAtBlockingLimit) {
    yield createAssistantAPIErrorMessage({ content: PROMPT_TOO_LONG_ERROR_MESSAGE, ... })
    return { reason: 'blocking_limit' }
  }
}

The reasoning behind the order

On why tier ④ must come before tier ⑤, the source has one precise sentence:

The counterintuitive design of tier ⑥

Note the trigger condition for the hard block: it is in effect only when auto-compaction is turned off. The comment explains:

6.2 Tier ①: the tool result budget

Spilling a single result to disk

export const PREVIEW_SIZE_BYTES = 2000                     // how many bytes to preview
export const PERSISTED_OUTPUT_TAG = '<persisted-output>'    // wrapper tag
export const TOOL_RESULTS_SUBDIR = 'tool-results'          // subdirectory on disk
export const TOOL_RESULT_CLEARED_MESSAGE = '[Old tool result content cleared]'

claude-code/src/utils/toolResultStorage.ts

The flow: a result exceeds the tool’s declared maxResultSizeChars → the full content is written to the tool-results/ directory → the model receives “a preview of the first 2000 bytes + the file path” → when it needs the full text, the model goes and Reads that file itself.

The Infinity exception

The per-message aggregate budget

Beyond the single-result limit, there is also a ContentReplacementState:

export type ContentReplacementState = {
  seenIds: ...        // result ids that have already passed the budget check
  ...
}
export function createContentReplacementState(): ContentReplacementState
export function cloneContentReplacementState(...): ContentReplacementState

What it guards against: the model fires off 20 search calls in parallel, each result within the single-result limit, but the total blows up.

Its lifecycle is also carefully managed; the comment describes three cases:

6.3 Tier ③: micro-compaction and cache edits

The dilemma

The goal is modest: delete old tool results that are no longer useful. But deleting them outright has a fatal side effect:

The fix: have the server delete inside the cache

/**
 * Cached microcompact path - uses cache editing API to remove tool results
 * without invalidating the cached prefix.
 *
 * - Does NOT modify local message content
 *   (cache_reference and cache_edits are added at API layer)
 * - Uses count-based trigger/keep thresholds from GrowthBook config
 * - Takes precedence over regular microcompact (no disk persistence)
 */
async function cachedMicrocompactPath(messages, querySource) {
  const mod    = await getCachedMCModule()
  const state  = ensureCachedMCState()
  const config = mod.getCachedMCConfig()

  // 1. Scan for the call ids of every "compactable tool"
  const compactableToolIds = new Set(collectCompactableToolIds(messages))

  // 2. Group by "user message" and register these tool results
  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)
    }
  }

  // 3. Ask the state machine: which ones should be deleted? (keep the most recent N)
  const toolsToDelete = mod.getToolResultsToDelete(state)

  if (toolsToDelete.length > 0) {
    // 4. Generate a cache_edits instruction block and queue it for the API layer
    const cacheEdits = mod.createCacheEditsBlock(state, toolsToDelete)
    if (cacheEdits) pendingCacheEdits = cacheEdits
    ...
    // 5. ★ Return the messages unchanged — not a single byte was modified locally
    return { messages, compactionInfo: { pendingCacheEdits: {...} } }
  }
  return { messages }
}

claude-code/src/services/compact/microCompact.ts

Only 8 kinds of tool have deletable results

const COMPACTABLE_TOOLS = new Set<string>([
  FILE_READ_TOOL_NAME,      // read a file
  ...SHELL_TOOL_NAMES,      // Bash / PowerShell
  GREP_TOOL_NAME,           // content search
  GLOB_TOOL_NAME,           // filename search
  WEB_SEARCH_TOOL_NAME,     // web search
  WEB_FETCH_TOOL_NAME,      // fetch a web page
  FILE_EDIT_TOOL_NAME,      // edit a file
  FILE_WRITE_TOOL_NAME,     // write a file
])

What these 8 have in common: the result is a one-time observation — read a file, search for a word, run a command; once the model has digested it, the original text is no longer needed.

Other tools’ results (for instance TodoWrite, which maintains the to-do list) represent ongoing, still-valid state; deleting them would cause amnesia.

How many tokens were deleted? You have to wait for the server to tell you

// query.ts, after the streaming response ends
if (feature('CACHED_MICROCOMPACT') && pendingCacheEdits) {
  const lastAssistant = assistantMessages.at(-1)
  const usage = lastAssistant?.message.usage
  // ★ This field is "cumulative/sticky" (the total since the session began), not this request's delta
  const cumulativeDeleted = usage
    ? ((usage as unknown as Record<string, number>).cache_deleted_input_tokens ?? 0) : 0
  const deletedTokens = Math.max(0,
    cumulativeDeleted - pendingCacheEdits.baselineCacheDeletedTokens)   // subtract the pre-request baseline
  if (deletedTokens > 0) {
    yield createMicrocompactBoundaryMessage(
      pendingCacheEdits.trigger, 0, deletedTokens, pendingCacheEdits.deletedToolIds, [])
  }
}

Because nothing was changed locally, the client does not know how much was actually saved, so the “compacted” notification message is deferred until after the API response.

Side effect: there is a brief “perception gap” window — during the few seconds between “deciding to delete” and “the response coming back,” the client’s estimate of the context size runs high. This is also why the auto-compaction threshold checks later on are full of manual compensation terms (such as - snipTokensFreed).

Three guards against state contamination

// Guard 1: run cache editing only for the main thread
if (mod.isCachedMicrocompactEnabled() &&
    mod.isModelSupportedForCacheEditing(model) &&
    isMainThreadSource(querySource)) {
  return await cachedMicrocompactPath(messages, querySource)
}

Comment: “Only run cached MC for the main thread to prevent forked agents (session_memory, prompt_suggestion, etc.) 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.”

In other words: run cached micro-compaction only for the main thread, to keep forked agents (session memory, prompt suggestions, etc.) from registering their tool results in the global state, which would make the main thread try to delete tools that do not exist in its own conversation at all.

The root of the problem: cachedMCState is a module-level global singleton, holding its own copy of the truth alongside the message array. This is the biggest source of complexity in the whole mechanism.

The path in the other direction: the time-based trigger

export function evaluateTimeBasedTrigger(messages, querySource) {
  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 }
}

The comment lays out the logic of this path:

The Math.max(1, ...) boundary trap

// Floor at 1: slice(-0) returns the full array (paradoxically keeps everything),
// and clearing ALL results leaves the model with zero working context.
// Neither degenerate is sensible — always keep at least the last.
const keepRecent = Math.max(1, config.keepRecent)
const keepSet  = new Set(compactableIds.slice(-keepRecent))
const clearSet = new Set(compactableIds.filter(id => !keepSet.has(id)))

In other words: floor it at 1: because slice(-0) returns the entire array (paradoxically deleting nothing), while clearing every result would leave the model with no working context at all. Neither degenerate case makes sense.

(In JavaScript, slice(-N) means “take the last N.” But -0 is numerically equal to 0, and slice(0) means “take everything from the start.” So configuring “keep the most recent 0” actually behaves as “keep everything” — a classic boundary-value trap.)

After clearing, reset the state and notify monitoring

suppressCompactWarning()
// The global cached-micro-compaction state holds tool ids registered in earlier turns. We just cleared some
// of their content, and by changing the prompt we invalidated the server cache. If the next turn's cached
// micro-compaction ran with stale state, it would try to cache_edit entries the server no longer has. So reset it.
resetMicrocompactState()

// We just changed the prompt content — the next response's cache reads will be low, but we caused that
// ourselves; it isn't a cache break. Tell the detector to expect a dip.
if (feature('PROMPT_CACHE_BREAK_DETECTION') && querySource) {
  notifyCacheDeletion(querySource)
}

That final notifyCacheDeletion points to the cache-break detection system covered in Chapter 12 — it watches for “a sudden drop in cache hit rate” and alerts. This one is a “legitimate drop,” so it has to be told in advance not to raise a false alarm.

6.4 Tier ⑤: auto summary compaction

Thresholds

export const WARNING_THRESHOLD_BUFFER_TOKENS = 20_000   // buffer below the warning line
export const ERROR_THRESHOLD_BUFFER_TOKENS   = 20_000   // buffer below the error line

const threshold        = getAutoCompactThreshold(model)
const warningThreshold = threshold - WARNING_THRESHOLD_BUFFER_TOKENS
const errorThreshold   = threshold - ERROR_THRESHOLD_BUFFER_TOKENS

Compaction is a “forked subagent” call

Compaction itself calls the model to produce a summary. Claude Code runs it in a forked subagent, and lets the fork inherit the parent’s full tool set — not because summarization needs tools, but so the cache key matches and the cache prefix the parent already built gets reused.

That decision led to a real production issue, and the source comment even preserved the numbers:

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.

`

claude-code/src/services/compact/prompt.ts

Two-part output: the scratchpad pattern

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

And the processing function formatCompactSummary() strips the entire analysis block, placing only the summary block into the context. Source comment: “The <analysis> block is a drafting scratchpad that formatCompactSummary() strips before the summary reaches context.”

Telemetry after a successful compaction

logEvent('tengu_auto_compact_succeeded', {
  originalMessageCount:  messages.length,
  compactedMessageCount: compactionResult.summaryMessages.length +
                         compactionResult.attachments.length +
                         compactionResult.hookResults.length,
  preCompactTokenCount, postCompactTokenCount, truePostCompactTokenCount,
  compactionInputTokens:  compactionUsage?.input_tokens,
  compactionOutputTokens: compactionUsage?.output_tokens,
  compactionCacheReadTokens:     compactionUsage?.cache_read_input_tokens ?? 0,
  compactionCacheCreationTokens: compactionUsage?.cache_creation_input_tokens ?? 0,
  compactionTotalTokens: ...,
  queryChainId: ..., queryDepth: ...,
})

Note that there are three “post-compaction token counts”: postCompactTokenCount and truePostCompactTokenCount. The difference between them is exactly the “perception gap” described earlier — one is the client’s estimate, the other the true value returned by the server. Reporting both the estimate and the true value lets them continuously monitor the estimator’s error.

6.5 When the context really does overflow: the three-tier recovery cascade

Why step ③ must not run the stop hooks

Take a moment to appreciate the shape of this loop. The “pre-finish quality check” feature is perfectly reasonable on its own, but when the cause of failure is “the context no longer fits,” it will:

1. See a failed response
2. Judge it inadequate and generate feedback along the lines of “your answer has the following problems…”
3. Inject that feedback into the context — the context gets even longer
4. Retry → even further over → fails again → back to step 1

7 · The Permission System

The utils/permissions/ directory holds 21 files, and the core permissions.ts alone is 51 KB. This chapter gives the complete answer to one question: “on what grounds does this tool call get to run?”

7.1 Six Permission Modes

const PERMISSION_MODE_CONFIG: Partial<Record<PermissionMode, PermissionModeConfig>> = {
  default:           { title: 'Default',             symbol: '',    color: 'text' },
  plan:              { title: 'Plan Mode',           symbol: '⏸',   color: 'planMode' },
  acceptEdits:       { title: 'Accept edits',        symbol: '⏵⏵',  color: 'autoAccept' },
  bypassPermissions: { title: 'Bypass Permissions',  symbol: '⏵⏵',  color: 'error' },
  dontAsk:           { title: "Don't Ask",           symbol: '⏵⏵',  color: 'error' },
  ...(feature('TRANSCRIPT_CLASSIFIER') ? {
  auto:              { title: 'Auto mode',           symbol: '⏵⏵',  color: 'warning' },
  } : {}),
}

claude-code/src/utils/permissions/PermissionMode.ts

There's also a carefully drawn distinction at the type level:

export function isExternalPermissionMode(mode: PermissionMode): mode is ExternalPermissionMode {
  if (process.env.USER_TYPE !== 'ant') return true      // external users have no auto, so always true
  return mode !== 'auto' && mode !== 'bubble'
}

export function toExternalPermissionMode(mode: PermissionMode): ExternalPermissionMode {
  return getModeConfig(mode).external      // auto maps to default externally
}

Internal modes need an external mapping. The auto mode reports itself to external interfaces as default — so SDK users never see a mode value they can't understand and can't set.

7.2 The Ten-Step Decision Cascade

The core function hasPermissionsToUseToolInner() is a strictly ordered chain of checks, evaluated top to bottom; the first one that matches decides the outcome:

The four source comments on the bypass-immune layer

// 1d. Tool implementation denied (catches bash subcommand denies wrapped ...)
// 1e. Tool requires user interaction even in bypass mode
// 1f. Content-specific ask rules from tool.checkPermissions take precedence
//     over bypassPermissions mode. When a user explicitly configures a
//     content-specific ask rule (e.g. Bash(npm publish:*)), the tool's
//     checkPermissions returns {behavior:'ask', ...}. This must be respected
//     even in bypass mode, just as deny rules are respected at step 1d.
// 1g. Safety checks (e.g. .git/, .claude/, .vscode/, shell configs) are
//     bypass-immune — they must prompt even in bypassPermissions mode.

7.3 Auto Mode: Model Classifier + Three-Tier Fast Path

When the verdict lands on ASK and the current mode is auto, Claude Code doesn't pop a dialog. Instead it calls the model one more time to judge whether the action is safe. This dedicated call is the “classifier.”

But the classifier isn't cheap — it's an extra API request per tool call. So several layers stand in front of it:

if (feature('TRANSCRIPT_CLASSIFIER') &&
    (appState.toolPermissionContext.mode === 'auto' ||
     (appState.toolPermissionContext.mode === 'plan' && isAutoModeActive()))) {

  // Intercept 1: a safety check fired, and it's one the classifier "isn't allowed to approve"
  if (result.decisionReason?.type === 'safetyCheck' &&
      !result.decisionReason.classifierApprovable) {
    if (appState.toolPermissionContext.shouldAvoidPermissionPrompts) {
      return { behavior:'deny', message: result.message,
               decisionReason: { type:'asyncAgent',
                 reason:'Safety check requires interactive approval and permission '
                      + 'prompts are not available in this context' } }
    }
    return result       // stays ASK
  }

  // Intercept 2: the tool declares "a human must be present"
  if (tool.requiresUserInteraction?.() && result.behavior === 'ask') return result

  // Intercept 3: PowerShell (unless a special compile-time flag is on)
  if (tool.name === POWERSHELL_TOOL_NAME && !feature('POWERSHELL_AUTO_MODE')) { ... }

  // Fast path ①: pose as acceptEdits mode and ask the tool again
  if (result.behavior === 'ask' &&
      tool.name !== AGENT_TOOL_NAME && tool.name !== REPL_TOOL_NAME) {
    const acceptEditsResult = await tool.checkPermissions(parsedInput, {
      ...context,
      getAppState: () => ({ ...context.getAppState(),
        toolPermissionContext: { ...state.toolPermissionContext,
                                 mode: 'acceptEdits' as const } }),
    })
    if (acceptEditsResult.behavior === 'allow') {
      logEvent('tengu_auto_mode_decision', { decision:'allowed', fastPath:'acceptEdits', ... })
      return { behavior:'allow', updatedInput: acceptEditsResult.updatedInput ?? input,
               decisionReason: { type:'mode', mode:'auto' } }
    }
  }

  // Fast path ②: allowlist of safe tools
  if (classifierDecisionModule!.isAutoModeAllowlistedTool(tool.name)) {
    logEvent('tengu_auto_mode_decision', { decision:'allowed', fastPath:'allowlist', ... })
    return { behavior:'allow', updatedInput: input, decisionReason: { type:'mode', mode:'auto' } }
  }

  // Nothing matched → actually call the classifier
  const action = formatActionForClassifier(tool.name, input)
  setClassifierChecking(toolUseID)
  let classifierResult
  try {
    classifierResult = await classifyYoloAction(
      context.messages,                    // ★ the full transcript
      action,
      context.options.tools,
      appState.toolPermissionContext,
      context.abortController.signal)
  } finally {
    clearClassifierChecking(toolUseID)
  }
  ...
}

claude-code/src/utils/permissions/permissions.ts

What's clever about fast path ①

It temporarily disguises the permission mode as acceptEdits and asks the tool again. The logic: if even the permissive mode would allow this operation, it's genuinely harmless, and there's no need to pay for a classifier call.

But two tools are explicitly excluded:

The classifier sees the full transcript

Note the first argument to classifyYoloAction(context.messages, ...): the entire transcript, not just this one command.

This matters. An rm -rf build/ is safe in the context of “the user asked to clean up build artifacts” and impossible to judge without that context. But it raises a problem: the full transcript can run to tens of thousands of tokens, and stuffing it into the classifier would blow it up.

So the tool interface has a method built specifically for this:

/**
 * Returns a compact representation of this tool use for the auto-mode
 * security classifier. Examples: `ls -la` for Bash, `/tmp/x: new content`
 * for Edit. Return '' to skip this tool in the classifier transcript
 * (e.g. tools with no security relevance). May return an object to avoid
 * double-encoding when the caller JSON-wraps the value.
 */
toAutoClassifierInput(input: z.infer<Input>): unknown

Each tool supplies its own compressed representation that keeps only the security-relevant semantics: Bash gives the command-line text, Edit gives “path + new content,” and tools with no security implications return an empty string and drop out of view entirely.

Consecutive-denial tracking: breaking deadlocks

// any successful allow resets the consecutive-denial counter
if (result.behavior === 'allow') {
  const currentDenialState = context.localDenialTracking ?? appState.denialTracking
  if (appState.toolPermissionContext.mode === 'auto' &&
      currentDenialState && currentDenialState.consecutiveDenials > 0) {
    const newDenialState = recordSuccess(currentDenialState)
    persistDenialState(context, newDenialState)
  }
  return result
}

Once consecutive denials hit a threshold, the system stops trusting the classifier and falls back to human confirmation. It guards against this deadlock: the classifier keeps denying because of some misjudgment, the model doesn't understand why and keeps rephrasing and retrying — both sides burn money and nothing ever moves forward.

Note the fallback in context.localDenialTracking ?? appState.denialTracking:

7.4 Permission Rule Syntax

Users can write permission rules in the config file. The syntax has two levels:

Three kinds of rules: alwaysAllowRules (always allow), alwaysDenyRules (always deny), and alwaysAskRules (always ask).

Whole-tool deny rules take effect “before the model ever sees the tool”

/**
 * Filters out tools that are blanket-denied by the permission context.
 * A tool is filtered out if there's a deny rule matching its name with no
 * ruleContent (i.e., a blanket deny for that tool).
 *
 * Uses the same matcher as the runtime permission check (step 1a), so MCP
 * server-prefix rules like `mcp__server` strip all tools from that server
 * before the model sees them — not just at call time.
 */
export function filterToolsByDenyRules<T>(tools, permissionContext): T[] {
  return tools.filter(tool => !getDenyRuleForTool(permissionContext, tool))
}

Shadowed-rule detection

utils/permissions/ has a file called shadowedRuleDetection.ts. The problem it solves:

7.5 Sandboxing and Read-Only Command Detection

Read-only commands are allowed automatically

utils/shell/readOnlyCommandValidation.ts, 66.7 KB. Its job is to decide “is this shell command read-only?” If so, it can be allowed automatically without bothering the user.

That's much harder than it looks, because it has to handle:

• Pipes and redirects — ls | grep foo is read-only; ls > out.txt is not
• Command substitution — echo $(rm -rf /) hides a write inside
• Compound commands — cd /tmp && ls contains two commands, and both need judging
• Aliases and functions — the user may have aliased ls to something else

So the utils/bash/ directory contains a complete shell grammar parser: bashParser.ts (128 KB) + ast.ts (109 KB). It parses shell commands into an abstract syntax tree and analyzes the tree, instead of regex-matching strings.

And there's an experimental alternative implementation: the compile-time flags include TREE_SITTER_BASH and TREE_SITTER_BASH_SHADOW — the latter's name (shadow) shows they're validating the new parser in shadow mode: both parsers run at the same time, disagreements are logged, but the old parser's result is still the one used. That collects accuracy data on the new implementation at zero risk.

OS-level sandboxing

On macOS, Claude Code uses the system's built-in sandbox-exec mechanism (also known as seatbelt). It applies a policy file when a process launches, restricting which paths the process can access and whether it can reach the network.

Step 1b of the permission chain has a special branch tied to the sandbox:

// 1b. Check if the entire tool should always ask for permission
const askRule = getAskRuleForTool(...)
if (askRule) {
  // When "auto-allow inside the sandbox" is on, sandboxable commands skip the ask rule
  // and are auto-allowed through Bash's checkPermissions.
  // Commands that won't be sandboxed (on the exclude list, or with sandboxing explicitly off) still obey the ask rule.
  if (!canSandboxAutoAllow) {
    return { behavior:'ask', ... }
  }
  // otherwise fall through and let Bash's checkPermissions handle the per-command rules
}

The logic: if this command will run inside the sandbox, it doesn't matter that it “looks dangerous” — the sandbox will contain it. So the ask can be skipped. That's “trading stronger isolation for fewer interruptions.”

7.6 The Full Data Structure Behind a Permission Decision

export type ToolPermissionContext = DeepImmutable<{
  mode: PermissionMode
  additionalWorkingDirectories: Map<string, AdditionalWorkingDirectory>
  alwaysAllowRules: ToolPermissionRulesBySource
  alwaysDenyRules:  ToolPermissionRulesBySource
  alwaysAskRules:   ToolPermissionRulesBySource
  isBypassPermissionsModeAvailable: boolean
  isAutoModeAvailable?: boolean
  strippedDangerousRules?: ToolPermissionRulesBySource   // ★ dangerous rules that were stripped
  shouldAvoidPermissionPrompts?: boolean                 // background tasks: can't show a dialog
  awaitAutomatedChecksBeforeDialog?: boolean
  prePlanMode?: PermissionMode                           // mode before entering plan mode, for restoring
}>

Two fields deserve attention:

strippedDangerousRules: rules the system actively strips out

A user's config may contain rules that are “so broad they're dangerous.” The system strips them at load time and records what it stripped (so the UI can tell the user “this rule of yours was ignored because it's too broad”).

The concrete stripping logic is visible in the source, for example:

• isOverlyBroadPowerShellAllowRule — strips allow-everything rules like PowerShell(*)
• isDangerousPowerShellPermission — strips allow rules with prefixes like iex (download-and-execute) and Start-Process

DeepImmutable: immutability at the type level

This wrapper type makes the entire permission context completely read-only at the type-system level — any code that tries to mutate it fails to compile. Changes to permission state have to go through the dedicated applyPermissionUpdates() function, which guarantees every change passes through one unified validation and persistence path.

7.7 Explainability of Permission Decisions

Every permission decision carries a decisionReason field:

{ type: 'rule',        rule: {...} }            // a rule matched
{ type: 'mode',        mode: 'auto' }           // because of the current mode
{ type: 'hook',        hookName: 'PermissionRequest', reason: ... }  // decided by a hook
{ type: 'safetyCheck', classifierApprovable: false }   // safety check
{ type: 'asyncAgent',  reason: '...' }          // background task can't interact

And a dedicated module, permissionExplainer.ts, translates these reasons into plain language for the user.

8 · Subagents

The tools/AgentTool/ directory; its main file is 228 KB. This is the most complex of all the tools — because its job is to recursively launch another complete agent.

8.1 The Primary Motivation Is Context Isolation, Not Parallelism

8.2 Three Forms

8.3 Forking: Pushing Prompt Caching to the Limit

The typical use of forking is “spawn 5 subagents at once to explore the same problem from different angles.” Their five contexts are almost identical — the only difference is the final line: “you take direction A / B / C / D / E.”

Prompt caching is prefix-matched. So:

Four things done to make that happen

① The system prompt is passed as “already-rendered bytes”

/**
 * The getSystemPrompt here is unused: the fork path passes
 * `override.systemPrompt` with the parent's already-rendered system prompt
 * bytes, threaded via `toolUseContext.renderedSystemPrompt`. Reconstructing
 * by re-calling getSystemPrompt() can diverge (GrowthBook cold→warm)
 * and bust the prompt cache; threading the rendered bytes is byte-exact.
 */

claude-code/src/tools/AgentTool/forkSubagent.ts

Put plainly: the getSystemPrompt here goes unused: the fork path passes the parent's already-rendered system prompt bytes, threaded through the renderedSystemPrompt field. Regenerating by calling the generator again can diverge (because the feature-flag config may have gone from cold cache to warm cache), which busts the prompt cache; passing the rendered bytes is byte-exact.

To unpack the trap: the system prompt's content isn't entirely fixed; it can include A/B experiment variants. And the experiment config is itself cached — at the moment the parent generates its prompt, some experiment config may still be in a “cold cache” state (using the default value); a few seconds later, when the child regenerates it, the config has become “warm cache” (using the real value). The two generations produce different bytes, and the cache is wasted entirely.

The corresponding field is defined in Tool.ts:

/**
 * Parent's rendered system prompt bytes, frozen at turn start.
 * Used by fork subagents to share the parent's prompt cache — re-calling
 * getSystemPrompt() at fork-spawn time can diverge (GrowthBook cold→warm)
 * and bust the cache. See forkSubagent.ts.
 */
renderedSystemPrompt?: SystemPrompt

“frozen at turn start” — that's the key.

② The tool list is inherited as-is

/**
 * Synthetic agent definition for the fork path.
 *
 * Not registered in builtInAgents — used only when `!subagent_type` and the
 * experiment is active. `tools: ['*']` with `useExactTools` means the fork
 * child receives the parent's exact tool pool (for cache-identical API
 * prefixes). `permissionMode: 'bubble'` surfaces permission prompts to the
 * parent terminal. `model: 'inherit'` keeps the parent's model for context
 * length parity.
 */
export const FORK_AGENT = {
  tools: ['*'],
  permissionMode: 'bubble',
  model: 'inherit',
  ...
}

Each of the three fields has its reason:

• tools: ['*'] together with useExactTools — the child gets the parent's exact tool pool. It won't use that many tools, but tool definitions are part of the request prefix; change them and the cache is gone.
• permissionMode: 'bubble' — permission confirmations bubble up to the terminal where the parent lives. The subagent has no UI of its own.
• model: 'inherit' — inherits the parent's model, guaranteeing the same context window size. If the child used a model with a smaller window, the inherited history might simply not fit.

③ Message construction: only the last text block differs

/**
 * Build the forked conversation messages for the child agent.
 *
 * For prompt cache sharing, all fork children must produce byte-identical
 * API request prefixes. This function:
 * 1. Keeps the full parent assistant message (all tool_use blocks, thinking, text)
 * 2. Builds a single user message with tool_results for every tool_use block
 *    using an identical placeholder, then appends a per-child directive text block
 *
 * Result: [...history, assistant(all_tool_uses), user(placeholder_results..., directive)]
 * Only the final text block differs per child, maximizing cache hits.
 */
export function buildForkedMessages(...)

What's clever about the “placeholder tool results”: the parent's message contains 5 tool calls (one per fork). By the API's rules, every tool call must have a paired result. But the 5 forks haven't finished yet, so real results don't exist. So each one gets filled with exactly the same placeholder content — satisfying the pairing requirement while guaranteeing all 5 children see an identical stretch.

The source even has a dedicated constant for it:

/** Must be identical across all fork children for prompt cache sharing. */

④ The recursive-fork guard: moved down from the interface layer to the call layer

/**
 * Guard against recursive forking. Fork children keep the Agent tool in their
 * tool pool for cache-identical tool definitions, so we reject fork attempts
 * at call time by detecting the fork boilerplate tag in conversation history.
 */
export function isInForkChild(messages: MessageType[]): boolean { ... }

The conventional approach is “remove the Agent tool from the subagent's tool pool.” But that changes the tool definitions and breaks the cache. So instead: keep the tool, but at the moment it's actually called, check the conversation history for a fork marker:

if (isInForkChild(toolUseContext.messages)) {
  throw new Error('Fork is not available inside a forked worker. '
                + 'Complete your task directly using your tools.')
}

An extra notice for worktree isolation

/**
 * Notice injected into fork children running in an isolated worktree.
 * Tells the child to translate paths from the inherited context, re-read
 * potentially stale files, and that its changes are isolated.
 */
export function buildWorktreeNotice(...)

If a forked child runs in an isolated git worktree, the file paths in the history it inherited point at the parent's directory. So it has to be told explicitly: translate paths, files may no longer be the version you saw, and your changes are isolated.

8.4 Tool Restrictions on Subagents

export const ALL_AGENT_DISALLOWED_TOOLS = new Set([
  TASK_OUTPUT_TOOL_NAME,        // can't view other tasks' output
  EXIT_PLAN_MODE_V2_TOOL_NAME,  // can't exit plan mode (session-wide global state)
  ENTER_PLAN_MODE_TOOL_NAME,    // can't enter plan mode
  // internal users may nest subagents; external users may not
  ...(process.env.USER_TYPE === 'ant' ? [] : [AGENT_TOOL_NAME]),
  ASK_USER_QUESTION_TOOL_NAME,  // ★ can't ask the user questions
  TASK_STOP_TOOL_NAME,          // can't stop other tasks
  // prevent recursive workflow execution inside a subagent
  ...(feature('WORKFLOW_SCRIPTS') ? [WORKFLOW_TOOL_NAME] : []),
])

export const CUSTOM_AGENT_DISALLOWED_TOOLS = new Set([...ALL_AGENT_DISALLOWED_TOOLS])

claude-code/src/constants/tools.ts

The allowlist for background async agents is stricter

/*
 * Async Agent Tool Availability Status (Source of Truth)
 */
export const ASYNC_AGENT_ALLOWED_TOOLS = new Set([
  FILE_READ_TOOL_NAME,      // read files
  WEB_SEARCH_TOOL_NAME,     // web search
  TODO_WRITE_TOOL_NAME,     // todo list
  GREP_TOOL_NAME,           // content search
  WEB_FETCH_TOOL_NAME,      // fetch web pages
  GLOB_TOOL_NAME,           // filename search
  ...
])

Note the shift here from a “denylist” to an “allowlist” — and nearly everything on it is a read-only tool.

8.5 Constructing a Subagent's Context

Creating a subagent constructs a new ToolUseContext. Several fields are handled with care:

/**
 * Always-shared setAppState for session-scoped infrastructure (background
 * tasks, session hooks). Unlike setAppState, which is no-op for async agents
 * (see createSubagentContext), this always reaches the root store so agents
 * at any nesting depth can register/clean up infrastructure that outlives
 * a single turn. Only set by createSubagentContext; main-thread contexts
 * fall back to setAppState.
 */
setAppStateForTasks?: (f: (prev: AppState) => AppState) => void

Put plainly: an “always-shared” state setter for session-scoped infrastructure (background tasks, session hooks). Unlike the regular setAppState (a no-op for async agents), this one always reaches the root store — so an agent at any nesting depth can register or clean up infrastructure that outlives a single turn. Only set when a subagent context is created; main-thread contexts fall back to the regular setAppState.

Two more related fields:

agentId?: AgentId      // set only for subagents; hooks use it to tell whether a call came from a subagent
agentType?: string     // the subagent's type name

/** When true, preserve toolUseResult on messages even for subagents.
 *  Used by in-process teammates whose transcripts are viewable by the user. */
preserveToolUseResults?: boolean

That last field tells you: by default, a subagent's tool results are discarded (saves memory; the user can't see them anyway). But for the “in-process teammate” kind of subagent, whose transcript is visible to the user, they're kept.

8.6 Built-in Agent Types

tools/AgentTool/builtInAgents.ts defines several built-in types; the most commonly used:

Users can also define their own — write a Markdown file under .claude/agents/*.md, with front matter declaring the name, description, available tools, and model. loadAgentsDir.ts handles loading them.

8.7 The Forms Background Tasks Take

The tasks/ directory holds several task forms; they differ in “where it runs” and “how it communicates”:

Task completion is reported back to the main loop via the message queue — the “process-level global queue” from section 3.9, where each agent takes only the notifications addressed to it.

8.8 Cascading Interruption

The abort controllers form a tree:

9 · The Extension System

An “extension point” means: letting third parties, or users themselves, add capabilities to the system without modifying the main program's source code. Claude Code has four kinds of extension points, each with a different mechanism.

9.1 The Four Extension Points Compared

9.2 The Skill System

Form

A skill is a SKILL.md file with YAML metadata at the top (the industry calls it frontmatter):

The core mechanism: progressive disclosure

Claude Code has a dedicated function to quantify the resident cost:

export function estimateSkillFrontmatterTokens(skill: Command): number

Because every skill's frontmatter is resident in the context, the fixed cost of installing 100 skills has to be measurable — otherwise users keep installing until they discover they're burning thousands of tokens per turn for nothing.

Loader implementation details

// skills/loadSkillsDir.ts
export type LoadedFrom = ...                    // which source it was loaded from
export function getSkillsPath(...)              // path to the skills directory
export function estimateSkillFrontmatterTokens(skill: Command): number
function parseHooksFromFrontmatter(...)         // parse hooks bundled with the skill
function parseSkillPaths(frontmatter): string[] | undefined
export function parseSkillFrontmatterFields(...)
export function createSkillCommand({...})       // wrap a skill as a command object
function isSkillFile(filePath: string): boolean
function transformSkillFiles(files: MarkdownFile[]): MarkdownFile[]
function buildNamespace(targetDir: string, baseDir: string): string   // namespace
function getSkillCommandName(filePath: string, baseDir: string): string
export const getSkillDirCommands = memoize(...)  // ★ result is cached
export function clearSkillCaches()

// dynamic skills: registered at runtime, not on disk
const dynamicSkillDirs  = new Set<string>()
const dynamicSkills     = new Map<string, Command>()

A few points worth noting:

• buildNamespace — skills have namespaces. A skill at skills/git/commit/SKILL.md gets the name git:commit. Prevents skills from different sources from colliding on names.
• memoize — the load result is cached. Scanning the skills directories means a lot of file reads, which can't happen every time. clearSkillCaches() exists alongside it for the /reload command.
• Dynamic skills — skills can be registered at runtime without writing a file. Plugins and MCP servers can use this mechanism to provide skills.

Skills are the bridge that “turns commands into tools”

Recall the dividing line from section 0.3: tools/ is what the model can call; commands/ is what only a human can type.

Skills break that boundary — they expose a piece of “command-style” content (a fixed procedure, domain knowledge) to the model in the form of a tool. And exposing it is cheap, because only a one-line description stays resident.

9.3 The Plugin System

The utils/plugins/ directory:

The corresponding slash commands live under commands/plugin/:

• ManagePlugins.tsx (314 KB) — the plugin management UI
• BrowseMarketplace.tsx (117 KB) — the marketplace browsing UI
• PluginSettings.tsx (126 KB) — plugin settings

Note that the UI code is bigger than the logic code. That's typical of terminal UIs — drawing an interactive list in a terminal, handling keyboard navigation, and rendering a scrollbar takes far more code than the same feature on a web page.

Cache-first loading

// QueryEngine.ts
// Cache-only: headless/SDK/CCR startup must not block on network for
// ref-tracked plugins. CCR populates the cache via CLAUDE_CODE_SYNC_PLUGIN_INSTALL
// (headlessPluginInstall) or CLAUDE_CODE_PLUGIN_SEED_DIR before this runs;
// SDK callers that need fresh source can call /reload-plugins.
const [skills, { enabled: enabledPlugins }] = await Promise.all([
  getSlashCommandToolSkills(getCwd()),
  loadAllPluginsCacheOnly(),        // ★ reads the cache only, no network requests
])

Put plainly: cache-only mode: headless / SDK / remote-environment startup must not block on the network to fetch “ref-tracked plugins.” … Callers that need fresh source can run the /reload-plugins command.

This is an important startup-performance constraint: startup in any automated scenario must not depend on the network. The network may be slow, down, or require authentication — and a job running in a pipeline can't hang because of it.

9.4 The MCP Client

MCP stands for Model Context Protocol, an open standard for connecting agents to external tool services. The services/mcp/ directory implements the client.

Two transports

Tool-name prefixes

MCP tool names get a prefix: mcp__server__tool. That way:

• Same-named tools from different servers don't collide
• Permission rules can be configured in bulk by server prefix (mcp__github matches every tool from that server)

But there's an exception mode: the environment variable CLAUDE_AGENT_SDK_MCP_NO_PREFIX turns the prefix off. So the Tool interface has a dedicated field to cope:

/**
 * For MCP tools: the server and tool names as received from the MCP server
 * (unnormalized). Present on all MCP tools regardless of whether `name` is
 * prefixed (mcp__server__tool) or unprefixed (CLAUDE_AGENT_SDK_MCP_NO_PREFIX mode).
 */
mcpInfo?: { serverName: string; toolName: string }

Whether or not the name is prefixed, the original server name and tool name are stored separately. That way permission checks, telemetry, and error messages all get accurate provenance without parsing the name string.

Asking the user for information (Elicitation)

The MCP protocol lets the server turn around and ask the user for information (say, “please enter your API key”). Claude Code has dedicated handling:

/**
 * Optional handler for URL elicitations triggered by tool call errors (-32042).
 * In print/SDK mode, this delegates to structuredIO.handleElicitation.
 * In REPL mode, this is undefined and the queue-based UI path is used.
 */
handleElicitation?: (
  serverName: string,
  params: ElicitRequestURLParams,
  signal: AbortSignal,
) => Promise<ElicitResult>

Two paths: in interactive mode, go through the UI queue and show a dialog (the corresponding component, ElicitationDialog.tsx, is 175 KB); in headless mode, go through the structured I/O protocol and forward the request to the outer caller.

And -32042 is a specific error code in the MCP protocol meaning “I need information from the user before I can continue.”

Other MCP-related tools

• ListMcpResourcesTool / ReadMcpResourceTool — besides tools, MCP can provide “resources” (readable data); these two tools let the model access them
• McpAuthTool — handles the OAuth authentication flow
• ReadMcpResourceDirTool — lists a resource directory (for servers that declare support)

9.5 Hooks: 15 Kinds of Lifecycle Events

Hooks let users run their own scripts at specific moments in the system. This is the most powerful and most dangerous extension point — because hooks can block operations and modify arguments.

// event types in types/hooks.ts
hookEventName: z.literal('PreToolUse')          // before a tool runs
hookEventName: z.literal('PostToolUse')         // after a tool runs
hookEventName: z.literal('PostToolUseFailure')  // after a tool fails
hookEventName: z.literal('PermissionRequest')   // on a permission request
hookEventName: z.literal('PermissionDenied')    // on a permission denial
hookEventName: z.literal('UserPromptSubmit')    // when the user submits a prompt
hookEventName: z.literal('SessionStart')        // session start
hookEventName: z.literal('Setup')               // initialization / maintenance
hookEventName: z.literal('SubagentStart')       // subagent start
hookEventName: z.literal('Notification')        // notification
hookEventName: z.literal('Elicitation')         // MCP elicitation
hookEventName: z.literal('ElicitationResult')   // elicitation result
hookEventName: z.literal('CwdChanged')          // working directory changed
hookEventName: z.literal('FileChanged')         // file modified externally
hookEventName: z.literal('WorktreeCreate')      // worktree created

claude-code/src/types/hooks.ts

A few more are defined elsewhere: Stop (before finishing), PreCompact (before compaction), and PostSampling (after model sampling).

The hook execution engine

The utils/hooks/ directory:

The existence of ssrfGuard.ts deserves attention. HTTP hooks send event content to a user-configured URL. Without protection, a malicious (or manipulated) config could make Claude Code hit http://169.254.169.254/ (the cloud provider's metadata endpoint, which hands out temporary credentials) — the classic server-side request forgery attack.

Hook progress feedback

export function startHookProgressInterval(params: {...}): ...
export const HOOK_TIMING_DISPLAY_THRESHOLD_MS = 500

Hooks are scripts users wrote themselves, so their run time is completely uncontrolled. Therefore:

• The timer is only shown past 500 milliseconds (avoids UI flicker for fast hooks)
• An interval timer periodically emits progress events so the user knows “the system isn't stuck; your hook is running”

Conditional hook matching

Hook configs can carry conditions, such as “only fire when the Bash tool runs a git command.” That takes cooperation from the tool:

/**
 * Prepare a matcher for hook `if` conditions (permission-rule patterns like
 * "git *" from "Bash(git *)"). Called once per hook-input pair; any
 * expensive parsing happens here. Returns a closure that is called per
 * hook pattern. If not implemented, only tool-name-level matching works.
 */
preparePermissionMatcher?(input: z.infer<Input>): Promise<(pattern: string) => boolean>

Note the design: it returns a closure rather than doing the match directly. Because a single tool call may need checking against dozens of hook patterns, and parsing (say, turning a shell command into a syntax tree) is expensive. So do the “expensive preparation” once and return a “cheap matcher” to call repeatedly.

9.6 Output Styles

outputStyles/ is a small but interesting extension point: it lets users replace the “personality” portion of the system prompt.

One of its effects in the code is that the query-source identifier becomes dynamic:

// Prefix-match because promptCategory.ts sets the querySource to
// 'repl_main_thread:outputStyle:<style>' when a non-default output style
// is active. The bare 'repl_main_thread' is only used for the default style.
function isMainThreadSource(querySource: QuerySource | undefined): boolean {
  return !querySource || querySource.startsWith('repl_main_thread')
}

The comment also mentions a bug this produced:

10 · The Terminal UI Layer

146 UI components, 87 state-management units, 50 files of a customized framework. This layer accounts for a large slice of the codebase's bulk, yet it almost never comes up in architecture discussions. This chapter fills that gap.

10.1 Writing a Terminal UI in React

First, the thing itself: Ink is a framework that lets you write terminal UIs in React syntax.

The upside is that you reuse React's entire mental model: components, state-driven re-rendering, hooks. The cost is that you're dealing with a “canvas” that can only show monospaced characters, has no concept of pixels, and can be resized by the user at any moment.

Claude Code forked its own copy of Ink

The src/ink/ directory has 50 files — their customized version of Ink. The filenames show what they changed:

10.2 The Four Biggest Components

10.3 Why the Input Box Is 347 KB

An “input box” sounds like it should be simple. But this one has to handle:

10.4 The Virtualized Message List

A long session can have thousands of messages. If every re-render walked all of them and computed their layout, the UI would freeze into uselessness.

“Virtualization” means: render only the few messages visible in the current viewport, and for the rest, remember only how tall they are.

The related components:

• VirtualMessageList.tsx (145 KB) — the virtualized list itself
• Messages.tsx (144 KB) — the dispatch logic for rendering messages
• ScrollKeybindingHandler.tsx (146 KB) — scrolling and keyboard navigation

The hard part: in a terminal, “how tall a message is” isn't fixed. It depends on terminal width (resize the window and every message's height changes), whether the content wraps, whether it contains code blocks, whether it's collapsed. So heights have to be cached and recomputed in bulk when the width changes.

10.5 Six Rendering States for Tool Results

Recall from section 4.1 that the Tool interface has more than 10 rendering methods. They correspond to the different states of a tool call:

That renderToolUseMessage receives “partial input” is worth noting:

/**
 * Render the tool use message. Note that `input` is partial because we render
 * the message as soon as possible, possibly before tool parameters have fully
 * streamed in.
 */
renderToolUseMessage(input: Partial<z.infer<Input>>, options): React.ReactNode

To let the user see “what the agent has started doing” as early as possible, the UI starts rendering before the arguments have finished streaming. So every render function has to cope with “this field might not exist yet.”

10.6 Collapsing: Avoiding Screen Flood

/**
 * Returns information about whether this tool use is a search or read operation
 * that should be collapsed into a condensed display in the UI. Examples include
 * file searching (Grep, Glob), file reading (Read), and bash commands like find,
 * grep, wc, etc.
 *
 * - `isSearch: true` for search operations (grep, find, glob patterns)
 * - `isRead: true` for read operations (cat, head, tail, file read)
 * - `isList: true` for directory-listing operations (ls, tree, du)
 */
isSearchOrReadCommand?(input): { isSearch: boolean; isRead: boolean; isList?: boolean }

An agent exploring a codebase might read 20 files in a row. If every read displayed its full content, the user's screen would be flooded and the information that actually matters (the model's reasoning and conclusions) would be buried.

So these operations collapse into one line, something like “Read 20 files.” And the criterion is “the specific content of this call,” not “the tool type” — it's the same Bash tool, but running grep should collapse while running npm test must not (the user needs to see the test output).

10.7 87 State-Management Units

The hooks/ directory holds React custom hooks (something entirely different from the “user hooks” of chapter 9; they just share the English word). The names show how many kinds of state the UI has to manage:

10.8 The Interface Between UI and Kernel: Callbacks in ToolUseContext

The main loop from chapter 3 has no idea the UI exists. The interface between them is a set of optional callbacks in ToolUseContext:

setToolJSX?: SetToolJSXFn                    // lets a tool insert custom components into the UI
addNotification?: (notif: Notification) => void
appendSystemMessage?: (msg) => void          // append a UI-only system message
sendOSNotification?: (opts) => void          // OS-level notification (iTerm2/Kitty/bell)
setInProgressToolUseIDs: (f) => void         // which tools are running (draws the spinner)
setHasInterruptibleToolInProgress?: (v) => void
setResponseLength: (f) => void
setStreamMode?: (mode: SpinnerMode) => void  // the spinner's form
onCompactProgress?: (event: CompactProgressEvent) => void
setSDKStatus?: (status: SDKStatus) => void
openMessageSelector?: () => void
requestPrompt?: (sourceName, summary) => (request) => Promise<PromptResponse>

All of them are optional (marked with ?). That's the key — in headless mode none of these callbacks exist, and the kernel works as usual, just without producing any UI side effects.

One callback's comment explains the boundary of this design:

/** Append a UI-only system message to the REPL message list. Stripped at the
 *  normalizeMessagesForAPI boundary — the Exclude<> makes that type-enforced. */
appendSystemMessage?: (msg: Exclude<SystemMessage, SystemLocalCommandMessage>) => void

Put plainly: append a “UI-only” system message to the interactive UI's message list. It gets stripped at the “normalize into API format” boundary — and that Exclude type enforces this at the type level.

10.9 A Fun Detail: ANSI to PNG

utils/ansiToPng.ts, 209.9 KB — the largest file in the utils/ directory.

What it does: renders terminal output (text with ANSI color control codes) into a PNG image.

It serves the “share” feature — when a user wants to send a stretch of conversation to a colleague, plain text loses all the colors and formatting. Converting to an image preserves the terminal's visual look intact.

Why so big? Because it has to implement its own font renderer: parse the ANSI sequences → compute each character's position → draw glyphs onto a pixel canvas → handle the widths of Chinese characters and emoji → encode as PNG. All of that is free in a browser (the browser does it for you); in a command-line program, every bit has to be written by hand.

11 · Persistence and Resume

utils/sessionStorage.ts, 176 KB. This chapter covers how conversations get written to disk, how they're resumed, and how file changes get rolled back.

11.1 The Transcript Format: JSONL

JSONL stands for JSON Lines: a text file where every line is a complete JSON object.

The reasons for choosing JSONL over one big JSON array are practical:

There's a read-size cap as protection:

export const MAX_TRANSCRIPT_READ_BYTES = 50 * 1024 * 1024   // 50 MB

11.2 The Transcript Is a Tree, Not a List

Note that every record above has two fields, uuid and parentUuid. That tells you the transcript is structurally a tree.

Why a tree?

The comment quoted in section 2.5 can now be read in full:

11.3 The Write Queue

Writes don't go straight to the file every time. In between sits a write queue, whose two properties came up in section 2.5:

• 100 ms deferred serialization — a message entering the queue isn't turned into a JSON string immediately; it waits a moment and gets processed in a batch
• Order preservation — even when callers submit fire-and-forget, the write order matches the submission order

The purpose of that 100 ms delay was covered in section 2.5: it gives “the usage fields on the model's message getting filled in” a time window. Because the API layer emits the message first and receives the usage data afterward.

There's also a flushSessionStorage() function for forcing a drain:

// QueryEngine.ts, right before yielding the final result
// Flush buffered transcript writes before yielding result.
// The desktop app kills the CLI process immediately after receiving the
// result message, so any unflushed writes would be lost.
if (persistSession) {
  if (isEnvTruthy(process.env.CLAUDE_CODE_EAGER_FLUSH) ||
      isEnvTruthy(process.env.CLAUDE_CODE_IS_COWORK)) {
    await flushSessionStorage()
  }
}

Put plainly: drain the buffered transcript writes before yielding the result message. The desktop app kills the CLI process the moment it receives the result message, so any un-drained writes would be lost.

11.4 Subagent Records: Sidechain Files

export function setAgentTranscriptSubdir(...)
export function clearAgentTranscriptSubdir(agentId: string): void
export function getAgentTranscriptPath(agentId: AgentId): string

export type AgentMetadata = { ... }
export async function writeAgentMetadata(...)
export async function readAgentMetadata(...)

A subagent's transcript is written to its own file, with a metadata record alongside (task description, status, start time, and so on). The main transcript keeps only “a subagent was spawned” and “here's what it returned.”

The benefit of this design: the main record doesn't balloon with a subagent's hundreds of messages, yet when you need to investigate, you can follow the agentId to the complete sub-record.

Remote agents have a separate set of their own:

export type RemoteAgentMetadata = { ... }
export async function writeRemoteAgentMetadata(taskId, ...)
export async function readRemoteAgentMetadata(taskId)
export async function deleteRemoteAgentMetadata(taskId)
export async function listRemoteAgentMetadata()

11.5 Resume: Three Ways

Resume takes a few optional modifiers:

• --fork-session — generate a new session ID. The original session stays untouched; it's “save as”
• --resume-session-at <message-id> — resume only up to the specified message, discarding everything after. It's “go back to a save point”

Rebuilding the chain on resume

The applyPreservedSegmentRelinks function mentioned in section 2.6 handles sessions that have been compacted:

11.6 File History: Rolling Back Files the Agent Changed

utils/fileHistory.ts. This is lightweight version control independent of git.

export type FileHistoryBackup   = { ... }    // one backup
export type FileHistorySnapshot = { ... }    // a snapshot at a point in time
export type FileHistoryState    = { ... }    // overall state
export type DiffStats = ...                  // diff statistics

export function fileHistoryEnabled(): boolean
export async function fileHistoryTrackEdit(...)       // record one edit
export async function fileHistoryMakeSnapshot(...)    // take a snapshot
export async function fileHistoryRewind(...)          // ★ rewind
export function fileHistoryCanRestore(...)            // can it be restored
export async function fileHistoryGetDiffStats(...)    // diff statistics
export async function fileHistoryHasAnyChanges(...)
export async function checkOriginFileChanged(...)     // ★ detect external modification
export function fileHistoryRestoreStateFromLog(...)   // rebuild state from the log
export async function copyFileHistoryForResume(...)   // copy history on resume

When snapshots are taken

// QueryEngine.ts
if (fileHistoryEnabled() && persistSession) {
  messagesFromUserInput
    .filter(messageSelector().selectableUserMessagesFilter)
    .forEach(message => {
      void fileHistoryMakeSnapshot(
        (updater) => { setAppState(prev => ({ ...prev, fileHistory: updater(prev.fileHistory) })) },
        message.uuid,      // ★ snapshots are anchored to the "user message's uuid"
      )
    })
}

Every user message gets a snapshot. So the user can say “go back to the state before I asked this question” — the matching command-line flag:

--rewind-files <user-message-id>
  Restore files to state at the specified user message and exit (requires --resume)
  (i.e. roll the files back to how they stood at that user message, then quit)

Detecting external modifications

checkOriginFileChanged handles this scenario: the agent read a.ts, you changed it in your editor, and now the agent wants to change the same file.

Without detection, the agent would edit based on the old content and overwrite your changes. So it detects and flags — typically by rejecting the edit and requiring the model to re-read first.

11.7 Multi-Source Settings and Migrations

Settings source priority

--setting-sources <sources>
  Comma-separated list of setting sources to load (user, project, local).

The existence of the “local” layer matters: it keeps personal, temporary settings (say, “authorize one more directory on this machine of mine”) from polluting the team-shared project settings.

Settings migrations

The migrations/ directory has 13 files. Their job: after the program is upgraded, automatically convert old-format settings files to the new format.

Any product maintained over the long term needs this — otherwise every change to the settings structure would break existing users' configs. And migrations have to be idempotent and safe to run repeatedly, because you don't know which version the user is upgrading from.

11.8 The Memory Directory

memdir/, 10 files. It manages long-term memory across sessions.

The recall mechanism was covered in section 3.9: prefetch + model judges relevance + dedup against the read-file state.

Note a trait of this design: memories are human-readable plain-text files that can be managed with git. No vector database, no embedding model.

There's also the special CLAUDE.md file, which is loaded nested by directory level: when working in ~/project/src/utils/, it loads ~/project/CLAUDE.md, ~/project/src/CLAUDE.md, and ~/project/src/utils/CLAUDE.md in turn. The closer to the current directory, the more specific the rules and the higher their priority.

12 · The Observability System

This chapter covers something that almost never appears in architecture discussions but decides whether a product can keep evolving over the long run: how the system knows what's happening to itself.

12.1 Instrumentation Density

The numbers first:

12.2 Event Naming

Every event starts with tengu_ (tengu is an internal codename). The event names that appear in the main loop show the naming pattern:

Two patterns in the naming

Pattern one: paired instrumentation. xxx_used / xxx_not_used, xxx_before / xxx_after — that's what lets you compute ratios and deltas, not just absolute counts.

The pair tengu_streaming_tool_execution_used/not_used, for instance, gives you “the streaming executor's enablement rate” directly. If that ratio suddenly drops after a release, some code path is unexpectedly bypassing it.

Pattern two: carry the decision's “why.” tengu_auto_mode_decision records not just “allowed or denied” but also fastPath: 'acceptEdits' | 'allowlist' — which fast path was taken. That's what lets you evaluate “what percentage of classifier calls did the fast paths intercept,” in other words, whether the optimization is worth it at all.

12.3 Query Chain Tracing

Nearly every instrumentation call carries two fields:

queryChainId: queryChainIdForAnalytics,   // unique ID for this user request
queryDepth:   queryTracking.depth,        // agent nesting depth (main 0, child 1, grandchild 2)

The generation logic was covered in section 3.9:

const queryTracking = toolUseContext.queryTracking
  ? { chainId: toolUseContext.queryTracking.chainId,          // inherit the parent's chain ID
      depth:   toolUseContext.queryTracking.depth + 1 }       // depth +1
  : { chainId: deps.uuid(), depth: 0 }                        // top level: create a new one

12.4 Privacy Protection at the Type Level

The instrumentation code is full of an odd type cast:

toolName: sanitizeToolNameForAnalytics(tool.name),
errorDetails: errorContent.slice(0, 2000)
  as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
queryChainId: queryTracking.chainId
  as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,

Read the type name as plain words: analytics metadata: I verified this is not code or file paths.

There's a companion sanitizer too: sanitizeToolNameForAnalytics() — because MCP tool names include the server name, and server names can be user-defined and contain sensitive information.

12.5 Cache-Break Detection

A dedicated subsystem monitors the health of the prompt cache: services/api/promptCacheBreakDetection.ts, controlled by the compile-time flag PROMPT_CACHE_BREAK_DETECTION.

What it monitors

Normally, a session's cache-read volume should grow turn over turn (the history keeps getting longer, so more and more of it hits the cache). If it suddenly plunges on some turn, the cache was broken — some code changed the context prefix.

But some drops are legitimate

So the system provides an interface for proactive notification:

// microCompact.ts, after a cache edit runs
// Notify cache break detection that cache reads will legitimately drop
if (feature('PROMPT_CACHE_BREAK_DETECTION')) {
  notifyCacheDeletion(querySource ?? 'repl_main_thread')
}

// after time-based microcompaction runs
// We just changed the prompt content — the next response's cache read will
// be low, but that's us, not a break. Tell the detector to expect a drop.
if (feature('PROMPT_CACHE_BREAK_DETECTION') && querySource) {
  notifyCacheDeletion(querySource)
}

Put plainly: we just changed the prompt content — the next response's cache read will be low, but that's us, not a break. Tell the detector to expect a drop.

12.6 Profiling Checkpoints

Two sets of checkpoints are scattered through the code:

// startup path
profileCheckpoint('cli_entry')
profileCheckpoint('cli_dump_system_prompt_path')
profileCheckpoint('cli_bridge_path')
...

// latency tracking in headless mode
headlessProfilerCheckpoint('before_getSystemPrompt')
headlessProfilerCheckpoint('after_getSystemPrompt')
headlessProfilerCheckpoint('before_skills_plugins')
headlessProfilerCheckpoint('after_skills_plugins')
headlessProfilerCheckpoint('system_message_yielded')
headlessProfilerCheckpoint('query_started')

// inside the main loop
queryCheckpoint('query_fn_entry')
queryCheckpoint('query_snip_start') / queryCheckpoint('query_snip_end')
queryCheckpoint('query_microcompact_start') / ('query_microcompact_end')
queryCheckpoint('query_autocompact_start') / ('query_autocompact_end')
queryCheckpoint('query_setup_start') / ('query_setup_end')
queryCheckpoint('query_api_loop_start')
queryCheckpoint('query_api_streaming_start') / ('query_api_streaming_end')
queryCheckpoint('query_tool_execution_start') / ('query_tool_execution_end')
queryCheckpoint('query_recursive_call')

Note how these checkpoints are distributed: they map almost exactly onto each stage of the five-stage pipeline from chapter 6. That's no coincidence — only by measuring each stage's time on its own can you judge “whether optimizing this stage is worth it.”

There's a heavier option too: the compile-time flag PERFETTO_TRACING. Perfetto is Google's performance tracing tool, which produces a visual timeline.

12.7 Slow-Operation Logging

The compile-time flags include SLOW_OPERATION_LOGGING, with a matching module utils/slowOperations.ts. It exports a function called jsonStringify — meaning even “turn an object into a JSON string” has been wrapped on its own and brought under slow-operation monitoring.

Why? Because in this system, the object being serialized may be hundreds of MB of message history. At that scale, JSON.stringify blocks the main thread for hundreds of milliseconds — and the main thread is simultaneously rendering the streaming UI, so the stutter is visible to the user immediately.

12.8 The In-Memory Error Buffer

const errorLogWatermark = getInMemoryErrors().at(-1)
...
errors: (() => {
  const all = getInMemoryErrors()
  const start = errorLogWatermark ? all.lastIndexOf(errorLogWatermark) + 1 : 0
  return [ `[ede_diagnostic] ...`, ...all.slice(start).map(_ => _.error) ]
})()

The system keeps a ring buffer holding only the most recent 100 entries of error logs in memory. When an execution fails, the errors “within this turn's range” get packaged into the result together.

Section 2.7 covered the watermark trick here: remember a reference to the element, not an array index, because the ring buffer shifts and indices slide away.

12.9 Loud Logging for Internal Errors

// To help track down bugs, log loudly for ants
logAntError('Query error', error)

The system distinguishes two kinds of error logging:

12.10 Cost-Awareness in Instrumentation

One last point worth noting: instrumentation has costs of its own, and Claude Code is aware of it.

// query.ts
const dumpPromptsFetch = config.gates.isAnt
  ? createDumpPromptsFetch(toolUseContext.agentId ?? config.sessionId)
  : undefined

The comment explains why this object is created only once:

13 · Build and Distribution

The last chapter covers how 512,000 lines of TypeScript become a single file you can double-click to run, and how that build process in turn shapes the way the code is written.

13.1 The Bun Single-File Executable

The facts first:

$ ls -la ~/.local/share/claude/versions/
-rwxr-xr-x  272553824  2.1.223      ← 260 MB
-rwxr-xr-x  279661952  2.1.226      ← 267 MB
-rwxr-xr-x  310740672  2.1.234      ← 296 MB

One file, 296 MB, directly executable. No Node.js to install, no npm install, no runtime dependencies of any kind.

This is a Bun capability: it can package “the JavaScript runtime + all your code + every dependency + all static assets” into one binary.

Embedding native programs

Section 4.4 mentioned a conditional:

// Ant-native builds have bfs/ugrep embedded in the bun binary (same ARGV0
// trick as ripgrep). When available, find/grep in Claude's shell are aliased
// to these fast tools, so the dedicated Glob/Grep tools are unnecessary.
...(hasEmbeddedSearchTools() ? [] : [GlobTool, GrepTool]),

Put plainly: internal native builds embed bfs / ugrep in the bun executable (using the same ARGV0 trick as ripgrep). When they're available, find/grep in Claude's shell are aliased to these fast tools, so the standalone Glob/Grep tools become unnecessary.

13.2 Compile-Time Feature Flags: 89 of Them

This pattern is everywhere in the source:

import { feature } from 'bun:bundle'

const reactiveCompact = feature('REACTIVE_COMPACT')
  ? (require('./services/compact/reactiveCompact.js') as typeof import('...'))
  : null

if (feature('CONTEXT_COLLAPSE')) {
  collapseOwnsIt = (contextCollapse?.isContextCollapseEnabled() ?? false) && isAutoCompactEnabled()
}

The count comes to 89 distinct compile-time flags. A partial list:

13.3 Dead-Code Elimination: Why It's Not Just an “if”

feature() is fundamentally different from an ordinary runtime check: at bundle time it's replaced with the literal true or false, and the bundler then deletes the unreachable branch wholesale.

That has three consequences:

The coding style born of the “excluded strings” check

The source has several comments like this:

// Entire block gated behind feature() so the excluded string
// is eliminated from external builds.
if (feature('CACHED_MICROCOMPACT') && pendingCacheEdits) { ... }

// The subtype check lives inside the injected callback so feature-gated
// strings stay out of this file (excluded-strings check).
snipReplay?: (yieldedSystemMsg, store) => { messages, executed } | undefined

The second one is especially telling. To keep an internal feature's string out of the external artifact, they turned a piece of logic into “a callback injected from outside” — so the string exists only on the injecting side (a module compiled only in internal builds).

Another spot: the ESLint rules join in

// biome-ignore-all assist/source/organizeImports: ANT-ONLY import markers must not be reordered
/* eslint-disable custom-rules/no-process-env-top-level, @typescript-eslint/no-require-imports */
/* eslint-disable custom-rules/no-top-level-side-effects */

You can see several custom lint rules:

• custom-rules/no-process-env-top-level — forbids reading environment variables at module top level (top-level code runs at import time, which would break the fast path's “zero loading”)
• custom-rules/no-top-level-side-effects — forbids top-level side effects (same reason)
• custom-rules/require-tool-match-name — requires the unified tool-name matching function (tools have aliases, so comparing strings directly would miss some)
• “ANT-ONLY import markers must not be reordered” — import-sorting tools would scramble those markers and defeat dead-code elimination

These rules are automated guardians of the build constraints. Not humans eyeballing it in code review, but violating code simply failing the check.

13.4 Compile-Time Macros

// MACRO.VERSION is inlined at build time
console.log(`${MACRO.VERSION} (Claude Code)`)

MACRO is a macro replaced with a literal at build time. So the --version fast path doesn't even need to read a config file (section 1.2).

13.5 Runtime Feature Flags: A Separate System

Besides compile-time flags, there's a set of runtime flags, using GrowthBook (an A/B experimentation platform):

const capEnabled = getFeatureValue_CACHED_MAY_BE_STALE('tengu_otk_slot_v1', false)

Note the function name: getFeatureValue_CACHED_MAY_BE_STALE (get feature value — cached — may be stale).

How the two flag systems divide the work

The two are often stacked: the compile-time flag decides “is this code present,” and the runtime flag decides “if present, should it run.” The cached microcompaction in section 6.3 works this way:

if (feature('CACHED_MICROCOMPACT')) {              // compile-time: external builds don't have this code
  const mod = await getCachedMCModule()
  if (mod.isCachedMicrocompactEnabled() &&         // runtime: can be switched off at any time
      mod.isModelSupportedForCacheEditing(model) &&
      isMainThreadSource(querySource)) {
    return await cachedMicrocompactPath(messages, querySource)
  }
}

13.6 Versions and Updates

The layout of the install directory reveals the update strategy:

~/.local/share/claude/
├── ClaudeCode.app/                the desktop app
└── versions/
    ├── 2.1.223                    ← old version, kept
    ├── 2.1.226                    ← old version, kept
    └── 2.1.234                    ← current version

~/.local/bin/claude  →  symlink pointing at versions/2.1.234

Multiple versions coexist; a symlink switches the current one. That way:

• An update is “download the new version + repoint the symlink,” an atomic operation, so there's no “program broke halfway through an update”
• If something goes wrong, rollback takes a second (repoint the symlink)
• Running processes on the old version are unaffected (they've already loaded the file into memory)

The cost is disk usage — three versions is 800 MB. So utils/nativeInstaller/installer.ts (53 KB) presumably has logic for cleaning up old versions.

13.7 Architectural Constraints Inferred from the Build

This chapter's content has actually left traces in every preceding chapter. To sum up “how the build shaped the code”: