Agent Design Space — Six Decisions

## Full reference: the six design decisions

This pack is the architect's framework. Every production coding agent must answer the six questions below. Claude Code is one set of answers. LangGraph, Devin, SWE-Agent, OpenHands, and Aider are alternative answers. Your system is another — but your answers must be explicit, or you will discover them by outage.

Derived from VILA-Lab/Dive-into-Claude-Code build-your-own-agent.md (CC-BY-NC-SA-4.0, arXiv 2604.14228). Paraphrased with citation; specific numbers and layer counts are quoted from the paper.

### Decision 1: Where does reasoning live?

**The question:** How much decision-making is in the model vs. in your harness code?

| Approach | Example | Trade-off |
|---|---|---|
| Minimal scaffolding | Claude Code (~1.6% AI logic, 98.4% infrastructure) | Model has maximum latitude; harness enforces boundaries. Bets on model capability improving over time. |
| Explicit state graphs | LangGraph | Developer controls flow; easier to debug and predict. Constrains the model and requires updating as capabilities improve. |
| Heavy planning scaffolding | Devin | Multi-step planners + task trackers. More reliable for complex workflows; the scaffolding itself becomes maintenance burden. |

**Key insight (paper):** As frontier models converge in capability (top 3 within 1% on SWE-bench), the *operational harness* becomes the differentiator, not the model or the scaffolding. Investing in deterministic infrastructure (context management, safety, recovery) may yield greater reliability than adding planning constraints.

**Questions to ask yourself:**
- How capable is the model you're targeting? More capable models need less scaffolding.
- How predictable must your workflows be? Regulated domains may need explicit graphs.
- How fast is model capability improving? Heavy scaffolding becomes tech debt if models outgrow it.

### Decision 2: What is your safety posture?

**The question:** How do you prevent the agent from doing harmful things?

| Approach | Example | Trade-off |
|---|---|---|
| Deny-first with layered enforcement | Claude Code (7 independent layers) | Very safe; can create approval fatigue (93% of prompts approved without review). Requires graduated trust mechanisms. |
| Container isolation | SWE-Agent, OpenHands (Docker) | Strong boundary, coarse-grained. Everything inside container is allowed; nothing outside reachable. |
| VCS rollback | Aider (git-based) | Lightweight; only protects against file changes. Doesn't prevent network requests, data exfiltration, or shell side effects. |
| Approval-only | Basic chatbots | Simple; behaviorally unreliable at scale. Users stop reading prompts. |

**Key insight (paper):** Defense-in-depth only works when safety layers have *independent failure modes*. Claude Code's layers share an economic constraint (token costs) — commands exceeding 50 subcommands bypass security analysis entirely because per-subcommand parsing would starve the event loop. Design your layers to fail independently.

**On approval fatigue:** Users approve 93% of permission prompts. The fix is not more warnings but restructured boundaries — sandboxing and classifiers that create safe zones for autonomous operation.

**Questions to ask yourself:**
- What is the worst thing your agent could do? (Delete production data? Send emails? Exfiltrate code?)
- Can sandboxing reduce the number of decisions users must make?
- Do your safety layers share failure modes (e.g., all depend on token budget)?

### Decision 3: How do you manage context?

**The question:** The context window is finite. How do you decide what the model sees?

| Approach | Example | Trade-off |
|---|---|---|
| Graduated compaction pipeline | Claude Code (5 layers) | Preserves most information for longest time. Complex to implement and debug. Compression invisible to users. |
| Simple truncation | Many basic agents | Easy. Loses potentially critical early context. |
| Sliding window | Some chat apps | Predictable. No semantic awareness of what matters. |
| RAG (retrieval-augmented) | Some IDE integrations | Can access entire codebase. Retrieval quality is a bottleneck, chunks may lack surrounding context. |
| Single summarization | Some agents | One summary pass. A single compression can lose critical details. |

**Key insight (paper):** Context is the *binding constraint* that shapes nearly every other architectural decision. Lazy loading, deferred tool schemas, summary-only subagent returns, and per-tool-result budgets all exist because context is scarce. Design for context scarcity from day one.

**The graduated approach:** Apply the least disruptive compression first. Budget Reduction (cheap) → History trim / Snip (cheap) → Microcompact (cache-aware, medium) → Context Collapse (virtual projection, medium) → Auto-Compact (full model summary, expensive last resort).

**Questions to ask yourself:**
- What is your context window size? This determines how aggressive your compression needs to be.
- Do you need to support long sessions (hours of work)? Single-pass truncation won't survive.
- Can you separate 'guidance' context (instructions) from 'working' context (conversation)?

**Warning:** Answering Decision 3 without a measured token-budget ceiling is guessing. Pair with `nine-context-sources` for the order, `turn-execution-pipeline` for where the shapers run.

### Decision 4: How do you handle extensibility?

**The question:** How do external tools, custom instructions, and user customizations plug into your system?

| Approach | Example | Trade-off |
|---|---|---|
| Graduated context-cost mechanisms | Claude Code (hooks=0, skills=low, plugins=medium, MCP=high) | Different extensions at different costs. Complex to manage; scales. |
| Single unified API | Many tool-use frameworks | Simple. Every extension consumes context, limiting scalability. |
| Plugin marketplace (monoculture) | IDE extensions | Rich ecosystem potential. Quality control and security review become bottlenecks. |

**Key insight (paper):** Not all extensions need to consume context tokens. Hooks (zero cost) handle lifecycle events without touching the context window. Skills (low cost) inject only when relevant. Reserve high-context-cost mechanisms (MCP) for genuinely new tool surfaces.

**The three injection points:** Every agent loop has three places where extensions can intervene:
1. **assemble()** — what the model sees (instructions, tool schemas).
2. **model()** — what the model can reach (available tools).
3. **execute()** — whether/how an action runs (permission gates, pre/post hooks).

**Questions to ask yourself:**
- How many tools will your agent need to support? More tools = more context pressure.
- Do you need third-party extensions? Plan for security and quality control (see `cve-pre-trust-window`).
- Can you defer tool schema loading until the model actually needs the tool?

### Decision 5: How do subagents work?

**The question:** When the agent spawns sub-tasks, do they share context or run in isolation?

| Approach | Example | Trade-off |
|---|---|---|
| Isolated context + summary return | Claude Code (sidechain transcripts) | Prevents context explosion (~7× token cost). Subagents can't share fine-grained state. |
| Shared context | Some multi-agent frameworks | Full information sharing. Context fills up fast with N agents. |
| Message passing | Actor-model systems | Clean boundaries. Requires explicit protocol design. |

**Key insight (paper):** Subagent sessions cost ~7× the tokens of standard sessions. In Claude Code, only summaries return to the parent — full history never enters the parent context. This is essential for context conservation.

**SkillTool vs AgentTool (the knob you will get wrong first):** SkillTool injects instructions into the current context (cheap, same window). AgentTool spawns a new isolated context window (expensive, ~7× tokens, context-safe). Reach for SkillTool for small deterministic behaviors; AgentTool only when the subagent genuinely needs its own context.

**Questions to ask yourself:**
- Do your sub-tasks need to see each other's work?
- How do you prevent N subagents from consuming N × context-window tokens?
- Do subagents inherit parent permissions, or establish their own?

### Decision 6: How do sessions persist?

**The question:** What happens when a session ends? What carries over?

| Approach | Example | Trade-off |
|---|---|---|
| Append-only JSONL | Claude Code | Auditable, reconstructable, simple. Poor query power. |
| Database | Some enterprise agents | Rich queries, fast lookups. Adds infrastructure dependency, reduces transparency. |
| Stateless | Most chat APIs | Simplest. No resume, no fork, no audit trail. |

**Key insight (paper):** **Never restore permissions on resume.** Trust is always re-established in the current session. Security state should not persist implicitly across session boundaries.

**On auditability:** Append-only JSONL means every event is human-readable, version-controllable, and reconstructable without specialized tooling. The slight loss in query power is worth the transparency.

**Questions to ask yourself:**
- Can your sessions be paused and resumed? If yes, what MUST not carry over (permissions, secrets, classifier state)?
- Do you need to diff two sessions to debug a regression? JSONL is greppable; a DB requires a query.
- Who reads the transcript? If the answer is 'only the system,' a DB is fine. If it's 'a human on call,' JSONL wins.

## The Meta-Pattern: three recurring design commitments

Across all six decisions, three patterns recur in Claude Code's architecture. Staff engineers rebuilding Claude Code almost always miss these. If you are copying Claude Code's answers without these three commitments, you are copying the shape without the spine.

1. **Graduated layering over monolithic mechanisms** — safety, context, and extensibility all use *stacked independent stages* rather than single solutions. Seven safety layers, five compaction shapers, four extension mechanisms. Layers fail independently; monoliths fail all at once.

2. **Append-only designs favoring auditability over query power** — session transcripts, prompt history, subagent sidechains, file-history checkpoints: all append-only. Nothing is destructively edited. You trade query power for reconstructability and transparency. Agents amplify every bug, so 'what happened' must be recoverable from disk without a specialized tool.

3. **Model judgment within a deterministic harness** — the model decides freely; the harness enforces boundaries. The 1.6% / 98.4% ratio is not accidental. If you find yourself writing a planning graph to constrain the model, ask whether a deterministic harness enforcing post-conditions would do the same job without fighting the model.

## How to use this pack in practice

1. At the top of the architecture doc, write one paragraph per decision.
2. Link each paragraph to the pack that implements your answer.
3. Explicitly name the Meta-Pattern commitments you accept or decline. Declining is fine; silently declining is not.
4. In PR review, any change that touches one of the six decisions must update the paragraph. Mid-sprint drift is the number-one cause of 'we agreed on X but shipped Y'.
5. Cite this pack in your PR description when you argue for an answer.

## When 'rebuild Claude Code' comes up

A staff engineer proposes rebuilding Claude Code. Route the conversation through the Meta-Pattern first. Ask:
- Will you commit to graduated layering everywhere? (If not, defense-in-depth will degrade.)
- Will you commit to append-only everywhere? (If not, your audit trail is a lie.)
- Will the harness be deterministic around a freely-judging model? (If not, you are building a state graph, not a harness.)

If the team rejects any of the three, the answer is usually 'build something else.' Most 'rebuild Claude Code' attempts miss at least one of the three commitments and ship a product that looks like Claude Code but doesn't survive contact with users.

Sourced from VILA-Lab/Dive-into-Claude-Code (CC-BY-NC-SA-4.0, arXiv 2604.14228). The six decisions and the Meta-Pattern are paraphrased with citation; percentages and layer counts quoted from build-your-own-agent.md.