The Harness Is the Machine: Task Contracts, Worktrees, Receipts

A complete architectural guide to task contracts, isolated worktrees, adversarial verification, and the compounding flywheel across Opus, Sonnet, Haiku, and Fable 5.5

bookmark this and read the complete production agent playbook below ↓

When an autonomous AI agent fails 14 turns into a multi-file refactor, most developers make the same mistake

They rewrite the prompt

Then they switch models

Then they upgrade to a larger context window

The agent still forgets earlier decisions. It still modifies the wrong files. It still outputs: All 48 unit tests passed successfully, without running a test runner

The failure comes from the environment around the model. That environment is the harness. Designing it is Harness Engineering

Dario Amodei, CEO of Anthropic, explained this during the launch of Claude Code:

Of course, you need an interface, you need a harness to use them

The model is the engine. The harness is the machine

Put Claude Sonnet 5.5 into an unmanaged chat window, and it achieves an 18% success rate on complex multi-file engineering tasks. Put that same model into an engineered harness with path boundaries, isolated git worktrees, sub-second linter sensors, and adversarial verification, and task completion reaches 95%

Below is the complete architectural blueprint for building production autonomous agents using Claude Code and the Anthropic 5.5 model stack across Opus 5.5, Sonnet 5.5, Haiku 5.5, and Fable 5.5

• Stage 1: Pre-Flight Task Contract Human intent compiles into a bounded task_contract.json via Claude Opus 5.5

• Stage 2: Sandboxed Worktree Isolation Harness spawns an isolated git worktree before any tool executes

• Stage 3: Autonomous Implementation Claude Sonnet 5.5 executes code modifications within strict path allowlists

• Stage 4: Sub-Second Sensor Interception Claude Haiku 5.5 validates every bash tool call and parameter in real time

• Stage 5: Adversarial Red-Teaming Claude Fable 5.5 attacks the diff, searching race conditions and edge cases

• Stage 6: Deterministic Evidence Gate Physical pre-commit hook verifies test output and signs receipt.json

• Stage 7: Compounding Memory Flywheel Failures crystallize into permanent rules, skills, and regression evals on disk

Observing the same model across two operating environments explains why autonomous agents break down:

System Breakdown: Raw Chat Window vs. Engineered Harness

Execution Surface

• Raw Chat: Flat string buffer with interleaved chat history

• Engineered Harness: Sandboxed git worktree filesystem plus state ledger files Task Boundaries

• Raw Chat: Open-ended conversational prompt (e.g. Refactor auth)

• Engineered Harness: Machine-readable JSON contract with strict path allowlists Tool Execution

• Raw Chat: Unchecked tool calls where the model self-approves syntax

• Engineered Harness: Pre-tool hooks and static typecheckers intercepting all inputs State Persistence

• Raw Chat: Transient context window that dies when the session terminates

• Engineered Harness: Durable append-only ledger persisted directly to disk Verification Logic

• Raw Chat: Model validates itself and claims the code works

• Engineered Harness: Decoupled skeptic agent (Claude Fable 5.5) proving test logs Failure Recovery

• Raw Chat: Human reprompts while the model invents new excuses

• Engineered Harness: Automatic rollback to clean checkpoint hash, recording failure to evals End-to-End Success Rate

• Raw Chat: 18% completion on complex multi-turn workflows

• Engineered Harness: 95% deterministic task convergence

When an agent runs in a chat window, context pollution compounds with every turn. By turn 8, earlier instructions drown under thousands of tokens of raw tool output. The model begins guessing parameter names and enters repetitive error loops

The harness converts conversation into stateful software infrastructure

Building production agents on a single model fails economically. Running Opus 5.5 for file linting burns budget at $15 per million tokens. Running Haiku 5.5 for system decomposition breaks the architecture

A production harness uses role specialization:

The Claude 5.5 Harness Role Division

Claude Opus 5.5 (Lead Architect and Arbiter)

• Assignment: Generates task contracts, reviews architectural invariants, settles merge conflicts

• Economics: High reasoning depth at $15.00 per million tokens Claude Sonnet 5.5 (Autonomous Engineer)

• Assignment: Writes production code, modifies modules, executes bash tool calls

• Economics: Fast agentic coding at $3.00 per million tokens Claude Haiku 5.5 (Sub-Second Gatekeeper)

• Assignment: Validates tool parameters, enforces path bounds, runs linters

• Economics: Millisecond response latency at $0.25 per million tokens Claude Fable 5.5 (Adversarial Skeptic)

• Assignment: Attacks code diffs, fuzzes boundary cases, searches race conditions

• Economics: Hostile security red-teaming at $2.50 per million tokens

An autonomous agent must not write code from conversational instructions. Before Claude Sonnet 5.5 generates token 1, Claude Opus 5.5 compiles a machine-readable task_contract.json

The contract defines four boundaries:

1. Path Boundary (filesystem_boundary): Explicit list of files the agent can read and edit. Any attempt to touch .env or root package files triggers an immediate interrupt

2. Economic Envelope (budget): Hard limits on dollar spend, conversation turns, and wall-clock execution seconds

3. Acceptance Invariants (acceptance_criteria): Deterministic shell commands that must exit with code 0

4. Required Artifacts (required_evidence): Verification files that must exist on disk before the task closes

{
  "$schema": "https://anthropic.com/schemas/agent-contract-v1.json",
  "task_id": "refactor-session-auth-842",
  "created_at": "2026-11-04T19:30:00Z",
  "architect_model": "claude-opus-5-5",
  "worker_model": "claude-sonnet-5-5",
  "budget": {
    "max_cost_usd": 4.50,
    "max_turns": 20,
    "timeout_seconds": 600
  },
  "filesystem_boundary": {
    "allowed_read": [
      "src/auth/",
      "src/types/auth.ts",
      "tests/auth/",
      "package.json"
    ],
    "allowed_write": [
      "src/auth/jwt.ts",
      "src/auth/session_manager.ts",
      "tests/auth/jwt.test.ts"
    ],
    "forbidden_write": [
      ".env",
      "src/database/",
      "infra/",
      "package.json"
    ]
  },
  "acceptance_criteria": [
    {
      "type": "command",
      "exec": "npm run test:auth",
      "expected_exit_code": 0
    },
    {
      "type": "command",
      "exec": "npx tsc --noEmit",
      "expected_exit_code": 0
    },
    {
      "type": "evidence",
      "artifact_path": ".claude/receipts/receipt-refactor-session-auth-842.json"
    }
  ]
}

System Prompt: Opus 5.5 Contract Architect

You are the Lead System Architect operating inside Claude Code
Your sole job is to translate human feature requests and bug reports into a deterministic, bounded task contract

You do not write application code. You do not make assumptions
You analyze the repository structure and emit a valid JSON object matching the task_contract schema

Rules:
1. Never grant write access to root config files, environment secrets, or package manager lockfiles unless explicitly mandated
2. Define unambiguous, deterministic shell commands as acceptance criteria (e.g. npm test, pytest tests/unit/)
3. Estimate the economic envelope: assign strict limits for cost ($USD), conversation turns, and execution seconds
4. Restrict the write boundary to the minimum viable module

Output valid JSON only

Dumping 150,000 tokens of repository text into Claude Code triggers three failures:

1. Context Smearing: Attention over critical invariants degrades

2. Economic Waste: Every turn pays the full input token tax

3. Branch Contamination: Editing the live working branch leaves half-finished code that halts other engineers

Production harnesses use Topological Context and Worktree Isolation

1. The Root Map: Production CLAUDE.md

CLAUDE.md functions as an index map that directs attention to specific documentation nodes on demand:

Architecture Invariants
- Runtime: Node.js v22.x LTS, TypeScript v5.7
- Framework: Fastify (Strict schema-first routing)
- Storage: PostgreSQL via Prisma ORM, Redis for token revocation

Topological Directory Map
- src/auth/: JWT issuance, refresh rotation, cryptographic signatures
- src/middleware/: Fastify request lifecycle hooks and rate limiters
- tests/fixtures/: Synthetic database seeds and test tokens
- .claude/state/: Durable agent session ledgers and change receipts

Operational Rules
1. Never execute raw SQL queries; use Prisma client methods
2. Never commit code directly to main or develop
3. All code modifications must execute within .agent_worktrees/
4. Run npm run lint and npm run test before declaring task completion

2. Physical Isolation: isolate_worktree.sh

Instead of modifying the main working tree, the harness clones the repository into an isolated sandbox:

set -euo pipefail

TASK_ID="${1:-task-$(date +%s)}"
BASE_BRANCH="${2:-main}"
WORKTREE_PATH=".agent_worktrees/${TASK_ID}"

echo "[HARNESS] Initializing isolated git worktree for: ${TASK_ID}"

mkdir -p .agent_worktrees
git worktree add -b "agent/${TASK_ID}" "${WORKTREE_PATH}" "${BASE_BRANCH}"

if [ -f .env.example ]; then
    cp .env.example "${WORKTREE_PATH}/.env"
fi

echo "[HARNESS] Isolated worktree ready at ${WORKTREE_PATH}"
echo "[HARNESS] Launching Claude Code in sandboxed boundary..."

cd "${WORKTREE_PATH}"
claude --dangerously-skip-permissions false

Most agent failures stem from mixing reasoning, execution, and memory inside one chat thread

A production harness separates the system into three distinct planes:

1. Brain Plane (Neural Weights): Claude Opus 5.5 for architecture, Claude Sonnet 5.5 for code implementation

2. Hands Plane (Execution Environment): Containerized bash, language runtimes, pre-tool interceptors

3. History Plane (Durable Substrate): Git worktrees, state files on disk, and decision_ledger.jsonl

Directory Architecture for Claude Code Production Harness:

my-project/
  CLAUDE.md
  .agent_worktrees/
  .claude/
    config.json
    contracts/
      task-auth-842.json
    hooks/
      pre-tool.sh
      post-tool.sh
    receipts/
      receipt-auth-842.json
    skills/
      audit-diff.sh
    state/
      decision_ledger.jsonl

A model must not evaluate its own code. If Claude Sonnet 5.5 writes an authentication module, its self-review overlooks its own assumptions. It claims: The implementation handles all race conditions and passed tests

Production systems separate generation from verification:

1. Claude Sonnet 5.5 builds the code

2. Claude Fable 5.5 acts as an Adversarial Skeptic with instructions to challenge the pull request

3. Claude Haiku 5.5 executes as a physical gatekeeper hook that intercepts shell commands before execution

System Prompt: Fable 5.5 Adversarial Skeptic

You are the Lead Security Skeptic and Red Teamer in this repository
Claude Sonnet 5.5 has proposed a code modification. Your goal is to DISPROVE its correctness

You are not here to write praise
Your mission is to find reasons why this code will crash in production under scale, concurrency, or malicious input

Audit Checklist:
1. Concurrency: What happens if two requests arrive with identical payloads at the same millisecond?
2. Boundary Conditions: What happens with null, empty arrays, MAX_INT, or malformed UTF-8 inputs?
3. State Invariants: Does this commit mutate database state without a surrounding transactional rollback boundary?
4. Path Leaks: Did the worker touch or read any file outside its contract allowlist?

If you find a flaw, output:
STATUS: REJECTED
REASON: <Detailed vulnerability reproduction trace>

If you cannot break the implementation after hostile scrutiny, output:
STATUS: APPROVED
EVIDENCE: <Test command outputs and invariant proof>

Hook Script: .claude/hooks/pre-tool.sh

set -euo pipefail

TOOL_NAME="$1"
TOOL_INPUT_JSON="$2"

if [ "${TOOL_NAME}" = "Bash" ]; then
    COMMAND=$(echo "${TOOL_INPUT_JSON}" | jq -r '.command // empty')
    
    if [[ "${COMMAND}" =~ "git commit" ]] || [[ "${COMMAND}" =~ "git push" ]]; then
        echo "[SECURITY GATE] Git commit detected. Verifying change receipt..."
        
        RECEIPT_FILE=$(find .claude/receipts -type f 2>/dev/null | grep "receipt-" | head -n 1 || true)
        
        if [ -z "${RECEIPT_FILE}" ]; then
            echo "[SECURITY ERROR] No change receipt found in .claude/receipts/"
            echo "[SECURITY ERROR] Action aborted. Run verification before committing"
            exit 1
        fi
        
        VERDICT=$(jq -r '.verifier_verdict.status // empty' "${RECEIPT_FILE}")
        if [ "${VERDICT}" != "APPROVED" ]; then
            echo "[SECURITY ERROR] Receipt verdict is '${VERDICT}', not 'APPROVED'"
            echo "[SECURITY ERROR] Commit blocked by Adversarial Skeptic Gate"
            exit 1
        fi
        
        echo "[SECURITY GATE] Verified receipt: ${RECEIPT_FILE}. Authorization granted"
    fi
fi

exit 0

In physical manufacturing, technicians do not install an aircraft component without an inspection certificate. Autonomous software engineering requires the same rule: No Receipt, No Commit

Every task writes a signed receipt-{task_id}.json to disk before the harness permits merging into the base branch

Change Receipt: receipt-refactor-session-auth-842.json

{
  "receipt_id": "rcpt-20261104-99124",
  "task_id": "refactor-session-auth-842",
  "timestamp": "2026-11-04T19:38:12Z",
  "worker_model": "claude-sonnet-5-5",
  "verifier_model": "claude-fable-5-5",
  "git_worktree": ".agent_worktrees/refactor-session-auth-842",
  "head_commit_hash": "e7b8c4d21f890a3b",
  "diff_summary": {
    "files_changed": 2,
    "insertions": 54,
    "deletions": 11,
    "modified_files": [
      "src/auth/jwt.ts",
      "src/auth/session_manager.ts"
    ]
  },
  "deterministic_evidence": {
    "test_command": "npm run test:auth",
    "exit_code": 0,
    "tests_passed": 18,
    "tests_failed": 0,
    "typecheck_command": "npx tsc --noEmit",
    "typecheck_exit_code": 0
  },
  "verifier_verdict": {
    "status": "APPROVED",
    "fuzzed_scenarios": [
      "expired_refresh_token_replay",
      "empty_bearer_header_injection",
      "concurrent_session_revocation"
    ],
    "cryptographic_signature": "sha256:4f89d3bc281e09"
  }
}

The largest financial leak in agent development is transient debugging

A developer spends an hour correcting an agent. They point out an unexported type, an unhandled database transaction, or a violated schema. The agent fixes it, the session closes, and the terminal terminates

The next morning, the model starts from scratch. The team pays for the same intelligence, makes the same manual corrections, and burns the same token budget

A production harness converts failures into permanent software assets through four crystallization stages:

1. Runtime Incident: The agent fails a test or violates an invariant

2. Invariant Rule Extraction: Opus 5.5 synthesizes the negative constraint into .claude/rules/database_invariants.md

3. Executable Skill Synthesis: The procedural fix compiles into a bash tool in .claude/skills/verify-schema.sh

4. Regression Eval Hardening: The failing case joins the evals/ test suite to prevent regressions

Skill Script: .claude/skills/audit-diff.sh

set -euo pipefail

CONTRACT_FILE="${1:-.claude/contracts/active_contract.json}"

if [ ! -f "${CONTRACT_FILE}" ]; then
    echo "[SKILL ERROR] Active contract file not found: ${CONTRACT_FILE}"
    exit 1
fi

echo "[SKILL] Auditing modified files against contract path allowlist..."
ALLOWED_FILES=$(jq -r '.filesystem_boundary.allowed_write[]' "${CONTRACT_FILE}")
MODIFIED_FILES=$(git diff --name-only origin/main)

for file in ${MODIFIED_FILES}; do
    MATCH=false
    for pattern in ${ALLOWED_FILES}; do
        if [[ "${file}" == ${pattern} ]]; then
            MATCH=true
            break
        fi
    done
    if [ "${MATCH}" = false ]; then
        echo "[SECURITY VIOLATION] File '${file}' is not in the contract write allowlist"
        exit 1
    fi
done

echo "[SKILL] Path boundaries validated successfully"
echo "[SKILL] Executing static type check..."
npx tsc --noEmit
echo "[SKILL] All checks passed. Diff is safe for adversarial review"

Audit the workspace against this 10-point checklist before launching Claude Code on tasks longer than 15 minutes:

1. Path Allowlist Enforced: filesystem_boundary is defined with explicit allowlists in task_contract.json

2. Worktree Physical Isolation: The agent operates inside .agent_worktrees/ rather than the active branch

3. Top-Level Context Map: CLAUDE.md stays under 150 lines and serves as an index rather than an encyclopedia

4. Model Role Specialization: Roles divide across Opus 5.5 (Contract), Sonnet 5.5 (Worker), Haiku 5.5 (Linter), and Fable 5.5 (Skeptic)

5. Physical Tool Gatekeeper: .claude/hooks/pre-tool.sh intercepts git commit to enforce receipt verification

6. Decoupled Verification: Self-approval is disabled; verification requires an adversarial audit from Fable 5.5

7. Deterministic Acceptance Tests: The contract requires shell commands (npm test, pytest) to exit with code 0

8. Durable State on Disk: Session memory writes to .claude/state/decision_ledger.jsonl rather than the chat buffer

9. Change Receipt Generated: The completed task outputs a structured receipt-{task_id}.json containing diff stats and test logs

10. Financial Circuit Breaker: An economic envelope (budget.max_cost_usd) halts runaway loops automatically

Prompt engineering treated frontier models like magic chat boxes that required the right combination of words

Harness Engineering is the industrial phase of autonomous software

Claude Opus, Sonnet, Haiku, and Fable 5.5 are stochastic reasoning engines. They do not need more adjectives in their prompts. They need deterministic boundaries, isolated filesystems, adversarial verifiers, and physical circuit breakers

Investing in the harness turns model execution from a roulette wheel into predictable, composable, production-grade software infrastructure

bookmark this and share it with your engineering team before deploying your next autonomous agent cluster ↓

additional alpha - https://t.me/+-e0O9zoaMvQ1NjAy

~marfin