Turn Execution Pipeline

## Full reference: the 9-step pipeline

### 1. Anchor statistic — why this pack exists

The VILA-Lab Dive-into-Claude-Code paper (arXiv 2604.14228) analyzed Claude Code's source and concluded: **~1.6% AI decision logic, ~98.4% deterministic infrastructure**. The "loop" — the while-true-call-model-call-tools shape — is trivial. The harness around it is what resists re-implementation. This pack names the harness explicitly so you can clone it, audit it, or argue about it with a shared vocabulary.

The paper further identifies three recurring design commitments that this pipeline instantiates:

1. **Graduated layering over monolithic mechanisms** — the 5 shapers are explicitly cheapest-first, not a single "smart" compactor.
2. **Append-only designs favoring auditability over query power** — the transcript is the source of truth; you can replay a turn from its record without needing a live DB.
3. **Model judgment within a deterministic harness** — the model gets to pick tools, words, and reasoning; the harness decides whether the call is allowed, how much budget is left, and when to stop.

### 2. The 9 steps (architecture.md §Turn Execution 9-Step Pipeline)

1. **Settings resolution** — merge the 4-level CLAUDE.md hierarchy (managed at /etc/claude-code, user at ~/.claude, project at repo root, local at CLAUDE.local.md) with .claude/settings.json. Do this once per turn even if the files have not changed; hot-reload on file mtime is an acceptable optimization but the merge must be pure.
2. **State initialization** — turn-local caches, shaper-invocation log, retry counter, reactive-compaction-fired flag. This state is deliberately scoped to the turn; nothing in here survives to the next turn except via the transcript.
3. **Context assembly** — pull from the 9 ordered context sources (see the nine-context-sources pack for the exact order). Do not reorder.
4. **Five pre-model shapers** — run sequentially, cheapest-first. Described in detail below.
5. **Model call** — single Anthropic Messages API call (or equivalent). Streamed.
6. **Tool dispatch** — parse tool_use blocks from the assistant message; one dispatch per block.
7. **Permission gate** — each tool call goes through the 4-stage authorization pipeline (see seven-safety-layers pack).
8. **Tool execution** — the tool actually runs. Hooks fire here too (PostToolUse).
9. **Stop-condition check** — pure predicate over the transcript and budget. Done if no pending tool_use blocks, no unresolved tool_results, and under budget.

### 3. The 5 pre-model shapers (architecture.md §Five Pre-Model Context Shapers)

Order and triggers are not negotiable; re-ordering is the canonical anti-pattern.

| Stage | Strategy | Trigger | Cost class |
|---|---|---|---|
| Budget Reduction | Per-message size caps | Always active | O(n) string truncation |
| Snip | Trim older history | Feature-gated (HISTORY_SNIP) | O(n) slice |
| Microcompact | Cache-aware fine-grained compression | Always (time-based), optional cache-aware path | O(n) with cache lookup |
| Context Collapse | Read-time virtual projection (non-destructive) | Feature-gated (CONTEXT_COLLAPSE) | O(n) but preserves original |
| Auto-Compact | Full model-generated summary (last resort) | When all else fails | 1 extra model call — expensive |

Key properties:

- **Cheapest first**: if Budget Reduction alone brings you under budget, none of the later shapers run. This is the graduated-layering commitment applied to compaction.
- **Context Collapse is non-destructive**: the original messages are preserved; only the read-time projection is compressed. This matters when a later tool call needs the raw text.
- **Auto-Compact is a model call**: it costs tokens. Firing it on every turn defeats the point of the earlier shapers. If you see Auto-Compact in more than ~10% of turns, your earlier shapers are misconfigured.

### 4. Recovery mechanisms (architecture.md §Recovery Mechanisms)

Three layers of recovery, in order of how often they fire:

1. **Max output token escalation** — up to 3 retries per turn. If the model hits the max_tokens ceiling and produces a truncated assistant message, retry with an expanded ceiling. After 3 retries, surface a failure.
2. **Reactive compaction** — fires at most once per turn. When a model call fails with prompt-too-long and the overflow chain's collapse step did not free enough budget, compress via Auto-Compact and retry the model call.
3. **Prompt-too-long overflow chain** — the formal recovery path: try context-collapse overflow first (non-destructive, cheap), then reactive compaction (expensive but catches everything), then terminate. The terminate branch is not optional; a loop that retries forever on prompt-too-long is the way you lose $200 of Opus tokens before breakfast.

Additional recovery: **streaming fallback** (if streaming disconnects, switch to non-streaming for the retry) and **fallback model switching** (if a specific model ID returns a hard error, try the next in a configured chain). These are implementation choices more than architectural requirements.

### 5. Binding resource constraint: the 200K-token context window

The paper's fourth design question is "What is the binding resource constraint?" Claude Code's answer: the ~200K-token context window. Everything in the shaper chain and the recovery chain exists to keep the next model call under that ceiling. This is not a coincidence. If you are cloning the pipeline for a model with a different context ceiling, tune the shaper triggers accordingly — but do not remove the chain; the graduated layering is the point.

### 6. Stop-condition design

A pure predicate: given the current transcript and budget, return { done: boolean; reason: string }. Done iff:

1. The last assistant message contains no tool_use blocks.
2. No tool_result messages are outstanding (every tool_use has a matching tool_result).
3. budget.used < budget.max.

Make this a pure function. The single most common cause of runaway turns in clone implementations is a stop check that has side effects, reads live state, or depends on timing. If you cannot assert "running this function twice returns the same answer," your loop will sometimes get stuck.

### 7. Implementation cost split (from the paper's 98.4% stat)

A rough breakdown of engineering effort, back-computed from the paper's emphasis:

- Loop skeleton: ~2% of LoC.
- 5 shapers: ~20% of LoC, ~40% of the hard bugs.
- Recovery chain + retries: ~10% of LoC, ~30% of the hard bugs.
- Permission system + hooks: ~25% of LoC (see seven-safety-layers pack).
- Context assembly + CLAUDE.md hierarchy: ~15% of LoC (see nine-context-sources pack).
- Tool registry + MCP + plugins + skills: ~25% of LoC.

The model-specific prompt and tool schemas — the part everyone thinks is "the agent" — is the last 1-3%.

### 8. Cross-references to other packs

- **seven-safety-layers** documents step 7 (permission gate) in full.
- **nine-context-sources** documents step 3 (context assembly) in full.
- **claude-code-guide** is the operator's view; this pack is the implementer's view.
- **advisor-pattern-v2** runs inside this pipeline as a specialized loop shape.

### 9. Anti-patterns

1. **Running Auto-Compact first** because "it's the smart one." Budget Reduction alone handles most cases; Auto-Compact is a model call.
2. **Making the stop check stateful** — reading live budget from a counter that shapers mutate non-monotonically creates non-determinism.
3. **Unlimited retries on prompt-too-long** — terminate branch is not optional.
4. **Reactive compaction firing more than once per turn** — this is a hard cap in the design; relaxing it creates a recursion risk.
5. **Reordering shapers by "what feels heaviest"** — the order encodes cost, not urgency.
6. **Skipping hooks because they are slow** — PreToolUse hooks and PostToolUse hooks are part of the turn's side effects; dropping them changes semantics.

### 10. Proof of work

Run a turn trace on a real workload. Verify, in order: settings merged, 9 sources assembled, shaperLog names shapers cheapest-first, model call issued once (or retried up to 3 times with visible retries), tool dispatch count matches tool_use blocks, permission decision recorded per call, stop reason logged. If any of those are missing, the clone is incomplete.

### 11. License + attribution

This pack paraphrases and cites architecture content from VILA-Lab/Dive-into-Claude-Code (arXiv 2604.14228, CC-BY-NC-SA-4.0). Verbatim passages retained under the NC-SA terms; paraphrased summaries are original and credited per the non-commercial + share-alike constraint. Do not remove the attribution entry from `sources[]`.