Agent Architecture: Building AI-Powered Development Harnesses

TL;DR: Claude Code is not a chat box with file access. It is a programmable runtime with 30 documented lifecycle events, each hookable with shell scripts the model cannot skip. Stack hooks into dispatchers, dispatchers into skills, skills into agents, agents into workflows, and you get an autonomous development harness that enforces constraints, delegates work, persists memory across sessions, and orchestrates multi-agent deliberation. Claude Code v2.1.147 added the off-by-default Workflow tool (CLAUDE_CODE_WORKFLOWS=1), moving deterministic multi-agent orchestration from pure userland scripts toward a first-party runtime primitive; v2.1.149 reinforces the same lesson from the security side with PowerShell permission-bypass fixes and a git-worktree sandbox allowlist fix. Hooks and evidence gates still own correctness.⁵²⁵³ This guide covers every layer of that stack: from a single hook to a 10-agent consensus system. Zero frameworks required. All bash and JSON.

Andrej Karpathy coined a term for what grows around an LLM agent: claws. The hooks, scripts, and orchestration that let the agent grip the world outside its context window.¹ Most developers treat AI coding agents as interactive assistants. They type a prompt, watch it edit a file, and move on. That framing caps productivity at whatever you can personally oversee.

The infrastructure mental model is different: an AI coding agent is a programmable runtime with an LLM kernel. Every action the model takes passes through hooks you control. You define policies, not prompts. The model operates within your infrastructure the same way a web server operates within nginx rules. You do not sit at nginx and type requests. You configure it, deploy it, and monitor it.

The distinction matters because infrastructure compounds. A hook that blocks credentials in bash commands protects every session, every agent, every autonomous run. A skill that encodes your evaluation rubric applies consistently whether you invoke it or an agent does. An agent that reviews code for security runs the same checks whether you are watching or not.²

Key Takeaways

• Hooks guarantee execution; prompts do not. Use hooks for linting, formatting, security checks, and anything that must run every time regardless of model behavior. Exit code 2 blocks actions. Exit code 1 only warns.³
• Skills encode domain expertise that auto-activates. The description field determines everything. Claude uses LLM reasoning (not keyword matching) to decide when to apply a skill.⁴
• Subagents prevent context bloat. Isolated context windows for exploration and analysis keep the main session lean. Run independent subagents in parallel, and use agent teams when workers need sustained coordination.⁵
• Memory lives in the filesystem. Files persist across context windows. CLAUDE.md, MEMORY.md, rules directories, and handoff documents form a structured external memory system.⁶
• Multi-agent deliberation catches blind spots. Single agents cannot challenge their own assumptions. Two independent agents with different evaluation priorities catch structural failures that quality gates cannot address.⁷
• The harness pattern is the system. CLAUDE.md, hooks, skills, agents, and memory are not independent features. They compose into a deterministic layer between you and the model that scales with automation.

How to Use This Guide

Each section builds on the previous. The Decision Framework at the end provides a lookup table for choosing the right mechanism for each problem type.

Five-Minute Golden Path

Before the deep dive, here is the shortest path from zero to a working harness. One hook, one skill, one subagent, one outcome.

Step 1: Create a security hook (2 minutes)

Create .claude/hooks/block-secrets.sh:

#!/bin/bash
INPUT=$(cat)
CMD=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
if echo "$CMD" | grep -qEi '(AKIA|sk-|ghp_|password=)'; then
    echo "BLOCKED: Potential secret in command" >&2
    exit 2
fi

Wire it in .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": ".claude/hooks/block-secrets.sh" }]
      }
    ]
  }
}

Result: Every bash command Claude runs is now screened for leaked credentials. The model cannot skip this check.

Step 2: Create a code review skill (1 minute)

Create .claude/skills/reviewer/SKILL.md with frontmatter (name: reviewer, description: Review code for security issues, bugs, and quality problems. Use when examining changes, reviewing PRs, or auditing code., allowed-tools: Read, Grep, Glob) and a checklist: SQL injection, XSS, hardcoded secrets, missing error handling, functions over 50 lines.

Result: Claude auto-activates this expertise whenever you mention review, check, or audit.

Step 3: Spawn a subagent (30 seconds)

In any Claude Code session, ask Claude to review the last 3 commits for security issues using a separate agent. Claude spawns an Explore agent that reads the diff, applies your review skill, and returns a summary. Your main context stays clean.

What you now have

A three-layer harness: a deterministic security gate (hook), domain expertise that auto-activates (skill), and isolated analysis that protects your context (subagent). Every section below expands one of these three layers.

Why Agent Architecture Matters

Simon Willison frames the current moment around a single observation: writing code is cheap now.⁸ Correct. But the corollary is that verification is now the expensive part. Cheap code without verification infrastructure produces bugs at scale. The investment that pays off is not a better prompt. It is the system around the model that catches what the model misses.

Three forces make agent architecture necessary:

Context windows are finite and lossy. Every file read, tool output, and conversation turn consumes tokens. Microsoft Research and Salesforce tested 15 LLMs across 200,000+ simulated conversations and found a 39% average performance drop from single-turn to multi-turn interaction.⁹ The degradation starts in as few as two turns and follows a predictable curve: precise multi-file edits in the first 30 minutes degrade into single-file tunnel vision by minute 90. Longer context windows do not fix this. The same study’s “Concat” condition (full conversation as a single prompt) achieved 95.1% of single-turn performance with identical content. The degradation comes from turn boundaries, not token limits.

Model behavior is probabilistic, not deterministic. Telling Claude “always run Prettier after editing files” works roughly 80% of the time.³ The model might forget, prioritize speed, or decide the change is “too small.” For compliance, security, and team standards, 80% is not acceptable. Hooks guarantee execution: every Edit or Write triggers your formatter, every time, no exceptions. Deterministic beats probabilistic.

Single perspectives miss multi-dimensional problems. A single agent reviewing an API endpoint checked authentication, validated input sanitization, and verified CORS headers. Clean bill of health. A second agent, prompted separately as a penetration tester, found the endpoint accepted unbounded query parameters that could trigger denial-of-service through database query amplification.⁷ The first agent never checked because nothing in its evaluation framework treated query complexity as a security surface. That gap is structural. No amount of prompt engineering fixes it.

Agent architecture addresses all three: hooks enforce deterministic constraints, subagents manage context isolation, and multi-agent orchestration provides independent perspectives. Together they form the harness.

The Harness Pattern

The harness is not a framework. It is a pattern: a composable set of files, scripts, and conventions that wrap an AI coding agent in deterministic infrastructure. The components:

┌──────────────────────────────────────────────────────────────┐
│                      THE HARNESS PATTERN                      │
├──────────────────────────────────────────────────────────────┤
│  ORCHESTRATION                                                │
│  ┌────────────┐  ┌────────────┐  ┌────────────┐             │
│  │   Agent     │  │   Agent    │  │  Consensus │             │
│  │   Teams     │  │  Spawning  │  │  Validation│             │
│  └────────────┘  └────────────┘  └────────────┘             │
│  Multi-agent deliberation, parallel research, voting          │
├──────────────────────────────────────────────────────────────┤
│  EXTENSION LAYER                                              │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐    │
│  │  Skills   │  │  Hooks   │  │  Memory  │  │  Agents  │    │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘    │
│  Domain expertise, deterministic gates, persistent state,     │
│  specialized subagents                                        │
├──────────────────────────────────────────────────────────────┤
│  INSTRUCTION LAYER                                            │
│  ┌──────────────────────────────────────────────────────┐    │
│  │     CLAUDE.md  +  .claude/rules/  +  MEMORY.md       │    │
│  └──────────────────────────────────────────────────────┘    │
│  Project context, operational policy, cross-session memory    │
├──────────────────────────────────────────────────────────────┤
│  CORE LAYER                                                   │
│  ┌──────────────────────────────────────────────────────┐    │
│  │           Main Conversation Context (LLM)             │    │
│  └──────────────────────────────────────────────────────┘    │
│  Your primary interaction; finite context; costs money        │
└──────────────────────────────────────────────────────────────┘

Instruction Layer: CLAUDE.md files and rules directories define what the agent knows about your project. They load automatically at session start and after every compaction. This is the agent’s long-term architectural memory.

Extension Layer: Skills provide domain expertise that auto-activates based on context. Hooks provide deterministic gates that fire on every matching tool call. Memory files persist state across sessions. Custom agents provide specialized subagent configurations.

Orchestration Layer: Multi-agent patterns coordinate independent agents for research, review, and deliberation. Spawn budgets prevent runaway recursion. Consensus validation ensures quality.

The key insight: most users work entirely in the Core Layer, watching context bloat and costs climb. Power users configure the Instruction and Extension layers, then use the Core Layer only for orchestration and final decisions.²

Managed vs. Self-Hosted Harnesses (April 2026)

Throughout early 2026, the “build your own harness” path was the only real option. In April 2026, that changed. Anthropic shipped Claude Managed Agents in public beta (April 8): harness loop + tool execution + sandbox container + state persistence as a REST API, billed at standard tokens plus $0.08/session-hour. OpenAI’s Agents SDK update (April 16) formalized the same split — harness and compute as separate layers, with native sandbox providers (Blaxel, Cloudflare, Daytona, E2B, Modal, Runloop, Vercel) and snapshot/rehydrate for surviving container loss.²³²⁴

The deeper SDK surface for the OpenAI side landed in openai-agents Python v0.14.0 (released April 15, 2026; announced April 16): a SandboxAgent subclass of Agent with default_manifest, sandbox instructions, and capabilities; a Manifest describing the fresh-workspace contract (files, dirs, local files, Git repos, env, users, mounts); a SandboxRunConfig for per-run wiring of sandbox client, live session injection, manifest overrides, snapshots, and materialization concurrency limits. Built-in capabilities cover shell access, filesystem editing, image inspection, skills, sandbox memory, and compaction. Sandbox memory persists extracted lessons across runs and progressively discloses them; workspaces support local files, Git repo entries, and remote mounts (S3, R2, GCS, Azure Blob, S3 Files); snapshots are portable across providers. Backends: UnixLocalSandboxClient, DockerSandboxClient, and hosted clients for Blaxel, Cloudflare, Daytona, E2B, Modal, Runloop, and Vercel via optional extras.²⁴

For Python projects that want to embed the Claude Code runtime as a library — between “shell out to claude” and “REST API to Managed Agents” — claude-agent-sdk-python is the third option. The April 28-29 series (v0.1.69 → v0.1.71) bumped the bundled CLI to v2.1.123, raised the floor on the mcp dependency to >=1.19.0 (older versions silently dropped CallToolResult returns from in-process MCP tools, leaving the model with a validation-error blob), and brought SandboxNetworkConfig to schema parity with the TypeScript SDK (allowedDomains, deniedDomains, allowManagedDomainsOnly, allowMachLookup).³⁰ As of 2026-08-01 the package sits at v0.2.128 on PyPI (bundling Claude CLI v2.1.220, with the mcp floor now >=1.23.0), and the TypeScript SDK at v0.3.220; the 0.2.x line is incremental over the 0.1.x surface described here — the include_hook_events, skills, and sandbox-config options below remain current — with recent releases focused on subprocess-cleanup and NDJSON-stream reliability.⁸⁶

If your harness includes a voice or realtime layer, openai-agents-python v0.17.0 (May 8, 2026) updated RealtimeAgent to default to gpt-realtime-2.⁴¹ Existing realtime sessions pick up the new default automatically; pin the previous model explicitly if you need to hold the old behavior for evaluation.

In July 2026 the managed column gained a multi-agent story on the OpenAI side too: openai-agents-python v0.18.2 (July 11) and openai-agents-js v0.13.2 (July 10) add hosted multi-agent support in beta — OpenAI-managed orchestration of multiple agents as a hosted service, the direct counterpart to Anthropic’s Managed Multiagent Orchestration public beta covered in the Multi-Agent Orchestration section.⁷³ Both vendors now offer the same trade on the multi-agent tier that the table below describes for single agents: the vendor runs the delegation loop, you give up the hook surface.

The architectural fork is now real:

When to pick which: self-hosted remains right for teams that already have infrastructure muscle, want skills/hooks they control, or are optimizing a specific workflow deeply. Managed is right for teams without dedicated platform engineers, when time-to-value matters more than customization, or when agent runs need to survive laptop closures reliably without you building that persistence layer. The two are compatible — you can run a self-hosted harness that delegates specific long-running tasks to Managed Agents via its REST API.

What the Harness Looks Like on Disk

~/.claude/
├── CLAUDE.md                    # Personal global instructions
├── settings.json                # User-level hooks and permissions
├── skills/                      # Personal skills (44+)
│   ├── code-reviewer/SKILL.md
│   ├── security-auditor/SKILL.md
│   └── api-designer/SKILL.md
├── agents/                      # Custom subagent definitions
│   ├── security-reviewer.md
│   └── code-explorer.md
├── rules/                       # Categorized rule files
│   ├── security.md
│   ├── testing.md
│   └── git-workflow.md
├── hooks/                       # Hook scripts
│   ├── validate-bash.sh
│   ├── auto-format.sh
│   └── recursion-guard.sh
├── configs/                     # JSON configuration
│   ├── recursion-limits.json
│   └── deliberation-config.json
├── state/                       # Runtime state
│   ├── recursion-depth.json
│   └── agent-lineage.json
├── handoffs/                    # Session handoff documents
│   └── deliberation-prd-7.md
└── projects/                    # Per-project memory
    └── {project}/memory/MEMORY.md

.claude/                         # Project-level (in repo)
├── CLAUDE.md                    # Project instructions
├── settings.json                # Project hooks
├── skills/                      # Team-shared skills
├── agents/                      # Team-shared agents
└── rules/                       # Project rules

Every file in this structure serves a purpose. The ~/.claude/ tree is personal infrastructure that applies to all projects. The .claude/ tree in each repository is project-specific and shared via git. Together, they form the complete harness.

Skills System

Skills are model-invoked extensions. Claude discovers and applies them automatically based on context, without you explicitly calling them.⁴ The moment you catch yourself re-explaining the same context across sessions is the moment you should build a skill.

When to Build a Skill

Skills are for knowledge Claude always has available. Slash commands are for actions you explicitly trigger. If you are deciding between the two, ask: “Should Claude apply this automatically, or should I decide when to run it?”

Creating a Skill

Skills live in four possible locations, from broadest to narrowest scope:⁴

Every skill requires a SKILL.md file with YAML frontmatter:

---
name: code-reviewer
description: Review code for security vulnerabilities, performance issues,
  and best practice violations. Use when examining code changes, reviewing
  PRs, analyzing code quality, or when asked to review, audit, or check code.
allowed-tools: Read, Grep, Glob
---

# Code Review Expertise

## Security Checks
When reviewing code, verify:

### Input Validation
- All user input sanitized before database operations
- Parameterized queries (no string interpolation in SQL)
- Output encoding for rendered HTML content

### Authentication
- Session tokens validated on every protected endpoint
- Permission checks before data mutations
- No hardcoded credentials or API keys in source

Frontmatter Reference

The Description Field Is Everything

At session start, Claude Code extracts every skill’s name and description and injects them into Claude’s context. When you send a message, Claude uses language model reasoning to decide if any skill is relevant. Independent analysis of the Claude Code source confirms the mechanism: skill descriptions are injected into an available_skills section of the system prompt, and the model uses standard language understanding to select relevant skills.¹⁰

Bad description:

description: Helps with code

Effective description:

description: Review code for security vulnerabilities, performance issues,
  and best practice violations. Use when examining code changes, reviewing
  PRs, analyzing code quality, or when asked to review, audit, or check code.

The effective description includes: what it does (review code for specific issue types), when to use it (examining changes, PRs, quality analysis), and trigger phrases (review, audit, check) that users naturally type.

Note that auto-activation is a dial, not a law: as of v2.1.215, Claude no longer self-invokes the bundled /verify and /code-review skills — they run on explicit invocation only, a deliberate walk-back of description-driven activation for heavyweight review skills whose unprompted runs cost more than they earned.⁷⁴

Context Budget

All skill descriptions share a context budget that scales dynamically at 1% of the context window, with a fallback of 8,000 characters.⁴ If you have many skills, keep each description concise and put the key use case first. You can override the budget via the SLASH_COMMAND_TOOL_CHAR_BUDGET environment variable,¹¹ but the better fix is shorter, more precise descriptions. Run /context during a session to check whether any skills are being excluded.

Supporting Files and Organization

Skills can reference additional files in the same directory:

~/.claude/skills/code-reviewer/
├── SKILL.md                    # Required: frontmatter + core expertise
├── SECURITY_PATTERNS.md        # Referenced: detailed vulnerability patterns
└── PERFORMANCE_CHECKLIST.md    # Referenced: optimization guidelines

Reference them from SKILL.md with relative links. Claude reads these files on-demand when the skill activates. Keep SKILL.md under 500 lines and move detailed reference material to supporting files.¹²

Sharing Skills via Git

Project skills (.claude/skills/ in the repo root) are shared via version control:⁴

mkdir -p .claude/skills/domain-expert
# ... write SKILL.md ...
git add .claude/skills/
git commit -m "feat: add domain-expert skill for payment processing rules"
git push

When teammates pull, they get the skill automatically. No installation, no configuration. This is the most effective way to standardize expertise across a team.

Skills as a Prompt Library

Beyond single-purpose skills, the directory structure works as an organized prompt library:

~/.claude/skills/
├── code-reviewer/          # Activates on: review, audit, check
├── api-designer/           # Activates on: design API, endpoint, schema
├── sql-analyst/            # Activates on: query, database, migration
├── deploy-checker/         # Activates on: deploy, release, production
└── incident-responder/     # Activates on: error, failure, outage, debug

Each skill encodes a different facet of your expertise. Together, they form a knowledge base that Claude draws from automatically based on context. A junior developer gets senior-level guidance without asking for it.

Skills Compose with Hooks

Skills can define their own hooks in frontmatter that activate only while the skill runs. This creates domain-specific behavior that does not pollute other sessions:²

---
name: deploy-checker
description: Verify deployment readiness. Use when preparing to deploy,
  release, or push to production.
hooks:
  PreToolUse:
    - matcher: Bash
      hooks:
        - type: command
          command: "bash -c 'INPUT=$(cat); CMD=$(echo \"$INPUT\" | jq -r \".tool_input.command\"); if echo \"$CMD\" | grep -qE \"deploy|release|publish\"; then echo \"DEPLOYMENT COMMAND DETECTED. Running pre-flight checks.\" >&2; fi'"
---

Philosophy skills auto-activate via SessionStart hooks, injecting quality constraints into every session without explicit invocation. The skill itself is knowledge. The hook is enforcement. Together, they form a policy layer.

Common Skill Mistakes

Too-broad descriptions. A git-rebase-helper skill that activates on any git-related prompt (rebases, merges, cherry-picks, even git status) pollutes context on 80% of sessions. The fix is either tightening the description or adding disable-model-invocation: true and requiring explicit /skill-name invocation.⁴

Too many skills competing for budget. More skills means more descriptions competing for the 1% context budget. If you notice skills not activating, check /context for excluded ones. Prioritize fewer, well-described skills over many vague ones.

Critical information buried in supporting files. Claude reads SKILL.md immediately but only accesses supporting files when needed. If critical information is in a supporting file, Claude might not find it. Put essential information in SKILL.md directly.⁴

SDK Skill Surface (May 8, 2026)

Self-hosted harnesses on claude-agent-sdk-python v0.1.77+ should use the skills option on ClaudeAgentOptions to declare available skills, not the legacy "Skill" value in allowed_tools.³⁷ The "Skill" shorthand is deprecated and the dedicated option gives Claude Code more structured information about which skills are available. Bundled CLI in v0.1.77 is v2.1.133.

Plugin and Skill Convergence in .claude/skills/ (May 29, 2026)

Skills have always loaded from a project’s .claude/skills/ directory. Claude Code v2.1.157 extends that directory to plugins: a plugin placed in .claude/skills/ now loads automatically with no marketplace registration, and claude plugin init <name> scaffolds a fresh one there with the manifest and SKILL.md already wired.⁵⁸ That closes the gap between the two project-tooling shapes that used to live in different places — a bare skill committed straight to the repo, versus a plugin that bundles a skill plus hooks plus an MCP server but previously needed a marketplace to install. The practical effect for harness design: project-scoped tooling no longer needs a registry detour to ship — write it, commit it, and teammates get the same surface on git pull. Plugins still own the bundled-installable use case (hooks + skills + MCP servers + agents in one ZIP); the change is that a project no longer has to stand up a marketplace just to load one from its own tree.

Hiding the Bundled Surface as Governance (June 8, 2026)

Skills are capability, and capability is attack surface. Claude Code v2.1.169 adds a disableBundledSkills setting (and the matching CLAUDE_CODE_DISABLE_BUNDLED_SKILLS environment variable) that hides the bundled skills, workflows, and built-in slash commands from the model entirely.⁶⁰ For a hardened or regulated harness, this is a deliberate attack-surface reduction: an operator who has audited and approved a specific set of project and personal skills can suppress everything Anthropic ships in the box, so the model only ever reasons over the surface the operator vetted. Treat it the same way you treat a tool allowlist — the default is broad capability, and turning the default off is a governance decision, not a convenience toggle.

Nested .claude/skills and Closest-Wins Resolution (June 16, 2026)

Claude Code v2.1.178 made project tooling location-aware. Skills in nested .claude/skills directories now load when you are working on files under that directory, not just from the repo root; on a name clash the nested skill appears as <dir>:<name> so both stay reachable.⁶³ The same release made the rest of the project surface resolve closest-to-the-working-directory: when an agent, workflow, or output-style name collides across nested .claude/ directories, the one nearest the working directory wins, and a project-scope workflow save targets the closest existing .claude/workflows/ rather than always the root.⁶³ For a monorepo or a repo-of-repos this is the difference between one flat global surface and per-package tooling that activates in context — a services/api/.claude/skills/ can carry API-specific skills that surface only while you work in that tree, without colliding with a services/web/ skill of the same name.

Hook Architecture

Hooks are shell commands triggered by Claude Code lifecycle events.³ They run outside the LLM as plain scripts, not prompts interpreted by the model. The model wants to run rm -rf /? A 10-line bash script checks the command against a blocklist and rejects it before the shell ever sees it. The hook fires whether the model wants it to or not.

Available Events

Claude Code exposes 30 documented lifecycle events across eight categories as of this guide update. The event list grows with releases, so treat the reference docs as the source of truth and check the cheat sheet for the current full table before wiring production hooks:¹³

Two recent refinements matter for background and multi-agent harnesses. As of v2.1.198, background claude agents sessions fire the Notification hook with trigger values agent_needs_input and agent_completed, so a coordinator can react the moment a fleet member blocks on a prompt or finishes — the notification-driven equivalent of polling claude agents --json. And as of v2.1.199, the SessionStart, Setup, and SubagentStart hooks surface stderr when they exit with code 2 (previously that output was silently discarded), so a startup or subagent-launch hook that fails now explains why instead of failing blind.

DirectoryAdded (v2.1.219) closes the mid-session workspace gap. The event list has been stable since MessageDisplay arrived in v2.1.152; DirectoryAdded is the first new lifecycle event since, and it fires after /add-dir — or the SDK’s register_repo_root control request — registers a new working directory partway through a session.⁸⁴ The gap it closes is real: until now a harness could validate a workspace exhaustively at SessionStart and then watch a second repository get bolted on with no hook firing at all. Anything you assert about the workspace at startup — trust checks, secret scans, path-scoping rules derived from the tree, per-repo policy loading — needs to re-run here, because a session’s directory set is no longer fixed at launch. The event is informational rather than blocking, so treat it as a trigger to re-derive state and to record provenance, not as a gate; if a directory must never be addable, deny it in settings rather than trying to veto it from a hook. The SDK side landed the same release (TypeScript v0.3.219 adds DirectoryAdded to the control-protocol lifecycle events), so SDK-hosted harnesses see it on the same footing as CLI ones.⁸⁵

Exit Code Semantics

Exit codes determine whether hooks block actions:³

Critical: Every security hook must use exit 2, not exit 1. Exit 1 is a non-blocking warning. The dangerous command still executes. This is the most common hook mistake across teams.¹⁴

Hook Configuration

Hooks live in settings files. Project-level (.claude/settings.json) for shared hooks. User-level (~/.claude/settings.json) for personal hooks:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/validate-bash.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'if [[ \"$FILE_PATH\" == *.py ]]; then black --quiet \"$FILE_PATH\" 2>/dev/null; fi'"
          }
        ]
      }
    ]
  }
}

The matcher field filters an event-specific value. For tool events, it matches tool_name values such as Bash, Edit, Write, Read, Glob, Grep, MCP tool names like mcp__server__tool, or * for all tools. Simple names and |-separated lists are exact matches; values with other characters are JavaScript regular expressions. Some events do not support matchers and always fire when configured.¹³ As of Claude Code v2.1.195, matchers containing hyphenated identifiers (code-reviewer, mcp__brave-search) exact-match instead of accidentally substring-matching — a hook aimed at one agent or server no longer fires on every name that merely contains the string; to cover all tools from a hyphenated MCP server, write the explicit pattern mcp__brave-search__.*.⁶⁶ v2.1.214 applied the same discipline to path patterns: a hook if: condition using a single-segment dir/** pattern now matches only <cwd>/dir, not every directory named dir anywhere in the tree — write **/dir/** when you genuinely mean any depth.⁷⁴ As with the v2.1.195 change, the fix trades accidental breadth for declared intent; audit any hook conditions that were silently relying on the old any-depth behavior.

Hook Input/Output Protocol

Hooks receive JSON on stdin with full context:

{
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test",
    "description": "Run test suite"
  },
  "session_id": "abc-123",
  "agent_id": "main",
  "agent_type": "main"
}

For advanced control, PreToolUse hooks can output JSON to modify tool input, inject context, or make permission decisions. Use the hookSpecificOutput wrapper — the older top-level decision/reason format is deprecated for PreToolUse:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow",
    "permissionDecisionReason": "Command validated and modified",
    "updatedInput": {
      "command": "npm test -- --coverage --ci"
    },
    "additionalContext": "Note: This database has a 5-second query timeout."
  }
}

Three Types of Guarantees

Before writing any hook, ask: what kind of guarantee do I need?¹⁴

Formatting guarantees ensure consistency after the fact. PostToolUse hooks on Write/Edit run your formatter after every file change. The model’s output does not matter because the formatter normalizes everything.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'if [[ \"$FILE_PATH\" == *.py ]]; then black --quiet \"$FILE_PATH\" 2>/dev/null; elif [[ \"$FILE_PATH\" == *.js ]] || [[ \"$FILE_PATH\" == *.ts ]]; then npx prettier --write \"$FILE_PATH\" 2>/dev/null; fi'"
          }
        ]
      }
    ]
  }
}

Safety guarantees prevent dangerous actions before they execute. PreToolUse hooks on Bash inspect commands and block destructive patterns with exit code 2:

#!/bin/bash
# validate-bash.sh — block dangerous commands
INPUT=$(cat)
CMD=$(echo "$INPUT" | jq -r '.tool_input.command')

if echo "$CMD" | grep -qE "rm\s+-rf\s+/|git\s+push\s+(-f|--force)\s+(origin\s+)?main|git\s+reset\s+--hard|DROP\s+TABLE"; then
    echo "BLOCKED: Dangerous command detected: $CMD" >&2
    exit 2
fi

Quality guarantees validate state at decision points. PreToolUse hooks on git commit commands run your linter or test suite and block the commit if quality checks fail:

#!/bin/bash
# quality-gate.sh — lint before commit
INPUT=$(cat)
CMD=$(echo "$INPUT" | jq -r '.tool_input.command')

if echo "$CMD" | grep -qE "^git\s+commit"; then
    if ! LINT_OUTPUT=$(ruff check . --select E,F,W 2>&1); then
        echo "LINT FAILED -- fix before committing:" >&2
        echo "$LINT_OUTPUT" >&2
        exit 2
    fi
fi

Hook Types Beyond Shell Commands

Claude Code supports five hook types:¹³

Command hooks (type: "command") run shell scripts. Fast, deterministic, no token cost.

MCP tool hooks (type: "mcp_tool") call a tool on an already-connected MCP server. Use them when validation logic already lives behind an MCP boundary and does not need a separate shell script.

Prompt hooks (type: "prompt") send a single-turn prompt to a fast Claude model. The model returns { "ok": true } to allow or { "ok": false, "reason": "..." } to block. Use for nuanced evaluation that regex cannot express.

Agent hooks (type: "agent") spawn a subagent with tool access (Read, Grep, Glob) for multi-turn verification. They are experimental; prefer command hooks for production gates and reserve agent hooks for checks that genuinely require inspecting actual files or test output:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "agent",
            "prompt": "Verify all unit tests pass. Run the test suite and check results. $ARGUMENTS",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

As of Claude Code v2.1.140, agent hook input includes subagent_type, which lets a shared hook distinguish a security-reviewer run from an explorer or generic worker without guessing from prompt text.⁴⁹

HTTP hooks (type: "http") send the event’s JSON input as a POST request to a URL and receive JSON back. Use for webhooks, external notification services, or API-based validation (v2.1.63+). Not supported for SessionStart events:

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "http",
            "url": "https://your-webhook.example.com/hook",
            "headers": { "Authorization": "Bearer $WEBHOOK_TOKEN" },
            "allowedEnvVars": ["WEBHOOK_TOKEN"],
            "timeout": 10
          }
        ]
      }
    ]
  }
}

Async Hooks

Hooks can run in the background without blocking execution. Add async: true for non-critical operations like notifications and logging:¹³

{
  "type": "command",
  "command": ".claude/hooks/notify-slack.sh",
  "async": true
}

Use async for notifications, telemetry, and backups. Never use async for formatting, validation, or anything that must complete before the next action.

Dispatchers Over Independent Hooks

Running seven hooks all firing on the same event, each reading stdin independently, creates race conditions. Two hooks writing to the same JSON state file concurrently will truncate the JSON. Every downstream hook that parses that file breaks.²

The fix: one dispatcher per event that runs hooks sequentially from cached stdin:

#!/bin/bash
# dispatcher.sh — run hooks sequentially with cached stdin
INPUT=$(cat)
HOOK_DIR="$HOME/.claude/hooks/pre-tool-use.d"

for hook in "$HOOK_DIR"/*.sh; do
    [ -x "$hook" ] || continue
    echo "$INPUT" | "$hook"
    EXIT_CODE=$?
    if [ "$EXIT_CODE" -eq 2 ]; then
        exit 2  # Propagate block
    fi
done

Debugging Hooks

Five techniques for debugging hooks that fail silently:¹⁴

1. Test scripts independently. Pipe sample JSON: echo '{"tool_input":{"command":"git commit -m test"}}' | bash your-hook.sh
2. Use stderr for debug output. Exit code 2 stderr is fed back to Claude as an error message. Non-blocking stderr (exit 1, 3, etc.) appears only in verbose mode (Ctrl+O).
3. Watch for jq failures. Wrong JSON paths return null silently. Test jq expressions against real tool input.
4. Verify exit codes. A PreToolUse hook that uses exit 1 provides zero enforcement while appearing to work.
5. Keep hooks fast. Hooks run synchronously. Keep all hooks under 2 seconds, ideally under 500ms.

SDK-Side Hook Event Streaming

Self-hosted harnesses built on claude-agent-sdk-python (v0.1.74+, May 6, 2026) can subscribe to hook events directly from the message stream rather than going through shell-script callbacks.³⁶ Set include_hook_events=True on ClaudeAgentOptions and HookEventMessage objects (PreToolUse, PostToolUse, Stop, and others) yield from the same iterator as assistant messages and tool results. This mirrors the TypeScript SDK’s includeHookEvents option; bundled CLI was bumped to v2.1.129 in the same release.

The event-stream pattern is the right fit when your harness already lives in Python and you want hook signals in the same control flow as model output. The shell-script hook contract (exit codes, stdin JSON, dispatchers) remains the right answer for harnesses that compose multiple tools, share hooks across Claude Code and Codex, or need exit-code semantics for blocking.

The TypeScript SDK’s July 2026 series (v0.3.205–v0.3.208) made the streamed protocol itself more contractual.⁷⁰ Interrupts now return typed receipts: an interrupt acknowledges which queued messages are still pending via still_queued UUIDs, and sessions advertise the interrupt_receipt_v1 capability in system/init, so a coordinator can distinguish “interrupt landed” from “interrupt raced past a message already in flight.” command_lifecycle frames report queued/started/completed/cancelled/discarded per message — the first first-party answer to “what happened to the message I sent” without transcript inference. Smaller surfaces landed too: an AgentToolCompletedOutput type for subagent completion payloads, and canUseTool callbacks may now return {behavior: 'allow'} without an updatedInput field.

One line in that series is a security floor, not a feature: v0.3.208 fixed a caller abort arriving during a pending hook being converted into hook success — which meant a tool gated by a PreToolUse hook could execute after the caller had aborted.⁷⁰ If your harness uses SDK-side hooks as a permission gate and relies on abort to cancel in-flight work, treat v0.3.208 as the minimum version; below it, “aborted” did not reliably mean “blocked.” Python v0.2.127 (July 24, 2026) is the second bypass of this shape in a month — query() closed stdin on the first result frame while background subagents were still running, so their SDK-MCP tool calls failed with "Stream closed" and bypassed PreToolUse hooks entirely.⁸⁵ Name the pattern and watch for it: SDK-side hook enforcement fails open at lifecycle edges — abort, teardown, stream close — where the transport dies before the hook verdict is collected, and it fails silently, because a bypassed hook looks exactly like a hook that approved. Pin both SDK floors, and keep the shell-hook layer as the enforcement you can prove.

Effort and Session Provenance (May 7-8, 2026)

Two additions in Claude Code v2.1.132 and v2.1.133 give hooks and subprocesses better signal about their execution context:³⁸³⁹

• effort.level in hook input. Hooks now receive an effort.level JSON field on the same input that carries tool_input and session_id. The same value is exported as the $CLAUDE_EFFORT env var, so Bash commands can read it without parsing JSON. Use this to scale hook cost with effort tier: skip expensive validation on low, run the full security gate on xhigh or max.
• CLAUDE_CODE_SESSION_ID env var on Bash subprocesses. Bash tool subprocesses now see the same session_id value the hooks see, exposed as CLAUDE_CODE_SESSION_ID. This closes the provenance gap for tools that log per-session state and were previously unable to correlate subprocess events with hook events.

Both signals are available without code changes; existing hooks that ignore the new fields keep working.

autoMode.hard_deny and v2.1.136 Hook/Plugin Fixes (May 8, 2026)

Claude Code v2.1.136 added a new hard-deny tier to auto mode and fixed a cluster of plugin and MCP issues that affected long-running harnesses:⁴⁰

• settings.autoMode.hard_deny. Auto mode classifier rules that block unconditionally, regardless of user intent or allow exceptions. This sits above the existing allow/deny matchers as a non-negotiable governance lever. Use it for rules that must never be overridden (force-push to main, secret-bearing files, production database access) even when an operator has approved the broader category in their personal settings.
• autoMode.classifyAllShell (v2.1.193). By default the auto-mode classifier only reviews shell commands matching arbitrary-code-execution patterns. This setting routes every Bash/PowerShell command through the classifier — the maximal-coverage posture for a governed harness — and the same release surfaces denial reasons in the transcript, the toast, and /permissions, which turns silent blocks into auditable decisions. Codex tightened the equivalent surface in v0.142.2: PowerShell commands containing executable AST regions its safety classifier cannot inspect now require approval instead of passing silently.⁶⁶
• Hook ask floors the classifier (v2.1.211). The hook-versus-auto-mode precedence question is now settled: a PreToolUse hook that returns an ask permission decision floors the final outcome at a prompt — auto mode cannot escalate it back to allow for unsandboxed Bash commands.⁶⁹ For a governed harness this is the missing guarantee tier: a hook’s ask is a deterministic human-in-the-loop stop that survives even fully automatic permission postures. Use ask (not just exit-2 blocks) for the operations where you want a human decision rather than a refusal.
• The classifier model is pinned per session (v2.1.210). The auto-mode classifier defaults to Sonnet 5 and is pinned for the session, so mid-session model switches no longer change which model is making permission classifications.⁶⁹ Classification consistency is a governance property; this removes a quiet source of drift.
• MCP servers no longer disappear after /clear. Servers configured in .mcp.json, plugins, and claude.ai connectors had been silently dropping out of the active set after a /clear in the VS Code extension, JetBrains plugin, and Agent SDK. The fix lands in v2.1.136. If you saw “MCP server X went missing mid-session,” this was the cause.
• MCP OAuth refresh-token loss on concurrent refresh. Users with several remote MCP servers should no longer need daily re-authentication. Concurrent refresh writes were overwriting each other.
• Plan mode now blocks file writes correctly. A matching Edit(...) allow rule was bypassing plan-mode write protection. Plan mode is now enforced regardless of allow rules.
• Plugin Stop and UserPromptSubmit hooks no longer fail mid-session. Cache cleanup was deleting plugin-version files still in use by the running session, breaking these two hook events specifically. The fix keeps in-use versions pinned.
• skills entry in plugin.json. Setting skills was hiding the plugin’s default skills/ directory. Now the entry composes correctly, and pointing it at a file path raises an explicit error instead of failing silently.
• CLAUDE_ENV_FILE SessionStart hook env vars going stale. Vars exported by SessionStart hooks via CLAUDE_ENV_FILE were going stale after /resume or /clear. Fixed in v2.1.136. Sessions now re-source the env file on these events.

For governance harnesses, the operationally interesting line items are autoMode.hard_deny (new lever) and the MCP-disappearance fix (silent failure that broke long sessions). Everything else is a quality-of-life cleanup.

Structured Hook Arguments and Block Continuation (May 11, 2026)

Claude Code v2.1.139 added two hook details that matter for production harnesses: an args: string[] exec form for command hooks, and continueOnBlock for PostToolUse hooks.⁴²⁴⁴ Prefer args when a hook needs dynamic values or path placeholders. It spawns the command directly without a shell, which removes a whole class of quoting and injection mistakes.

Use continueOnBlock when a PostToolUse hook should feed its rejection reason back to Claude and continue the turn instead of ending the flow. Treat it as an operator-experience feature, not a security bypass. A blocking gate should still block the unsafe outcome.

The same release passes CLAUDE_PROJECT_DIR to MCP stdio servers and lets plugin configs reference ${CLAUDE_PROJECT_DIR} in commands.⁴² MCP tools should resolve project-relative paths from that value rather than from whichever process working directory happened to launch the server. The early-July 2026 releases (v2.1.203–v2.1.206) extended the same principle to the protocol level: MCP roots/list now includes the session’s additional working directories, with roots/list_changed notifications when they change — so a server that respects MCP roots tracks the real multi-directory workspace shape instead of assuming a single project directory.⁶⁸

Claude Code v2.1.140 is mostly a reliability release for harness operators: it fixes ConfigChange hooks not firing on settings changes, closes edge cases where disableAllHooks and allowManagedHooksOnly did not compose correctly across settings levels, and stops permission dialogs from exposing unintended environment variables returned by hook results.⁴⁹ That makes the existing governance patterns in this section more dependable; it does not require a new hook architecture.

Claude Code v2.1.141 adds a hook-output terminalSequence field for desktop notifications, window titles, and bells without a controlling terminal.⁵⁰ Treat that as operator signaling, not enforcement. Security and quality gates should still communicate failures through the normal blocking contract: structured hook output plus the exit behavior that prevents the unsafe action. The same release adds claude agents --cwd <path> for scoping Agent View to one directory, CLAUDE_CODE_PLUGIN_PREFER_HTTPS for plugin installs in environments without GitHub SSH keys, and ANTHROPIC_WORKSPACE_ID for workload-identity federation rules that cover more than one workspace.⁵⁰ Those are architecture details for team harnesses: narrower operational views, fewer plugin-install assumptions, and explicit enterprise token scoping.

Claude Code v2.1.142 is more important for background-session orchestration than for hook semantics.⁵¹ claude agents can now dispatch background sessions with explicit directory, settings, MCP, plugin, permission, model, and effort flags instead of depending on wrapper state. Fast mode defaulted to Opus 4.7 at that release, with CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE=1 as the pin for a harness with measured dependence on Opus 4.6’s behavior — as of v2.1.219, Opus 4.7 is out of fast mode entirely and /fast applies to Opus 5 and Opus 4.8.⁸⁴ Root-level plugin SKILL.md discovery and plugin-provided LSP visibility reduce packaging ambiguity. Fixes to MCP_TOOL_TIMEOUT, pre-existing background-session worktrees, daemon sleep/wake and post-upgrade cleanup, and plugin cache cleanup close reliability gaps that otherwise look like orchestration bugs.

Stop-hook steering, cross-session authority, and multi-agent v2 (June 2026)

Four changes from early June matter for harness and multi-agent design.⁵⁹

Stop/SubagentStop hooks gained a steering channel. As of Claude Code v2.1.163, a Stop or SubagentStop hook can return hookSpecificOutput.additionalContext to hand Claude feedback and keep the turn going, without the response being labeled a hook error. Before this, a Stop hook’s only real lever was the exit-2 block, which reads as an error and counts toward the consecutive-block cap. For a quality-gate harness this is the cleaner primitive: a Stop hook that detects “you said done but the tests are red” can now inject “here is what is still failing, continue” instead of hard-blocking. Use the block for genuine stop conditions and additionalContext for “not done yet, here is why.”

Cross-session messaging no longer carries borrowed authority. v2.1.166 hardened the multi-session case: messages relayed via SendMessage from another Claude session no longer carry the originating user’s authority, so a receiving session refuses relayed permission requests and auto mode blocks them. If your orchestration has agents message each other, treat an inbound message as untrusted data, not as an authenticated instruction. This is the same principle the security section applies to tool output, extended to inter-agent messaging. As of v2.1.199, Claude Code also detects and warns when a SendMessage is misrouted because two agents share the same name — a reliability complement to this authority boundary, since a message reaching the wrong same-named agent is its own class of orchestration bug.

Model resilience became a first-class setting. The fallbackModel setting now chains up to three backup models, tried in order when the primary is overloaded or unavailable, and a turn auto-retries once on the fallback for unexpected non-retryable API errors. For a long-running autonomous harness, this turns a transient primary-model outage into a graceful degradation rather than a dropped run. claude agents --json also added a waitingFor field (v2.1.162) that surfaces what a blocked background session is waiting on, such as a permission prompt — an observability win for any coordinator polling a fleet of agents.

Safe mode for clean-room governance and troubleshooting. Claude Code v2.1.169 adds a --safe-mode flag (and the matching CLAUDE_CODE_SAFE_MODE environment variable) that starts a session with every customization disabled at once: CLAUDE.md, plugins, skills, hooks, and MCP servers.⁶⁰ This is the inverse of the harness — a deliberate clean-room. Use it to answer the question every operator eventually asks: “is this behavior coming from the model, or from something I configured?” When a hook misfires, a skill activates when it should not, or an MCP server poisons context, --safe-mode gives you a known-empty baseline to diff against. It is also a governance primitive: a way to run the bare model with none of the persistent authority your harness normally grants, which matters when you need to reproduce a result without any operator-defined scaffolding influencing it.

A note on model tiers. As of Claude Code v2.1.197 (June 30, 2026), Claude Sonnet 5 is the shipped default model for new sessions — native 1M context, promotional $2/$10 per-MTok pricing through August 31 — replacing Opus 4.8 as the out-of-the-box choice. This guide treats Opus 5 (claude-opus-5) as the recommended agentic default: the model to run autonomous harnesses on unless you deliberately choose otherwise, because long-horizon, high-stakes agent loops are exactly where Opus’s reasoning depth earns its cost. Opus 5 shipped July 24, 2026 as the new default Opus in Claude Code v2.1.219 — 1M context, $5/$25 per MTok (the same price as Opus 4.8 it replaces), fast mode at $10/$50 for roughly 2.5× the default speed — and Anthropic reports it more than doubling Opus 4.8 on Frontier-Bench v0.1 while landing within 0.5% of Fable 5’s CursorBench 3.2 score at half the cost.⁸⁴⁸⁷ Same price, more capability, and a model Anthropic characterizes as “much stronger at verifying its work and iterating carefully” is the rare upgrade that needs no cost argument for harness work; the migration from 4.8 is an id change. Drop to Sonnet 5 for cost-sensitive or high-throughput work where its speed-to-intelligence ratio wins. Above Opus sits Claude Fable 5 (claude-fable-5), launched June 9, 2026 — a new tier described as Anthropic’s most powerful model, a “Mythos-class” system made safe for general use, selectable in Claude Code v2.1.170 via /model claude-fable-5.⁶⁰ Reach for the higher tier deliberately, on the decisions where raw reasoning depth justifies the cost, not as a blanket setting for a fleet. Two housekeeping consequences of the Opus 5 cutover: Opus 4.7 is out of fast mode (/fast now applies to Opus 5 and Opus 4.8), and the auto-mode classifier’s Fable-5 fallback — “the best available Opus model” since v2.1.176 — now resolves to Opus 5.⁸⁴

Codex shipped multi-agent v2. Codex CLI v0.137.0 keeps the runtime choice with each thread, exposes cleaner follow-up and metadata defaults for spawned agents (hide_spawn_agent_metadata now defaults to true), and propagates raw parent events to child listeners. Its subagent model stays explicit: built-in default/worker/explorer agent types, TOML-defined custom agents, and concurrency controls (agents.max_threads default 6, agents.max_depth default 1). The same release adds a v1 skills extension with per-turn skill-catalog resolution and new thread-start/turn-error lifecycle contributor events, narrowing the gap with Claude Code’s hook/skill surface while keeping the kernel-sandbox posture as the default boundary. Codex v0.138.0–v0.139.0 then hardened multi-agent v2 for production: inter-agent message payloads are now encrypted, a v2 agent config catalog plus an agent-residency LRU manage which agents stay resident, and concurrency is counted by active execution rather than by spawned threads, so idle agents no longer consume a slot.⁶¹ The lifecycle API matured too — close_agent was renamed interrupt_agent (v0.139.0) to reflect that it interrupts a running agent rather than merely closing a handle — and MCP startup warnings raised by a subagent now stay scoped to the owning thread instead of duplicating up into the parent’s transcript.⁶¹ For anyone building Codex-side orchestration, these are the difference between a demo and a fleet: encrypted message transport, bounded residency, execution-counted concurrency, and warnings that do not leak across the thread boundary. Codex v0.140.0 then opened a cross-tool seam: /import selectively pulls setup, project config, and recent chats from Claude Code into Codex, and sessions became permanently deletable (codex delete / /delete, with confirmation safeguards).⁶⁴ /import is the first official acknowledgment that operators move between harnesses — the configuration you build for one is no longer trapped there.

Memory and Context

Every AI conversation operates within a finite context window. As the conversation grows, the system compresses earlier turns to make room for new content. The compression is lossy. Architectural decisions documented in turn 3 may not survive to turn 15.⁹

The Three Mechanisms of Multi-Turn Collapse

The MSR/Salesforce study identified three independent mechanisms, each requiring a different intervention:⁹

Strategy 1: Filesystem as Memory

The most reliable memory across context boundaries lives in the filesystem. Claude Code reads CLAUDE.md and memory files at the start of every session and after every compaction.⁶

~/.claude/
├── configs/           # 14 JSON configs (thresholds, rules, budgets)
│   ├── deliberation-config.json
│   ├── recursion-limits.json
│   └── consensus-profiles.json
├── hooks/             # 95 lifecycle event handlers
├── skills/            # 44 reusable knowledge modules
├── state/             # Runtime state (recursion depth, agent lineage)
├── handoffs/          # 49 multi-session context documents
├── docs/              # 40+ system documentation files
└── projects/          # Per-project memory directories
    └── {project}/memory/
        └── MEMORY.md  # Always loaded into context

The MEMORY.md file captures errors, decisions, and patterns across sessions. When you discover that ((VAR++)) fails with set -e in bash when VAR is 0, you record it. Three sessions later, when you encounter a similar integer edge case in Python, the MEMORY.md entry surfaces the pattern.¹⁵

Auto Memory (v2.1.32+): Claude Code automatically records and recalls project context. As you work, Claude writes observations to ~/.claude/projects/{project-path}/memory/MEMORY.md. Auto memory loads the first 200 lines into your system prompt at session start. Keep it concise and link to separate topic files for detailed notes.⁶ As of v2.1.210, a MEMORY.md write that exceeds the size limit errors instead of silently truncating⁶⁹ — the failure surfaces at write time rather than as memory entries that quietly vanished. If your harness automates memory writes, handle that error; it is the platform telling you the file needs curation, not a retry.

Memory curation over memory volume (May 2026): A recent arXiv preprint on LLM-agent cooperation frames expanded recall as a possible failure mode: in the authors’ experiments, longer visible history degraded cooperation in 18 of 28 model-game settings.⁴⁸ Treat this as a design warning, not a finished law. The production rule is already clear enough: keep MEMORY.md short, link out to details, and put decision-ready summaries in handoffs. Raw transcript dumps, tool logs, and long recall feeds belong in searchable storage, not automatically in the active prompt.

Strategy 2: Proactive Compaction

Claude Code’s /compact command summarizes the conversation and frees context space while preserving key decisions, file contents, and task state.¹⁵

When to compact: - After completing a distinct subtask (feature implemented, bug fixed) - Before starting a new area of the codebase - When Claude starts repeating or forgetting earlier context - Roughly every 25-30 minutes during intensive sessions

Custom compaction instructions in CLAUDE.md:

# Summary Instructions
When using compact, focus on:
- Recent code changes
- Test results
- Architecture decisions made this session

Compaction protects the conversation; the /cd command (Claude Code v2.1.169) protects the prompt cache. It moves a session to a new working directory mid-stream without breaking the cache that has accumulated over the turn.⁶⁰ Before this, changing directories meant a fresh session and a cold cache. For a long-running session that pivots from one repository to a sibling — common in monorepo and multi-service work — /cd keeps the expensive cached prefix intact while repointing the filesystem context.

Strategy 3: Session Handoffs

For tasks spanning multiple sessions, create handoff documents that capture the full state:

## Handoff: Deliberation Infrastructure PRD-7
**Status:** Hook wiring complete, 81 Python unit tests passing
**Files changed:** hooks/post-deliberation.sh, hooks/deliberation-pride-check.sh
**Decision:** Placed post-deliberation in PostToolUse:Task, pride-check in Stop
**Blocked:** Spawn budget model needs inheritance instead of depth increment
**Next:** PRD-8 integration tests in tests/test_deliberation_lib.py

The Status/Files/Decision/Blocked/Next structure provides the successor session with full context at minimal token cost. Starting a new session with claude -c (continue) or reading the handoff document goes straight to implementation.¹⁵

Strategy 4: Fresh-Context Iteration (The Ralph Loop)

For sessions exceeding 60-90 minutes, spawn a fresh Claude instance per iteration. State persists through the filesystem, not through conversational memory. Each iteration gets the full context budget:¹⁶

Iteration 1: [200K tokens] -> writes code, creates files, updates state
Iteration 2: [200K tokens] -> reads state from disk, continues
Iteration 3: [200K tokens] -> reads updated state, continues
...
Iteration N: [200K tokens] -> reads final state, verifies criteria

Compare with a single long session:

Minute 0:   [200K tokens available] -> productive
Minute 30:  [150K tokens available] -> somewhat productive
Minute 60:  [100K tokens available] -> degraded
Minute 90:  [50K tokens available]  -> significantly degraded
Minute 120: [compressed, lossy]     -> errors accumulate

The fresh-context-per-iteration approach trades 15-20% overhead for the orient step (reading state files, scanning git history) against full cognitive resources per iteration.¹⁶ The cost-benefit calculation: for sessions under 60 minutes, a single conversation is more efficient. Beyond 90 minutes, fresh-context produces higher-quality output despite the overhead.

Strategy 5: Managed Memory Curation (Dreaming)

Anthropic’s Claude Managed Agents added Dreaming as a Research Preview on May 6, 2026.³⁵ Per Anthropic: “Dreaming is a scheduled process that reviews your agent sessions and memory stores, extracts patterns, and curates memories so your agents improve over time.”³⁵

Dreaming runs in the background between sessions, not on the critical path. It complements rather than replaces the filesystem-as-memory pattern: your MEMORY.md file remains the load-bearing surface; Dreaming writes curated memory entries into the Managed Agents memory store, which the agent reads at session start. The two patterns coexist for harnesses that mix self-hosted filesystem state with managed-side curation.

Dreaming is in Research Preview, so behavior may change. The session-handoffs and CLAUDE.md patterns documented above remain the authoritative memory mechanism for self-hosted harnesses.

The Anti-Patterns

Reading entire files when you need 10 lines. A single 2,000-line file read consumes 15,000-20,000 tokens. Use line offsets: Read file.py offset=100 limit=20 saves the vast majority of that cost.¹⁵

Keeping verbose error output in context. After debugging a bug, your context holds 40+ stack traces from failed iterations. A single /compact after fixing the bug frees that dead weight.

Starting every session by reading every file. Let Claude Code’s glob and grep tools find relevant files on demand, saving 100,000+ tokens of unnecessary pre-loading.¹⁵

Subagent Patterns

Subagents are specialized Claude instances that handle complex tasks independently. They start with a clean context (no pollution from the main conversation), operate with specified tools, and return results as summaries. The exploration results do not bloat your main conversation; only the conclusions return.⁵

Built-In Subagent Types

Creating Custom Subagents

Define subagents in .claude/agents/ (project) or ~/.claude/agents/ (personal):

---
name: security-reviewer
description: Expert security code reviewer. Use PROACTIVELY after any code
  changes to authentication, authorization, or data handling.
tools: Read, Grep, Glob, Bash
model: opus
permissionMode: plan
---

You are a senior security engineer reviewing code for vulnerabilities.

When invoked:
1. Identify the files that were recently changed
2. Analyze for OWASP Top 10 vulnerabilities
3. Check for secrets, hardcoded credentials, SQL injection
4. Report findings with severity levels and remediation steps

Focus on actionable security findings, not style issues.

Subagent Configuration Fields

Worktree Isolation

Subagents can operate in temporary git worktrees, providing a complete isolated copy of the repository:⁵

---
name: experimental-refactor
description: Attempt risky refactoring in isolation
isolation: worktree
tools: Read, Write, Edit, Bash, Grep, Glob
---

You have an isolated copy of the repository. Make changes freely.
If the refactoring succeeds, the changes can be merged back.
If it fails, the worktree is discarded with no impact on the main branch.

Worktree isolation is essential for experimental work that might break the codebase.

Isolation is only isolation if it holds. Claude Code v2.1.210 fixed a bug where worktree-isolated subagents could mutate the main checkout — the exact failure the mechanism exists to prevent.⁶⁹ If you rely on isolation: worktree as a safety boundary rather than a convenience, treat v2.1.210 as the floor. The companion permission change cuts the other way: as of v2.1.211, “always allow” rules persist at the repository root across worktrees, so a rule accepted inside one worktree applies to sibling worktrees of the same repository.⁶⁹ That is the right ergonomics for parallel worktree agents, but it means an allow granted during a throwaway experiment outlives the experiment — grant with the whole repository in mind, not just the worktree in front of you.

v2.1.216 finished the job, moving worktree isolation from bug-fix to enforcement-grade.⁷⁴ The v2.1.210 fix stopped worktree subagents from mutating the main checkout through ordinary git invocation, but git itself offers explicit redirection — git -C <path>, --git-dir, and the GIT_DIR/GIT_WORK_TREE environment variables — and a worktree-isolated subagent could still aim any of them at the shared checkout. All of those escape hatches are now closed. The same release fixed worktree sessions occasionally landing in a different project’s leftover worktree, stopped workflow and scheduled-task writes from following a symlink planted at .claude to a target outside the project, and made /rewind refuse to traverse symlinks and hard links. The pattern across all four fixes is the same: an isolation boundary must hold against deliberate redirection — git environment overrides, symlink planting — not just against default behavior. If isolation: worktree is a safety boundary in your harness rather than a convenience, v2.1.216 is the new floor.

Parallel Subagents

Use parallel subagents for independent research tasks that do not need to coordinate with each other:⁵

> Have three explore agents search in parallel:
> 1. Authentication code
> 2. Database models
> 3. API routes

Each agent runs in its own context window, finds relevant code, and returns a summary. The main context stays clean.

The Recursion Guard

Without spawn limits, agents delegate to agents that delegate to agents, each one losing context and burning tokens. The recursion guard pattern enforces budgets:¹⁶

#!/bin/bash
# recursion-guard.sh — enforce spawn budget
CONFIG_FILE="${HOME}/.claude/configs/recursion-limits.json"
STATE_FILE="${HOME}/.claude/state/recursion-depth.json"

MAX_DEPTH=2
MAX_CHILDREN=5
DELIB_SPAWN_BUDGET=2
DELIB_MAX_AGENTS=12

# Read current depth
current_depth=$(jq -r '.depth // 0' "$STATE_FILE" 2>/dev/null)

if [[ "$current_depth" -ge "$MAX_DEPTH" ]]; then
    echo "BLOCKED: Maximum recursion depth ($MAX_DEPTH) reached" >&2
    exit 2
fi

# Increment depth using safe arithmetic (not ((VAR++)) with set -e)
new_depth=$((current_depth + 1))
jq --argjson d "$new_depth" '.depth = $d' "$STATE_FILE" > "${STATE_FILE}.tmp"
mv "${STATE_FILE}.tmp" "$STATE_FILE"

Critical lesson: Use spawn budgets, not just depth limits. Depth-based limits track parent-child chains (blocked at depth 3) but miss width: 23 agents at depth 1 is still “depth 1.” A spawn budget tracks total active children per parent, capped at a configurable maximum. The budget model maps to the actual failure mode (too many total agents) rather than a proxy metric (too many nesting levels).⁷

The nesting-depth default has moved three times; do not build on it. Claude Code v2.1.172 (June 10, 2026) let sub-agents spawn their own sub-agents, nesting up to 5 levels deep — where delegation was previously effectively one level.⁶² That held from v2.1.172 through v2.1.216. v2.1.217 (July 21, 2026) cut it to 1, turning nested spawning off by default. Then v2.1.219 (July 24, 2026) settled it in the middle: “Subagents can now spawn nested subagents up to depth 3 by default (was 1); set CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1 to disable nesting.”⁸⁴ Five, then one, then three — the last two moves inside three days.

The useful reading is not that any one of those numbers is correct. It is that the platform is still searching for the right default, which makes “whatever ships” the wrong thing for a harness to inherit. Treat nesting depth as an explicit budget line: set CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH to the depth your architecture actually needs — for most orchestration that is 1 or 2 — so an upgrade cannot quietly change how deep your fleet delegates. The standing argument is unchanged by any of this churn: agents-delegating-to-agents chains burn context and tokens faster than they produce results, and depth is a hazard to budget for, not a capability to reach for. The recursion guard above is what keeps a deep tree from fanning out into hundreds of active agents whichever way the default drifts next, and a limit you set yourself is the only depth number that still means what you think it means after the next release.

Auto mode now vets spawns before they launch. Claude Code v2.1.178 closed the matching governance gap: in auto mode, subagent spawns are evaluated by the permission classifier before the subagent launches, not only once it starts taking actions.⁶³ Previously a subagent could be spawned to request an action the parent session would have been blocked from taking — the spawn itself was the bypass. Vetting at spawn time means the recursion guard and the permission model finally meet: a child cannot be used as a laundering step for an action the policy forbids.

The platform now ships a native spawn budget. Claude Code v2.1.212 (July 2026) added first-party runaway-loop guardrails: sessions are capped at 200 subagent spawns by default (CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION to tune, /clear resets the counter), and WebSearch is capped at 200 calls per session (CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION).⁶⁹ The spawn-budget pattern this section has documented as userland scripting since v1.0 is now platform-provided — validation of the budget model over the depth model. But note the calibration: 200 spawns is an order of magnitude above the 12-agent budget in the config above. The native caps are fuses against a truly runaway loop, not budgets tuned to your architecture. Keep the userland guard for per-parent budgets, depth tracking, and limits that match what your orchestration should actually do; let the platform cap catch whatever slips past it.

The first-party guardrail set now covers four axes. Three of them backstop exactly what the userland guard in this section tracks: total spawns per session (v2.1.212, cap 200, CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION), nesting depth (CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH, default currently 3 and demonstrably unstable), and concurrent execution (v2.1.217, default 20, CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS — one message can no longer fan out unbounded background agents).⁷⁸⁸⁴ v2.1.219 adds a fourth that userland guards generally did not have: orchestration width, the number of agents a single planned workflow is allowed to contain, shipped as a default guideline of “aim for fewer than 15 agents” and settable from any settings file via workflowSizeGuideline (covered in the Workflow Tool section below). The spawn-budget pattern is now backstopped on every axis it was designed for, plus one it wasn’t.

The calibration note still applies, but unevenly. 200 spawns and 20 concurrent agents are fuses — an order of magnitude above the 12-agent deliberation budget in the config above, sized to catch a runaway loop rather than to shape an architecture. The width guideline is the first native number in the same register as a real budget: 15 agents per workflow sits right next to this guide’s 12, close enough that adopting the platform default costs you nothing and disagreeing with it means you have an actual reason. Set the three fuses to values you can defend; set the width guideline to the shape of the orchestration you meant to build.

Agent Teams (Research Preview)

Agent Teams coordinate multiple Claude Code instances that work independently, communicate via a shared mailbox and task list, and can challenge each other’s findings:⁵

Enable with: export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

When to use agent teams vs subagents:

Agent View and Goal Loops (May 2026)

Claude Code v2.1.139 added Agent View, a research-preview interface started with claude agents that shows running, blocked, and completed Claude Code sessions from one screen.⁴²⁴³ The official docs frame it as a way to dispatch and manage many sessions, see what each session is doing, and identify which ones need operator input.⁴³ This gives multi-agent work an operations view that final summaries cannot provide.

Use Agent View when promoting a subagent or team pattern: inspect which sessions are blocked, which are still running, and whether the work distribution matches the intended architecture. Do not treat it as proof of quality. It is observability; tests, review gates, and evidence reports still decide whether the work is sound.

The same release added /goal, which sets a completion condition and lets Claude continue across turns until the condition is met, including interactive, -p, and Remote Control use.⁴² Treat /goal as a session-scoped completion loop, not a substitute for deterministic gates. It is useful for keeping an agent focused on a target, but tests, citation checks, deploy checks, and security hooks should remain command- or script-backed where failure must block.

Workflow Tool (v2.1.147+)

Claude Code v2.1.147 adds an off-by-default Workflow tool for deterministic multi-agent orchestration. Enable it with CLAUDE_CODE_WORKFLOWS=1.⁵² Architecturally, this is important because it gives Claude Code a first-party orchestration primitive for flows that previously required custom dispatch scripts, mailbox state, and subagent coordination conventions.

Do not delete the harness around it. A Workflow can structure execution, but it does not replace your safety model. Keep PreToolUse and PostToolUse hooks as the blocking layer, keep spawn budgets or workflow step budgets to prevent runaway width, keep filesystem state auditable, and keep final evidence reports outside the model’s self-assessment. In practice: use Workflow for orchestration shape; use hooks, tests, and review gates for truth.

Dynamic workflows now ship an opinion about width (v2.1.219). Dynamic workflows default to a medium size guideline — “aim for fewer than 15 agents” — with other sizes and an unrestricted option available under Dynamic workflow size in /config, and the current guideline shown in the running-workflow status line.⁸⁴ The number is advisory, not enforced; it steers the planner rather than blocking a wide plan. What makes it worth configuring is the delivery mechanism: the new workflowSizeGuideline settings key can be set from any settings file — including managed settings and project settings, and it is in the TypeScript SDK settings types as of v0.3.219 — so orchestration width becomes something a team or an org can standardize instead of something each operator rediscovers.⁸⁵ Set it at the project level to encode what your codebase’s work actually decomposes into. Two operator notes: the /config row hides itself while a settings file is driving the value, which is the correct behavior but reads as a missing setting if you don’t know why; and because the guideline steers the planner rather than gating execution, it belongs in the shape column, not the safety column. Runaway width is still the spawn cap’s job.

The framing worth keeping is that this is a fourth first-party guardrail axis — orchestration width, alongside spawn count, nesting depth, and concurrent execution — and the first one Anthropic has calibrated at a plausible working size rather than as a runaway fuse. Fifteen agents per workflow is the same order of magnitude as the 12-agent deliberation budget this guide has used since v1.0. When the platform’s default and your own budget converge from opposite directions, that is the closest thing to independent corroboration these numbers ever get.

Session Forking and Auto-Backgrounded MCP (July 2026)

Claude Code v2.1.212 reshaped two orchestration primitives.⁶⁹ /fork now creates a new background session from the current conversation state — the forked line runs independently while the original keeps working — and the previous in-session behavior was renamed /subtask. The distinction matters for orchestration design: /subtask is a scoped detour inside one session’s lifecycle; /fork is a cheap way to mint a parallel background session that inherits full context, closer to a Ralph-loop spawn than to a subagent. If your harness scripts assumed /fork stayed in-session, they now dispatch background work.

The same release auto-backgrounds slow MCP calls: an MCP tool call that runs longer than two minutes is moved to background execution automatically (tune the threshold with CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS).⁶⁹ A slow MCP server no longer stalls the agentic loop — but it also means “the tool returned” and “the turn continued” are no longer the same event, so hooks or scripts that assumed synchronous MCP completion should key off the tool result, not the turn boundary.

For headless orchestration, v2.1.211 added --forward-subagent-text (env: CLAUDE_CODE_FORWARD_SUBAGENT_TEXT), which forwards subagent assistant text into stream-json output.⁶⁹ A coordinator process consuming the parent’s stream can now observe subagent progress directly instead of polling transcripts or waiting for the final summary — the observability complement to background-by-default subagents. v2.1.219 extended it past the first level: subagents spawned at depth 2 or deeper now appear in the forwarded stream as well, keyed by their spawning Agent tool_use id.⁸⁴ That key is the part to build on. With nesting back on by default, a flat stream of subagent text is ambiguous — the id tells a coordinator which parent produced which child, so the delegation tree can be reconstructed from the stream instead of inferred. If your stream consumer was written against one level of subagents, it will now see text from agents it never knew existed; group by the spawning tool_use id rather than assuming every forwarded line belongs to a direct child.

Multi-Agent Orchestration

Single-agent AI systems have a structural blind spot: they cannot challenge their own assumptions.⁷ Multi-agent deliberation forces independent evaluation from multiple perspectives before any decision locks.

Cross-tool orchestration (April 2026): Google open-sourced Scion on April 7 — a multi-agent hypervisor that runs Claude Code, Gemini CLI, and other “deep agents” as concurrent processes, each with isolated container, git worktree, and credentials. Runs local, hub, or Kubernetes. Explicit philosophy: “isolation over constraints” — agents run with high autonomy inside boundaries enforced at the infrastructure layer, not in the prompt.²⁵ This directly extends the subagent-isolation argument across different tool vendors. If your workflow spans Claude and OpenAI models, Scion is the first real reference implementation for cross-tool subagents with per-agent worktree + credential isolation.

Debate is not a silver bullet: The M3MAD-Bench research cluster (early 2026) found that multi-agent debate plateaus and can be subverted by misleading consensus — valid arguments lose when other agents confidently assert the wrong answer.²⁶ Tool-MAD improves this by giving each agent heterogeneous tool access and using Faithfulness/Relevance scores in the judge stage. If you’re building debate-style orchestration, invest in (a) tool heterogeneity per agent and (b) quantitative judge scoring rather than assuming more agents = better answers.

Managed Multiagent Orchestration and Outcomes (Public Beta)

If you don’t want to build the deliberation infrastructure described below, Multiagent Orchestration entered Public Beta in Claude Managed Agents on May 6, 2026.³⁵ Per Anthropic: “When there is too much work for a single agent to do well, multiagent orchestration lets a lead agent break the job into pieces and delegate each one to a specialist with its own model, prompt, and tools.”³⁵ Specialists “work in parallel on a shared filesystem and contribute to the lead agent’s overall context.”³⁵

Tracing comes in the box. Per Anthropic: “you can also trace every step in the Claude Console: which agent did what, in what order, and why, giving you full visibility into how your task was delegated and executed.”³⁵

The companion Public Beta feature is Outcomes. Per Anthropic: “you write a rubric describing what success looks like and the agent works toward it. A separate grader evaluates the output against your criteria in its own context window, so it isn’t influenced by the agent’s reasoning.”³⁵ This is the managed-service version of the two-gate validation pattern documented later in this section: the rubric replaces the hand-written gate, the separate grader replaces the consensus validator.

Self-hosted deliberation remains the right answer when the validation needs to integrate with your own hook surface (PreToolUse blocking, exit-code semantics, custom dispatchers) or when the harness must run without external dependencies. Managed Multiagent is the right answer when standard delegation plus rubric grading is the contract you actually need.

Minimum Viable Deliberation

Start with 2 agents and 1 rule: agents must evaluate independently before seeing each other’s work.⁷

Decision arrives
  |
  v
Confidence check: is this risky, ambiguous, or irreversible?
  |
  +-- NO  -> Single agent decides (normal flow)
  |
  +-- YES -> Spawn 2 agents with different system prompts
             Agent A: "Argue FOR this approach"
             Agent B: "Argue AGAINST this approach"
             |
             v
             Compare findings
             |
             +-- Agreement with different reasoning -> Proceed
             +-- Genuine disagreement -> Investigate the conflict
             +-- Agreement with same reasoning -> Suspect herding

This pattern covers 80% of the value. Everything else adds incremental improvement.

The Confidence Trigger

Not every task needs deliberation. A confidence scoring module evaluates four dimensions:¹⁷

1. Ambiguity - Does the query have multiple valid interpretations?
2. Domain complexity - Does it require specialized knowledge?
3. Stakes - Is the decision reversible?
4. Context dependency - Does it require understanding the broader system?

The score maps to three levels:

The threshold adapts by task type. Security decisions require 0.85 consensus. Documentation changes need only 0.50. This prevents over-engineering simple tasks while ensuring risky decisions get scrutiny.⁷

The State Machine

Seven phases, each gated by the previous:⁷

IDLE -> RESEARCH -> DELIBERATION -> RANKING -> PRD_GENERATION -> COMPLETE
                                                                    |
                                                              (or FAILED)

RESEARCH: Independent agents investigate the topic. Each agent gets a different persona (Technical Architect, Security Analyst, Performance Engineer, and others). Context isolation ensures agents cannot see each other’s findings during research.

DELIBERATION: Agents see all research findings and generate alternatives. The Debate agent identifies conflicts. The Synthesis agent combines non-contradictory findings.

RANKING: Each agent scores every proposed approach across 5 weighted dimensions:

The Two-Gate Validation Architecture

Two validation gates catch problems at different stages:⁷

Gate 1: Consensus Validation (PostToolUse hook). Runs immediately after each deliberation agent completes: 1. Phase must have reached at least RANKING 2. Minimum 2 agents completed (configurable) 3. Consensus score meets the task-adaptive threshold 4. If any agent dissented, concerns must be documented

Gate 2: Pride Check (Stop hook). Runs before the session can close: 1. Diverse methods: multiple unique personas represented 2. Contradiction transparency: dissents have documented reasons 3. Complexity handling: at least 2 alternatives generated 4. Consensus confidence: classified as strong (above 0.85) or moderate (0.70-0.84) 5. Improvement evidence: final confidence exceeds initial confidence

Two hooks at different lifecycle points match how failures actually occur: some are instant (bad score) and some are gradual (low diversity, missing dissent documentation).⁷

Why Agreement Is Dangerous

Charlan Nemeth studied minority dissent from 1986 through her 2018 book In Defense of Troublemakers. Groups with dissenters make better decisions than groups that reach quick agreement. The dissenter does not need to be right. The act of disagreement forces the majority to examine assumptions they would otherwise skip.¹⁸

Wu et al. tested whether LLM agents can genuinely debate and found that without structural incentives for disagreement, agents converge toward the most confident-sounding initial response regardless of correctness.¹⁹ Liang et al. identified the root cause as “Degeneration-of-Thought”: once an LLM establishes confidence in a position, self-reflection cannot generate novel counterarguments, making multi-agent evaluation structurally necessary.²⁰

Independence is the critical design constraint. Two agents evaluating the same deployment strategy with visibility into each other’s findings produced scores of 0.45 and 0.48. Same agents without visibility: 0.45 and 0.72. The gap between 0.48 and 0.72 is the cost of herding.⁷

Detecting Fake Agreement

A conformity detection module tracks patterns suggesting agents are agreeing without genuine evaluation:⁷

Score clustering: Every agent scoring within 0.3 points on a 10-point scale signals shared context contamination rather than independent assessment. When five agents evaluating an authentication refactor all scored security risk between 7.1 and 7.4, re-running with fresh context isolation spread the scores to 5.8-8.9.

Boilerplate dissent: Agents copying each other’s concern language rather than generating independent objections.

Absent minority perspectives: Unanimous approval from personas with conflicting priorities (a Security Analyst and a Performance Engineer rarely agree on everything).

The conformity detector catches the obvious cases (roughly 10-15% of deliberations where agents converge too quickly). For the remaining 85-90%, the consensus and pride check gates provide sufficient validation.

What Didn’t Work in Deliberation

Free-form debate rounds. Three rounds of back-and-forth text for a database indexing discussion produced 7,500 tokens of debate. Round 1: genuine disagreement. Round 2: restated positions. Round 3: identical arguments in different words. Structured dimension scoring replaced free-form debate, dropping cost by 60% while improving ranking quality.⁷

Single validation gate. The first implementation ran one validation hook at session end. An agent completed deliberation with a 0.52 consensus score (below threshold), then continued on unrelated tasks for 20 minutes before the session-end hook flagged the failure. Splitting into two gates (one at task completion, one at session end) caught the same problems at different lifecycle points.⁷

Cost of Deliberation

Each research agent processes roughly 5,000 tokens of context and generates 2,000-3,000 tokens of findings. With 3 agents, that is 15,000-24,000 additional tokens per decision. With 10 agents, roughly 50,000-80,000 tokens.⁷

At current Opus pricing, a 3-agent deliberation costs approximately $0.68-0.90. A 10-agent deliberation costs $2.25-3.00. The system triggers deliberation on roughly 10% of decisions, so the amortized cost across all decisions is $0.23-0.30 per session. Whether that is worth it depends on what a bad decision costs.

When to Deliberate

CLAUDE.md Design

CLAUDE.md is operational policy for an AI agent, not a README for humans.²¹ The agent does not need to understand why you use conventional commits. It needs to know the exact command to run and what “done” looks like.

The Precedence Hierarchy

Rules files load automatically and provide structured context without cluttering CLAUDE.md.⁶

What Gets Ignored

These patterns reliably produce no observable change in agent behavior:²¹

Prose paragraphs without commands. “We value clean, well-tested code” is documentation, not operations. The agent reads it and proceeds to write code without tests because there is no actionable instruction.

Ambiguous directives. “Be careful with database migrations” is not a constraint. “Run alembic check before applying migrations. Abort if downgrade path is missing.” is.

Contradictory priorities. “Move fast and ship quickly” plus “Ensure comprehensive test coverage” plus “Keep runtime under 5 minutes” plus “Run full integration tests before every commit.” The agent cannot satisfy all four simultaneously and defaults to skipping verification.²¹

Style guides without enforcement. “Follow the Google Python Style Guide” without ruff check --select D gives the agent no mechanism to verify compliance.

What Works

Command-first instructions:

## Build and Test Commands
- Install: `pip install -r requirements.txt`
- Lint: `ruff check . --fix`
- Format: `ruff format .`
- Test: `pytest -v --tb=short`
- Type check: `mypy app/ --strict`
- Full verify: `ruff check . && ruff format --check . && pytest -v`

Closure definitions:

## Definition of Done
A task is complete when ALL of the following pass:
1. `ruff check .` exits 0
2. `pytest -v` exits 0 with no failures
3. `mypy app/ --strict` exits 0
4. Changed files have been staged and committed
5. Commit message follows conventional format: `type(scope): description`

Task-organized sections:

## When Writing Code
- Run `ruff check .` after every file change
- Add type hints to all new functions

## When Reviewing Code
- Check for security issues: `bandit -r app/`
- Verify test coverage: `pytest --cov=app --cov-fail-under=80`

## When Releasing
- Update version in `pyproject.toml`
- Run full suite: `pytest -v && ruff check . && mypy app/`

Escalation rules:

## When Blocked
- If tests fail after 3 attempts: stop and report the failing test with full output
- If a dependency is missing: check `requirements.txt` first, then ask
- Never: delete files to resolve errors, force push, or skip tests

Writing Order

If starting from scratch, add sections in this priority order:²¹

1. Build and test commands (the agent needs these before it can do anything useful)
2. Definition of done (prevents false completions)
3. Escalation rules (prevents destructive workarounds)
4. Task-organized sections (reduces irrelevant instruction parsing)
5. Directory scoping (monorepos: keeps service instructions isolated)

Skip style preferences until the first four are working.

The platform now audits your CLAUDE.md for you. As of the early-July 2026 releases (v2.1.203–v2.1.206), /doctor analyzes CLAUDE.md and proposes trimming content the model can derive from the codebase itself — restated directory layouts, framework conventions the code already exhibits, command lists that duplicate package scripts.⁶⁸ This is first-party confirmation of the section’s thesis: instructions earn their tokens by encoding what the agent cannot infer (policies, thresholds, closure definitions), not what it can read from disk. Run /doctor after significant CLAUDE.md growth and treat its trim proposals as a starting point — but keep the operational rules it may flag as “derivable” if they are load-bearing constraints rather than descriptions.

File Imports

Reference other files within CLAUDE.md:

See @README.md for project overview
Coding standards: @docs/STYLE_GUIDE.md
API documentation: @docs/API.md
Personal preferences: @~/.claude/preferences.md

Import syntax: relative (@docs/file.md), absolute (@/absolute/path.md), or home directory (@~/.claude/file.md). Maximum depth: 5 levels of imports.⁶

Cross-Tool Instruction Compatibility

AGENTS.md is an open standard recognized by every major AI coding tool.²¹ If your team uses multiple tools, write AGENTS.md as the canonical source and mirror relevant sections to tool-specific files:

The patterns in AGENTS.md (command-first, closure-defined, task-organized) work in any instruction file regardless of tool. Do not maintain parallel instruction sets that drift apart. Write one authoritative source and mirror.

Codex Parity Notes

Codex now has first-class equivalents for the major harness layers, but the migration is a pattern translation, not a file copy. Codex reads AGENTS.md before work begins, layering global guidance from ~/.codex with project and nested repository instructions.³¹ Codex skills use the same SKILL.md mental model with progressive disclosure: Codex starts with the skill name, description, and file path, then loads the full skill only when it decides to use it.³² Codex also has native hooks, plugin-bundled hooks, managed hooks, MCP support, and explicit subagent workflows.³³³⁴

Codex v0.138.0–v0.139.0 hardened that AGENTS.md discovery for non-trivial workspaces: loading now routes through the environment’s filesystem abstraction and preserves logical paths during the discovery walk, so the right file is selected even when the workspace is a remote filesystem or a symlinked tree.⁶¹ This matters whenever your canonical AGENTS.md is the authoritative source and the agent is operating over a mounted, container-materialized, or symlinked checkout — the cases where a naive path walk silently picks the wrong instruction file or none at all. If you mirror one authoritative AGENTS.md across services, treat this as the floor for trusting that the file the agent actually loaded is the one you wrote.

Codex v0.141.0 then hardened the remote-execution path itself: remote executors now connect over authenticated, end-to-end encrypted Noise-relay channels (the control plane and executor no longer trust the relay between them), cross-platform remote execution preserves the executor’s native working directory and shell, and TLS accepts P-521 certificate signatures for enterprise proxies.⁶⁵ If your orchestration drives Codex executors across a network boundary, this is the difference between a trusted-relay assumption and an end-to-end-encrypted one — treat it as the baseline for any remote-executor topology.

The July 2026 line shows the two runtimes converging on the same primitives from opposite directions.⁷² Codex v0.143.0 makes MCP tools load via tool search by default — tool schemas are deferred and fetched on demand rather than front-loaded into context — the same deferred-tool-loading pattern Claude Code exposes through its ToolSearch surface, and the correct answer on both runtimes to context bloat at high MCP tool counts. Codex v0.144.0 adds a writes app-approval mode: read-only actions run without prompting while writes require approval — a genuinely new permission-mode primitive sitting between read-only and auto-approve that Claude Code’s mode list does not directly express (its closest analogue is plan mode, which blocks writes outright rather than prompting per write). The same release takes MCP interactive auth to GA. And v0.144.5 expands dangerous-command detection, mirroring the destructive-command guardrails Claude Code shipped in v2.1.183 and v2.1.208. For cross-runtime harness design, the convergence is the story: deferred tool loading, graded write approval, and intent-level dangerous-command blocking are becoming table stakes rather than vendor differentiators.

Codex v0.145.0 pushes the convergence further on two fronts.⁷⁶ The opt-in multi-agent V2 surface stabilized: sub-agent models, reasoning levels, and concurrency are now configurable, and the previously removed agent roles are restored — Codex’s answer to per-subagent model and effort configuration in .claude/agents/ frontmatter. And /import grew into full cross-harness migration: beyond the Claude Code settings import that shipped in v0.140.0, it now migrates settings from Claude Code and Cursor — MCP servers, plugins, sessions, commands, and project-scoped memories included. For teams running both runtimes, the migration cost between them keeps dropping in one direction; the harness layers you build on Claude Code — servers, skills-as-commands, memory — are increasingly portable state rather than lock-in.

The practical mapping:

The important difference: Claude subagents can be selected automatically from descriptions, while Codex currently documents subagent workflows as explicit. That makes skills and hooks the right default for always-on harness behavior in Codex; subagents are for deliberate parallel work, review, and exploration.

Testing Your Instructions

Verify the agent actually reads and follows your instructions:

# Check active instructions
claude --print "What instructions are you following for this project?"

# Verify specific rules are active
claude --print "What is your definition of done?"

The acid test: Ask the agent to explain your build commands. If it cannot reproduce them verbatim, the instructions are either too verbose (content pushed out of context), too vague (agent cannot extract actionable instructions), or not being discovered. GitHub’s analysis of 2,500 repositories found that vagueness causes most failures.²¹

Production Patterns

Opus 4.7 Long-Horizon Patterns (April 2026)

Claude Opus 4.7 (April 16, 2026) shipped with specific capabilities that change what a harness needs to defend against:²⁹

• Tool-failure resilience: Opus 4.7 continues through tool failures that halted Opus 4.6 sessions. You can reduce — but not eliminate — defensive retry wrappers in subagent code. Keep the hook-level guards; trim the in-prompt “if the tool fails, try again three times” scaffolding.
• xhigh effort tier (Opus-4.7 only): Sits between high and max. Recommended default for coding and agentic workloads. On long-running subagents, xhigh meaningfully outperforms high with sub-proportional token cost. max remains the right choice for single-shot hard reasoning; xhigh is better for sustained tasks.
• Token-budget ceiling: Configurable per agent run via output_config.task_budget (beta header task-budgets-2026-03-13). The model sees a running countdown and gracefully scopes work to the budget instead of running out unexpectedly. Use for agentic loops where you want predictable token spend without sacrificing quality on short prompts.
• Implicit-need awareness: First Claude model to pass “implicit-need” tests — recognizing when the user’s literal request underspecifies what they actually need. This makes CLAUDE.md’s “clarifying rules” section less necessary. If your CLAUDE.md is 200 lines of “also consider X when the user asks for Y” guardrails, prune the ones that are now covered natively.

Worktree Base, Sandbox Paths, and Admin Settings (May 7, 2026)

Claude Code v2.1.133 adds four admin-tier settings worth knowing about for production harnesses:³⁹

The worktree.baseRef revert is the one to flag for users: agents that relied on the v2.1.128-v2.1.132 behavior (worktrees branching from local HEAD) lose access to unpushed work in fresh worktrees unless they opt back in.

OTel Feedback Survey for Enterprise Observability (May 8, 2026)

Claude Code v2.1.136 added CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL to re-enable the in-session quality survey for enterprises capturing the responses through OpenTelemetry.⁴⁰ If your org sinks OTel events to a central observability stack, this env var puts the survey back into the data path so quality signal flows through the same pipeline as latency and error metrics. Treat it as opt-in: the default keeps the survey suppressed, which is correct for non-OTel deployments.

Corporate Launchers and MCP-Scale Performance (July 2026)

Two v2.1.207 changes matter for production deployments.⁶⁸ CLAUDE_CODE_PROCESS_WRAPPER lets managed environments launch the Claude Code process through a corporate wrapper binary — the integration point for endpoint agents, launch-time policy checks, and environments where every process must run under a mandated supervisor. If your enterprise previously faked this with shell aliases or forked launcher scripts, this is the supported seam.

The same release cut runtime overhead where harnesses feel it most: up to 7× faster tool-use rounds in sessions with high MCP tool counts, and 79× smaller session transcripts.⁶⁸ This softens — without reversing — the Cost as Architecture guidance: CLI-first still wins for stateless one-shot operations, but a harness carrying dozens of MCP tools no longer pays the per-round penalty it did in the spring, and transcript storage stops being a hidden cost of long autonomous runs.

The Quality Loop

A mandatory review process for all non-trivial changes:

1. Implement - Write the code
2. Review - Re-read every line. Catch typos, logic errors, unclear sections
3. Evaluate - Run the evidence gate. Check patterns, edge cases, test coverage
4. Refine - Fix every issue. Never defer to “later”
5. Zoom Out - Check integration points, imports, adjacent code for regressions
6. Repeat - If any evidence gate criterion fails, return to step 4
7. Report - List what changed, how verified, cite specific evidence

The Evidence Gate

“I believe” and “it should” are not evidence. Cite file paths, test output, or specific code.

If you cannot produce evidence for any row, return to Refine.²²

Human Merge Authority

A May 2026 arXiv study of 29,585 AI-agent pull-request lifecycles separates operational agency from merge governance.⁴⁷ The useful architecture lesson is simple: agents can start work, carry branches forward, open PRs, review work, and summarize risk, while merge authority remains a separate governance boundary.

Make that boundary explicit in the harness. Let agents prepare PRs and collect evidence; require human approval for merges, releases, and destructive repository operations unless the organization has a separately audited automation policy. Where automation executes a merge, preserve logs that distinguish the executor from the human or policy that authorized it.

Error Handling Patterns

Atomic file writes. Multiple agents writing to the same state file simultaneously corrupts JSON. Write to .tmp files, then mv atomically. The OS guarantees mv is atomic on the same filesystem.¹⁷

# Atomic state update
jq --argjson d "$new_depth" '.depth = $d' "$STATE_FILE" > "${STATE_FILE}.tmp"
mv "${STATE_FILE}.tmp" "$STATE_FILE"

State corruption recovery. If state gets corrupted, the recovery pattern recreates from safe defaults rather than crashing:¹⁶

if ! jq -e '.depth' "$RECURSION_STATE_FILE" &>/dev/null; then
    # Corrupted state file, recreate with safe defaults
    echo '{"depth": 0, "agent_id": "root", "parent_id": null}' > "$RECURSION_STATE_FILE"
    echo "- Recursion state recovered (was corrupted)"
fi

The ((VAR++)) bash trap. ((VAR++)) returns exit code 1 when VAR is 0 because 0++ evaluates to 0, which bash treats as false. With set -e enabled, this kills the script. Use VAR=$((VAR + 1)) instead.¹⁶

Blast Radius Classification

Classify every agent action by blast radius and gate accordingly:²

Remote Control (connecting to local Claude Code from any browser or mobile app) turns the “External” gate from a blocking wait into an async notification. The agent keeps working on the next task while you review the previous one from your phone.²

Task Specification for Autonomous Runs

Effective autonomous tasks include three elements: objective, completion criteria, and context pointers:¹⁶

OBJECTIVE: Implement multi-agent deliberation with consensus validation.

COMPLETION CRITERIA:
- All tests in tests/test_deliberation_lib.py pass (81 tests)
- post-deliberation.sh validates consensus above 70% threshold
- recursion-guard.sh enforces spawn budget (max 12 agents)
- No Python type errors (mypy clean)

CONTEXT:
- Follow patterns in lib/deliberation/state_machine.py
- Consensus thresholds in configs/deliberation-config.json
- Spawn budget model: agents inherit budget, not increment depth

Criteria must be machine-verifiable: test pass/fail, linter output, HTTP status codes, file existence checks. An early task that asked the agent to “write tests that pass” produced assert True and assert 1 == 1. Technically correct. Practically worthless.¹⁶

Failure Modes to Watch For

A Concrete Session Trace

A session trace from an autonomous run processing a PRD with 5 stories:²

1. SessionStart fires. Dispatcher injects: current date, project detection, philosophy constraints, cost tracking initialization. Five hooks, 180ms total.

2. Agent reads the PRD, plans the first story. UserPromptSubmit fires. Dispatcher injects: active project context, session drift baseline.

3. Agent calls Bash to run tests. PreToolUse:Bash fires. Credentials check, sandbox validation, project detection. 90ms. Tests run. PostToolUse:Bash fires: activity heartbeat logged, drift check.

4. Agent calls Write to create a file. PreToolUse:Write fires: file scope check. PostToolUse:Write fires: lint check, commit tracking.

5. Agent finishes the story. Stop fires. Quality gate checks: did the agent cite evidence? Hedging language? TODO comments in the diff? If any check fails, exit 2 and the agent continues.

6. Independent verification: A fresh agent runs the test suite without trusting the previous agent’s self-report.

7. Three code review agents spawn in parallel. Each reviews the diff independently. If any reviewer flags CRITICAL, the story goes back in the queue.

8. Story passes. Next story loads. The cycle repeats for all 5 stories.

Total hooks fired across 5 stories: ~340. Total time in hooks: ~12 seconds. That overhead prevented three credential leaks, one destructive command, and two incomplete implementations in a single overnight run.

Case Study: Overnight PRD Processing

A production harness processed 12 PRDs (47 stories) across 8 overnight sessions. Metrics compare the first 4 PRDs (minimal harness: CLAUDE.md only) against the last 8 (full harness: hooks, skills, quality gates, multi-agent review).

The two credential leaks required rotating API keys and auditing downstream services: roughly 4 hours of incident response. The harness overhead that prevented the equivalent was 2.4 seconds of bash per story. The false completion rate dropped from 35% to 4% because the Stop hook independently ran tests before allowing the agent to report done.

Security Considerations

The Five Principles of Trustworthy Agents (Anthropic, April 2026)

Anthropic published a formal framework for agent trustworthiness on April 9, 2026.²⁷ The five principles parallel — and extend — the Evidence Gate thinking in this guide:

Anthropic also donated MCP to the Linux Foundation’s Agentic AI Foundation, joining AGENTS.md (now jointly stewarded with OpenAI, Google, Cursor, Factory, Sourcegraph). Agent interoperability standards are now vendor-neutral.²⁷

MCP’s stateless turn and self-reported identity (July 2026). The MCP specification is mid-transition to a stateless core (SEP-2575), which drops the stateful initialize handshake that used to carry server identity. A draft-spec change merged July 16 (PR #3002) restores identity as an optional surface: servers may include an io.modelcontextprotocol/serverInfo object in response _meta, and clientInfo becomes optional on requests.⁷¹ The security-relevant part is what the spec says about trust: this identity is self-reported and unverified — display and logging only — and SHOULD NOT drive security decisions. If your harness keys allowlists, permission rules, or logging-based audit on an MCP server’s declared name, that name is a claim, not a credential; pin trust to the transport and configuration (which server you configured at which endpoint), never to what the server says it is. The finalized stateless spec revision is scheduled for July 28, 2026 — expect the protocol-level details in this section to firm up in the next update.

Skill sandbox tooling: For teams that treat skills as an attack surface, Permiso’s SandyClaw (launched April 2, 2026) runs skills in a dedicated sandbox and delivers evidence-backed verdicts from Sigma/YARA/Nova/Snort detection. First product in the skill-sandbox category.²⁸

The Sandbox

Claude Code supports an optional sandbox mode (enabled via settings.json or the /sandbox command) that restricts network access and filesystem operations using OS-level isolation (seatbelt on macOS, bubblewrap on Linux). When enabled, the sandbox prevents the model from making arbitrary network requests or accessing files outside the project directory. Without sandboxing, Claude Code uses a permission-based model where you approve or deny individual tool calls.¹³

May 2026 security floor. Claude Code v2.1.149 fixed a PowerShell working-directory permission bypass, several PowerShell allow-rule and stale-variable permission-analysis gaps, and a git-worktree sandbox write-allowlist bug that covered the full main repository root instead of only shared git internals.⁵³ If your harness allows PowerShell or worktree-isolated agents, treat v2.1.149+ as the floor and keep shell rules narrow. Broad PowerShell(*) and all-repo write exceptions are orchestration shortcuts, not safety boundaries.

OpenAI Agents SDK sandbox lockdown (v0.17.0, May 8, 2026). On the OpenAI side, openai-agents-python v0.17.0 tightened a parallel boundary: LocalFile.src and LocalDir.src are now constrained to within the materialization base_dir (the SDK process current working directory when the manifest is applied), unless the source is explicitly granted via Manifest.extra_path_grants with SandboxPathGrant.⁴¹ Relative local sources resolve from base_dir; absolute paths must already sit inside it or carry a grant. This closes a local artifact boundary issue: prior versions allowed manifests to pull arbitrary host paths into a sandbox workspace. Migration: declare trusted host roots at the manifest level with SandboxPathGrant(path=..., read_only=True) for read-only mounts. Treat extra_path_grants as trusted application configuration; never populate grants from model output or untrusted manifest input.

OpenAI Agents SDK follow-up floor (v0.17.3). The 0.17.1-0.17.3 line added more sandbox and session hardening: archive extraction limits, GitRepo subpath validation, clearer sandbox-provider errors, mountpoint credentials kept out of sandbox commands, rejection of relative sandbox workspace roots, and Vercel-sandbox terminal-state handling.⁵⁴ If you are using OpenAI-hosted or provider-backed sandboxes rather than only Claude Code hooks, treat 0.17.3 as the current floor for the patterns in this section.

Three Containment Patterns Across Products (Anthropic, May 2026)

Anthropic’s engineering post “How we contain Claude across products” (May 25, 2026) is the vendor’s own articulation of the principles this section teaches piecemeal — the settings-level sandbox above, the worktree-isolation floor, the treat-everything-as-untrusted stance.⁸¹ Its core move is mapping containment strength to product surface, and the mapping is itself the lesson: there is no one correct isolation design, only isolation matched to who is watching and what can go wrong.

• Ephemeral gVisor containers (claude.ai). Server-side execution runs in gVisor containers on isolated infrastructure with a per-session ephemeral filesystem. The threat model is infrastructure and tenant isolation — the user’s machine is never reachable, so nothing local needs defending.
• Human-in-the-loop OS sandboxing (Claude Code). The pattern described in the sandbox paragraph above, stated as policy: Seatbelt on macOS and bubblewrap on Linux, with reads allowed, writes confined to the workspace, and network denied by default — the human approves what the boundary does not cover. Anthropic open-sourced the runtime (sandbox-runtime) so the boundary is auditable. The post is candid about the weak link: roughly 93% of permission prompts get approved, and the auto-mode classifier — catching roughly 83% of overeager behaviors before execution while cutting approval prompts by 84% — exists precisely because approval fatigue is a security property, not a UX complaint. That is the check-layer posture this guide has tracked since v2.1.193.
• Sealed VMs (Claude Cowork). Full virtual machines on platform hypervisors — Apple Virtualization framework on macOS, HCS on Windows — with only the selected workspace and .claude folder mounted; nothing else on the host is visible. Credentials never enter the VM: they stay in the host keychain, and each session receives a scoped, independently revocable token. A defensive MITM proxy inside the VM enforces it, passing only requests that carry the VM’s own provisioned session token — an attacker-embedded key is rejected at the boundary, because only the VM knows provenance.

The design principles underneath the taxonomy are the transferable part. Contain at the environment layer first, steer at the model layer second: any probabilistic defense has a non-zero miss rate, so deterministic boundaries must catch what prompt-level steering misses — the hooks-guarantee-execution argument of this guide, restated by the vendor. Match isolation strength to the user’s capacity for oversight: a developer can evaluate a bash command before approving it; a knowledge worker cannot — which is why Code gets a permission dialog and Cowork gets a sealed VM. Prefer battle-tested primitives over custom isolation code: hypervisors, seccomp, and container runtimes survived adversarial scrutiny better than Anthropic’s own custom allowlist proxies and configuration parsers did. Treat project-local config and tool outputs as untrusted: the post’s instruction is to treat project-open and config-load like any inbound request from the internet, and tool output as an attack surface even when the tool is trusted — the same stance this guide applies to inter-agent messages, subagent-read content, and self-reported MCP identity. Keep credentials outside the sandbox: scoped, revocable, per-session tokens rather than ambient keys the agent could leak.

The settings surface is catching up to the first principle (v2.1.219). “Contain at the environment layer first” is easy to endorse and has been awkward to actually configure, because Claude Code’s sandbox resolved what its rules did not cover by asking — and a permission prompt is a probabilistic defense wearing a deterministic costume, as the 93%-approval figure above concedes. sandbox.network.strictAllowlist removes the question for egress: with it set, a sandboxed command’s request to a non-allowlisted host is denied outright instead of prompting.⁸⁴ Pair it with v2.1.216’s sandbox.filesystem.disabled and the two settings compose into a posture rather than a pile of toggles — filesystem and network containment are independently selectable, and network containment can now be made deterministic. For an unattended harness this is the more important of the two, because egress is where an injected instruction becomes exfiltration, and the terminal case of approval fatigue is that there is nobody at the keyboard to be fatigued. The cost is the ordinary cost of a deterministic boundary: the allowlist has to be right, and a host you forgot fails as an opaque denial rather than a question. Enumerate the hosts your agents legitimately need, then take the prompt away.

None of this replaces the hook layer; it sits beneath it. The containment patterns are the deterministic floor, and the worktree-enforcement history in this guide is the same lesson in miniature: a boundary only counts if it holds against deliberate redirection, and the primitives most likely to hold are the ones that were not written for the occasion.

Permission Boundaries

The permission system gates operations at multiple levels:

Parameter-Level Permission Rules (June 2026)

Claude Code v2.1.178 extended permission rules from the tool level down to the parameter level: Tool(param:value) matches against a tool’s input parameters, with * as a wildcard. The canonical example is Agent(model:opus) — a rule that blocks subagents from being spawned on a specific model tier.⁶³ Architecturally, this closes a gap the four-level table above could not express: previously you allowed or denied a tool wholesale, but could not constrain how it was called. A governance policy can now say “subagents may spawn, but not on the Fable 5 tier” or “Bash is allowed, but not with this flag” as a deterministic rule rather than a prompt-level request.

A companion managed setting, enforceAvailableModels (v2.1.175), constrains model selection from the top down: it pins the Default model and prevents user- or project-scoped settings from widening the managed availableModels allowlist.⁶³ The two compose — the allowlist defines which tiers exist for the session at all, and parameter-level rules constrain how subagents draw from it. As of v2.1.196, administrators can also set an organization-wide default model from the org console, surfaced as “Org default” in /model, so a fleet inherits a governed default without each operator pinning one — a floor to complement the allowlist’s ceiling.

Path-Scoped Allow Rules Anchor to the Working Directory (July 2026)

Claude Code v2.1.214 closed a quiet over-match in path-scoped permission rules: an allow rule with a single-segment dir/** pattern — Edit(src/**), say — was auto-approving edits to any directory named src at any depth, including vendor/some-package/src/ and every other nested src/ the rule’s author never meant to bless. Such rules now anchor to <cwd>/dir only; if you genuinely want any-depth matching, declare it with **/dir/**.⁷⁴ Deny and ask rules deliberately keep the old any-depth matching. That asymmetry is the correct fail-safe design: an allow rule that matches too narrowly fails safe (you get a prompt), while a deny rule that matches too narrowly fails open (a blocked path slips through) — so allows got stricter and denies stayed broad. If your settings rely on single-segment allow patterns to cover nested paths, they silently stopped doing so at v2.1.214; that is the fix working as intended, but it is worth a pass over your allowlists to re-declare the breadth you actually want.

Auto-Mode Destructive-Command Guardrails (June 2026)

Claude Code v2.1.183 narrowed auto mode’s blast radius for the operations that silently lose work or tear down environments. Auto mode now hard-blocks, unless you explicitly asked for them in the session: destructive git operations (git reset --hard, git checkout -- ., git clean -fd, git stash drop); git commit --amend when the commit wasn’t made by the agent this session; and infrastructure teardown (terraform destroy, pulumi destroy, cdk destroy) unless you named the specific stack.⁶⁵ Architecturally, this is the complement to the spawn-vetting and parameter-level rules above: rather than gating which tool or how it’s spawned, it gates a small set of specific irreversible commands by intent — the agent can still run them, but only on explicit instruction, not on its own initiative. For an autonomous harness, encode the same principle in your own PreToolUse hooks: the commands that destroy state deserve a deny-by-default rule that only an explicit operator signal lifts.

July 2026: auto mode goes enterprise, and one prompt becomes unwaivable. Auto mode reached GA on Amazon Bedrock, Google Vertex AI, and Microsoft Foundry in v2.1.207, with a disableAutoMode managed setting as the enterprise opt-out — the classifier-as-check-layer posture is now available on every first-party enterprise platform, and disabling it is an explicit governance decision rather than a platform gap.⁶⁸ v2.1.208 then made the catastrophic-removal guard absolute: confirmation prompts for catastrophic removals now pierce both --dangerously-skip-permissions and auto mode.⁶⁸ That is a notable precedent — the first confirmation in Claude Code that no permission posture, including the explicit bypass flag, can waive. Autonomous-harness designs that assumed --dangerously-skip-permissions meant literally zero prompts should account for this one exception; it fires exactly where an unattended loop can do the most unrecoverable damage.

Anti-Fabrication Guardrails (July 2026)

The v2.1.203–v2.1.206 releases closed two paths by which an agent could fabricate its own audit trail.⁶⁸ First, an auto-mode rule now blocks tampering with transcript files — the session record is no longer something the session’s own tool calls can rewrite. Second, background-task notifications now explicitly state that no human input occurred while the task ran. That second one targets a subtle failure: a model summarizing a background task could previously present (or invent) an in-transcript “approval” that never happened, and nothing in the notification contradicted it. Now the notification itself is the counter-evidence.

The architecture lesson generalizes to the Evidence Gate: transcripts, notifications, and logs are audit surfaces, and audit surfaces must not be writable by the thing they audit. The platform now enforces this for its own transcript; apply the same rule to your harness — evidence reports, test outputs, and deliberation records belong outside the model’s writable path.

Prompt Injection Defense

Skills and hooks provide defense-in-depth against prompt injection:

Skills with tool restrictions prevent a compromised prompt from gaining write access:

allowed-tools: Read, Grep, Glob

PreToolUse hooks validate every tool call regardless of how the model was prompted:

# Block credential file access regardless of prompt
if echo "$FILE_PATH" | grep -qE "\.(env|pem|key|credentials)$"; then
    echo "BLOCKED: Sensitive file access" >&2
    exit 2
fi

Subagent isolation limits blast radius. A subagent with permissionMode: plan cannot make changes even if its prompt is compromised.

The platform floor rose in July 2026. Claude Code v2.1.210 hardened the Agent tool against indirect prompt injection carried in content a subagent read — a poisoned file, web page, or tool result pulled in by a subagent has less ability to steer the delegation surface itself.⁶⁹ And v2.1.211 hardened the human link in the chain: permission previews now neutralize bidirectional-override, zero-width, and look-alike Unicode characters, so a command can no longer be crafted to display as innocuous in the approval dialog while executing something else.⁶⁹ The second fix matters most for harnesses where a human approves rendered previews under time pressure — the display was an injection surface too. Neither change replaces the hook-level defenses above; they raise the floor beneath them.

Agent Logs and Guardrails Are Security Surfaces

Two May 2026 advisories reinforce a pattern: agent infrastructure creates new places for sensitive content and executable policy to leak or escape. GitHub Advisory GHSA-f3jg-756w-gm35 covers a Gryph Agents payload-filter issue where sensitive tool-payload content could remain in local SQLite logs under default logging behavior.⁴⁵ OSV GHSA-wxxx-gvqv-xp7p covers a LiteLLM custom-code guardrail sandbox escape in an admin-protected proxy endpoint.⁴⁶

The production rule: treat agent transcripts, tool payloads, SQLite logs, and guardrail execution as sensitive infrastructure. Redact before persistence, apply retention limits, and keep custom guardrail code sandboxed and reviewable. A prompt-level “do not log secrets” rule is not enough; the logging and guardrail path needs deterministic tests.

Hook Security

HTTP hooks that interpolate environment variables into headers require an explicit allowedEnvVars list to prevent arbitrary environment variable exfiltration:¹³

{
  "type": "http",
  "url": "https://api.example.com/notify",
  "headers": {
    "Authorization": "Bearer $MY_TOKEN"
  },
  "allowedEnvVars": ["MY_TOKEN"]
}

The Human-Agent Division of Responsibility

Security in agent architectures requires a clear division between human and agent responsibilities:¹⁷

The pattern: humans own decisions that require organizational context, ethical judgment, or strategic direction. Agents own decisions that require computational search across large possibility spaces. Hooks enforce the boundary.

Recursive Hook Enforcement

Hooks fire for subagent actions too.¹³ If Claude spawns a subagent via the Agent tool, your PreToolUse and PostToolUse hooks execute for every tool the subagent uses. Without recursive hook enforcement, a subagent could bypass your safety gates. The SubagentStop event lets you run cleanup or validation when a subagent completes.

This is not optional. An agent that spawns a subagent without your security hooks is an agent that can force-push to main, read credential files, or run destructive commands while your gates watch the main conversation do nothing.

Cost as Architecture

Cost is an architectural decision, not an operational afterthought.² Three levels:

Token level. System prompt compression. Remove tutorial code examples (the model knows the APIs), collapse duplicate rules across files, and replace explanations with constraints. “Reject tool calls matching sensitive paths” does the same work as a 15-line explanation of why credentials should not be read.

Agent level. Fresh spawns over long conversations. Each story in an autonomous run gets a new agent with a clean context. The context never balloons because each agent starts fresh. Briefing instead of memory: models execute a clear briefing better than they navigate 30 steps of accumulated context.

Architecture level. CLI-first over MCP when the operation is stateless. A claude --print call for a one-shot evaluation costs less and adds no connection overhead. MCP makes sense when the tool needs persistent state or streaming.

Decision Framework

When to use each mechanism:

Skills vs Hooks vs Subagents

FAQ

How many hooks is too many?

Performance, not count, is the constraint. Each hook runs synchronously, so total hook execution time adds to every matched tool call. 95 hooks across user-level and project-level settings run without noticeable latency when each hook completes in under 200ms. The threshold to watch: if a PostToolUse hook adds more than 500ms to every file edit, the session feels sluggish. Profile your hooks with time before deploying them.¹⁴

Can hooks block Claude Code from running a command?

Yes. PreToolUse hooks block any tool action by exiting with code 2. Claude Code cancels the pending action and shows the hook’s stderr output to the model. Claude sees the rejection reason and suggests a safer alternative. Exit 1 is a non-blocking warning where the action still proceeds.³

Where should I put hook configuration files?

Hook configurations go in .claude/settings.json for project-level hooks (committed to your repository, shared with your team) or ~/.claude/settings.json for user-level hooks (personal, applied to every project). Project-level hooks take precedence when both exist. Use absolute paths for script files to avoid working-directory issues.¹⁴

Does every decision need deliberation?

No. The confidence module scores decisions across four dimensions (ambiguity, complexity, stakes, context dependency). Only decisions scoring below 0.70 overall confidence trigger deliberation, roughly 10% of total decisions. Documentation fixes, variable renames, and routine edits skip deliberation entirely. Security architecture, database schema changes, and irreversible deployments trigger it consistently.⁷

How do I test a system designed to produce disagreement?

Test both success paths and failure paths. Success: agents disagree productively and reach consensus. Failure: agents converge too quickly, never converge, or exceed spawn budgets. End-to-end tests simulate each scenario with deterministic agent responses, verifying that both validation gates catch every documented failure mode. A production deliberation system runs 141 tests across three layers: 48 bash integration tests, 81 Python unit tests, and 12 end-to-end pipeline simulations.⁷

What is the latency impact of deliberation?

A 3-agent deliberation adds 30-60 seconds of wall-clock time (agents run sequentially through the Agent tool). A 10-agent deliberation adds 2-4 minutes. The consensus and pride check hooks each run in under 200ms. The primary bottleneck is LLM inference time per agent, not orchestration overhead.⁷

How long should a CLAUDE.md file be?

Keep each section under 50 lines and the total file under 150 lines. Long files get truncated by context windows, so front-load the most critical instructions: commands and closure definitions before style preferences.²¹

Can this work with tools other than Claude Code?

The architectural principles (hooks as deterministic gates, skills as domain expertise, subagents as isolated contexts, filesystem as memory) apply conceptually to any agentic system. The specific implementation uses Claude Code’s lifecycle events, matcher patterns, and Agent tool. AGENTS.md carries the same patterns to Codex, Cursor, Copilot, Amp, and Windsurf.²¹ The harness pattern is tool-agnostic even if the implementation details are tool-specific.

Quick Reference Card

Hook Configuration

{
  "hooks": {
    "PreToolUse": [{"matcher": "Bash", "hooks": [{"type": "command", "command": "script.sh"}]}],
    "PostToolUse": [{"matcher": "Write|Edit", "hooks": [{"type": "command", "command": "format.sh"}]}],
    "Stop": [{"matcher": "", "hooks": [{"type": "agent", "prompt": "Verify tests pass. $ARGUMENTS"}]}],
    "SessionStart": [{"matcher": "", "hooks": [{"type": "command", "command": "setup.sh"}]}]
  }
}

Skill Frontmatter

---
name: my-skill
description: What it does and when to use it. Include trigger phrases.
allowed-tools: Read, Grep, Glob
---

Subagent Definition

---
name: my-agent
description: When to invoke. Include PROACTIVELY for auto-delegation.
tools: Read, Grep, Glob, Bash
model: opus
permissionMode: plan
---

Instructions for the subagent.

Exit Codes

Key Commands

File Locations

Changelog

References