Inside AI Coding Agent Harnesses: OpenCode & Claude Code

The Illusion of the "Autonomous Model"

When developers watch an AI agent fix a complex race condition across four files, run an automated test suite, and submit a formatted Git commit, it is easy to assume the foundation model is doing all the heavy lifting.

In reality, a raw Large Language Model is just a statistical token predictor. It cannot read a file from your SSD, it cannot spawn a child process in bash, it cannot parse a compiler error code, and it has no memory of what it did three turns ago once its context window resets.

The engine that gives a model hands, eyes, and operational memory is the Agent Harness.

┌─────────────────────────────────────────────────────────────────────────┐
│                        AI CODING AGENT HARNESS                          │
│                                                                         │
│  ┌───────────────────────┐  Tool Calls   ┌───────────────────────────┐  │
│  │ Context & File Index  │ ◄───────────► │ Tool Dispatcher (Bash/MCP)│  │
│  └───────────────────────┘               └───────────────────────────┘  │
│             ▲                                          ▲                │
│             │ State & History           Executes Code  │                │
│             ▼                                          ▼                │
│  ┌───────────────────────┐               ┌───────────────────────────┐  │
│  │ Compaction & Pruning  │               │ Sandbox & Security Guards │  │
│  └───────────────────────┘               └───────────────────────────┘  │
└────────────────────────────────────┬────────────────────────────────────┘
                                     │ Filtered Prompts & Tool Definitions
                                     ▼
                    ┌─────────────────────────────────┐
                    │ RAW FOUNDATION MODEL (API)      │
                    │ Claude 3.7 / DeepSeek-V3 / GPT  │
                    └─────────────────────────────────┘

The difference between a model getting stuck in an infinite retry loop versus resolving a real GitHub issue on the first attempt almost never comes down to raw model parameters. It comes down to the engineering quality of the harness wrapping it.

Whether you are using terminal agents like Claude Code, extensible orchestration engines like OpenCode, or research harnesses benchmarking DeepSeek against SWE-bench, here is how modern agent harnesses actually work under the hood.

---

1. The Core Architecture of an Agent Harness

An agent harness is the complete software runtime that surrounds a model. It operates as an event-driven control loop responsible for five critical subsystems:

┌──────────────────────────────────────────────────────────────────────────┐
│ 1. Tool Protocol & Dispatch (Bash, Filesystem, LSP, MCP)                 │
├──────────────────────────────────────────────────────────────────────────┤
│ 2. Context Window Management & Token Compaction                          │
├──────────────────────────────────────────────────────────────────────────┤
│ 3. Multi-Agent Orchestration & Subagent Pipelines                        │
├──────────────────────────────────────────────────────────────────────────┤
│ 4. Deterministic Patching & Diff Application                             │
├──────────────────────────────────────────────────────────────────────────┤
│ 5. Execution Sandboxing & Security Interception                          │
└──────────────────────────────────────────────────────────────────────────┘

Subsystem 1: Tool Protocol & The Dispatch Loop

When an LLM wants to run a shell command, it does not execute anything directly. It emits a structured tool-call object:

{
  "name": "run_command",
  "parameters": {
    "CommandLine": "npm test -- tests/auth.spec.ts",
    "Cwd": "/workspace/project"
  }
}

The harness intercepts this call, checks permissions, launches a child process in a sandboxed shell, captures standard output (stdout) and standard error (stderr), truncates excessive log buffers, and formats the output back into a user/system message for the model’s next iteration.

Subsystem 2: Multi-Turn Context Compaction

A terminal coding session can easily generate 500,000 tokens of file contents, compiler stack traces, and linter warnings.

Because LLM context windows are finite and expensive, the harness maintains a rolling memory index. When token consumption crosses an established threshold (e.g., 75% of max context), the harness:

1. Summarizes completed milestones into structured state blocks.
2. Evicts raw tool execution outputs (keeping only exit codes and error summaries).
3. Preserves the active system prompt, current modified files, and active plan.

---

2. Comparing the Major Harness Architectures

Not all coding harnesses approach autonomous problem-solving the same way. The ecosystem in 2026 has coalesced around three distinct architectural philosophies:

---

3. Deep Dive: The OpenCode Multi-Agent Pipeline

While monolithic harnesses execute all operations through a single generalist prompt, engines like OpenCode divide problem-solving into specialized, staged subagents.

Instead of asking one model instance to plan, code, review, and test simultaneously (which frequently causes catastrophic hallucination cascades), OpenCode chains distinct specialized agent configurations:

┌──────────────┐     ┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│ Stage 1:     │     │ Stage 2:     │     │ Stage 3:     │     │ Stage 4:     │
│ Scope Analyst│ ──► │ Architect    │ ──► │ Coder Agent  │ ──► │ Code Reviewer│
└──────────────┘     └──────────────┘     └──────────────┘     └──────────────┘
  Refines user         Creates verified     Executes diffs       Adversarial
  requirements         implementation plan  via tools            correctness audit

Why Role Separation Matters in Production

When a single model generates code and immediately reviews its own work in the same context, it suffers from confirmation bias. It routinely ignores syntax bugs and logic flaws because its own generation weights dominate the attention matrix.

By handing the git diff to a clean subagent (reviewer) with a dedicated prompt that treats the output adversarially, the harness catches regressions before changes touch the working branch.

---

4. How Coding Harnesses Apply Diffs Reliably

One of the hardest problems in coding agent engineering is file editing reliability.

If an agent wants to change 5 lines in a 2,000-line file, asking the model to rewrite the entire file has a catastrophic failure rate:

• It burns thousands of unnecessary output tokens.
• The model frequently drops unrelated functions (hallucinating // ... rest of code remains unchanged ...).
• Indentation and formatting get mangled.

Modern harnesses use three distinct patching strategies:

┌─────────────────────────────────────────────────────────────────────────┐
│ 1. Exact Substring Search & Replace (`replace_file_content`)            │
│    Model passes exact `TargetContent` and `ReplacementContent`.         │
│    Fastest, zero-dependency, but fails if whitespace changes.           │
├─────────────────────────────────────────────────────────────────────────┤
│ 2. Unified Diff Patching (`git apply` / unidiff)                        │
│    Model emits standard hunk headers (`@@ -42,7 +42,8 @@`).            │
│    Reliable for Git workflows; rejects cleanly on conflicts.           │
├─────────────────────────────────────────────────────────────────────────┤
│ 3. AST-Aware Structural Replacement (Tree-sitter)                       │
│    Harness parses code into an Abstract Syntax Tree and replaces        │
│    entire node definitions (functions, classes) by identifier.          │
└─────────────────────────────────────────────────────────────────────────┘

Here is how an exact-block replacer is implemented inside a production TypeScript harness:

import { readFileSync, writeFileSync } from "fs";

export interface ReplacementChunk {
  startLine: number;
  endLine: number;
  targetContent: string;
  replacementContent: string;
}

export function applyPrecisePatch(filePath: string, chunk: ReplacementChunk): { success: boolean; error?: string } {
  const rawFile = readFileSync(filePath, "utf-8");
  const lines = rawFile.split("\n");

  // Validate line boundaries
  if (chunk.startLine < 1 || chunk.endLine > lines.length || chunk.startLine > chunk.endLine) {
    return { success: false, error: `Invalid line range [${chunk.startLine}, ${chunk.endLine}] in file with ${lines.length} lines.` };
  }

  // Extract candidate slice
  const targetSlice = lines.slice(chunk.startLine - 1, chunk.endLine).join("\n");

  // Normalize line endings to avoid CRLF / LF mismatches
  const normalizedSlice = targetSlice.replace(/\r\n/g, "\n");
  const normalizedTarget = chunk.targetContent.replace(/\r\n/g, "\n");

  if (!normalizedSlice.includes(normalizedTarget)) {
    return {
      success: false,
      error: `Target content does not match existing code at lines ${chunk.startLine}-${chunk.endLine}. Search failed.`
    };
  }

  // Replace exact block
  const updatedSlice = normalizedSlice.replace(normalizedTarget, chunk.replacementContent.replace(/\r\n/g, "\n"));
  
  const beforeLines = lines.slice(0, chunk.startLine - 1);
  const afterLines = lines.slice(chunk.endLine);

  const finalContent = [...beforeLines, updatedSlice, ...afterLines].join("\n");
  writeFileSync(filePath, finalContent, "utf-8");

  return { success: true };
}

---

5. Building a Minimal Autonomous Agent Harness

To understand how terminal agents like Claude Code or DeepSeek runners work, here is a functional, single-file TypeScript implementation of an agent dispatch loop with bash execution, file tools, and circuit breakers:

import { spawn } from "child_process";
import { readFileSync, writeFileSync, existsSync } from "fs";
import Anthropic from "@anthropic-ai/sdk";

const anthropic = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });

// 1. Define Supported Tools
const harnessTools: Anthropic.Tool[] = [
  {
    name: "execute_shell",
    description: "Run a shell command on the host system and return stdout/stderr",
    input_schema: {
      type: "object",
      properties: {
        command: { type: "string", description: "The bash command to execute" },
      },
      required: ["command"],
    },
  },
  {
    name: "read_file",
    description: "Read text contents of a file",
    input_schema: {
      type: "object",
      properties: {
        path: { type: "string", description: "Relative file path" },
      },
      required: ["path"],
    },
  },
  {
    name: "write_file",
    description: "Overwrite or create a file with new content",
    input_schema: {
      type: "object",
      properties: {
        path: { type: "string", description: "Target file path" },
        content: { type: "string", description: "Full file content" },
      },
      required: ["path", "content"],
    },
  }
];

// 2. Tool Execution Runtime
async function handleToolCall(name: string, input: any): Promise<string> {
  if (name === "read_file") {
    if (!existsSync(input.path)) return `Error: File "${input.path}" does not exist.`;
    return readFileSync(input.path, "utf-8");
  }

  if (name === "write_file") {
    writeFileSync(input.path, input.content, "utf-8");
    return `Successfully wrote ${input.content.length} characters to ${input.path}.`;
  }

  if (name === "execute_shell") {
    return new Promise((resolve) => {
      const proc = spawn(input.command, { shell: true });
      let output = "";
      proc.stdout.on("data", (data) => { output += data.toString(); });
      proc.stderr.on("data", (data) => { output += data.toString(); });
      proc.on("close", (code) => {
        resolve(`[Exit Code ${code}]\n${output.slice(0, 4000)}`); // Limit output buffer
      });
    });
  }

  return `Error: Unknown tool "${name}"`;
}

// 3. Autonomous Execution Loop
export async function runAgentHarness(taskPrompt: string, maxIterations = 15) {
  const messages: Anthropic.MessageParam[] = [
    { role: "user", content: taskPrompt }
  ];

  console.log(`🤖 Agent harness started for task: "${taskPrompt}"\n`);

  for (let iteration = 1; iteration <= maxIterations; iteration++) {
    console.log(`--- [Iteration ${iteration}/${maxIterations}] ---`);

    const response = await anthropic.messages.create({
      model: "claude-3-7-sonnet-20250219",
      max_tokens: 2048,
      tools: harnessTools,
      system: "You are an autonomous senior software engineer. Solve the user's task using available tools. When finished, summarize your changes.",
      messages,
    });

    // Append assistant response to context
    messages.push({ role: "assistant", content: response.content });

    // Check if the agent is done (no tool calls emitted)
    const toolCalls = response.content.filter((c) => c.type === "tool_use");
    if (toolCalls.length === 0) {
      console.log("\n✅ Task completed autonomously by agent.");
      const textBlock = response.content.find((c) => c.type === "text");
      return textBlock?.type === "text" ? textBlock.text : "Done.";
    }

    // Execute each tool and return results to the model
    const toolResultContents: Anthropic.ToolResultBlockParam[] = [];
    for (const tool of toolCalls) {
      if (tool.type === "tool_use") {
        console.log(`⚙️ Executing Tool: ${tool.name}(${JSON.stringify(tool.input)})`);
        const result = await handleToolCall(tool.name, tool.input);
        toolResultContents.push({
          type: "tool_result",
          tool_use_id: tool.id,
          content: result,
        });
      }
    }

    messages.push({ role: "user", content: toolResultContents });
  }

  throw new Error("Circuit breaker triggered: Agent exceeded maximum iterations.");
}

---

6. Security & Sandboxing: Preventing Agent Catastrophes

Giving an AI model access to a bash terminal without defensive guardrails is dangerous. In production, coding agent harnesses implement three essential security perimeters:

1. SSRF & Network Filtering

When an agent is allowed to query APIs or scrape documentation, it must never be allowed to access internal network endpoints:

• Block loopback ranges (127.0.0.1, localhost, ::1).
• Block private IP space (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16).
• Block cloud instance metadata services (169.254.169.254).

2. Forbidden Command Interception

The dispatch loop inspects every shell string before execution. Dangerous system-level commands (like rm -rf /, mkfs, raw disk writes, or modifying /etc/passwd) are blocked deterministically by the harness, bypassing the LLM entirely.

3. Human Approval Gates for Destructive Operations

For operations with high blast radiuses (e.g., git push --force, database drop migrations, or deploying cloud functions), the harness pauses execution and prompts the developer for explicit confirmation in the terminal.

---

The Future of Coding Agent Harnesses

As models like Claude 3.7 Sonnet, DeepSeek-V3, and o3-mini continue to commoditize raw reasoning capabilities, the competitive advantage shifts entirely to the harness.

The developers and companies building the most effective AI workflows are not just prompting better. They are engineering smarter context compaction, faster AST diff application, modular subagent pipelines, and native Model Context Protocol (MCP) integrations.

To explore real-world agent configuration files, check out our catalog of copy-ready Agent Skills and curated MCP Server Integrations.