Dismantling Pseudo-Agency: Deconstructing Harness Engineering in learn-claude-code

1. The Core Bottleneck: Engineering Reality vs. Workflow Hype

The software industry has drowned itself in a prompt-plumbing delusion. Engineering teams spend weeks wiring together brittle, drag-and-drop workflow platforms, connecting dozens of decision diamonds and static if-else branches, convincing themselves they are engineering intelligence. In production, these hardcoded graph pipelines break immediately. When an LLM hits an edge case, deterministic rule engines enter recursive failure states, context windows blow up, and developer velocity grinds to a complete halt.

The learn-claude-code repository by shareAI-lab demolishes this illusion. By examining the structural lineage running through DeepMind DQN, OpenAI Five, and modern software engineering LLMs, it makes a fundamental computer science assertion: Agency is never born out of application code. Agency is an intrinsic, learned capability baked into model weights through gradient descent and reinforcement learning. Application engineers do not create agents. Application engineers build harnesses.

💡 Core Architectural Insight: Agency belongs entirely to model training; the external codebase exists only to supply an operating vehicle—a deterministic harness comprising atomic tools, on-demand domain context, curated state observation, and permission boundaries.

This shift completely reframes the engineering challenge. The goal transitions from constructing brittle procedural rules to implementing atomic, zero-overhead execution harnesses that provide the model with transparent operational boundaries.

2. Core Architecture and Underlying Data Flow

learn-claude-code discards multi-agent bureaucracy in favor of a clean, high-performance control loop between the driver (the foundation model) and the vehicle (the environment harness). The architectural topology enforces an event-driven loop that turns host state into actionable context.

+-------------------------------------------------------------------------+
|                        HOST ENVIRONMENT / RUNTIME                       |
|                                                                         |
|   [Terminal / Filesystem] <------------+                                |
|             |                          |                                |
|      (Raw OS State)                    |                                |
|             v                          |                                |
|   +-------------------+                |                                |
|   | Observation Filter| (Diffs/Trunc)  | (Command Execution)            |
|   +-------------------+                |                                |
|             |                          |                                |
|      (Clean Evidence)                  |                                |
|             v                          |                                |
|   +-----------------------------------------------------------------+   |
|   |                     HARNESS ENGINE CORE                         |   |
|   |                                                                 |   |
|   |  +--------------------+   +----------------------------------+  |   |
|   |  |  Context Manager   |   |        Tool Interface            |  |   |
|   |  | (Pruning & Rolling)|   | (Read / Write / Bash / Glob)     |  |   |
|   |  +--------------------+   +----------------------------------+  |   |
|   +-----------------------------------------------------------------+   |
|             |                                  ^                        |
|      (Curated Context)                  (Tool Call Intent)              |
|             v                                  |                        |
|   +-----------------------------------------------------------------+   |
|   |                    FOUNDATIONAL LLM (DRIVER)                    |   |
|   |         Trained Reasoning Loop (Inference / CoT)                |   |
|   +-----------------------------------------------------------------+   |
+-------------------------------------------------------------------------+

The runtime pipeline is driven by three specific engineering constraints:

1. Observation Filtering: Unchecked output from bash processes or massive files is prohibited from polluting the context window. The harness intercepts raw logs, applies diffs, strips non-essential ANSI sequences, and compresses stdout down to deterministic evidence.
2. Dynamic Knowledge Retrieval: Architecture specs, project styles, and dependencies are never loaded statically up front. Instead, the model queries them lazily using atomic search primitives such as globbing and grep.
3. Permission Boundaries: System access is separated into safe observation tools (read-only file inspection, pattern matching) and mutated host operations (filesystem writes, shell executions). Destructive operations are routed through isolation layers and confirmation channels.

3. Technical Strategy and Benchmark Comparison

Designing infrastructure for software-focused agents requires selecting the right runtime tradeoffs. Here is how the minimal harness pattern compares directly against prevalent industry approaches:

By avoiding complex abstractions, the system minimizes serialization boundaries and hidden state mismatches. The harness pattern treats tool invocation as an exact hardware interface, allowing the model's native reasoning to navigate environment failures directly.

4. Hands-on Implementation: The Minimal Harness

The following implementation demonstrates a production-grade minimal harness in TypeScript, using the native Anthropic SDK without bloated third-party orchestration libraries.

Setup Environment

Initialize the project and pull the base dependencies:

mkdir minimal-harness && cd minimal-harness
npm init -y
npm install @anthropic-ai/sdk
npm install -D typescript @types/node tsx

Complete Executable Loop

Write the following production harness code into agent_runner.ts:

import Anthropic from "@anthropic-ai/sdk";
import { execSync } from "node:child_process";
import * as fs from "node:fs";
import * as path from "node:path";

// Initialize the native foundational driver client
const client = new Anthropic();

// Define atomic, low-level harness tools
const tools: Anthropic.Tool[] = [
  {
    name: "read_file",
    description: "Read the raw content of a local file as UTF-8 text",
    input_schema: {
      type: "object",
      properties: {
        filepath: { type: "string", description: "Relative or absolute path to the target file" },
      },
      required: ["filepath"],
    },
  },
  {
    name: "execute_command",
    description: "Execute a shell command in the local environment and capture output",
    input_schema: {
      type: "object",
      properties: {
        command: { type: "string", description: "The shell command to execute" },
      },
      required: ["command"],
    },
  },
];

// Host execution engine with strict boundaries and error catching
function executeHarnessTool(name: string, input: Record<string, unknown>): string {
  try {
    if (name === "read_file") {
      const targetPath = path.resolve(String(input.filepath));
      return fs.readFileSync(targetPath, "utf-8");
    }
    if (name === "execute_command") {
      // Bound execution time to 10s and cap output length to prevent context explosion
      const stdout = execSync(String(input.command), { timeout: 10000, encoding: "utf-8" });
      return stdout.length > 2000 ? stdout.slice(0, 2000) + "...[Output Truncated]" : stdout;
    }
    throw new Error(`Unsupported tool call: ${name}`);
  } catch (err: unknown) {
    const error = err as Error;
    return `ToolExecutionError: ${error.message}`;
  }
}

// Core driver-vehicle feedback loop
async function runHarnessLoop(taskPrompt: string) {
  const messageHistory: Anthropic.MessageParam[] = [
    { role: "user", content: taskPrompt }
  ];

  while (true) {
    const response = await client.messages.create({
      model: "claude-3-5-sonnet-latest",
      max_tokens: 4096,
      tools: tools,
      messages: messageHistory,
    });

    // Append current model reasoning and invocation intents
    messageHistory.push({ role: "assistant", content: response.content });

    if (response.stop_reason === "end_turn") {
      console.log("\n[Task Complete] Model Output:\n", response.content.find(c => c.type === "text")?.text);
      break;
    }

    if (response.stop_reason === "tool_use") {
      const toolUseBlocks = response.content.filter(
        (block): block is Anthropic.ToolUseBlock => block.type === "tool_use"
      );

      const toolResults: Anthropic.ToolResultBlockParam[] = [];

      for (const block of toolUseBlocks) {
        console.log(`[Tool Call] ${block.name}(${JSON.stringify(block.input)})`);
        const output = executeHarnessTool(block.name, block.input as Record<string, unknown>);
        toolResults.push({
          type: "tool_result",
          tool_use_id: block.id,
          content: output,
        });
      }

      // Feed environmental observations directly back to the model
      messageHistory.push({ role: "user", content: toolResults });
    }
  }
}

// Run harness with a verification command
runHarnessLoop("Read the package.json file in this directory and summarize the project dependencies.");

Execution and Expected Terminal Output

Execute the runner with your API credentials:

export ANTHROPIC_API_KEY="your-api-key"
npx tsx agent_runner.ts

The harness prints deterministic runtime signals:

[Tool Call] read_file({"filepath":"package.json"})

[Task Complete] Model Output:
 The project specifies `@anthropic-ai/sdk` as its core production dependency. 
Development dependencies include `typescript`, `@types/node`, and `tsx` to enable TypeScript execution directly from the terminal.

5. Production Hardening: Critical Gotchas

Deploying an autonomous harness into production codebases introduces distinct failure modes. The following safeguards must be enforced at the system boundary:

⚠️ Gotcha Alert [Unbounded Terminal Output & Attention Dilution]: Raw execution logs from operations like npm test or package management tools can dump thousands of lines into the context array, depleting the inference window and diluting model reasoning. Implement aggressive output truncation at the tool boundary. When standard streams exceed 100 lines, extract the head (30 lines), the tail (70 lines), and insert a compressed line count indicator, forcing the model to issue targeted inspect commands if deeper output is needed.

⚠️ Gotcha Alert [Destructive Filesystem Race Conditions]: Exposing a naive write_file tool encourages complete rewrites of large source files, often resulting in silent truncation, line-ending corruption, or dropped imports. Replace full rewrites with targeted string replacement primitives (e.g., str_replace with strict search-and-replace blocks) or Git patch operations. Gate every write operation behind a static analyzer (such as tsc --noEmit), and pipe compile errors straight back into the harness as observation errors for instant self-healing.

⚠️ Gotcha Alert [Ungated Shell Execution Out-of-Bounds]: Providing raw shell access without host containment turns the harness into an attack vector. Never run commands directly in the host environment. Route all mutation tasks through a non-root Linux namespace or an ephemeral Docker container with network egress whitelist rules, preventing inadvertent extraction of environment credentials or catastrophic host alterations.