Claude Code Harness

flowchart TD
  U["User"] -->|"prompt"| S["Surface Layer"]
  S -->|"assembled context"| AL["Agent Loop"]
  AL -->|"tool request"| SA["Safety and Action Layer"]
  SA -->|"approved action"| BE["Backend Execution"]
  BE -->|"tool result"| SL["State Layer"]
  SL -->|"updated context"| AL
  AL -->|"final reply"| S
  S -->|"response"| U

  subgraph SurfaceLayer["Surface Layer"]
    S
  end
  subgraph Core["Core Layer"]
    AL
  end
  subgraph Safety["Safety and Action Layer"]
    SA
  end
  subgraph State["State Layer"]
    SL
  end
  subgraph Backend["Backend Execution"]
    BE
  end
        

flowchart TD
  START(["Session Start"]) --> INIT["Init State"]
  INIT --> CTXASSEMBLE["Assemble Context"]
  CTXASSEMBLE --> COMPACT["Compaction Pass"]
  COMPACT --> INVOKE["Invoke Model API"]
  INVOKE -->|"streaming chunks"| STREAM["Stream Parser"]
  STREAM -->|"text only"| REPLY["Emit Reply"]
  REPLY --> DONE(["Loop End"])
  STREAM -->|"tool-use block"| PREHOOK["PreToolUse Hooks"]
  PREHOOK -->|"blocked"| INJECT["Inject Block Feedback"]
  INJECT --> CTXASSEMBLE
  PREHOOK -->|"allowed"| PERMCHECK["Permission Check"]
  PERMCHECK -->|"denied"| ASK{"Ask User?"}
  ASK -->|"no"| INJECT
  ASK -->|"yes"| EXEC["Execute Tool"]
  PERMCHECK -->|"approved"| EXEC
  EXEC --> POSTHOOK["PostToolUse Hooks"]
  POSTHOOK --> RESULT["Append Tool Result"]
  RESULT --> STOPCHECK{"Stop Condition?"}
  STOPCHECK -->|"no"| CTXASSEMBLE
  STOPCHECK -->|"yes - max turns"| DONE
  STOPCHECK -->|"yes - context full"| AUTOCOMPACT["Auto-Compact"]
  AUTOCOMPACT --> CTXASSEMBLE
        

flowchart LR
  MODEL["Claude Model"] -->|"tool-use block"| ROUTER["Tool Router"]

  ROUTER --> BUILTIN["Built-in Tools"]
  ROUTER --> MCP["MCP Server Tools"]
  ROUTER --> AGENT["Subagent Tool"]

  BUILTIN --> FIO["File I/O"]
  BUILTIN --> SHELL["Shell Exec"]
  BUILTIN --> GIT["Git Ops"]
  BUILTIN --> SEARCH["Search and Web"]
  BUILTIN --> NB["Notebook Edit"]
  BUILTIN --> TASK["Task and Memory"]

  MCP -->|"stdio or HTTP"| MSERVER["External MCP Server"]

  AGENT -->|"fork or worktree"| SUB["Subagent Loop"]

  FIO --> PERM["Permission Gate"]
  SHELL --> PERM
  GIT --> PERM
  SEARCH --> PERM
  NB --> PERM
  TASK --> PERM
  MSERVER --> PERM

  PERM -->|"approved"| EXEC["Execute"]
  PERM -->|"denied"| BLOCK["Block"]
        

flowchart TD
  REQ["Tool Request"] --> PREFILTER["Layer 1: Pre-filter"]
  PREFILTER -->|"tool not denied"| DENY1["Layer 2: Deny Rules"]
  PREFILTER -->|"globally denied"| BLOCKED(["Blocked"])
  DENY1 -->|"no deny match"| MODE["Layer 3: Permission Mode"]
  DENY1 -->|"deny matches"| BLOCKED
  MODE --> TIER{"Tier?"}
  TIER -->|"Tier 1 - safe"| AUTOAPPROVE(["Auto-approved"])
  TIER -->|"Tier 2 - modify"| CLASSIFIER["Layer 4: ML Classifier"]
  TIER -->|"Tier 3 - risky"| BLOCKED
  CLASSIFIER -->|"predicted safe"| SANDBOX["Layer 5: Shell Sandbox"]
  CLASSIFIER -->|"predicted risky"| ASK["Ask User"]
  ASK -->|"approved"| SANDBOX
  ASK -->|"denied"| BLOCKED
  SANDBOX -->|"passes"| HOOKCHECK["Layer 6: Hook Intercept"]
  SANDBOX -->|"fails"| BLOCKED
  HOOKCHECK -->|"allowed"| EXEC(["Execute"])
  HOOKCHECK -->|"blocked by hook"| BLOCKED
        

flowchart LR
  CONV["Conversation History"] --> B1["Stage 1: Budget Reduction"]
  B1 -->|"trim large tool outputs"| B2["Stage 2: Snip"]
  B2 -->|"drop old history blocks"| B3["Stage 3: Microcompact"]
  B3 -->|"fine-grained compress"| B4["Stage 4: Context Collapse"]
  B4 -->|"read-time projection"| B5["Stage 5: Auto-Compact"]
  B5 -->|"model-generated summary"| FIT{"Fits in window?"}
  FIT -->|"yes"| CALL["Model Call"]
  FIT -->|"no"| ERR["Error - stop loop"]

  B1 -.->|"enforce per-message size cap"| B1
  B3 -.->|"cache-aware compression"| B3
        

flowchart TD
  DISK["Disk-Based Memory"] --> L1["Managed Settings"]
  DISK --> L2["CLAUDE.md Files"]
  DISK --> L3["MEMORY.md Index"]
  DISK --> L4["Session JSONL"]
  DISK --> L5["Sidechain Transcripts"]

  L2 --> L2A["Repo root CLAUDE.md"]
  L2 --> L2B["Subdirectory CLAUDE.md"]
  L2 --> L2C["Auto-memory entries"]
  L2 --> L2D["Lazy nested rules"]

  L3 --> L3A["Topic files on-demand"]
  L3A -->|"loaded when relevant"| CTX["Context Assembly"]

  L4 --> L4A["Append-only turns"]
  L4A -->|"resume or fork"| CTX

  L1 --> CTX
  L2 --> CTX
  L3 --> CTX
        

flowchart LR
  SESSION_START(["SessionStart"]) --> PROMPT_SUBMIT["UserPromptSubmit"]
  PROMPT_SUBMIT --> PROMPT_EXPAND["UserPromptExpansion"]
  PROMPT_EXPAND --> INSTR_LOAD["InstructionsLoaded"]
  INSTR_LOAD --> PRE["PreToolUse"]
  PRE -->|"exit 0 - allow"| PERM["PermissionRequest"]
  PRE -->|"exit 2 - block"| FEEDBACK["Inject Feedback"]
  PERM -->|"granted"| EXEC_TOOL["Tool Execution"]
  PERM -->|"denied"| PERM_DENIED["PermissionDenied"]
  EXEC_TOOL -->|"success"| POST["PostToolUse"]
  EXEC_TOOL -->|"fail"| POST_FAIL["PostToolUseFailure"]
  POST --> BATCH["PostToolBatch"]
  POST_FAIL --> BATCH
  BATCH --> NOTIFY["Notification"]
  NOTIFY --> STOP_CHECK{"Stop?"}
  STOP_CHECK -->|"continue"| PRE
  STOP_CHECK -->|"done"| STOP_EV["Stop"]
  STOP_EV --> SESSION_END(["SessionEnd"])
  STOP_CHECK -->|"error"| STOP_FAIL["StopFailure"]
        

flowchart TD
  PARENT["Parent Agent Loop"] -->|"AgentTool call"| SPAWN{"Spawn Mode"}
  SPAWN -->|"Fork"| FORK["Fork Subagent"]
  SPAWN -->|"Worktree"| WT["Worktree Subagent"]
  SPAWN -->|"Teammate"| TM["Teammate Subagent"]

  FORK --> FLOOP["Isolated queryLoop"]
  WT --> WLOOP["Isolated queryLoop"]
  TM --> TLOOP["Isolated queryLoop"]

  FLOOP -->|"inherits parent system prompt"| CACHE["Shared Prompt Cache"]
  WLOOP -->|"overlay filesystem"| OVERLAY["Isolated File Overlay"]
  TLOOP -->|"collaborative channel"| SHARED["Shared Scratchpad"]

  FLOOP -->|"summary text only"| PARENT
  WLOOP -->|"summary + overlay diff"| PARENT
  TLOOP -->|"summary + escalations"| PARENT

  FLOOP --> SCHAIN1["Sidechain JSONL"]
  WLOOP --> SCHAIN2["Sidechain JSONL"]
  TLOOP --> SCHAIN3["Sidechain JSONL"]

  PARENT -->|"permission bubble"| USER["User Terminal"]