Merge d62995e2ff into 4b9d30f795

2026-03-31 18:54:37 +08:00 · 2026-03-31 18:54:37 +08:00 · a07dd5e8c5
commit a07dd5e8c5
parent 4b9d30f795 d62995e2ff
13 changed files with 3340 additions and 0 deletions
--- a/learn/01-system-overview.md
+++ b/learn/01-system-overview.md
@ -0,0 +1,268 @@
 # 1. System Overview
 > The entire Claude Code architecture in one diagram, then unpacked layer by layer.
 ---
 ## The Big Picture
 Claude Code is structured in **8 distinct layers**, each with a clear responsibility. Understanding these layers is the key to navigating the 512K-line codebase.
 ```mermaid
 %%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#1a1a2e', 'primaryTextColor': '#e0e0e0', 'primaryBorderColor': '#4a9eff', 'lineColor': '#4a9eff', 'secondaryColor': '#16213e', 'tertiaryColor': '#0f3460', 'edgeLabelBackground': '#1a1a2e'}}}%%
 graph TB
    CLI["CLI Entry<br/>main.tsx — 804KB"]:::entry
    SDK["SDK Entry<br/>Programmatic API"]:::entry
    MCP_S["MCP Server<br/>Expose as MCP"]:::entry
    REPL["REPL.tsx — 896KB<br/>Interactive Terminal Shell"]:::ui
    Comps["113 Components<br/>Messages, Diffs, Dialogs"]:::ui
    Hooks["83 React Hooks<br/>Permissions, Input, IDE"]:::ui
    QE["QueryEngine.ts<br/>Session Lifecycle Owner"]:::core
    QL["query.ts — 1730 lines<br/>Agentic Loop"]:::core
    CL["claude.ts — 3420 lines<br/>Anthropic API Client"]:::core
    TD["Tool Interface<br/>Tool.ts"]:::tool
    BT["42 Built-in Tools"]:::tool
    MT["MCP Tools — dynamic"]:::tool
    TO["Tool Orchestration<br/>Parallel Execution"]:::tool
    Compact["Compaction Pipeline<br/>snip / micro / auto /<br/>reactive / collapse"]:::ctx
    Rules["Allow + Deny Rules"]:::perm
    HK["PreToolUse Hooks"]:::perm
    Classifier["Auto-mode Classifier"]:::perm
    AS["AppState Store<br/>Immutable — 50+ fields"]:::state
    SS["Session Storage<br/>Transcripts + Resume"]:::state
    Cfg["Config Layer<br/>Global / Project / CLAUDE.md"]:::state
    Skills["Skills"]:::ext
    Plugins["Plugins"]:::ext
    Agents["Sub-agents + Swarms"]:::ext
    API["Anthropic Messages API"]:::external
    MCP_Ext["External MCP Servers"]:::external
    GrowthBook["GrowthBook + Statsig"]:::external
    CLI --> REPL
    SDK --> QE
    MCP_S --> QE
    REPL --> Comps
    REPL --> Hooks
    REPL --> QE
    REPL --> AS
    QE --> QL
    QL --> CL
    QL --> Compact
    QL --> TO
    CL --> API
    CL --> GrowthBook
    TO --> TD
    TD --> BT
    TD --> MT
    BT --> Rules
    BT --> HK
    MT --> Rules
    Rules --> Classifier
    QE --> SS
    REPL --> Cfg
    Skills --> TD
    Plugins --> TD
    Plugins --> MCP_Ext
    Agents --> QL
    MCP_Ext --> MT
    classDef entry fill:#0d4f4f,stroke:#17a2b8,color:#e0e0e0,stroke-width:2px
    classDef ui fill:#1a1a4e,stroke:#6f42c1,color:#e0e0e0,stroke-width:2px
    classDef core fill:#2d1b4e,stroke:#e83e8c,color:#e0e0e0,stroke-width:2px
    classDef tool fill:#1b3a1b,stroke:#28a745,color:#e0e0e0,stroke-width:2px
    classDef ctx fill:#3d2b00,stroke:#fd7e14,color:#e0e0e0,stroke-width:2px
    classDef perm fill:#4a1a1a,stroke:#dc3545,color:#e0e0e0,stroke-width:2px
    classDef state fill:#1a2d4a,stroke:#4a9eff,color:#e0e0e0,stroke-width:2px
    classDef ext fill:#2d2d0d,stroke:#ffc107,color:#e0e0e0,stroke-width:2px
    classDef external fill:#333,stroke:#888,color:#aaa,stroke-width:1px,stroke-dasharray: 5 5
 ```
 ---
 ## Layer 1: Entry Points
 There are **three ways** into Claude Code:
 | Entry | File | How It Works |
 |-------|------|-------------|
 | **CLI** | `src/main.tsx` (804KB) | Commander.js parses args → boots React/Ink → renders `REPL.tsx` |
 | **SDK** | `src/entrypoints/sdk/` | Programmatic API → creates `QueryEngine` directly |
 | **MCP Server** | `src/entrypoints/mcp.ts` | Exposes Claude Code itself as an MCP server |
 ### Key Insight: Parallel Prefetch
 Startup time is critical for a CLI tool. Claude Code parallelizes heavy work *before* any module evaluation:
 ```typescript
 // main.tsx — fired as side-effects before other imports
 startMdmRawRead()      // MDM settings (enterprise)
 startKeychainPrefetch() // API key from macOS Keychain
 ```
 Heavy modules like OpenTelemetry (~400KB) and gRPC (~700KB) are loaded lazily via dynamic `import()` only when needed.
 ---
 ## Layer 2: UI — React in a Terminal
 This is where it gets wild. Claude Code uses **React** (yes, the web framework) to render a terminal UI via [Ink](https://github.com/vadimdemedes/ink).
 | What | Count | Examples |
 |------|-------|---------|
 | Components | 113 files | Messages, Diffs, Dialogs, Settings, Spinners |
 | React Hooks | 83 files | `useCanUseTool`, `useVoice`, `useReplBridge`, `useTypeahead` |
 The crown jewel is `REPL.tsx` at **896KB** — a single React component that is the entire interactive terminal experience. It handles:
 - Message rendering and virtual scrolling
 - Permission dialogs
 - Tool progress indicators
 - Keyboard shortcuts and vim mode
 - Voice input
 - IDE bridge integration
 - Background task management
 ### Why React for a CLI?
 React's component model gives you:
 - **Declarative UI** — Describe what to render, not how
 - **Hooks** — Share stateful logic across 83 hooks
 - **State management** — AppState drives re-renders
 - **Composability** — 113 components snap together
 ---
 ## Layer 3: Core Engine
 The engine has three key files forming a pipeline:
 ```
 QueryEngine.ts → query.ts → claude.ts
 (session owner)   (loop)     (API client)
 ```
 1. **`QueryEngine.ts`** — Owns the session lifecycle. Creates a conversation, manages transcripts, tracks usage, and handles resume.
 2. **`query.ts`** — The **agentic loop**. This is the beating heart. It cycles between calling the model and executing tools until the model says `end_turn`. (See [Guide 2: The Agentic Loop](./02-agentic-loop.md))
 3. **`claude.ts`** — The Anthropic API client. Handles streaming SSE responses, retry logic (429/529), prompt caching, and model fallback. (See [Guide 8: API Client](./08-api-client.md))
 ---
 ## Layer 4: Tool System
 Every capability Claude Code has — reading files, running bash, searching the web — is implemented as a **Tool**. There are 42 built-in tools, plus dynamic MCP tools loaded at runtime.
 Tools are self-contained modules with a standard interface defined in `Tool.ts` (793 lines):
 ```typescript
 type Tool = {
  name: string
  inputSchema: ZodSchema       // Validate inputs
  checkPermissions(input, ctx)  // Permission check
  call(input, ctx)              // Execute
  prompt(options)               // Describe to model
  renderToolUseMessage(input)   // Terminal rendering
  // ... 30+ more methods
 }
 ```
 Full breakdown in [Guide 3: Tool System](./03-tool-system.md).
 ---
 ## Layer 5: Context Management
 LLMs have finite context windows. Claude Code has a sophisticated **5-stage compaction pipeline** to keep conversations within limits:
 1. **Snip Compact** — Sliding window, drop oldest turns
 2. **Micro Compact** — Truncate oversized individual tool results
 3. **Auto Compact** — Summarize via a separate API call
 4. **Context Collapse** — Read-time projection with archived views
 5. **Reactive Compact** — Emergency trigger on API 413 errors
 Full breakdown in [Guide 5: Context Management](./05-context-management.md).
 ---
 ## Layer 6: Permission System
 Claude Code can run arbitrary bash commands and write to any file. The permission system is a multi-layered defense:
 ```
 Deny Rules → Allow Rules → Tool Check → Hooks → Classifier → User Dialog
 ```
 Four distinct permission modes: Default, Plan, Auto, and Bypass.
 Full breakdown in [Guide 4: Permission System](./04-permission-system.md).
 ---
 ## Layer 7: State Management
 All application state lives in a **single immutable store** (`AppState`) with 50+ fields, following a simplified Redux pattern:
 - **Consumers** read state via `getAppState()` or React's `useAppState(selector)`
 - **Mutators** update via `setAppState(prev => newState)` (functional updates)
 - **Side effects** fire via `onChangeAppState` listeners
 - The `DeepImmutable<T>` type wrapper enforces immutability at the type level
 Full breakdown in [Guide 6: State Management](./06-state-management.md).
 ---
 ## Layer 8: Extensions
 Claude Code is extensible through four mechanisms:
 | Mechanism | What | Where |
 |-----------|------|-------|
 | **Skills** | Markdown instruction files | `.claude/skills/*.md` |
 | **Plugins** | Bundles of tools + MCP servers | Managed or user-installed |
 | **Hooks** | Pre/PostToolUse scripts | `settings.json` or CLAUDE.md |
 | **Agents** | Sub-agents, coordinators, swarms | AgentTool, tmux-based swarms |
 Full breakdown in [Guide 7: Extension Model](./07-extension-model.md).
 ---
 ## External Dependencies
 | Dependency | Role |
 |-----------|------|
 | **Anthropic Messages API** | The LLM backend — all model calls go here |
 | **External MCP Servers** | Third-party tools exposed via Model Context Protocol |
 | **GrowthBook** | Feature flags — gates like `VOICE_MODE`, `PROACTIVE`, `CONTEXT_COLLAPSE` |
 | **Statsig** | Additional analytics and experimentation |
 ---
 ## Design Principles
 Looking at the codebase, several design principles emerge:
 1. **Feature flags for dead code elimination** — `feature('X')` from `bun:bundle` strips unused code at build time
 2. **Lazy loading** — Heavy modules are `import()`ed only when needed
 3. **Immutable state** — `DeepImmutable<T>` enforces no mutation
 4. **Generator-based streaming** — `async function*` throughout for backpressure-aware streaming
 5. **Self-contained tools** — Each tool is a module with schema, permissions, execution, and rendering
 ---
 **Next:** [The Agentic Loop →](./02-agentic-loop.md)
--- a/learn/02-agentic-loop.md
+++ b/learn/02-agentic-loop.md
@ -0,0 +1,413 @@
 # 2. The Agentic Loop
 > How Claude Code cycles between the model and tools — the core of the entire system.
 ---
 ## What Is the "Agentic Loop"?
 The agentic loop is the mechanism that makes Claude Code more than a chatbot. Instead of:
 ```
 User → Model → Response (done)
 ```
 Claude Code does:
 ```
 User → Model → Tool Call → Model → Tool Call → ... → Response (done)
 ```
 The model can call tools, see results, and decide what to do next — in a **loop** — until it decides it's finished. This loop lives in **`query.ts`** (1,730 lines), and it's the most important file in the entire codebase.
 ---
 ## The Full Sequence
 ```mermaid
 %%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#1a1a2e', 'primaryTextColor': '#e0e0e0', 'lineColor': '#4a9eff', 'actorTextColor': '#e0e0e0', 'actorBorder': '#4a9eff', 'signalColor': '#4a9eff', 'noteBkgColor': '#16213e', 'noteTextColor': '#e0e0e0', 'activationBkgColor': '#2d1b4e', 'activationBorderColor': '#e83e8c'}}}%%
 sequenceDiagram
    participant U as User
    participant QE as QueryEngine
    participant PI as processUserInput
    participant Q as query.ts
    participant CP as Compaction
    participant C as claude.ts
    participant API as Anthropic API
    participant T as Tool Executor
    participant H as Hooks
    U->>QE: submitMessage(prompt)
    activate QE
    QE->>PI: parse slash commands, @mentions, attachments
    PI-->>QE: messages[], shouldQuery
    alt Slash command — no API call needed
        QE-->>U: return local result
    else Model query required
        QE->>QE: persist transcript to disk
        QE->>Q: query(messages, systemPrompt, tools)
        activate Q
        loop Agentic Loop — until end_turn or max_turns
            Q->>CP: snip compact
            CP->>CP: micro compact
            CP->>CP: auto compact
            CP->>CP: context collapse
            CP-->>Q: compacted messages
            Q->>C: queryModel(messages, tools, thinking)
            activate C
            C->>C: build request: betas, cache, effort, budget
            C->>API: POST /v1/messages — SSE stream
            activate API
            API-->>C: message_start — usage
            API-->>C: content_block — thinking / text / tool_use
            API-->>C: message_delta — stop_reason, final usage
            deactivate API
            C-->>Q: yield AssistantMessage + StreamEvents
            deactivate C
            alt stop_reason = end_turn
                Q->>H: postSamplingHooks
                Q->>Q: handleStopHooks
                Q-->>QE: return Terminal result
            else stop_reason = tool_use
                Q->>T: runTools(toolUseBlocks)
                activate T
                T->>T: validate input against schema
                T->>H: PreToolUse hooks
                T->>T: check permissions
                T->>T: call(input, context)
                T->>H: PostToolUse hooks
                T-->>Q: yield tool_result messages
                deactivate T
                Q->>Q: inject CLAUDE.md attachments
                Note over Q: push tool_results, continue loop
            else stop_reason = max_tokens
                Q->>Q: truncation retry — up to 3x
                Q->>CP: reactive compact — emergency
            end
        end
        deactivate Q
        QE->>QE: accumulate usage, persist transcript
        QE-->>U: yield SDKMessage stream
    end
    deactivate QE
 ```
 ---
 ## Anatomy of `query.ts`
 The file exports a single async generator function:
 ```typescript
 export async function* query(params: QueryParams):
  AsyncGenerator<StreamEvent | Message | ToolUseSummaryMessage, Terminal> {
  // ... 1,730 lines of agentic loop
 }
 ```
 ### Why an Async Generator?
 This is a crucial design decision. An async generator (`async function*`) lets query.ts:
 1. **Yield messages as they arrive** — The consumer (REPL or SDK) sees each message in real-time
 2. **Maintain backpressure** — The loop pauses if the consumer isn't ready
 3. **Support cancellation** — `.return()` on the generator cleanly tears down the loop
 4. **Compose generators** — `yield*` delegates to sub-generators seamlessly
 ### The Loop State
 Each loop iteration carries mutable state:
 ```typescript
 type State = {
  messages: Message[]                      // Conversation history
  toolUseContext: ToolUseContext            // Tool execution context
  autoCompactTracking: AutoCompactTrackingState  // Compact progress
  maxOutputTokensRecoveryCount: number     // Truncation retry counter
  hasAttemptedReactiveCompact: boolean     // Emergency compact flag
  turnCount: number                        // Loop iteration counter
  pendingToolUseSummary: Promise<...>       // Async summary generation
  transition: Continue | undefined         // Why we're in this iteration
 }
 ```
 ---
 ## Phase 1: Pre-Processing — Before the API Call
 Before every API call, query.ts runs a **compaction pipeline** on the message history:
 ```typescript
 // 1. Apply per-message tool result budgets
 messagesForQuery = await applyToolResultBudget(messagesForQuery, ...)
 // 2. Snip compact — sliding window over old turns
 if (feature('HISTORY_SNIP')) {
  const snipResult = snipModule.snipCompactIfNeeded(messagesForQuery)
  messagesForQuery = snipResult.messages
 }
 // 3. Micro compact — truncate oversized tool results
 const microcompactResult = await deps.microcompact(messagesForQuery, ...)
 messagesForQuery = microcompactResult.messages
 // 4. Context collapse — read-time projection
 if (feature('CONTEXT_COLLAPSE') && contextCollapse) {
  const collapseResult = await contextCollapse.applyCollapsesIfNeeded(...)
  messagesForQuery = collapseResult.messages
 }
 // 5. Auto compact — full summarization via API
 const { compactionResult } = await deps.autocompact(messagesForQuery, ...)
 ```
 Each stage is feature-gated and runs **independently**. They compose — snip reduces history, micro truncates individual results, auto summarizes the whole thing, collapse archives old views.
 ### Blocking Limit Check
 After compaction, the loop checks if we're at the **blocking limit** (>98% context used):
 ```typescript
 const { isAtBlockingLimit } = calculateTokenWarningState(
  tokenCountWithEstimation(messagesForQuery),
  toolUseContext.options.mainLoopModel,
 )
 if (isAtBlockingLimit) {
  yield createAssistantAPIErrorMessage({ content: PROMPT_TOO_LONG_ERROR_MESSAGE })
  return { reason: 'blocking_limit' }
 }
 ```
 This prevents the API call entirely if we know it'll fail.
 ---
 ## Phase 2: The API Call
 The actual model call uses `claude.ts`:
 ```typescript
 for await (const message of deps.callModel({
  messages: prependUserContext(messagesForQuery, userContext),
  systemPrompt: fullSystemPrompt,
  thinkingConfig: toolUseContext.options.thinkingConfig,
  tools: toolUseContext.options.tools,
  signal: toolUseContext.abortController.signal,
  options: {
    model: currentModel,
    fallbackModel,
    effortValue: appState.effortValue,
    taskBudget: params.taskBudget,
    // ... 20+ more options
  },
 })) {
  // Process each streamed message
 }
 ```
 Responses stream in as SSE events. The loop processes three content block types:
 | Block Type | What Happens |
 |-----------|-------------|
 | `thinking` | Rendered in UI, not sent back to model |
 | `text` | Rendered as markdown in terminal |
 | `tool_use` | Triggers tool execution (next phase) |
 ---
 ## Phase 3: Tool Execution
 When the model responds with `tool_use` blocks, the loop executes them:
 ```typescript
 // Parallel tool execution
 const toolResults = yield* runTools(toolUseBlocks, canUseTool, toolUseContext)
 ```
 ### Streaming Tool Execution
 A performance optimization: tools can begin executing **while the model is still streaming**:
 ```typescript
 const useStreamingToolExecution = config.gates.streamingToolExecution
 let streamingToolExecutor = useStreamingToolExecution
  ? new StreamingToolExecutor(tools, canUseTool, toolUseContext)
  : null
 ```
 The `StreamingToolExecutor` starts validating and permission-checking tool calls as their blocks arrive, before the full response is complete.
 ### Tool Lifecycle
 Each tool goes through:
 1. **Schema Validation** — Zod validates the input against `tool.inputSchema`
 2. **PreToolUse Hooks** — User-defined scripts can approve, deny, or modify the input
 3. **Permission Check** — Deny rules → Allow rules → Tool-specific check → Classifier → User dialog
 4. **Execution** — `tool.call(input, context)` runs the actual operation
 5. **PostToolUse Hooks** — Scripts run after execution with the result
 ---
 ## Phase 4: Loop Continuation
 After tools execute, the loop decides what to do next based on the `stop_reason`:
 ### `end_turn` — Model is done
 ```typescript
 if (stop_reason === 'end_turn') {
  // Run post-sampling hooks
  await executePostSamplingHooks(assistantMessage, toolUseContext)
  // Check stop hooks (can force continuation)
  const stopResult = await handleStopHooks(assistantMessage, messages)
  if (stopResult.shouldContinue) {
    // Inject hook feedback and continue loop
  } else {
    return { reason: 'end_turn' }  // Terminal — loop exits
  }
 }
 ```
 ### `tool_use` — Model wants to use tools
 The tool results are pushed to messages and the loop continues:
 ```typescript
 messages.push(...toolResults)
 // Inject CLAUDE.md attachments for newly-discovered memory files
 const attachments = await getAttachmentMessages(messages, toolUseContext)
 messages.push(...attachments)
 // Continue to next iteration (back to Phase 1)
 ```
 ### `max_tokens` — Response was truncated
 ```typescript
 if (maxOutputTokensRecoveryCount < MAX_OUTPUT_TOKENS_RECOVERY_LIMIT) {
  // Retry with increased max_tokens
  state.maxOutputTokensRecoveryCount++
  continue
 } else {
  // Trigger reactive compact as last resort
  state.hasAttemptedReactiveCompact = true
 }
 ```
 ---
 ## QueryEngine: The Session Wrapper
 `QueryEngine.ts` wraps `query()` in a session lifecycle:
 ```typescript
 class QueryEngine {
  private mutableMessages: Message[]
  private totalUsage: NonNullableUsage
  private readFileState: FileStateCache
  async *submitMessage(prompt): AsyncGenerator<SDKMessage> {
    // 1. Parse user input (slash commands, @mentions)
    const { messages, shouldQuery } = await processUserInput({ input: prompt })
    // 2. Persist transcript to disk
    await recordTranscript(messages)
    // 3. Run the agentic loop
    if (shouldQuery) {
      for await (const message of query({ messages, systemPrompt, tools })) {
        // 4. Map internal messages to SDK format
        yield normalizedSDKMessage(message)
        // 5. Persist each message
        await recordTranscript(messages)
      }
    }
    // 6. Return final result with usage stats
    yield { type: 'result', total_cost_usd, usage, duration_ms }
  }
 }
 ```
 ---
 ## Key Patterns to Understand
 ### 1. Generator Composition
 The codebase uses `yield*` heavily to compose generators:
 ```typescript
 // query.ts delegates to sub-generators
 yield* runTools(toolUseBlocks, canUseTool, toolUseContext)
 // QueryEngine delegates to query
 for await (const message of query(params)) {
  yield* normalizeMessage(message)
 }
 ```
 ### 2. Feature-Gated Loading
 Code paths are gated by build-time feature flags:
 ```typescript
 const reactiveCompact = feature('REACTIVE_COMPACT')
  ? require('./services/compact/reactiveCompact.js')
  : null
 // Later...
 if (reactiveCompact?.isReactiveCompactEnabled()) {
  // This entire branch is eliminated in builds where REACTIVE_COMPACT is false
 }
 ```
 ### 3. Tombstone Messages
 When a streaming fallback occurs (model switch mid-stream), orphaned messages are tombstoned:
 ```typescript
 for (const msg of assistantMessages) {
  yield { type: 'tombstone', message: msg }  // Removed from UI + transcript
 }
 assistantMessages.length = 0  // Reset
 ```
 ### 4. Task Budget Tracking
 API-level task budgets track spend across compaction boundaries:
 ```typescript
 if (params.taskBudget) {
  const preCompactContext = finalContextTokensFromLastResponse(messagesForQuery)
  taskBudgetRemaining = Math.max(
    0,
    (taskBudgetRemaining ?? params.taskBudget.total) - preCompactContext,
  )
 }
 ```
 ---
 ## Common Debugging Scenarios
 | Symptom | Where to Look |
 |---------|--------------|
 | Loop never stops | Check `maxTurns` limit, `handleStopHooks` |
 | Tool not executing | Permission system — check deny rules, hooks, classifier |
 | Context too large | Compaction pipeline — which stage is failing? |
 | Model fallback | `withRetry` in claude.ts — 529 overloaded triggers |
 | Truncation errors | `MAX_OUTPUT_TOKENS_RECOVERY_LIMIT` (3 retries) |
 ---
 **Previous:** [← System Overview](./01-system-overview.md) · **Next:** [Tool System →](./03-tool-system.md)
--- a/learn/03-tool-system.md
+++ b/learn/03-tool-system.md
@ -0,0 +1,445 @@
 # 3. Tool System
 > How 42 built-in tools are defined, validated, orchestrated, and rendered.
 ---
 ## Overview
 Every capability Claude Code has — reading files, running bash, editing code, searching the web — is a **Tool**. Tools are the bridge between the model's intentions and the real world.
 ```mermaid
 %%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#1a1a2e', 'primaryTextColor': '#e0e0e0', 'primaryBorderColor': '#28a745', 'lineColor': '#28a745', 'secondaryColor': '#16213e', 'tertiaryColor': '#0f3460'}}}%%
 graph TB
    subgraph Interface["Tool Interface — Tool.ts"]
        direction LR
        IS["inputSchema<br/>Zod validation"]
        CP["checkPermissions"]
        CALL["call — execute"]
        PROMPT["prompt — model instructions"]
        RENDER["render — terminal UI"]
    end
    IS --> CP --> CALL --> PROMPT --> RENDER
    subgraph FileOps["File Operations"]
        FR["FileRead"]
        FW["FileWrite"]
        FE["FileEdit"]
        GL["Glob"]
        GR["Grep"]
        NE["NotebookEdit"]
    end
    subgraph Exec["Execution"]
        BA["Bash"]
        PS["PowerShell"]
    end
    subgraph Web["Web"]
        WF["WebFetch"]
        WS["WebSearch"]
    end
    subgraph AgentTools["Agent and Task"]
        AG["Agent — spawn sub-agent"]
        TC["TaskCreate"]
        TG["TaskGet"]
        TU["TaskUpdate"]
        TL["TaskList"]
        TS["TaskStop"]
        SM["SendMessage"]
    end
    subgraph Meta["Meta Tools"]
        AQ["AskUserQuestion"]
        SK["SkillTool"]
        TW["TodoWrite"]
        EP["EnterPlanMode"]
        XP["ExitPlanMode"]
        TSR["ToolSearch"]
    end
    subgraph Dynamic["Dynamic — Runtime Loaded"]
        MCP_T["MCP Tools<br/>from external servers"]
        LSP_T["LSP Tool<br/>language server queries"]
    end
    subgraph Orchestration["Orchestration Layer"]
        RUN["toolOrchestration.ts<br/>runTools — parallel dispatch"]
        STE["StreamingToolExecutor<br/>execute as blocks stream in"]
        TEX["toolExecution.ts — 60KB<br/>single tool lifecycle"]
        THK["toolHooks.ts<br/>Pre/Post hook dispatch"]
    end
    Interface --> FileOps
    Interface --> Exec
    Interface --> Web
    Interface --> AgentTools
    Interface --> Meta
    Interface --> Dynamic
    FileOps --> Orchestration
    Exec --> Orchestration
    Web --> Orchestration
    AgentTools --> Orchestration
    Meta --> Orchestration
    Dynamic --> Orchestration
    RUN --> STE
    RUN --> TEX
    TEX --> THK
 ```
 ---
 ## The Tool Interface — `Tool.ts` (793 lines)
 Every tool implements the `Tool<Input, Output, Progress>` type. Here are the key methods:
 ```mermaid
 %%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#1a1a2e', 'primaryTextColor': '#e0e0e0', 'lineColor': '#28a745', 'primaryBorderColor': '#28a745'}}}%%
 flowchart LR
    subgraph Definition["Tool Definition"]
        NAME["name: string"]
        SCHEMA["inputSchema: Zod"]
        ALIASES["aliases?: string array"]
        HINT["searchHint?: string"]
    end
    subgraph Lifecycle["Lifecycle Methods"]
        VAL["validateInput<br/>pre-execution check"]
        PERM["checkPermissions<br/>allow / deny / prompt"]
        CALL["call<br/>execute the tool"]
        DESC["description<br/>model-facing summary"]
    end
    subgraph Rendering["Rendering Methods"]
        RUM["renderToolUseMessage<br/>show input in terminal"]
        RRM["renderToolResultMessage<br/>show output in terminal"]
        RPM["renderToolUseProgressMessage<br/>spinner / progress bar"]
        GRP["renderGroupedToolUse<br/>parallel display"]
    end
    subgraph Metadata["Metadata Methods"]
        RO["isReadOnly<br/>does it write?"]
        CS["isConcurrencySafe<br/>parallel safe?"]
        EN["isEnabled<br/>available now?"]
        DS["isDestructive<br/>irreversible?"]
        AC["toAutoClassifierInput<br/>safety classifier text"]
    end
    Definition --> Lifecycle --> Rendering
    Definition --> Metadata
 ```
 ### The `buildTool` Factory
 All tools go through `buildTool()` which provides safe defaults:
 ```typescript
 const TOOL_DEFAULTS = {
  isEnabled: () => true,
  isConcurrencySafe: () => false,    // Assume not safe
  isReadOnly: () => false,            // Assume writes
  isDestructive: () => false,
  checkPermissions: (input) =>        // Defer to general system
    Promise.resolve({ behavior: 'allow', updatedInput: input }),
  toAutoClassifierInput: () => '',    // Skip classifier
  userFacingName: () => '',
 }
 export function buildTool(def) {
  return { ...TOOL_DEFAULTS, userFacingName: () => def.name, ...def }
 }
 ```
 This "fail-closed" design means a tool that forgets to implement `isConcurrencySafe` defaults to `false` (not safe for parallel execution).
 ---
 ## The 42 Built-in Tools
 ```mermaid
 %%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#1a1a2e', 'primaryTextColor': '#e0e0e0', 'lineColor': '#17a2b8', 'primaryBorderColor': '#17a2b8'}}}%%
 graph TB
    subgraph FileOps["File Operations — Read + Write + Search"]
        FR["FileRead<br/>Read files, images,<br/>PDFs, notebooks"]
        FW["FileWrite<br/>Create or overwrite<br/>entire files"]
        FE["FileEdit<br/>Partial string<br/>replacement edits"]
        GL["Glob<br/>File pattern<br/>matching search"]
        GR["Grep<br/>ripgrep content<br/>search"]
        NE["NotebookEdit<br/>Jupyter notebook<br/>cell editing"]
    end
    subgraph Exec["Execution — Run Commands"]
        BA["Bash<br/>Shell command<br/>execution"]
        PS["PowerShell<br/>Windows shell<br/>execution"]
        REPL["REPL<br/>Persistent JS/TS<br/>runtime context"]
    end
    subgraph Web["Web — Fetch and Search"]
        WF["WebFetch<br/>HTTP GET to URLs<br/>HTML to markdown"]
        WS["WebSearch<br/>Web search via<br/>Brave or similar"]
    end
    subgraph AgentTask["Agent and Task Management"]
        AG["Agent<br/>Spawn sub-agent<br/>with forked context"]
        TC["TaskCreate<br/>Background task"]
        TG["TaskGet<br/>Check task status"]
        TU["TaskUpdate<br/>Update task state"]
        TL["TaskList<br/>List all tasks"]
        TS["TaskStop<br/>Terminate task"]
        SM["SendMessage<br/>Inter-agent<br/>messaging"]
        TmC["TeamCreate<br/>Create agent team"]
        TmD["TeamDelete<br/>Remove agent team"]
    end
    subgraph Meta["Meta Tools — Control Claude's Behavior"]
        AQ["AskUserQuestion<br/>Interactive prompt"]
        SK["SkillTool<br/>Execute skills"]
        TW["TodoWrite<br/>Manage task lists"]
        EP["EnterPlanMode<br/>Switch to read-only"]
        XP["ExitPlanMode<br/>Resume full access"]
        TSR["ToolSearch<br/>Find deferred tools"]
        BF["Brief<br/>Toggle concise mode"]
        SL["Sleep<br/>Idle wait for<br/>proactive mode"]
        SO["SyntheticOutput<br/>Structured JSON<br/>output"]
    end
    subgraph Dynamic["Dynamic — Loaded at Runtime"]
        MCP["MCP Tools<br/>From external<br/>MCP servers"]
        LSP["LSP Tool<br/>Language server<br/>queries"]
    end
    subgraph Special["Special Purpose"]
        EW["EnterWorktree<br/>Git worktree<br/>isolation"]
        XW["ExitWorktree<br/>Leave worktree"]
        RT["RemoteTrigger<br/>Remote execution"]
        SC["ScheduleCron<br/>Timed triggers"]
        CF["Config<br/>Settings management"]
    end
 ```
 ---
 ## Tool Orchestration — Parallel Execution
 When the model returns multiple `tool_use` blocks, Claude Code can execute them **in parallel**:
 ```mermaid
 %%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#1a1a2e', 'primaryTextColor': '#e0e0e0', 'lineColor': '#4a9eff', 'primaryBorderColor': '#4a9eff'}}}%%
 sequenceDiagram
    participant Q as query.ts
    participant O as toolOrchestration.ts
    participant STE as StreamingToolExecutor
    participant T1 as Tool 1 — FileRead
    participant T2 as Tool 2 — Grep
    participant T3 as Tool 3 — Bash
    participant P as Permission System
    Q->>O: runTools(3 tool_use blocks)
    activate O
    Note over O: Check concurrency safety
    O->>STE: FileRead — isConcurrencySafe = true
    O->>STE: Grep — isConcurrencySafe = true
    O->>STE: Bash — isConcurrencySafe = false
    par Parallel Execution
        STE->>P: checkPermissions(FileRead)
        P-->>STE: allow
        STE->>T1: call(input)
        T1-->>STE: result
        STE->>P: checkPermissions(Grep)
        P-->>STE: allow
        STE->>T2: call(input)
        T2-->>STE: result
    end
    Note over STE: Wait for parallel tools
    STE->>P: checkPermissions(Bash)
    P-->>STE: prompt user
    STE->>T3: call(input)
    T3-->>STE: result
    O-->>Q: yield all tool_result messages
    deactivate O
 ```
 Key files in the orchestration layer:
 - **`toolOrchestration.ts`** — `runTools()`: dispatches tools, handles parallel vs. sequential
 - **`StreamingToolExecutor`** — Starts permission checks while model is still streaming
 - **`toolExecution.ts`** (60KB) — Single tool lifecycle: validate → permissions → execute → hooks
 - **`toolHooks.ts`** — Dispatches PreToolUse and PostToolUse hooks
 ---
 ## Single Tool Lifecycle
 ```mermaid
 %%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#1a1a2e', 'primaryTextColor': '#e0e0e0', 'lineColor': '#28a745', 'primaryBorderColor': '#28a745'}}}%%
 flowchart TD
    BLOCK["tool_use block arrives<br/>from model stream"]:::start
    PARSE["Parse + validate input<br/>via Zod inputSchema"]:::step
    VAL{"validateInput?"}:::check
    DENY_VAL["Return error to model<br/>with validation message"]:::deny
    PRE_HOOK["Run PreToolUse hooks<br/>user-defined scripts"]:::hook
    HOOK_R{"Hook result?"}:::check
    PERM["Check permissions<br/>deny → allow → tool → hooks → classifier → dialog"]:::step
    PERM_R{"Permission?"}:::check
    EXEC["tool.call(input, context)<br/>execute the operation"]:::step
    RESULT["Map output to tool_result<br/>via mapToolResultToToolResultBlockParam"]:::step
    SIZE{"Result exceeds<br/>maxResultSizeChars?"}:::check
    PERSIST["Persist to disk<br/>return file path + preview"]:::step
    POST_HOOK["Run PostToolUse hooks"]:::hook
    RENDER["Render in terminal<br/>renderToolResultMessage"]:::step
    YIELD["Yield tool_result<br/>to query loop"]:::done
    DENY_PERM["Return permission_denied<br/>error to model"]:::deny
    BLOCK --> PARSE --> VAL
    VAL -->|"pass"| PRE_HOOK
    VAL -->|"fail"| DENY_VAL
    PRE_HOOK --> HOOK_R
    HOOK_R -->|"approve"| PERM
    HOOK_R -->|"deny"| DENY_PERM
    HOOK_R -->|"modify input"| PERM
    PERM --> PERM_R
    PERM_R -->|"allow"| EXEC
    PERM_R -->|"deny"| DENY_PERM
    EXEC --> RESULT --> SIZE
    SIZE -->|"within limit"| POST_HOOK
    SIZE -->|"exceeds limit"| PERSIST --> POST_HOOK
    POST_HOOK --> RENDER --> YIELD
    classDef start fill:#1a2d4a,stroke:#4a9eff,color:#e0e0e0,stroke-width:2px
    classDef step fill:#1b3a1b,stroke:#28a745,color:#e0e0e0,stroke-width:2px
    classDef check fill:#2d2d0d,stroke:#ffc107,color:#e0e0e0,stroke-width:2px
    classDef hook fill:#3d2b00,stroke:#fd7e14,color:#e0e0e0,stroke-width:2px
    classDef deny fill:#4a1a1a,stroke:#dc3545,color:#e0e0e0,stroke-width:2px
    classDef done fill:#0d4f4f,stroke:#17a2b8,color:#e0e0e0,stroke-width:2px
 ```
 ---
 ## ToolSearch — Deferred Tool Loading
 With 42+ tools, sending all schemas to the model wastes tokens. **ToolSearch** defers tools that aren't immediately needed:
 ```mermaid
 %%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#1a1a2e', 'primaryTextColor': '#e0e0e0', 'lineColor': '#ffc107', 'primaryBorderColor': '#ffc107'}}}%%
 flowchart LR
    ALL["42+ Tools"]:::input
    SPLIT{"shouldDefer?"}:::check
    EAGER["~15 Eager Tools<br/>Always in prompt<br/>FileRead, Bash, Grep..."]:::eager
    DEFER["~27 Deferred Tools<br/>Schema not sent initially<br/>TaskCreate, WebSearch..."]:::defer
    ALWAYS["alwaysLoad Tools<br/>Forced eager by MCP meta"]:::eager
    SEARCH["ToolSearch Tool<br/>Model searches by keyword<br/>using searchHint"]:::tool
    FOUND["Tool schema injected<br/>into next request"]:::result
    ALL --> SPLIT
    SPLIT -->|"no"| EAGER
    SPLIT -->|"yes"| DEFER
    SPLIT -->|"alwaysLoad"| ALWAYS
    DEFER --> SEARCH
    SEARCH --> FOUND
    classDef input fill:#1a2d4a,stroke:#4a9eff,color:#e0e0e0,stroke-width:2px
    classDef check fill:#2d2d0d,stroke:#ffc107,color:#e0e0e0,stroke-width:2px
    classDef eager fill:#1b3a1b,stroke:#28a745,color:#e0e0e0,stroke-width:2px
    classDef defer fill:#3d2b00,stroke:#fd7e14,color:#e0e0e0,stroke-width:2px
    classDef tool fill:#2d1b4e,stroke:#6f42c1,color:#e0e0e0,stroke-width:2px
    classDef result fill:#0d4f4f,stroke:#17a2b8,color:#e0e0e0,stroke-width:2px
 ```
 ---
 ## Dynamic Tools — MCP and LSP
 Beyond built-in tools, Claude Code loads tools dynamically at runtime:
 ```mermaid
 %%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#1a1a2e', 'primaryTextColor': '#e0e0e0', 'lineColor': '#17a2b8', 'primaryBorderColor': '#17a2b8'}}}%%
 flowchart TD
    subgraph MCP["MCP Tools — Model Context Protocol"]
        SRV["External MCP Servers<br/>configured in settings"]
        CONN["MCPConnectionManager<br/>stdio / SSE transport"]
        DISC["Discover tools<br/>via tools/list"]
        WRAP["Wrap as Tool objects<br/>name: mcp__server__tool"]
    end
    subgraph LSP["LSP Tool — Language Server Protocol"]
        LS["Language Server<br/>runtime type info"]
        QUERY_LSP["Query definitions,<br/>references, diagnostics"]
    end
    SRV --> CONN --> DISC --> WRAP
    LS --> QUERY_LSP
    MERGE["Merged into tool pool<br/>via useMergedTools hook"]:::merge
    WRAP --> MERGE
    QUERY_LSP --> MERGE
    classDef merge fill:#1b3a1b,stroke:#28a745,color:#e0e0e0,stroke-width:2px
 ```
 MCP tools are prefixed with `mcp__<server>__<tool>` unless running in SDK no-prefix mode. They go through the same permission system as built-in tools.
 ---
 ## Key Design Decisions
 ### 1. Self-Contained Modules
 Each tool directory (`src/tools/<ToolName>/`) contains everything:
 - `index.ts` — Tool definition via `buildTool()`
 - `prompt.ts` — Model-facing instructions
 - `*.test.ts` — Tests
 - Additional helpers as needed
 ### 2. Fail-Closed Defaults
 `buildTool()` defaults are conservative:
 - `isConcurrencySafe = false` — Won't run in parallel unless explicitly safe
 - `isReadOnly = false` — Assumed to write unless stated otherwise
 - `checkPermissions` defaults to `allow` — But the general permission system still applies
 ### 3. Result Size Budgets
 Each tool has `maxResultSizeChars`. Oversized results are persisted to disk and the model gets a truncated preview + file path. This prevents single tool results from consuming the entire context window.
 ### 4. Observable Input Backfilling
 `backfillObservableInput()` adds derived fields to tool inputs for SDK consumers and transcripts, without mutating the API-bound input (which would break prompt caching):
 ```typescript
 // The API sees: { file_path: "src/foo.ts" }
 // SDK/transcript sees: { file_path: "src/foo.ts", resolved_path: "/abs/path/src/foo.ts" }
 ```
 ---
 **Previous:** [← The Agentic Loop](./02-agentic-loop.md) · **Next:** [Permission System →](./04-permission-system.md)
--- a/learn/04-permission-system.md
+++ b/learn/04-permission-system.md
@ -0,0 +1,339 @@
 # 4. Permission System
 > How Claude Code prevents an AI from doing dangerous things — a multi-layered defense.
 ---
 ## Why Permissions Matter
 Claude Code can run **arbitrary bash commands**, **write to any file**, and **make network requests**. Without a permission system, a single misguided model response could `rm -rf /` your entire system.
 The permission system is a chain of checks — if any link denies, the tool doesn't run.
 ---
 ## The Permission Flow
 ```mermaid
 %%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#1a1a2e', 'primaryTextColor': '#e0e0e0', 'lineColor': '#dc3545', 'primaryBorderColor': '#dc3545'}}}%%
 flowchart TD
    ENTRY["Tool call arrives"]:::start
    DR{"Deny rules?<br/>blanket deny, pattern match"}
    AR{"Allow rules?<br/>always-allow from settings"}
    TSP{"tool.checkPermissions?<br/>tool-specific logic"}
    HOOK{"PreToolUse hooks?<br/>user-defined scripts"}
    CLASS{"Auto-mode classifier?<br/>transcript safety analysis"}
    DIALOG{"User permission dialog<br/>Y / n / always-allow"}
    ALLOW["ALLOW<br/>execute tool"]:::allow
    DENY["DENY<br/>return error to model"]:::deny
    ENTRY --> DR
    DR -->|"matched deny rule"| DENY
    DR -->|"no match"| AR
    AR -->|"matched allow rule"| ALLOW
    AR -->|"no match"| TSP
    TSP -->|"tool says allow"| HOOK
    TSP -->|"tool says deny"| DENY
    HOOK -->|"hook approves"| ALLOW
    HOOK -->|"hook denies"| DENY
    HOOK -->|"no decision"| CLASS
    CLASS -->|"classified safe"| ALLOW
    CLASS -->|"classified unsafe"| DIALOG
    CLASS -->|"not in auto-mode"| DIALOG
    DIALOG -->|"user accepts"| ALLOW
    DIALOG -->|"user rejects"| DENY
    DIALOG -->|"always allow"| AR
    classDef start fill:#1a2d4a,stroke:#4a9eff,color:#e0e0e0,stroke-width:2px
    classDef allow fill:#1b3a1b,stroke:#28a745,color:#e0e0e0,stroke-width:2px
    classDef deny fill:#4a1a1a,stroke:#dc3545,color:#e0e0e0,stroke-width:2px
 ```
 ---
 ## Layer 1: Deny Rules
 **First check. Highest priority. Cannot be overridden.**
 Deny rules are pattern-matched against tool name and input. If a deny rule matches, the tool is **immediately rejected** — no further checks run.
 Sources of deny rules:
 - `settings.json` — User-configured
 - CLAUDE.md — Project-level rules
 - Organization policy — Enterprise MDM settings
 Example deny rules:
 ```json
 {
  "alwaysDenyRules": {
    "settings": [
      { "tool": "Bash", "pattern": "rm -rf" },
      { "tool": "FileWrite", "pattern": "/etc/*" }
    ]
  }
 }
 ```
 ### Permission Matching
 Tools can implement `preparePermissionMatcher()` for custom pattern matching:
 ```typescript
 // Bash tool: "git *" matches any git command
 preparePermissionMatcher(input) {
  return async (pattern) => minimatch(input.command, pattern)
 }
 ```
 ---
 ## Layer 2: Allow Rules
 If no deny rule matched, check if an **allow rule** grants automatic approval.
 Allow rules come from:
 - User clicking "always allow" in the permission dialog
 - `settings.json` configuration
 - Slash command grants (e.g., `/plan` exit grants specific operations)
 ```mermaid
 %%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#1a1a2e', 'primaryTextColor': '#e0e0e0', 'lineColor': '#28a745', 'primaryBorderColor': '#28a745'}}}%%
 flowchart LR
    subgraph Sources["Allow Rule Sources"]
        S1["settings.json<br/>user config"]
        S2["CLAUDE.md<br/>project rules"]
        S3["User dialog<br/>always-allow choice"]
        S4["Command grants<br/>plan mode exit"]
    end
    MERGE["ToolPermissionContext<br/>alwaysAllowRules"]:::merge
    CHECK{"Pattern match<br/>against tool + input"}:::check
    ALLOW["Auto-approved"]:::allow
    NEXT["Continue to<br/>next layer"]:::next
    S1 --> MERGE
    S2 --> MERGE
    S3 --> MERGE
    S4 --> MERGE
    MERGE --> CHECK
    CHECK -->|"match"| ALLOW
    CHECK -->|"no match"| NEXT
    classDef merge fill:#1a2d4a,stroke:#4a9eff,color:#e0e0e0,stroke-width:2px
    classDef check fill:#2d2d0d,stroke:#ffc107,color:#e0e0e0,stroke-width:2px
    classDef allow fill:#1b3a1b,stroke:#28a745,color:#e0e0e0,stroke-width:2px
    classDef next fill:#333,stroke:#888,color:#e0e0e0,stroke-width:1px
 ```
 ---
 ## Layer 3: Tool-Specific Permissions
 Each tool implements `checkPermissions(input, context)`:
 ```typescript
 // Example: FileRead defaults to allow (it's read-only)
 checkPermissions: () => Promise.resolve({ behavior: 'allow' })
 // Example: Bash checks if the command is read-only
 checkPermissions: (input) => {
  if (isReadOnlyCommand(input.command)) {
    return { behavior: 'allow' }
  }
  return { behavior: 'askUser', message: `Run: ${input.command}` }
 }
 ```
 The result can be:
 - `{ behavior: 'allow' }` — Approved
 - `{ behavior: 'deny', message }` — Rejected with reason
 - `{ behavior: 'askUser', message }` — Escalate to user prompt
 ---
 ## Layer 4: PreToolUse Hooks
 User-defined scripts that run before tool execution. Configured in `settings.json` or CLAUDE.md:
 ```json
 {
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": "/path/to/safety-check.sh"
      }
    ]
  }
 }
 ```
 Hook scripts receive the tool name and input as JSON on stdin. They can:
 - **Approve** (exit 0, no output)
 - **Deny** (exit non-zero, stderr has reason)
 - **Modify input** (exit 0, stdout has modified JSON)
 ---
 ## Layer 5: Auto-Mode Classifier
 In `--auto` mode, a **classifier** examines the conversation transcript to determine if a tool call is safe:
 ```mermaid
 %%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#1a1a2e', 'primaryTextColor': '#e0e0e0', 'lineColor': '#17a2b8', 'primaryBorderColor': '#17a2b8'}}}%%
 flowchart TD
    TC["Tool call in auto-mode"]:::start
    BUILD["Build classifier input<br/>tool.toAutoClassifierInput(input)"]:::step
    TRANSCRIPT["Append recent transcript<br/>for context"]:::step
    CLASSIFY["Run safety classifier<br/>is this operation safe?"]:::step
    SAFE{"Classified as?"}:::check
    ALLOW["Auto-approved<br/>no user prompt"]:::allow
    PROMPT["Escalate to<br/>user dialog"]:::deny
    TC --> BUILD --> TRANSCRIPT --> CLASSIFY --> SAFE
    SAFE -->|"safe"| ALLOW
    SAFE -->|"unsafe"| PROMPT
    classDef start fill:#1a2d4a,stroke:#4a9eff,color:#e0e0e0,stroke-width:2px
    classDef step fill:#0d4f4f,stroke:#17a2b8,color:#e0e0e0,stroke-width:2px
    classDef check fill:#2d2d0d,stroke:#ffc107,color:#e0e0e0,stroke-width:2px
    classDef allow fill:#1b3a1b,stroke:#28a745,color:#e0e0e0,stroke-width:2px
    classDef deny fill:#4a1a1a,stroke:#dc3545,color:#e0e0e0,stroke-width:2px
 ```
 Each tool provides `toAutoClassifierInput()` which returns a compact representation for the classifier. Security-irrelevant tools return `''` to skip classification.
 ---
 ## Layer 6: User Permission Dialog
 The last resort — ask the human:
 ```
 ╭────────────────────────────────────────╮
 │  Claude wants to run:                  │
 │                                        │
 │  $ npm install lodash                  │
 │                                        │
 │  (Y)es  ·  (n)o  ·  (a)lways allow    │
 ╰────────────────────────────────────────╯
 ```
 Choosing "always allow" adds a permanent allow rule.
 ---
 ## Permission Modes
 ```mermaid
 %%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#1a1a2e', 'primaryTextColor': '#e0e0e0', 'lineColor': '#fd7e14', 'primaryBorderColor': '#fd7e14'}}}%%
 flowchart TB
    START(["Session Start"]):::neutral --> DEFAULT
    DEFAULT["DEFAULT MODE<br/>Prompt user on every write tool"]:::mode1
    PLAN["PLAN MODE<br/>Read tools auto-approved<br/>Write tools require approval"]:::mode2
    AUTO["AUTO MODE<br/>Classifier decides safety<br/>Safe = allow, Unsafe = prompt"]:::mode3
    BYPASS["BYPASS MODE<br/>Everything auto-approved<br/>No permission checks"]:::mode4
    DEFAULT -->|"/plan command<br/>or model enters plan"| PLAN
    PLAN -->|"model exits<br/>plan mode"| DEFAULT
    DEFAULT -->|"--auto flag<br/>user opts in"| AUTO
    AUTO -->|"denial limit<br/>exceeded"| DEFAULT
    DEFAULT -->|"--dangerously-<br/>skip-permissions"| BYPASS
    classDef neutral fill:#333,stroke:#888,color:#e0e0e0,stroke-width:1px
    classDef mode1 fill:#1a2d4a,stroke:#4a9eff,color:#e0e0e0,stroke-width:2px
    classDef mode2 fill:#2d2d0d,stroke:#ffc107,color:#e0e0e0,stroke-width:2px
    classDef mode3 fill:#0d4f4f,stroke:#17a2b8,color:#e0e0e0,stroke-width:2px
    classDef mode4 fill:#4a1a1a,stroke:#dc3545,color:#e0e0e0,stroke-width:2px
 ```
 ### Default Mode
 - Every write operation prompts the user
 - Read operations (FileRead, Glob, Grep) auto-approved
 - Most secure, most friction
 ### Plan Mode
 - Entered via `/plan` command or model's `EnterPlanMode` tool
 - All read tools auto-approved
 - All write tools require explicit user approval
 - Model can plan freely, execute cautiously
 ### Auto Mode
 - Enabled via `--auto` flag
 - Safety classifier decides per-tool
 - Falls back to prompting if classifier says "unsafe"
 - Has a **denial limit** — too many denials drops back to Default
 ### Bypass Mode
 - Enabled via `--dangerously-skip-permissions`
 - **Everything auto-approved** — no checks at all
 - Named to be scary because it IS scary
 - No permission system protection whatsoever
 ---
 ## The `ToolPermissionContext` Type
 All permission state lives in `AppState.toolPermissionContext`:
 ```mermaid
 %%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#1a1a2e', 'primaryTextColor': '#e0e0e0', 'lineColor': '#dc3545', 'primaryBorderColor': '#dc3545'}}}%%
 graph TB
    subgraph TPC["ToolPermissionContext — Immutable"]
        MODE["mode<br/>default / plan / auto / bypass"]
        AWD["additionalWorkingDirectories<br/>extra safe paths"]
        ALLOW["alwaysAllowRules<br/>by source: settings, command, etc."]
        DENY["alwaysDenyRules<br/>by source"]
        ASK["alwaysAskRules<br/>force prompt even if allowed"]
        BPM["isBypassPermissionsModeAvailable<br/>can user enable bypass?"]
        AUTO_A["isAutoModeAvailable<br/>can user enable auto?"]
        AVOID["shouldAvoidPermissionPrompts<br/>background agents that cannot show UI"]
        AWAIT["awaitAutomatedChecksBeforeDialog<br/>coordinator workers"]
        PRE["prePlanMode<br/>mode to restore after plan exits"]
    end
 ```
 This is wrapped in `DeepImmutable<T>` — TypeScript enforces that nobody mutates this in place. Updates go through `setAppState(prev => ({ ...prev, toolPermissionContext: { ... } }))`.
 ---
 ## Denial Tracking
 Auto mode tracks denials to prevent runaway unsafe operations:
 ```mermaid
 %%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#1a1a2e', 'primaryTextColor': '#e0e0e0', 'lineColor': '#dc3545', 'primaryBorderColor': '#dc3545'}}}%%
 flowchart LR
    START["Auto mode active"]:::start
    D1["Denial 1"]:::deny
    D2["Denial 2"]:::deny
    DN["Denial N<br/>limit exceeded"]:::deny
    FALLBACK["Fall back to<br/>Default mode"]:::result
    START --> D1 --> D2 -->|"..."| DN --> FALLBACK
    classDef start fill:#0d4f4f,stroke:#17a2b8,color:#e0e0e0,stroke-width:2px
    classDef deny fill:#3d2b00,stroke:#fd7e14,color:#e0e0e0,stroke-width:2px
    classDef result fill:#1a2d4a,stroke:#4a9eff,color:#e0e0e0,stroke-width:2px
 ```
 This is stored in `DenialTrackingState` — for async subagents that can't show UI, a local tracking copy is used since their `setAppState` is a no-op.
 ---
 **Previous:** [← Tool System](./03-tool-system.md) · **Next:** [Context Management →](./05-context-management.md)
--- a/learn/05-context-management.md
+++ b/learn/05-context-management.md
@ -0,0 +1,106 @@
 # 5. Context Management — The Compaction Pipeline
 > How Claude Code keeps conversations within the model's context window.
 ---
 ## The Pipeline
 ```mermaid
 %%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#1a1a2e', 'primaryTextColor': '#e0e0e0', 'lineColor': '#fd7e14', 'primaryBorderColor': '#fd7e14'}}}%%
 flowchart LR
    RAW["Raw message<br/>history"]:::input
    S1["SNIP COMPACT<br/>Sliding window<br/>Drop oldest turns<br/>Preserve recent N"]:::stage1
    S2["MICRO COMPACT<br/>Truncate individual<br/>tool results exceeding<br/>size thresholds"]:::stage2
    S3["AUTO COMPACT<br/>Summarize full conversation<br/>via separate API call<br/>Circuit breaker on failure"]:::stage3
    S4["CONTEXT COLLAPSE<br/>Read-time projection<br/>Archived collapsed views<br/>Granular preservation"]:::stage4
    FINAL["Messages ready<br/>for API call"]:::output
    S5["REACTIVE COMPACT<br/>Emergency trigger<br/>on API 413 error<br/>Last resort"]:::emergency
    RAW ==> S1 ==> S2 ==> S3 ==> S4 ==> FINAL
    FINAL -. "API returns prompt_too_long" .-> S5
    S5 ==> FINAL
    classDef input fill:#1a2d4a,stroke:#4a9eff,color:#e0e0e0,stroke-width:2px
    classDef stage1 fill:#0d3d0d,stroke:#28a745,color:#e0e0e0,stroke-width:2px
    classDef stage2 fill:#0d4f4f,stroke:#17a2b8,color:#e0e0e0,stroke-width:2px
    classDef stage3 fill:#2d2d0d,stroke:#ffc107,color:#e0e0e0,stroke-width:2px
    classDef stage4 fill:#2d1b4e,stroke:#6f42c1,color:#e0e0e0,stroke-width:2px
    classDef output fill:#1a2d4a,stroke:#4a9eff,color:#e0e0e0,stroke-width:2px
    classDef emergency fill:#4a1a1a,stroke:#dc3545,color:#e0e0e0,stroke-width:2px
 ```
 ---
 ## Stage Details
 ### Stage 1: Snip Compact
 Sliding window that drops the oldest turns. The REPL keeps full history for UI scrollback — snip is a *read-time projection* only affecting what's sent to the API. Feature-gated via `HISTORY_SNIP`.
 ### Stage 2: Micro Compact
 Truncates individual tool results exceeding size thresholds. Results are cached by `tool_use_id` so subsequent iterations reuse cached truncations.  
 **Key file:** `src/services/compact/microCompact.ts` (19KB)
 ### Stage 3: Auto Compact
 Summarizes the full conversation via a **separate API call**. Has a circuit breaker — too many consecutive failures stops retrying.  
 **Key files:** `autoCompact.ts` (13KB), `compact.ts` (60KB), `prompt.ts` (16KB)
 ### Stage 4: Context Collapse
 Read-time projection that archives older segments with granular preservation. Exists in a separate store — the REPL's message array is never modified.
 ### Stage 5: Reactive Compact
 Emergency trigger when the API returns `prompt_too_long` (413). Last resort — only runs after a real API failure. Feature-gated via `REACTIVE_COMPACT`.
 ---
 ## Token Budget State Machine
 ```mermaid
 %%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#1a1a2e', 'primaryTextColor': '#e0e0e0', 'lineColor': '#ffc107', 'primaryBorderColor': '#ffc107'}}}%%
 flowchart LR
    N["NORMAL<br/>within limits"]:::green
    W["WARNING<br/>context > 80%"]:::yellow
    C["CRITICAL<br/>context > 95%"]:::orange
    B["BLOCKING<br/>context > 98%<br/>auto-compact OFF"]:::red
    AC["AUTO COMPACT<br/>fires automatically"]:::blue
    RC["REACTIVE<br/>emergency on 413"]:::darkred
    M["MANUAL<br/>user runs /compact"]:::gray
    N -->|"grows"| W
    W -->|"grows"| C
    C -->|"auto-compact ON"| AC
    C -->|"auto-compact OFF"| B
    AC -->|"success"| N
    AC -->|"fails + API 413"| RC
    RC -->|"success"| N
    B -->|"user: /compact"| M
    M -->|"success"| N
    classDef green fill:#1b3a1b,stroke:#28a745,color:#e0e0e0,stroke-width:2px
    classDef yellow fill:#2d2d0d,stroke:#ffc107,color:#e0e0e0,stroke-width:2px
    classDef orange fill:#3d2b00,stroke:#fd7e14,color:#e0e0e0,stroke-width:2px
    classDef red fill:#4a1a1a,stroke:#dc3545,color:#e0e0e0,stroke-width:2px
    classDef darkred fill:#3a0a0a,stroke:#a30000,color:#e0e0e0,stroke-width:2px
    classDef blue fill:#1a2d4a,stroke:#4a9eff,color:#e0e0e0,stroke-width:2px
    classDef gray fill:#2a2a2a,stroke:#888,color:#e0e0e0,stroke-width:1px
 ```
 ### Transitions
 - **NORMAL → WARNING** at 80% — UI shows warning indicator
 - **WARNING → CRITICAL** at 95% — compaction should fire
 - **CRITICAL → AUTO COMPACT** — if enabled, fires summarization API call
 - **CRITICAL → BLOCKING** — if auto-compact OFF, blocks new API calls
 - **BLOCKING → MANUAL** — user runs `/compact` to recover
 ---
 ## Tool Result Budget
 Separate from conversation compaction — a per-message budget for aggregate tool result size. Runs **before** the pipeline every iteration. Oversized results are persisted to disk, replaced with a file path + truncated preview. Tools with `maxResultSizeChars = Infinity` (e.g., FileRead) are exempt.
 ---
 **Previous:** [← Permission System](./04-permission-system.md) · **Next:** [State Management →](./06-state-management.md)
--- a/learn/06-state-management.md
+++ b/learn/06-state-management.md
@ -0,0 +1,148 @@
 # 6. State Management
 > A single immutable store with 50+ fields — how Claude Code manages application state.
 ---
 ## Architecture
 ```mermaid
 %%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#1a1a2e', 'primaryTextColor': '#e0e0e0', 'lineColor': '#4a9eff', 'primaryBorderColor': '#4a9eff'}}}%%
 graph TB
    subgraph Store["AppState — Single Immutable Store"]
        direction TB
        subgraph Core_S["Core Session State"]
            Model["mainLoopModel"]
            Think["thinkingEnabled"]
            Fast["fastMode"]
            Effort["effortValue"]
            Settings["settings: SettingsJson"]
        end
        subgraph Perm_S["Permission State"]
            TPC["toolPermissionContext"]
            Mode["mode: default / plan / auto / bypass"]
            Allow["alwaysAllowRules"]
            Deny["alwaysDenyRules"]
        end
        subgraph MCP_S["MCP State"]
            MCPCli["clients: MCPServerConnection array"]
            MCPTool["tools: Tool array"]
            MCPCmd["commands: Command array"]
        end
        subgraph Task_S["Background Tasks"]
            Tasks["tasks: taskId to TaskState map"]
            AgentReg["agentNameRegistry"]
            FG["foregroundedTaskId"]
        end
        subgraph UI_S["UI State"]
            Spec["speculation: predictive execution"]
            Suggest["promptSuggestion: autocomplete"]
            Notif["notifications queue"]
            Bridge["replBridge: remote control state"]
        end
        subgraph History_S["History and Tracking"]
            FH["fileHistory: snapshots for rewind"]
            Attr["attribution: commit metadata"]
            Todos["todos: per-agent lists"]
        end
    end
    REPL_C["REPL.tsx<br/>reads + subscribes"]:::consumer
    QE_C["QueryEngine<br/>reads via getAppState"]:::consumer
    Tools_C["Tools<br/>reads via ToolUseContext"]:::consumer
    SET["setAppState<br/>functional update"]:::mutator
    ONCHANGE["onChangeAppState<br/>side effect reactions"]:::mutator
    Store --> REPL_C
    Store --> QE_C
    Store --> Tools_C
    SET --> Store
    ONCHANGE --> Store
    classDef consumer fill:#1b3a1b,stroke:#28a745,color:#e0e0e0,stroke-width:2px
    classDef mutator fill:#2d1b4e,stroke:#e83e8c,color:#e0e0e0,stroke-width:2px
 ```
 ---
 ## Core Concepts
 ### Immutability via `DeepImmutable<T>`
 The `AppState` type is wrapped in `DeepImmutable<T>` — TypeScript enforces that no consumer can mutate state in place:
 ```typescript
 export type AppState = DeepImmutable<{
  settings: SettingsJson
  mainLoopModel: ModelSetting
  toolPermissionContext: ToolPermissionContext
  // ... 50+ fields
 }>
 ```
 ### Functional Updates
 State is updated via `setAppState(prev => newState)`:
 ```typescript
 setAppState(prev => ({
  ...prev,
  toolPermissionContext: {
    ...prev.toolPermissionContext,
    mode: 'plan',
  },
 }))
 ```
 ### Side Effects via `onChangeAppState`
 After state changes, `onChangeAppState.ts` fires reactive side effects — persisting settings, updating UI, notifying remote sessions, etc.
 ---
 ## Key State Groups
 ### Session State
 `mainLoopModel`, `thinkingEnabled`, `fastMode`, `effortValue` — control how the model behaves each turn.
 ### Permission State
 `toolPermissionContext` — contains mode, allow/deny rules, and bypass availability. See [Guide 4](./04-permission-system.md).
 ### MCP State
 `mcp.clients`, `mcp.tools`, `mcp.commands` — dynamically connected MCP servers and their exposed tools/commands.
 ### Background Tasks
 `tasks` — a map of `taskId → TaskState` for background agent tasks. `foregroundedTaskId` controls which task's messages appear in the main view.
 ### UI State
 `speculation` — predictive execution state for pre-computing responses. `promptSuggestion` — autocomplete suggestions. `notifications` — queued UI notifications.
 ### History
 `fileHistory` — snapshots for `/rewind`. `attribution` — commit metadata for git attribution. `todos` — per-agent task lists.
 ---
 ## Key Files
 ```mermaid
 %%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#1a1a2e', 'primaryTextColor': '#e0e0e0', 'lineColor': '#4a9eff', 'primaryBorderColor': '#4a9eff'}}}%%
 graph LR
    subgraph StateDir["src/state/"]
        AS["AppState.tsx<br/>React context + hooks"]
        ASS["AppStateStore.ts<br/>Type definition + defaults"]
        OC["onChangeAppState.ts<br/>Side effect reactions"]
        SEL["selectors.ts<br/>Derived state"]
        ST["store.ts<br/>Store type"]
    end
 ```
 ---
 **Previous:** [← Context Management](./05-context-management.md) · **Next:** [Extension Model →](./07-extension-model.md)
--- a/learn/07-extension-model.md
+++ b/learn/07-extension-model.md
@ -0,0 +1,248 @@
 # 7. Extension Model
 > Skills, plugins, hooks, sub-agents, and swarms — how Claude Code is extended.
 ---
 ## Overview
 ```mermaid
 %%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#1a1a2e', 'primaryTextColor': '#e0e0e0', 'lineColor': '#ffc107', 'primaryBorderColor': '#ffc107'}}}%%
 graph TB
    subgraph Skills["Skills"]
        BS["Bundled Skills<br/>shipped with CLI"]:::skill
        US["User Skills<br/>.claude/skills/*.md"]:::skill
        PS["Project Skills<br/>.claude/skills/ in repo"]:::skill
        SL["loadSkillsDir.ts<br/>discover + parse frontmatter"]:::loader
    end
    subgraph Plugins["Plugins"]
        MP["Managed Plugins<br/>org-level policy"]:::plugin
        IP["Installed Plugins<br/>user choice"]:::plugin
        BP["Built-in Plugins<br/>shipped with CLI"]:::plugin
        PL["pluginLoader.ts<br/>cache-only, versioned"]:::loader
    end
    subgraph Agents["Agents"]
        SA["Sub-agents via AgentTool<br/>forked context, own query loop"]:::agent
        CO["Coordinator Mode<br/>leader dispatches tasks,<br/>workers get limited tools"]:::agent
        SW["Swarms<br/>multi-process via tmux,<br/>mailbox message passing"]:::agent
        FA["Forked Agents<br/>share parent prompt cache,<br/>overlay filesystem"]:::agent
    end
    subgraph HookSys["Hooks"]
        PRE["PreToolUse<br/>before tool execution"]:::hook
        POST["PostToolUse<br/>after tool execution"]:::hook
        SESS["Session Hooks<br/>lifecycle events"]:::hook
        HC["Configured in<br/>settings.json or CLAUDE.md"]:::hook
    end
    CMD["commands.ts — Command Registry<br/>merges all sources"]:::registry
    TOOL["Tool.ts — Tool Interface"]:::registry
    QUERY["query.ts — Agentic Loop"]:::registry
    BS --> SL
    US --> SL
    PS --> SL
    SL --> CMD
    MP --> PL
    IP --> PL
    BP --> PL
    PL --> CMD
    PL -->|"plugin MCP servers"| TOOL
    CMD --> TOOL
    SA --> QUERY
    CO --> QUERY
    SW --> QUERY
    FA --> QUERY
    PRE --> TOOL
    POST --> TOOL
    HC --> PRE
    HC --> POST
    classDef skill fill:#0d4f4f,stroke:#17a2b8,color:#e0e0e0,stroke-width:2px
    classDef plugin fill:#2d2d0d,stroke:#ffc107,color:#e0e0e0,stroke-width:2px
    classDef agent fill:#2d1b4e,stroke:#6f42c1,color:#e0e0e0,stroke-width:2px
    classDef hook fill:#3d2b00,stroke:#fd7e14,color:#e0e0e0,stroke-width:2px
    classDef loader fill:#1a2d4a,stroke:#4a9eff,color:#e0e0e0,stroke-width:2px
    classDef registry fill:#1b3a1b,stroke:#28a745,color:#e0e0e0,stroke-width:3px
 ```
 ---
 ## Skills
 Skills are **markdown instruction files** with YAML frontmatter. They teach Claude Code how to do specific tasks.
 ```mermaid
 %%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#1a1a2e', 'primaryTextColor': '#e0e0e0', 'lineColor': '#17a2b8', 'primaryBorderColor': '#17a2b8'}}}%%
 flowchart TD
    subgraph Sources["Skill Sources"]
        BUNDLED["Bundled<br/>shipped with CLI"]:::bundled
        USER[".claude/skills/<br/>user-defined"]:::user
        PROJECT["repo .claude/skills/<br/>project-specific"]:::project
    end
    LOADER["loadSkillsDir.ts<br/>Discover + parse<br/>YAML frontmatter"]:::loader
    TOOL["SkillTool<br/>Model invokes via tool call"]:::tool
    CMD["Slash commands<br/>/skills to manage"]:::cmd
    BUNDLED --> LOADER
    USER --> LOADER
    PROJECT --> LOADER
    LOADER --> TOOL
    LOADER --> CMD
    classDef bundled fill:#0d4f4f,stroke:#17a2b8,color:#e0e0e0,stroke-width:2px
    classDef user fill:#1a2d4a,stroke:#4a9eff,color:#e0e0e0,stroke-width:2px
    classDef project fill:#2d2d0d,stroke:#ffc107,color:#e0e0e0,stroke-width:2px
    classDef loader fill:#2d1b4e,stroke:#6f42c1,color:#e0e0e0,stroke-width:2px
    classDef tool fill:#1b3a1b,stroke:#28a745,color:#e0e0e0,stroke-width:2px
    classDef cmd fill:#3d2b00,stroke:#fd7e14,color:#e0e0e0,stroke-width:2px
 ```
 **Key file:** `src/skills/loadSkillsDir.ts` (34KB)
 ---
 ## Plugins
 Plugins are bundles of tools, MCP servers, and commands. They extend Claude Code at a deeper level than skills.
 ```mermaid
 %%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#1a1a2e', 'primaryTextColor': '#e0e0e0', 'lineColor': '#ffc107', 'primaryBorderColor': '#ffc107'}}}%%
 flowchart TD
    subgraph Types["Plugin Types"]
        MANAGED["Managed Plugins<br/>org-level policy<br/>enterprise MDM"]:::managed
        INSTALLED["User Plugins<br/>installed via marketplace<br/>or manual"]:::installed
        BUILTIN["Built-in Plugins<br/>shipped with CLI"]:::builtin
    end
    CACHE["pluginLoader.ts<br/>cache-only loading<br/>versioned artifacts"]:::loader
    subgraph Provides["Plugin Provides"]
        TOOLS["Tools<br/>via MCP servers"]:::tool
        CMDS["Slash Commands"]:::cmd
        SKILLS_P["Skills"]:::skill
    end
    MANAGED --> CACHE
    INSTALLED --> CACHE
    BUILTIN --> CACHE
    CACHE --> TOOLS
    CACHE --> CMDS
    CACHE --> SKILLS_P
    classDef managed fill:#4a1a1a,stroke:#dc3545,color:#e0e0e0,stroke-width:2px
    classDef installed fill:#2d2d0d,stroke:#ffc107,color:#e0e0e0,stroke-width:2px
    classDef builtin fill:#0d4f4f,stroke:#17a2b8,color:#e0e0e0,stroke-width:2px
    classDef loader fill:#1a2d4a,stroke:#4a9eff,color:#e0e0e0,stroke-width:2px
    classDef tool fill:#1b3a1b,stroke:#28a745,color:#e0e0e0,stroke-width:2px
    classDef cmd fill:#3d2b00,stroke:#fd7e14,color:#e0e0e0,stroke-width:2px
    classDef skill fill:#2d1b4e,stroke:#6f42c1,color:#e0e0e0,stroke-width:2px
 ```
 **Key files:** `src/plugins/builtinPlugins.ts`, `src/utils/plugins/pluginLoader.ts`
 ---
 ## Agent System
 Claude Code can spawn **sub-agents** — each gets its own query loop, forked context, and limited tool set.
 ```mermaid
 %%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#1a1a2e', 'primaryTextColor': '#e0e0e0', 'lineColor': '#6f42c1', 'primaryBorderColor': '#6f42c1'}}}%%
 flowchart TD
    subgraph AgentTypes["Agent Types"]
        SUB["Sub-agent<br/>AgentTool spawns in-process<br/>forked context, own query loop"]:::sub
        COORD["Coordinator<br/>Leader dispatches tasks<br/>workers get limited tools"]:::coord
        SWARM["Swarm<br/>Multi-process via tmux<br/>mailbox message passing"]:::swarm
        FORK["Forked Agent<br/>Share parent prompt cache<br/>overlay filesystem"]:::fork
    end
    subgraph SubAgent["Sub-agent Details"]
        CONTEXT["Forked ToolUseContext<br/>cloned file cache<br/>separate abort controller"]
        LOOP["Own query loop<br/>independent agentic cycle"]
        RESULTS["Results flow back<br/>to parent as tool_result"]
    end
    subgraph SwarmDetails["Swarm Details"]
        TMUX["tmux sessions<br/>separate processes"]
        MAILBOX["Mailbox system<br/>JSON message passing"]
        LEADER["Leader process<br/>dispatches and coordinates"]
        WORKER["Worker processes<br/>limited tool access"]
    end
    SUB --> SubAgent
    SWARM --> SwarmDetails
    classDef sub fill:#2d1b4e,stroke:#6f42c1,color:#e0e0e0,stroke-width:2px
    classDef coord fill:#1a2d4a,stroke:#4a9eff,color:#e0e0e0,stroke-width:2px
    classDef swarm fill:#0d4f4f,stroke:#17a2b8,color:#e0e0e0,stroke-width:2px
    classDef fork fill:#2d2d0d,stroke:#ffc107,color:#e0e0e0,stroke-width:2px
 ```
 **Key files:** `src/tools/AgentTool/`, `src/coordinator/coordinatorMode.ts`
 ---
 ## Hooks
 User-defined scripts that run at specific points in the tool execution lifecycle:
 ```mermaid
 %%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#1a1a2e', 'primaryTextColor': '#e0e0e0', 'lineColor': '#fd7e14', 'primaryBorderColor': '#fd7e14'}}}%%
 sequenceDiagram
    participant M as Model
    participant Q as query.ts
    participant PRE as PreToolUse Hook
    participant T as Tool
    participant POST as PostToolUse Hook
    M->>Q: tool_use block
    Q->>PRE: Run hook script
    alt Hook approves
        PRE-->>Q: exit 0
        Q->>T: Execute tool
        T-->>Q: result
        Q->>POST: Run hook script
        POST-->>Q: done
        Q->>M: tool_result
    else Hook denies
        PRE-->>Q: exit non-zero
        Q->>M: error: denied by hook
    else Hook modifies input
        PRE-->>Q: exit 0 + modified JSON
        Q->>T: Execute with modified input
        T-->>Q: result
        Q->>POST: Run hook script
        POST-->>Q: done
        Q->>M: tool_result
    end
 ```
 Hooks are configured in `settings.json` with matchers:
 ```json
 {
  "hooks": {
    "PreToolUse": [
      { "matcher": "Bash", "command": "./check-safety.sh" }
    ],
    "PostToolUse": [
      { "matcher": "FileWrite", "command": "./format-on-save.sh" }
    ]
  }
 }
 ```
 ---
 **Previous:** [← State Management](./06-state-management.md) · **Next:** [API Client →](./08-api-client.md)
--- a/learn/08-api-client.md
+++ b/learn/08-api-client.md
@ -0,0 +1,220 @@
 # 8. API Client — `claude.ts`
 > Streaming, retries, caching, and model fallback — how Claude Code talks to the Anthropic API.
 ---
 ## Request Lifecycle
 ```mermaid
 %%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#1a1a2e', 'primaryTextColor': '#e0e0e0', 'lineColor': '#28a745', 'actorTextColor': '#e0e0e0', 'actorBorder': '#28a745', 'signalColor': '#28a745', 'noteBkgColor': '#16213e', 'noteTextColor': '#e0e0e0', 'activationBkgColor': '#1b3a1b', 'activationBorderColor': '#28a745'}}}%%
 sequenceDiagram
    participant Q as query.ts
    participant C as claude.ts
    participant R as withRetry
    participant K as AnthropicClient
    participant A as Anthropic API
    Q->>C: queryModel(messages, tools, options)
    activate C
    C->>C: resolve model — runtime override, plan-mode swap
    C->>C: normalize messages — strip internal fields
    C->>C: build tool schemas — filter by deny, defer via ToolSearch
    C->>C: configure betas, cache_control, effort, task_budget
    C->>C: add prompt cache breakpoints
    C->>C: compute metadata — user_id, session_id, device_id
    C->>R: withRetry(clientFactory, requestFn)
    activate R
    loop Retry on 429, 529, timeouts
        R->>K: getAnthropicClient(apiKey, model)
        K->>A: beta.messages.stream(params)
        activate A
        alt 200 OK
            A-->>R: SSE event stream
        else 429 Rate Limited
            R->>R: exponential backoff
        else 529 Overloaded
            R->>R: backoff + optional model fallback
        else 401 Auth Error
            R-->>C: CannotRetryError — abort
        end
        deactivate A
    end
    deactivate R
    C->>C: parse stream into AssistantMessage
    C->>C: update usage tracking and cost
    C->>C: detect prompt cache breaks
    C-->>Q: yield AssistantMessage + StreamEvents
    deactivate C
 ```
 ---
 ## Request Building
 Before each API call, `claude.ts` builds the request through several steps:
 ```mermaid
 %%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#1a1a2e', 'primaryTextColor': '#e0e0e0', 'lineColor': '#28a745', 'primaryBorderColor': '#28a745'}}}%%
 flowchart TD
    subgraph ModelRes["1. Model Resolution"]
        RUNTIME["Runtime override<br/>from AppState"]
        PLAN_SWAP["Plan-mode model<br/>swap for 200K+ contexts"]
        FALLBACK_M["Fallback model<br/>on 529 overload"]
    end
    subgraph MsgNorm["2. Message Normalization"]
        STRIP["Strip internal fields<br/>uuid, timestamp, etc."]
        THINKING["Preserve thinking blocks<br/>within trajectory boundaries"]
        SIGNS["Strip signature blocks"]
    end
    subgraph ToolBuild["3. Tool Schema Building"]
        FILTER_DENY["Filter denied tools"]
        DEFER["Defer tools via<br/>ToolSearch deferred loading"]
        EAGER["Eager tools always<br/>in prompt"]
    end
    subgraph Config["4. Request Configuration"]
        BETAS["Beta features<br/>prompt caching, token counting"]
        CACHE_CTL["cache_control breakpoints<br/>system prompt caching"]
        EFFORT_V["effort parameter<br/>controls thinking depth"]
        TASK_BUD["task_budget<br/>agentic turn spend limit"]
        METADATA["metadata<br/>user_id, session_id"]
    end
    ModelRes --> MsgNorm --> ToolBuild --> Config
    API_REQ["POST /v1/messages<br/>SSE stream"]:::api
    Config --> API_REQ
    classDef api fill:#1b3a1b,stroke:#28a745,color:#e0e0e0,stroke-width:2px
 ```
 ---
 ## Retry Logic — `withRetry`
 The retry wrapper handles transient API failures:
 ```mermaid
 %%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#1a1a2e', 'primaryTextColor': '#e0e0e0', 'lineColor': '#dc3545', 'primaryBorderColor': '#dc3545'}}}%%
 flowchart TD
    REQUEST["API Request"]:::start
    RESPONSE{"Response<br/>status?"}:::check
    OK["200 OK<br/>Stream response"]:::success
    RATE["429 Rate Limited"]:::error
    OVER["529 Overloaded"]:::error
    AUTH["401 Auth Error"]:::fatal
    TIMEOUT["Timeout"]:::error
    BACKOFF["Exponential backoff<br/>wait and retry"]:::retry
    FALLBACK_SWITCH["Switch to fallback model<br/>if configured"]:::retry
    ABORT["CannotRetryError<br/>abort immediately"]:::fatal
    REQUEST --> RESPONSE
    RESPONSE -->|"200"| OK
    RESPONSE -->|"429"| RATE --> BACKOFF --> REQUEST
    RESPONSE -->|"529"| OVER --> FALLBACK_SWITCH --> REQUEST
    RESPONSE -->|"401"| AUTH --> ABORT
    RESPONSE -->|"timeout"| TIMEOUT --> BACKOFF
    classDef start fill:#1a2d4a,stroke:#4a9eff,color:#e0e0e0,stroke-width:2px
    classDef check fill:#2d2d0d,stroke:#ffc107,color:#e0e0e0,stroke-width:2px
    classDef success fill:#1b3a1b,stroke:#28a745,color:#e0e0e0,stroke-width:2px
    classDef error fill:#3d2b00,stroke:#fd7e14,color:#e0e0e0,stroke-width:2px
    classDef fatal fill:#4a1a1a,stroke:#dc3545,color:#e0e0e0,stroke-width:2px
    classDef retry fill:#2d1b4e,stroke:#6f42c1,color:#e0e0e0,stroke-width:2px
 ```
 ### Streaming Fallback
 A unique feature: if the model is overloaded mid-stream (529), Claude Code can:
 1. **Tombstone** the partial assistant messages
 2. Switch to a fallback model
 3. Restart the stream from scratch
 4. The user sees no interruption — orphaned messages are removed from UI
 ---
 ## Prompt Caching
 Claude Code uses Anthropic's prompt cache to avoid re-processing unchanged context:
 ```mermaid
 %%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#1a1a2e', 'primaryTextColor': '#e0e0e0', 'lineColor': '#4a9eff', 'primaryBorderColor': '#4a9eff'}}}%%
 flowchart LR
    SYS["System prompt<br/>cache_control breakpoint"]:::cached
    TOOLS["Tool schemas<br/>cache_control breakpoint"]:::cached
    HISTORY["Conversation history<br/>bytes must match exactly"]:::uncached
    API["API Request"]:::api
    HIT["Cache HIT<br/>~90% cheaper<br/>~10x faster"]:::hit
    MISS["Cache MISS<br/>full processing<br/>new cache created"]:::miss
    SYS --> API
    TOOLS --> API
    HISTORY --> API
    API --> HIT
    API --> MISS
    classDef cached fill:#1b3a1b,stroke:#28a745,color:#e0e0e0,stroke-width:2px
    classDef uncached fill:#333,stroke:#888,color:#e0e0e0,stroke-width:1px
    classDef api fill:#1a2d4a,stroke:#4a9eff,color:#e0e0e0,stroke-width:2px
    classDef hit fill:#0d4f4f,stroke:#17a2b8,color:#e0e0e0,stroke-width:2px
    classDef miss fill:#3d2b00,stroke:#fd7e14,color:#e0e0e0,stroke-width:2px
 ```
 Cache breaks are detected and logged. The `backfillObservableInput()` pattern exists specifically to avoid breaking the cache — the original API-bound input is never mutated.
 ---
 ## SSE Stream Events
 The API returns Server-Sent Events in this order:
 ```mermaid
 %%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#1a1a2e', 'primaryTextColor': '#e0e0e0', 'lineColor': '#4a9eff', 'primaryBorderColor': '#4a9eff'}}}%%
 sequenceDiagram
    participant API as Anthropic API
    participant C as claude.ts
    API->>C: message_start — model, usage, id
    loop For each content block
        API->>C: content_block_start — type, index
        loop Delta events
            API->>C: content_block_delta — text / thinking / tool_use JSON
        end
        API->>C: content_block_stop
    end
    API->>C: message_delta — stop_reason, final usage
    API->>C: message_stop
    Note over C: Parse into AssistantMessage<br/>Track usage + cost<br/>Yield to query.ts
 ```
 ---
 ## Cost Tracking
 Every API call's usage is tracked in `cost-tracker.ts`:
 - Input tokens (including cache reads/writes)
 - Output tokens
 - Per-model pricing
 - Session totals exposed via `/cost` command
 ---
 **Previous:** [← Extension Model](./07-extension-model.md) · **Next:** [UI Architecture →](./09-ui-architecture.md)
--- a/learn/09-ui-architecture.md
+++ b/learn/09-ui-architecture.md
@ -0,0 +1,109 @@
 # 9. UI Architecture
 > Building a complex, interactive terminal UI with React and Ink.
 ---
 ## Overview
 Claude Code uses React (via [Ink](https://github.com/vadimdemedes/ink)) to render its terminal interface. This allows it to use React's declarative component model, hooks, and state management in a CLI context.
 ```mermaid
 %%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#1a1a2e', 'primaryTextColor': '#e0e0e0', 'lineColor': '#4a9eff', 'primaryBorderColor': '#4a9eff'}}}%%
 graph TB
    CLI["main.tsx<br/>Parses args, boots React"]:::entry
    INK["Ink rendered<br/>Terminal output"]:::external
    subgraph ReactApp["React Application"]
        APP["App.tsx<br/>Providers and Routing"]
        REPL["REPL.tsx (896KB)<br/>Main Interface"]
        subgraph Components["113 UI Components"]
            MESSAGES["Message Rendering<br/>User, Assistant, Tool"]
            DIALOGS["Permission Dialogs<br/>Y/n Prompts"]
            INPUT["Input Area<br/>Text, Voice, Paste"]
            INDICATORS["Spinners & Progress Bars"]
        end
        subgraph Hooks["83 Custom Hooks"]
            USE_STATE["useAppState"]
            USE_TOOL["useCanUseTool"]
            USE_INPUT["useInput"]
            USE_VOICE["useVoice"]
        end
    end
    CLI --> APP
    APP --> REPL
    REPL --> Components
    REPL --> Hooks
    Components --> INK
    classDef entry fill:#0d4f4f,stroke:#17a2b8,color:#e0e0e0,stroke-width:2px
    classDef external fill:#333,stroke:#888,color:#aaa,stroke-width:1px,stroke-dasharray: 5 5
 ```
 ---
 ## The REPL
 The core of the interface is `REPL.tsx` (896KB). It manages the main interaction loop from the UI perspective, orchestrating input, rendering the conversation history, and handling background tasks.
 ### Key Responsibilities
 1. **Virtual Scrolling**: The terminal can't hold infinite text. The REPL implements virtual scrolling, only rendering the messages that fit in the viewport plus a small buffer, while maintaining the illusion of a continuous scrollback.
 2. **Input Handling**: Manages the text input area, handling multiline input, pasting files/images, keyboard shortcuts (including vim mode), and voice input.
 3. **Task Foregrounding**: Only one agent task can write to the terminal at a time. The REPL manages which task is "foregrounded" and visible.
 4. **State Synchronization**: Subscribes to the single immutable `AppState` store to trigger re-renders when data changes.
 ---
 ## Component Architecture
 Claude Code breaks down the UI into 113 specialized components.
 ### Message Rendering
 Each message type has a dedicated component:
 - `UserMessage`: Renders user input.
 - `AssistantMessage`: Renders markdown text from the model, handling streaming updates gracefully.
 - `ToolUseMessage`: Displays the execution in progress (e.g., a spinner and the command being run).
 - `ToolResultMessage`: Shows the outcome, often truncating long outputs and providing "Show More" functionality.
 ### Layout and Styling
 Ink uses Yoga (a Flexbox engine) for layout. Components are composed using Flexbox principles, allowing for responsive terminal designs that adapt to the window size.
 ---
 ## State and Hooks
 The UI is deeply integrated with the `AppState` store.
 ```mermaid
 %%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#1a1a2e', 'primaryTextColor': '#e0e0e0', 'lineColor': '#28a745', 'primaryBorderColor': '#28a745'}}}%%
 flowchart LR
    STORE["AppState<br/>Immutable Store"]:::state
    REPL["REPL Component"]:::ui
    COMP["Child Components"]:::ui
    HOOKS["Selectors<br/>useAppState(selector)"]:::hook
    STORE --> HOOKS
    HOOKS --> REPL
    HOOKS --> COMP
    classDef state fill:#1a2d4a,stroke:#4a9eff,color:#e0e0e0,stroke-width:2px
    classDef hook fill:#1b3a1b,stroke:#28a745,color:#e0e0e0,stroke-width:2px
    classDef ui fill:#2d1b4e,stroke:#6f42c1,color:#e0e0e0,stroke-width:2px
 ```
 Custom hooks encapsulate complex logic:
 - `useInput`: Handles raw stdin data, necessary for keyboard shortcuts that bypass normal text input.
 - `useCanUseTool`: Connects a UI prompt to the permission system, pausing the engine until the user responds.
 ---
 **Previous:** [<- API Client](./08-api-client.md) | **Next:** [Configuration and System Prompt ->](./10-configuration-and-system-prompt.md)
--- a/learn/10-configuration-and-system-prompt.md
+++ b/learn/10-configuration-and-system-prompt.md
@ -0,0 +1,253 @@
 # 10. Configuration and System Prompt
 > How settings cascade from enterprise policy down to project CLAUDE.md, and how the system prompt is assembled.
 ---
 ## Configuration Hierarchy
 Claude Code loads settings from **5 layers**, each with strict priority. Higher layers override lower ones.
 ```mermaid
 %%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#1a1a2e', 'primaryTextColor': '#e0e0e0', 'lineColor': '#4a9eff', 'primaryBorderColor': '#4a9eff'}}}%%
 flowchart TD
    subgraph Sources["Configuration Sources — Highest to Lowest Priority"]
        direction TB
        ENT["Enterprise / MDM Policy<br/>managed-settings.json<br/>Org-level, cannot override"]:::ent
        USER["User Settings<br/>~/.claude/settings.json<br/>Per-user global defaults"]:::user
        PROJ["Project Settings<br/>.claude/settings.json<br/>Per-repo configuration"]:::proj
        MCP_CFG[".mcp.json<br/>Project MCP servers<br/>Committed to repo"]:::proj
        CLAUDE_MD["CLAUDE.md files<br/>Instructions, rules,<br/>memory for the model"]:::md
    end
    ENT --> MERGE
    USER --> MERGE
    PROJ --> MERGE
    MCP_CFG --> MERGE
    CLAUDE_MD --> MERGE
    MERGE["getInitialSettings<br/>Merge all layers<br/>Higher priority wins"]:::merge
    APPSTATE["AppState.settings<br/>Runtime configuration"]:::state
    MERGE --> APPSTATE
    classDef ent fill:#4a1a1a,stroke:#dc3545,color:#e0e0e0,stroke-width:2px
    classDef user fill:#2d2d0d,stroke:#ffc107,color:#e0e0e0,stroke-width:2px
    classDef proj fill:#0d4f4f,stroke:#17a2b8,color:#e0e0e0,stroke-width:2px
    classDef md fill:#2d1b4e,stroke:#6f42c1,color:#e0e0e0,stroke-width:2px
    classDef merge fill:#1a2d4a,stroke:#4a9eff,color:#e0e0e0,stroke-width:2px
    classDef state fill:#1b3a1b,stroke:#28a745,color:#e0e0e0,stroke-width:2px
 ```
 ### Enterprise / MDM Policy
 Highest priority. Set by organization admins via Mobile Device Management (macOS profiles). Stored at a managed file path. Users **cannot** override these settings. Controls things like:
 - Allowed/denied MCP servers
 - Permission mode restrictions
 - Feature availability
 - Analytics opt-out
 ### User Settings (`~/.claude/settings.json`)
 Per-user defaults. Controls preferences like allowed tools, custom deny rules, and hooks.
 ### Project Settings (`.claude/settings.json`)
 Per-repository settings. Committed to the repo so all collaborators share the same configuration.
 ### `.mcp.json`
 MCP server definitions for the project. Lives at the repo root. Defines which MCP servers are available. Validated via Zod schema (`McpServerConfigSchema`).
 ### CLAUDE.md
 Markdown instruction files that the model reads as part of its system prompt. These are the "memory" files that tell Claude about this specific project.
 ---
 ## CLAUDE.md Discovery
 CLAUDE.md files are discovered from multiple locations and merged:
 ```mermaid
 %%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#1a1a2e', 'primaryTextColor': '#e0e0e0', 'lineColor': '#6f42c1', 'primaryBorderColor': '#6f42c1'}}}%%
 flowchart TD
    subgraph Discovery["CLAUDE.md Discovery — getMemoryFiles"]
        GLOBAL["~/.claude/CLAUDE.md<br/>Global instructions"]:::global
        CWD_WALK["Walk from cwd up to git root<br/>Check each dir for CLAUDE.md<br/>and .claude/CLAUDE.md"]:::walk
        ADDITIONAL["--add-dir paths<br/>Extra directories to scan"]:::additional
    end
    FILTER["filterInjectedMemoryFiles<br/>Remove duplicates,<br/>check setting sources"]:::filter
    PARSE["getClaudeMds<br/>Read and concatenate<br/>all discovered files"]:::parse
    CACHE["setCachedClaudeMdContent<br/>Cache for auto-mode<br/>classifier to read"]:::cache
    INJECT["Injected into getUserContext<br/>becomes part of system prompt"]:::inject
    Discovery --> FILTER --> PARSE --> CACHE --> INJECT
    classDef global fill:#2d2d0d,stroke:#ffc107,color:#e0e0e0,stroke-width:2px
    classDef walk fill:#0d4f4f,stroke:#17a2b8,color:#e0e0e0,stroke-width:2px
    classDef additional fill:#1a2d4a,stroke:#4a9eff,color:#e0e0e0,stroke-width:2px
    classDef filter fill:#3d2b00,stroke:#fd7e14,color:#e0e0e0,stroke-width:2px
    classDef parse fill:#2d1b4e,stroke:#6f42c1,color:#e0e0e0,stroke-width:2px
    classDef cache fill:#333,stroke:#888,color:#e0e0e0,stroke-width:1px
    classDef inject fill:#1b3a1b,stroke:#28a745,color:#e0e0e0,stroke-width:2px
 ```
 The `--bare` flag skips auto-discovery but still honors explicit `--add-dir` paths.
 ---
 ## System Prompt Assembly
 The system prompt is what the model "sees" before any conversation messages. It's assembled from multiple pieces:
 ```mermaid
 %%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#1a1a2e', 'primaryTextColor': '#e0e0e0', 'lineColor': '#e83e8c', 'primaryBorderColor': '#e83e8c'}}}%%
 flowchart TD
    subgraph Priority["System Prompt Priority — buildEffectiveSystemPrompt"]
        OVERRIDE["1. Override System Prompt<br/>Set via loop mode<br/>REPLACES everything"]:::override
        COORD["2. Coordinator System Prompt<br/>If coordinator mode active"]:::coord
        AGENT["3. Agent System Prompt<br/>If mainThreadAgentDefinition set<br/>In proactive mode: APPENDED<br/>Otherwise: REPLACES default"]:::agent
        CUSTOM["4. Custom System Prompt<br/>Via --system-prompt flag"]:::custom
        DEFAULT["5. Default System Prompt<br/>The standard Claude Code prompt"]:::default
    end
    APPEND["appendSystemPrompt<br/>Always appended at end<br/>except when override is set"]:::append
    EFFECTIVE["Effective System Prompt<br/>Sent as system param<br/>in API request"]:::result
    OVERRIDE -->|"if set"| EFFECTIVE
    COORD -->|"if coordinator"| EFFECTIVE
    AGENT -->|"if agent defined"| EFFECTIVE
    CUSTOM -->|"if --system-prompt"| EFFECTIVE
    DEFAULT -->|"fallback"| EFFECTIVE
    APPEND --> EFFECTIVE
    classDef override fill:#4a1a1a,stroke:#dc3545,color:#e0e0e0,stroke-width:2px
    classDef coord fill:#3d2b00,stroke:#fd7e14,color:#e0e0e0,stroke-width:2px
    classDef agent fill:#2d1b4e,stroke:#6f42c1,color:#e0e0e0,stroke-width:2px
    classDef custom fill:#2d2d0d,stroke:#ffc107,color:#e0e0e0,stroke-width:2px
    classDef default fill:#1a2d4a,stroke:#4a9eff,color:#e0e0e0,stroke-width:2px
    classDef append fill:#0d4f4f,stroke:#17a2b8,color:#e0e0e0,stroke-width:2px
    classDef result fill:#1b3a1b,stroke:#28a745,color:#e0e0e0,stroke-width:2px
 ```
 ### System Prompt Sections
 Individual sections of the system prompt are defined via `systemPromptSection()`:
 ```mermaid
 %%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#1a1a2e', 'primaryTextColor': '#e0e0e0', 'lineColor': '#4a9eff', 'primaryBorderColor': '#4a9eff'}}}%%
 flowchart LR
    subgraph Sections["System Prompt Sections"]
        CACHED["Cached Sections<br/>Computed once at start<br/>Reused every turn<br/>Cleared on /clear or /compact"]:::cached
        VOLATILE["DANGEROUS Uncached Sections<br/>Recomputed every turn<br/>BREAKS prompt cache"]:::volatile
    end
    RESOLVE["resolveSystemPromptSections<br/>Check cache, compute if needed"]:::resolve
    PROMPT["Final system prompt string"]:::result
    CACHED --> RESOLVE
    VOLATILE --> RESOLVE
    RESOLVE --> PROMPT
    classDef cached fill:#1b3a1b,stroke:#28a745,color:#e0e0e0,stroke-width:2px
    classDef volatile fill:#4a1a1a,stroke:#dc3545,color:#e0e0e0,stroke-width:2px
    classDef resolve fill:#1a2d4a,stroke:#4a9eff,color:#e0e0e0,stroke-width:2px
    classDef result fill:#2d1b4e,stroke:#6f42c1,color:#e0e0e0,stroke-width:2px
 ```
 Most sections are **cached** (computed once, reused every turn) to preserve prompt cache hits. Volatile sections that recompute every turn are explicitly named `DANGEROUS_uncachedSystemPromptSection` as a warning.
 ---
 ## Context Injection
 Beyond the system prompt, two context objects are injected into every conversation:
 ```mermaid
 %%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#1a1a2e', 'primaryTextColor': '#e0e0e0', 'lineColor': '#28a745', 'primaryBorderColor': '#28a745'}}}%%
 flowchart LR
    subgraph SystemCtx["getSystemContext — memoized"]
        GIT["Git status snapshot<br/>branch, status, log,<br/>default branch, user"]
        INJECT_SYS["System prompt injection<br/>internal debugging only"]
    end
    subgraph UserCtx["getUserContext — memoized"]
        CMD["CLAUDE.md content<br/>all discovered files<br/>concatenated"]
        DATE["Current date<br/>ISO format"]
    end
    PREPEND["prependUserContext<br/>Prepended to messages<br/>before API call"]:::merge
    SystemCtx --> PREPEND
    UserCtx --> PREPEND
    classDef merge fill:#1b3a1b,stroke:#28a745,color:#e0e0e0,stroke-width:2px
 ```
 Both are **memoized** and cached for the duration of the conversation. They're cleared on `/clear` and `/compact`.
 ---
 ## Markdown Config Discovery
 Commands, agents, skills, and workflows are all loaded via `markdownConfigLoader.ts`:
 ```mermaid
 %%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#1a1a2e', 'primaryTextColor': '#e0e0e0', 'lineColor': '#fd7e14', 'primaryBorderColor': '#fd7e14'}}}%%
 flowchart TD
    subgraph Dirs["Search Directories — Priority Order"]
        MANAGED["Managed (enterprise)<br/>Policy-level configs"]:::ent
        USER_DIR["User (~/.claude/)<br/>Personal configs"]:::user
        PROJ_DIRS["Project (.claude/)<br/>Walk cwd up to git root<br/>Check each ancestor"]:::proj
    end
    LOADER["loadMarkdownFilesForSubdir<br/>Discover + parse YAML frontmatter<br/>+ markdown content"]:::loader
    DEDUP["Deduplicate by inode<br/>Handle symlinks gracefully"]:::dedup
    FILES["MarkdownFile array<br/>filePath, frontmatter,<br/>content, source"]:::result
    MANAGED --> LOADER
    USER_DIR --> LOADER
    PROJ_DIRS --> LOADER
    LOADER --> DEDUP --> FILES
    classDef ent fill:#4a1a1a,stroke:#dc3545,color:#e0e0e0,stroke-width:2px
    classDef user fill:#2d2d0d,stroke:#ffc107,color:#e0e0e0,stroke-width:2px
    classDef proj fill:#0d4f4f,stroke:#17a2b8,color:#e0e0e0,stroke-width:2px
    classDef loader fill:#1a2d4a,stroke:#4a9eff,color:#e0e0e0,stroke-width:2px
    classDef dedup fill:#3d2b00,stroke:#fd7e14,color:#e0e0e0,stroke-width:2px
    classDef result fill:#1b3a1b,stroke:#28a745,color:#e0e0e0,stroke-width:2px
 ```
 This same loader powers:
 - Slash commands (`.claude/commands/`)
 - Agents (`.claude/agents/`)
 - Skills (`.claude/skills/`)
 - Workflows (`.claude/workflows/`)
 - Output styles (`.claude/output-styles/`)
 Each entry is parsed with YAML frontmatter for metadata (description, tools, etc.) and the markdown body becomes the instructions.
 ---
 ## Key Files
 - `src/utils/systemPrompt.ts` — `buildEffectiveSystemPrompt()` logic
 - `src/constants/systemPromptSections.ts` — Section caching system
 - `src/context.ts` — `getSystemContext()`, `getUserContext()`, git status
 - `src/utils/markdownConfigLoader.ts` — CLAUDE.md and `.claude/` directory discovery
 - `src/utils/claudemd.ts` — Memory file reading and concatenation
 - `src/utils/settings/settings.ts` — Settings merge logic
 ---
 **Previous:** [<- UI Architecture](./09-ui-architecture.md) | **Next:** [MCP Deep Dive ->](./11-mcp-deep-dive.md)
--- a/learn/11-mcp-deep-dive.md
+++ b/learn/11-mcp-deep-dive.md
@ -0,0 +1,290 @@
 # 11. MCP Deep Dive
 > The Model Context Protocol subsystem -- transports, tool wrapping, authentication, and server lifecycle.
 ---
 ## What is MCP?
 MCP (Model Context Protocol) is an open protocol for connecting AI models to external tools and data sources. Claude Code is both an **MCP client** (connecting to external MCP servers) and can act as an **MCP server** (exposing its own tools to other systems).
 ```mermaid
 %%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#1a1a2e', 'primaryTextColor': '#e0e0e0', 'lineColor': '#4a9eff', 'primaryBorderColor': '#4a9eff'}}}%%
 graph TB
    subgraph ClaudeCode["Claude Code"]
        CLIENT["MCP Client<br/>Connects to external servers"]:::client
        SERVER["MCP Server Mode<br/>Exposes tools to other systems"]:::server
        TOOLS["42 Built-in Tools<br/>+ MCP tools merged in"]:::tools
    end
    subgraph External["External MCP Servers"]
        STDIO_S["stdio servers<br/>Local processes"]:::external
        SSE_S["SSE/HTTP servers<br/>Remote endpoints"]:::external
        WS_S["WebSocket servers<br/>Persistent connections"]:::external
        CLAUDE_AI["claude.ai proxy<br/>Managed connectors"]:::external
        IDE_S["IDE servers<br/>Editor integration"]:::external
    end
    CLIENT --> STDIO_S
    CLIENT --> SSE_S
    CLIENT --> WS_S
    CLIENT --> CLAUDE_AI
    CLIENT --> IDE_S
    STDIO_S --> TOOLS
    SSE_S --> TOOLS
    WS_S --> TOOLS
    CLAUDE_AI --> TOOLS
    IDE_S --> TOOLS
    classDef client fill:#1a2d4a,stroke:#4a9eff,color:#e0e0e0,stroke-width:2px
    classDef server fill:#2d1b4e,stroke:#6f42c1,color:#e0e0e0,stroke-width:2px
    classDef tools fill:#1b3a1b,stroke:#28a745,color:#e0e0e0,stroke-width:2px
    classDef external fill:#333,stroke:#888,color:#aaa,stroke-width:1px,stroke-dasharray: 5 5
 ```
 ---
 ## Transport Types
 Claude Code supports **6 transport types** for connecting to MCP servers:
 ```mermaid
 %%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#1a1a2e', 'primaryTextColor': '#e0e0e0', 'lineColor': '#17a2b8', 'primaryBorderColor': '#17a2b8'}}}%%
 flowchart TD
    subgraph Local["Local Transports"]
        STDIO["stdio<br/>Spawn local process<br/>Communicate via stdin/stdout<br/>Most common type"]:::local
        SDK_T["sdk<br/>In-process transport<br/>SDK-managed placeholder<br/>Tool calls route to SDK"]:::local
    end
    subgraph Remote["Remote Transports"]
        SSE["sse<br/>Server-Sent Events<br/>Legacy remote protocol<br/>OAuth authentication"]:::remote
        HTTP["http<br/>Streamable HTTP<br/>Modern remote protocol<br/>Per-request timeouts"]:::remote
        WS["ws<br/>WebSocket<br/>Persistent bidirectional<br/>TLS/proxy support"]:::remote
        CLAUDEAI["claudeai-proxy<br/>Via claude.ai OAuth<br/>Managed connectors<br/>Auto token refresh"]:::remote
    end
    subgraph IDE["IDE Transports"]
        SSE_IDE["sse-ide<br/>IDE SSE connection<br/>No authentication"]:::ide
        WS_IDE["ws-ide<br/>IDE WebSocket<br/>Auth token in header"]:::ide
    end
    classDef local fill:#1b3a1b,stroke:#28a745,color:#e0e0e0,stroke-width:2px
    classDef remote fill:#2d2d0d,stroke:#ffc107,color:#e0e0e0,stroke-width:2px
    classDef ide fill:#0d4f4f,stroke:#17a2b8,color:#e0e0e0,stroke-width:2px
 ```
 ---
 ## Connection Lifecycle
 ```mermaid
 %%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#1a1a2e', 'primaryTextColor': '#e0e0e0', 'lineColor': '#28a745', 'actorTextColor': '#e0e0e0', 'actorBorder': '#28a745', 'signalColor': '#28a745', 'noteBkgColor': '#16213e', 'noteTextColor': '#e0e0e0', 'activationBkgColor': '#1b3a1b', 'activationBorderColor': '#28a745'}}}%%
 sequenceDiagram
    participant H as useManageMCPConnections
    participant C as connectToServer (memoized)
    participant T as Transport Layer
    participant S as External Server
    H->>H: getAllMcpConfigs - merge all sources
    H->>H: Batch servers (local=3, remote=20)
    loop For each server
        H->>C: connectToServer(name, config)
        activate C
        alt Auth cached as needed
            C-->>H: return needs-auth
        else Server disabled
            C-->>H: return disabled
        else Policy blocked
            C-->>H: return not allowed
        end
        C->>T: Create transport (stdio/sse/http/ws)
        T->>S: Connect
        activate S
        alt auth required (401/403)
            S-->>C: Auth error
            C-->>H: return needs-auth
        else connection timeout
            S-->>C: Timeout (30s default)
            C-->>H: return error
        else success
            S-->>T: Connected
            deactivate S
            C->>S: tools/list
            S-->>C: Available tools
            C->>C: Wrap as MCPTool objects
            C-->>H: return connected + tools
        end
        deactivate C
    end
    H->>H: Update AppState.mcp
 ```
 ### Batched Connections
 Servers are connected in parallel batches to avoid overwhelming the system:
 - **Local (stdio) servers**: batch size of 3 (spawning processes is heavy)
 - **Remote servers**: batch size of 20 (network connections are lighter)
 The batch sizes are configurable via `MCP_SERVER_CONNECTION_BATCH_SIZE` and `MCP_REMOTE_SERVER_CONNECTION_BATCH_SIZE` environment variables.
 ---
 ## Tool Wrapping
 Each MCP tool is wrapped in a `MCPTool` object that implements the standard `Tool` interface:
 ```mermaid
 %%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#1a1a2e', 'primaryTextColor': '#e0e0e0', 'lineColor': '#ffc107', 'primaryBorderColor': '#ffc107'}}}%%
 flowchart LR
    MCP_TOOL["MCP Server Tool<br/>name, inputSchema,<br/>description"]:::raw
    WRAP["MCPTool wrapper<br/>Implements Tool interface<br/>name: mcp__server__tool"]:::wrap
    subgraph Lifecycle["Tool Call Lifecycle"]
        VALIDATE["Validate input<br/>via JSON Schema"]:::step
        PERM["Check permissions<br/>Same system as built-in"]:::step
        CALL["Forward to MCP server<br/>tools/call RPC"]:::step
        RESULT["Process result<br/>Truncate if needed<br/>Handle images"]:::step
    end
    MCP_TOOL --> WRAP --> VALIDATE --> PERM --> CALL --> RESULT
    classDef raw fill:#333,stroke:#888,color:#e0e0e0,stroke-width:1px
    classDef wrap fill:#2d2d0d,stroke:#ffc107,color:#e0e0e0,stroke-width:2px
    classDef step fill:#1b3a1b,stroke:#28a745,color:#e0e0e0,stroke-width:2px
 ```
 ### Naming Convention
 MCP tools are named `mcp__<server>__<tool>`:
 - `mcp__slack__send_message`
 - `mcp__github__create_issue`
 - `mcp__ide__getDiagnostics`
 The double-underscore separators prevent ambiguity. In SDK no-prefix mode, tools keep their original names.
 ### Description Capping
 MCP tool descriptions are capped at **2,048 characters**. OpenAPI-generated servers have been observed dumping 15-60KB of endpoint docs into descriptions, which wastes context tokens.
 ---
 ## Configuration Sources
 MCP server definitions come from multiple sources, merged with priority rules:
 ```mermaid
 %%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#1a1a2e', 'primaryTextColor': '#e0e0e0', 'lineColor': '#dc3545', 'primaryBorderColor': '#dc3545'}}}%%
 flowchart TD
    subgraph Sources["MCP Config Sources"]
        ENT["Enterprise managed-mcp.json<br/>Exclusive control if present"]:::ent
        GLOBAL["Global ~/.claude/settings.json<br/>mcpServers field"]:::user
        LOCAL[".claude/settings.local.json<br/>Local project overrides"]:::local
        PROJECT[".mcp.json at project root<br/>Committed to repo"]:::proj
        PLUGIN["Plugin MCP servers<br/>From installed plugins"]:::plugin
        CLAUDEAI["claude.ai connectors<br/>Fetched at startup"]:::claudeai
        CLI["--mcp-config flag<br/>Runtime override"]:::cli
        SDK_CFG["SDK mcp_set_servers<br/>Programmatic control"]:::sdk
    end
    MERGE["getAllMcpConfigs<br/>Merge + dedup + policy filter"]:::merge
    POLICY{"Enterprise policy<br/>allowedMcpServers?<br/>deniedMcpServers?"}:::check
    ALLOWED["Allowed servers<br/>proceed to connect"]:::allow
    BLOCKED["Blocked servers<br/>silently dropped"]:::deny
    Sources --> MERGE --> POLICY
    POLICY -->|"allowed"| ALLOWED
    POLICY -->|"denied"| BLOCKED
    classDef ent fill:#4a1a1a,stroke:#dc3545,color:#e0e0e0,stroke-width:2px
    classDef user fill:#2d2d0d,stroke:#ffc107,color:#e0e0e0,stroke-width:2px
    classDef local fill:#3d2b00,stroke:#fd7e14,color:#e0e0e0,stroke-width:2px
    classDef proj fill:#0d4f4f,stroke:#17a2b8,color:#e0e0e0,stroke-width:2px
    classDef plugin fill:#2d1b4e,stroke:#6f42c1,color:#e0e0e0,stroke-width:2px
    classDef claudeai fill:#1a1a4e,stroke:#6f42c1,color:#e0e0e0,stroke-width:2px
    classDef cli fill:#1a2d4a,stroke:#4a9eff,color:#e0e0e0,stroke-width:2px
    classDef sdk fill:#333,stroke:#888,color:#e0e0e0,stroke-width:1px
    classDef merge fill:#1b3a1b,stroke:#28a745,color:#e0e0e0,stroke-width:2px
    classDef check fill:#2d2d0d,stroke:#ffc107,color:#e0e0e0,stroke-width:2px
    classDef allow fill:#1b3a1b,stroke:#28a745,color:#e0e0e0,stroke-width:2px
    classDef deny fill:#4a1a1a,stroke:#dc3545,color:#e0e0e0,stroke-width:2px
 ```
 ### Deduplication
 Plugin and claude.ai connector servers are deduplicated against manually-configured servers:
 - **Signature-based**: Same `command+args` (stdio) or same `url` (remote) = same server
 - **Manual wins**: If a user manually configured a server, the plugin/connector duplicate is suppressed
 - **First-loaded wins**: Between plugins, the first one loaded takes priority
 ---
 ## Authentication
 Remote MCP servers may require OAuth authentication:
 ```mermaid
 %%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#1a1a2e', 'primaryTextColor': '#e0e0e0', 'lineColor': '#dc3545', 'primaryBorderColor': '#dc3545'}}}%%
 flowchart TD
    CONNECT["Connect to remote server"]:::start
    AUTH{"Auth required?"}:::check
    PROVIDER["ClaudeAuthProvider<br/>OAuth flow per server"]:::auth
    TOKENS["Retrieve/refresh tokens"]:::auth
    OK["Connection established"]:::success
    NEEDS["Status: needs-auth<br/>Cached for 15 min"]:::needsauth
    CALL["MCP tool call"]:::start
    CALL_AUTH{"401 on call?"}:::check
    RETRY["Refresh token<br/>retry once"]:::auth
    MCE["McpAuthError<br/>Update status to needs-auth"]:::error
    CONNECT --> AUTH
    AUTH -->|"no"| OK
    AUTH -->|"yes"| PROVIDER --> TOKENS
    TOKENS -->|"success"| OK
    TOKENS -->|"failure"| NEEDS
    CALL --> CALL_AUTH
    CALL_AUTH -->|"no"| OK
    CALL_AUTH -->|"yes"| RETRY
    RETRY -->|"success"| OK
    RETRY -->|"failure"| MCE
    classDef start fill:#1a2d4a,stroke:#4a9eff,color:#e0e0e0,stroke-width:2px
    classDef check fill:#2d2d0d,stroke:#ffc107,color:#e0e0e0,stroke-width:2px
    classDef auth fill:#2d1b4e,stroke:#6f42c1,color:#e0e0e0,stroke-width:2px
    classDef success fill:#1b3a1b,stroke:#28a745,color:#e0e0e0,stroke-width:2px
    classDef needsauth fill:#3d2b00,stroke:#fd7e14,color:#e0e0e0,stroke-width:2px
    classDef error fill:#4a1a1a,stroke:#dc3545,color:#e0e0e0,stroke-width:2px
 ```
 ### Session Expiry Handling
 MCP servers return HTTP 404 + JSON-RPC error code `-32001` when a session expires. Claude Code detects this, clears the connection cache, and reconnects automatically (`McpSessionExpiredError`).
 ---
 ## Key Files
 - `src/services/mcp/client.ts` (3,349 lines) -- Connection manager, tool wrapping, transport creation
 - `src/services/mcp/config.ts` (1,579 lines) -- Config merging, policy filtering, deduplication
 - `src/services/mcp/types.ts` -- Type definitions for server configs and connections
 - `src/services/mcp/auth.ts` -- OAuth provider and step-up authentication
 - `src/services/mcp/useManageMCPConnections.ts` -- React hook managing connection lifecycle
 - `src/tools/MCPTool/MCPTool.ts` -- MCPTool wrapper implementing the Tool interface
 ---
 **Previous:** [<- Configuration](./10-configuration-and-system-prompt.md) | **Next:** [Data Flow Walkthrough ->](./12-data-flow-walkthrough.md)
--- a/learn/12-data-flow-walkthrough.md
+++ b/learn/12-data-flow-walkthrough.md
@ -0,0 +1,341 @@
 # 12. Data Flow Walkthrough
 > Tracing a single user request from keystroke to rendered response -- end to end.
 ---
 ## The Complete Flow
 This diagram traces exactly what happens when a user types a prompt and presses Enter.
 ```mermaid
 %%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#1a1a2e', 'primaryTextColor': '#e0e0e0', 'lineColor': '#4a9eff', 'primaryBorderColor': '#4a9eff'}}}%%
 flowchart TD
    TYPE["User types in terminal"]:::input
    PASTE["Paste: text, image, file"]:::input
    VOICE["Voice input via STT"]:::input
    IDE_IN["IDE sends prompt"]:::input
    SDK_IN["SDK submitMessage"]:::input
    PARSE["Parse input<br/>slash commands, @mentions"]:::process
    SLASH{"Slash<br/>command?"}:::decision
    LOCAL["Execute locally<br/>clear, compact, model"]:::process
    ATTACH["Build attachments<br/>images, PDFs, CLAUDE.md"]:::process
    UMSG["Create UserMessage"]:::process
    SYS["Build system prompt<br/>tool descriptions +<br/>user rules + CLAUDE.md"]:::context
    GIT["Inject git context<br/>branch, commits, status"]:::context
    USR["Inject user context<br/>CLAUDE.md, date"]:::context
    CMP["Run compaction pipeline"]:::context
    CACHE["Apply cache_control<br/>prompt cache breakpoints"]:::context
    BUILD["Build API request<br/>model, betas, effort,<br/>task_budget, thinking"]:::api
    STREAM["Stream SSE response<br/>from Anthropic API"]:::api
    RETRY["withRetry wrapper<br/>429 backoff, 529 fallback"]:::api
    THINK["Thinking blocks"]:::response
    TEXT["Text blocks"]:::response
    TOOL_USE["tool_use blocks"]:::response
    VALIDATE["Validate input"]:::toolexec
    PERMS["Check permissions"]:::toolexec
    EXEC["Execute tool"]:::toolexec
    RESULT["Map to tool_result"]:::toolexec
    FEEDBACK["Push to messages<br/>LOOP BACK"]:::feedback
    RENDER["Render in terminal"]:::output
    TRANSCRIPT["Persist transcript"]:::output
    SDK_OUT["Yield SDK events"]:::output
    COST["Track cost + usage"]:::output
    TYPE --> PARSE
    PASTE --> PARSE
    VOICE --> PARSE
    IDE_IN --> PARSE
    SDK_IN --> PARSE
    PARSE --> SLASH
    SLASH -->|"yes"| LOCAL --> RENDER
    SLASH -->|"no"| ATTACH --> UMSG
    UMSG --> SYS --> GIT --> USR --> CMP --> CACHE
    CACHE --> BUILD --> STREAM
    STREAM --> RETRY --> STREAM
    STREAM --> THINK --> RENDER
    STREAM --> TEXT --> RENDER
    STREAM --> TOOL_USE
    TOOL_USE --> VALIDATE --> PERMS --> EXEC --> RESULT --> FEEDBACK
    FEEDBACK ==>|"loop back to<br/>compaction"| CMP
    TEXT -->|"end_turn"| TRANSCRIPT --> SDK_OUT --> COST
    classDef input fill:#0d4f4f,stroke:#17a2b8,color:#e0e0e0,stroke-width:2px
    classDef process fill:#1a2d4a,stroke:#4a9eff,color:#e0e0e0,stroke-width:2px
    classDef decision fill:#2d2d0d,stroke:#ffc107,color:#e0e0e0,stroke-width:2px
    classDef context fill:#2d1b4e,stroke:#6f42c1,color:#e0e0e0,stroke-width:2px
    classDef api fill:#1b3a1b,stroke:#28a745,color:#e0e0e0,stroke-width:2px
    classDef response fill:#3d2b00,stroke:#fd7e14,color:#e0e0e0,stroke-width:2px
    classDef toolexec fill:#1a1a4e,stroke:#6f42c1,color:#e0e0e0,stroke-width:2px
    classDef feedback fill:#4a1a1a,stroke:#dc3545,color:#e0e0e0,stroke-width:3px
    classDef output fill:#333,stroke:#888,color:#e0e0e0,stroke-width:1px
 ```
 ---
 ## Phase by Phase
 ### Phase 1: Input Capture
 The user's input can arrive from **5 different sources**, all converging into `processUserInput()`:
 ```mermaid
 %%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#1a1a2e', 'primaryTextColor': '#e0e0e0', 'lineColor': '#17a2b8', 'primaryBorderColor': '#17a2b8'}}}%%
 flowchart LR
    subgraph Sources["Input Sources"]
        KB["Keyboard input<br/>Direct typing in terminal"]
        PASTE["Clipboard paste<br/>Text, images, files"]
        VOICE["Voice<br/>STT transcription"]
        IDE["IDE Bridge<br/>Prompt from editor"]
        SDK["SDK<br/>Programmatic submitMessage"]
    end
    PUI["processUserInput<br/>Parse slash commands<br/>Resolve @mentions<br/>Build attachments"]:::process
    subgraph Output["Parse Result"]
        MSGS["messages array"]
        SHOULD["shouldQuery boolean"]
    end
    Sources --> PUI --> Output
    classDef process fill:#1a2d4a,stroke:#4a9eff,color:#e0e0e0,stroke-width:2px
 ```
 Slash commands (`/clear`, `/compact`, `/model`) are intercepted here and handled locally without an API call. Everything else proceeds to the model.
 ### Phase 2: Context Assembly
 Before sending to the API, the system assembles context from multiple sources:
 ```mermaid
 %%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#1a1a2e', 'primaryTextColor': '#e0e0e0', 'lineColor': '#6f42c1', 'primaryBorderColor': '#6f42c1'}}}%%
 flowchart TD
    subgraph SystemPrompt["System Prompt Assembly"]
        DEFAULT["Default prompt<br/>Claude Code identity"]
        TOOL_DESC["Tool descriptions<br/>42+ tool schemas"]
        SECTIONS["System prompt sections<br/>Cached or volatile"]
    end
    subgraph UserContext["User Context"]
        CLAUDE_MD["CLAUDE.md files<br/>Project instructions"]
        DATE["Current date"]
    end
    subgraph SystemContext["System Context"]
        GIT_STATUS["Git snapshot<br/>Branch, status, log"]
    end
    subgraph Compaction["Compaction Pipeline"]
        SNIP["Snip compact"]
        MICRO["Micro compact"]
        AUTO["Auto compact"]
        COLLAPSE["Context collapse"]
    end
    SystemPrompt --> FINAL["Final API request"]:::api
    UserContext --> FINAL
    SystemContext --> FINAL
    Compaction --> FINAL
    classDef api fill:#1b3a1b,stroke:#28a745,color:#e0e0e0,stroke-width:2px
 ```
 ### Phase 3: API Call and Streaming
 The request goes through `claude.ts` with retry logic:
 ```mermaid
 %%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#1a1a2e', 'primaryTextColor': '#e0e0e0', 'lineColor': '#28a745', 'primaryBorderColor': '#28a745'}}}%%
 flowchart LR
    REQ["API Request<br/>messages + system + tools"]:::req
    STREAM["SSE Stream"]:::stream
    subgraph Events["Stream Events in Order"]
        E1["message_start<br/>model, id, usage"]
        E2["content_block_start<br/>type + index"]
        E3["content_block_delta<br/>incremental text/tool JSON"]
        E4["content_block_stop"]
        E5["message_delta<br/>stop_reason + final usage"]
        E6["message_stop"]
    end
    REQ --> STREAM --> Events
    classDef req fill:#1a2d4a,stroke:#4a9eff,color:#e0e0e0,stroke-width:2px
    classDef stream fill:#1b3a1b,stroke:#28a745,color:#e0e0e0,stroke-width:2px
 ```
 Each content block is one of three types: **thinking** (internal reasoning), **text** (user-facing response), or **tool_use** (triggers tool execution).
 ### Phase 4: Tool Execution Loop
 When the model responds with `tool_use`, the agentic loop kicks in:
 ```mermaid
 %%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#1a1a2e', 'primaryTextColor': '#e0e0e0', 'lineColor': '#e83e8c', 'primaryBorderColor': '#e83e8c'}}}%%
 flowchart TD
    TOOL_USE["Model returns tool_use blocks"]:::start
    PAR{"Multiple tools?<br/>isConcurrencySafe?"}:::check
    PARALLEL["Execute in parallel<br/>Read-only tools"]:::exec
    SEQUENTIAL["Execute sequentially<br/>Write tools"]:::exec
    VALIDATE["Zod schema validation"]:::step
    HOOKS_PRE["PreToolUse hooks"]:::step
    PERM_CHECK["Permission check chain<br/>deny - allow - tool -<br/>hooks - classifier - dialog"]:::step
    EXECUTE["tool.call(input, context)"]:::step
    HOOKS_POST["PostToolUse hooks"]:::step
    MAP_RESULT["Map to tool_result message"]:::step
    INJECT["Inject CLAUDE.md attachments<br/>for newly-discovered dirs"]:::step
    PUSH["Push tool_results to messages<br/>Continue loop"]:::feedback
    TOOL_USE --> PAR
    PAR -->|"yes"| PARALLEL
    PAR -->|"no"| SEQUENTIAL
    PARALLEL --> VALIDATE
    SEQUENTIAL --> VALIDATE
    VALIDATE --> HOOKS_PRE --> PERM_CHECK --> EXECUTE --> HOOKS_POST --> MAP_RESULT --> INJECT --> PUSH
    PUSH ==>|"Back to<br/>compaction"| TOOL_USE
    classDef start fill:#1a2d4a,stroke:#4a9eff,color:#e0e0e0,stroke-width:2px
    classDef check fill:#2d2d0d,stroke:#ffc107,color:#e0e0e0,stroke-width:2px
    classDef exec fill:#0d4f4f,stroke:#17a2b8,color:#e0e0e0,stroke-width:2px
    classDef step fill:#1b3a1b,stroke:#28a745,color:#e0e0e0,stroke-width:2px
    classDef feedback fill:#4a1a1a,stroke:#dc3545,color:#e0e0e0,stroke-width:3px
 ```
 The loop continues until the model returns `stop_reason: end_turn`, hits `max_turns`, or is cancelled.
 ### Phase 5: Response Rendering
 The final response is rendered and persisted:
 ```mermaid
 %%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#1a1a2e', 'primaryTextColor': '#e0e0e0', 'lineColor': '#fd7e14', 'primaryBorderColor': '#fd7e14'}}}%%
 flowchart LR
    RESPONSE["Model final response<br/>stop_reason: end_turn"]:::input
    subgraph Rendering["Terminal Rendering"]
        MD["Markdown rendering<br/>via marked library"]
        SYNTAX["Syntax highlighting<br/>for code blocks"]
        DIFF["Diff rendering<br/>for file changes"]
    end
    subgraph Persistence["Persistence"]
        TRANSCRIPT["recordTranscript<br/>Persist to disk"]
        USAGE["Accumulate usage<br/>input + output tokens"]
        COST["Track cost<br/>per-model pricing"]
    end
    subgraph SDK_Events["SDK Events"]
        MSG["SDKMessage stream<br/>Normalized events"]
        RESULT_E["Result event<br/>total_cost, usage, duration"]
    end
    RESPONSE --> Rendering
    RESPONSE --> Persistence
    RESPONSE --> SDK_Events
    classDef input fill:#1a2d4a,stroke:#4a9eff,color:#e0e0e0,stroke-width:2px
 ```
 ---
 ## A Concrete Example
 Let's trace what happens when a user types: `fix the bug in utils.ts`
 ```mermaid
 %%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#1a1a2e', 'primaryTextColor': '#e0e0e0', 'lineColor': '#4a9eff', 'actorTextColor': '#e0e0e0', 'actorBorder': '#4a9eff', 'signalColor': '#4a9eff', 'noteBkgColor': '#16213e', 'noteTextColor': '#e0e0e0', 'activationBkgColor': '#2d1b4e', 'activationBorderColor': '#e83e8c'}}}%%
 sequenceDiagram
    participant U as User
    participant R as REPL.tsx
    participant QE as QueryEngine
    participant Q as query.ts
    participant C as claude.ts
    participant T as Tools
    U->>R: Types "fix the bug in utils.ts"
    R->>QE: submitMessage(prompt)
    Note over QE: Not a slash command, proceed
    QE->>QE: Persist transcript
    QE->>Q: query(messages, systemPrompt, tools)
    Note over Q: Turn 1 - Model reads code
    Q->>Q: Run compaction pipeline
    Q->>C: queryModel(messages)
    C-->>Q: tool_use: FileRead("utils.ts")
    Q->>T: Execute FileRead
    T-->>Q: File contents
    Note over Q: Turn 2 - Model analyzes
    Q->>C: queryModel(messages + file contents)
    C-->>Q: tool_use: Grep("error pattern")
    Q->>T: Execute Grep
    T-->>Q: Search results
    Note over Q: Turn 3 - Model fixes
    Q->>C: queryModel(messages + grep results)
    C-->>Q: tool_use: FileEdit("utils.ts", patch)
    Note over T: Permission check!
    T->>U: Allow FileEdit? (Y/n/always)
    U->>T: Y
    T-->>Q: Edit applied
    Note over Q: Turn 4 - Model confirms
    Q->>C: queryModel(messages + edit result)
    C-->>Q: text: "Fixed the bug" + end_turn
    Q-->>QE: Terminal result
    QE->>QE: Record transcript, track usage
    QE-->>R: Render response
    R->>U: Display formatted answer
 ```
 This shows the typical pattern: **read first, analyze, then write** -- with permission checks only on the write operation.
 ---
 ## Key Takeaways
 1. **Multiple entry points, single pipeline**: Whether input comes from keyboard, IDE, or SDK, it all converges into the same `processUserInput -> query -> claude.ts` pipeline.
 2. **Compaction runs every turn**: The 5-stage compaction pipeline runs *before every single API call*, not just when limits are hit.
 3. **Tools loop back**: Tool results are pushed to messages, and the entire pipeline (including compaction) runs again. This is the "agentic" part -- the model keeps going until it's done.
 4. **Permissions only interrupt writes**: Read-only tools (FileRead, Grep, Glob) in default mode flow through silently. Only write operations (FileEdit, Bash, FileWrite) trigger permission dialogs.
 5. **Everything is streamed**: From SSE events to async generators to React state updates, nothing blocks waiting for a full response. The user sees tokens as they arrive.
 ---
 **Previous:** [<- MCP Deep Dive](./11-mcp-deep-dive.md)
--- a/learn/README.md
+++ b/learn/README.md
@ -0,0 +1,160 @@
 # Learn Claude Code Architecture
 > A deep-dive educational guide into the internal architecture of Anthropic's Claude Code CLI — the agentic coding assistant that leaked via a `.map` file in March 2026.
 **Internal Codename:** Tengu  
 **Runtime:** Bun  
 **UI Framework:** React + Ink (React for CLI)  
 **Language:** TypeScript (strict)  
 **Scale:** ~1,900 files, 512,000+ lines of code
 ---
 ## Why This Guide Exists
 Claude Code is one of the most sophisticated agentic AI systems ever built. Its architecture contains lessons in:
 - **Agentic loop design** — How to build a multi-turn, tool-calling AI agent
 - **Terminal UI at scale** — 113 React components running in a terminal
 - **Permission systems** — Layered security for autonomous code execution
 - **Context management** — Keeping conversations within token limits
 - **Extension architectures** — Plugins, skills, hooks, and sub-agents
 Whether you're building your own AI agent, contributing to open-source AI tools, or just curious about how the sausage is made — this guide is for you.
 ---
 ## Guide Structure
 Start from the top and work down, or jump to whatever interests you:
 | # | Guide | What You'll Learn |
 |---|-------|-------------------|
 | 1 | [System Overview](./01-system-overview.md) | Bird's-eye view of every layer — entries, UI, core engine, tools, state |
 | 2 | [The Agentic Loop](./02-agentic-loop.md) | How `query.ts` drives the model → tool → model cycle |
 | 3 | [Tool System](./03-tool-system.md) | How 42 built-in tools are defined, validated, and executed |
 | 4 | [Permission System](./04-permission-system.md) | Deny rules, allow rules, hooks, classifier, user prompts |
 | 5 | [Context Management](./05-context-management.md) | Snip, micro, auto, reactive compact — the full pipeline |
 | 6 | [State Management](./06-state-management.md) | AppState store, immutability, and reactive side effects |
 | 7 | [Extension Model](./07-extension-model.md) | Skills, plugins, hooks, sub-agents, and swarms |
 | 8 | [API Client](./08-api-client.md) | `claude.ts` — streaming, retries, caching, and model fallback |
 | 9 | [UI Architecture](./09-ui-architecture.md) | React Ink, 113 components, and the 896KB REPL |
 | 10 | [Configuration and System Prompt](./10-configuration-and-system-prompt.md) | Settings hierarchy, CLAUDE.md discovery, prompt assembly |
 | 11 | [MCP Deep Dive](./11-mcp-deep-dive.md) | Transports, tool wrapping, auth, server lifecycle |
 | 12 | [Data Flow Walkthrough](./12-data-flow-walkthrough.md) | End-to-end trace of a single user request |
 ---
 ## Key Files Quick Reference
 | File | Size | Role |
 |------|------|------|
 | `src/main.tsx` | 804KB | CLI entrypoint — Commander.js parser + React/Ink bootstrap |
 | `src/screens/REPL.tsx` | 896KB | Interactive terminal shell — the heart of the UI |
 | `src/query.ts` | 1,730 lines | The agentic loop — model ↔ tool cycling |
 | `src/QueryEngine.ts` | 1,296 lines | Session lifecycle owner — wraps `query()` |
 | `src/Tool.ts` | 793 lines | Tool interface definition — every tool implements this |
 | `src/commands.ts` | ~25K | Slash command registry |
 | `src/state/AppStateStore.ts` | 570 lines | Immutable store with 50+ fields |
 | `src/services/compact/` | 11 files | The entire compaction pipeline |
 ---
 ## Architecture At A Glance
 ```mermaid
 %%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#1a1a2e', 'primaryTextColor': '#e0e0e0', 'primaryBorderColor': '#4a9eff', 'lineColor': '#4a9eff', 'secondaryColor': '#16213e', 'tertiaryColor': '#0f3460', 'edgeLabelBackground': '#1a1a2e'}}}%%
 graph TB
    CLI["CLI Entry<br/>main.tsx — 804KB"]:::entry
    SDK["SDK Entry<br/>Programmatic API"]:::entry
    MCP_S["MCP Server<br/>Expose as MCP"]:::entry
    REPL["REPL.tsx — 896KB<br/>Interactive Terminal Shell"]:::ui
    Comps["113 Components<br/>Messages, Diffs, Dialogs"]:::ui
    Hooks["83 React Hooks<br/>Permissions, Input, IDE"]:::ui
    QE["QueryEngine.ts<br/>Session Lifecycle Owner"]:::core
    QL["query.ts — 1730 lines<br/>Agentic Loop"]:::core
    CL["claude.ts — 3420 lines<br/>Anthropic API Client"]:::core
    TD["Tool Interface<br/>Tool.ts"]:::tool
    BT["42 Built-in Tools"]:::tool
    MT["MCP Tools — dynamic"]:::tool
    TO["Tool Orchestration<br/>Parallel Execution"]:::tool
    Compact["Compaction Pipeline<br/>snip / micro / auto /<br/>reactive / collapse"]:::ctx
    Rules["Allow + Deny Rules"]:::perm
    HK["PreToolUse Hooks"]:::perm
    Classifier["Auto-mode Classifier"]:::perm
    AS["AppState Store<br/>Immutable — 50+ fields"]:::state
    SS["Session Storage<br/>Transcripts + Resume"]:::state
    Cfg["Config Layer<br/>Global / Project / CLAUDE.md"]:::state
    Skills["Skills"]:::ext
    Plugins["Plugins"]:::ext
    Agents["Sub-agents + Swarms"]:::ext
    API["Anthropic Messages API"]:::external
    MCP_Ext["External MCP Servers"]:::external
    GrowthBook["GrowthBook + Statsig"]:::external
    CLI --> REPL
    SDK --> QE
    MCP_S --> QE
    REPL --> Comps
    REPL --> Hooks
    REPL --> QE
    REPL --> AS
    QE --> QL
    QL --> CL
    QL --> Compact
    QL --> TO
    CL --> API
    CL --> GrowthBook
    TO --> TD
    TD --> BT
    TD --> MT
    BT --> Rules
    BT --> HK
    MT --> Rules
    Rules --> Classifier
    QE --> SS
    REPL --> Cfg
    Skills --> TD
    Plugins --> TD
    Plugins --> MCP_Ext
    Agents --> QL
    MCP_Ext --> MT
    classDef entry fill:#0d4f4f,stroke:#17a2b8,color:#e0e0e0,stroke-width:2px
    classDef ui fill:#1a1a4e,stroke:#6f42c1,color:#e0e0e0,stroke-width:2px
    classDef core fill:#2d1b4e,stroke:#e83e8c,color:#e0e0e0,stroke-width:2px
    classDef tool fill:#1b3a1b,stroke:#28a745,color:#e0e0e0,stroke-width:2px
    classDef ctx fill:#3d2b00,stroke:#fd7e14,color:#e0e0e0,stroke-width:2px
    classDef perm fill:#4a1a1a,stroke:#dc3545,color:#e0e0e0,stroke-width:2px
    classDef state fill:#1a2d4a,stroke:#4a9eff,color:#e0e0e0,stroke-width:2px
    classDef ext fill:#2d2d0d,stroke:#ffc107,color:#e0e0e0,stroke-width:2px
    classDef external fill:#333,stroke:#888,color:#aaa,stroke-width:1px,stroke-dasharray: 5 5
 ```
 ---
 ## Prerequisites
 To get the most out of these guides, you should be comfortable with:
 - **TypeScript** — The entire codebase is strict TypeScript
 - **React** — The UI uses React (via Ink for the terminal)
 - **Async generators** — The agentic loop and streaming are built on `async function*`
 - **LLM APIs** — Familiarity with the Anthropic Messages API helps
 ---