$ Lessons for Builders

Practical takeaways from studying 1,902 TypeScript files of production agentic infrastructure. These are patterns worth stealing.

## Architecture Patterns Worth Stealing

How Claude Code stays debuggable at scale

Single-threaded loop for debuggability

No concurrent state mutations. Every tool call is sequential through the "nO" master loop. Makes debugging trivial and state predictable. When something breaks, the call stack tells the whole story.

Tool permission layering

Multiple layers: trust gate → deferred init → deny lists → per-tool safety checks. Defense in depth, not a single gate. Each layer is cheap to evaluate, and any one of them can block a dangerous operation.

Session compaction

When context fills up, compact instead of truncating. Preserves semantic meaning while reducing tokens. The agent can continue working on long tasks without losing critical context from early in the session.

Trust-gated init

Don't load dangerous capabilities until trust is verified. Tools literally don't exist in the pool until the gate passes. The LLM can't even hallucinate using a tool it hasn't been told about.

simplified master loop (codename 'nO')
while (session.active) {
  const userInput = await queryEngine.getInput();
  const toolCalls = await queryEngine.submit(userInput, {
    budget: session.remainingBudget,
    tools: toolPool.getAvailable(permissionContext),
  });

  for (const call of toolCalls) {
    // Sequential execution — no concurrency
    const result = await executionRegistry.route(call);
    session.transcript.append(result);
  }

  if (session.contextPressure > COMPACTION_THRESHOLD) {
    await session.compact(); // Preserve meaning, reduce tokens
  }
}

## Tool Design Patterns

How to give an LLM the right capabilities without the wrong ones

Tool abstraction: name + responsibility + source_hint

Each tool has a clean interface for the LLM to understand what it can do. The source_hint tells the model where results come from, improving grounding and reducing hallucination.

Permission deny lists

Both exact name matching and prefix-based blocking. Flexible enough for fine-grained control. You can deny 'FileWrite' exactly or deny everything starting with 'Dangerous' via prefix.

Simple mode fallback

When in doubt, restrict to BashTool + FileReadTool + FileEditTool. This minimum viable tool set covers 90% of coding tasks. Fewer tools means fewer opportunities for the model to pick the wrong one.

Deferred tool loading

Some tools are expensive to init (MCP connections, LSP servers). Load them lazily, only when trust allows. Startup stays fast, and unused tools never pay the init cost.

tool permission layering
// Layer 1: Trust gate — is the user trusted at all?
if (!trustContext.verified) return MINIMAL_TOOLS;

// Layer 2: Deferred init — load expensive tools now
await toolPool.loadDeferred(mcpConnections, lspServers);

// Layer 3: Deny lists — block specific tools
const filtered = toolPool.filter({
  denyNames: ["rm", "format", "drop"],
  denyPrefixes: ["Dangerous", "Internal"],
});

// Layer 4: Per-tool safety — tool-level checks
// BashTool: destructive command warnings + preapproved list
// FileWriteTool: path validation
// AgentTool: restricted sub-agent toolsets

## Multi-Agent Patterns

How Claude Code coordinates multiple AI workers

Built-in sub-agents by specialization

explore, plan, general, verification, claudeCodeGuide — each specialized for a task type. Specialization means smaller system prompts, focused tool sets, and better performance per task.

Agent memory snapshots

Agents can snapshot and restore memory, enabling context switching without losing work. Critical for multi-step workflows where the agent needs to come back to a previous state.

Fork vs Spawn

fork creates a child with shared context — good for subtasks that need parent's knowledge. spawn creates an independent agent — good for parallel work on separate concerns. Different tools for different coordination patterns.

Coordinator mode

One Claude orchestrating multiple worker Claudes with restricted toolsets and scratchpads. The coordinator sees summaries, not full transcripts. Hierarchical delegation with information compression.

fork vs spawn
// Fork: child inherits parent context
const child = await forkSubagent({
  parentContext: session.transcript,
  tools: parentTools.subset(["FileReadTool", "GrepTool", "GlobTool"]),
  task: "Find all uses of deprecated API",
});

// Spawn: independent agent, clean slate
const worker = await spawnMultiAgent({
  tools: ["BashTool", "FileEditTool"],
  scratchpad: new Scratchpad(),
  task: "Refactor auth module",
  reportTo: coordinator,
});

## What to Watch

Features that are built and waiting behind flags

near-ready

Background Agents (Kairos)

24/7 agents with GitHub webhooks, push notifications, PR monitoring. The biggest upcoming shift — agents that work while you sleep.

in progress

Voice Mode (Tengu)

Full push-to-talk with Deepgram Nova 3. Gemstone codenames for flags: tengu_cobalt_frost, tengu_amber_quartz.

near-ready

Coordinator Mode

Multi-agent orchestration at scale. One Claude spawning and managing workers with isolated tool sets.

built

Plugin Marketplace

Third-party extensions with discovery, installation, validation, and marketplace browsing. Full plugin lifecycle management.

built

Cron Scheduling

CronCreateTool, CronDeleteTool, CronListTool — agents as scheduled jobs. Basically agent-powered CI/CD.

## Key Takeaways

The 5 lessons that matter most

1

Single-threaded simplicity beats concurrent complexity for LLM agents

The entire Claude Code runtime is a sequential loop. No race conditions, no locks, no deadlocks. When your agent framework is hard to debug, that's a design smell.

2

Defense in depth for tool permissions — multiple layers, each cheap

Trust gate, deferred init, deny lists, per-tool safety, destructive command warnings. Five layers, each trivial to implement, together nearly impossible to bypass.

3

Session compaction is essential for long-running agents

Truncation loses information. Compaction preserves it. Any agent that runs for more than a few turns needs a strategy for managing context window pressure.

4

Specialize your sub-agents by task type

A general-purpose agent is mediocre at everything. An exploration agent with only read tools is excellent at investigation. Match the tool set to the job.

5

Build the infra for features before shipping them

44 feature flags, A/B testing, gradual rollout, kill switches. Claude Code has entire subsystems built and waiting behind flags. Ship the plumbing first.

Extracted from analysis of Claude Code v2.1.88 source maps.
Educational reference only.