Dissecting the Claude Code Harness - Part 1: The Execution Engine

// The model is a pure function: messages in, response out.
// It has no memory, no side effects, no access to the filesystem.

interface Message {
  role: "system" | "user" | "assistant" | "tool_result";
  content: string | ToolUseBlock[];
}

interface TextBlock {
  type: "text";
  content: string;
}

interface ToolUseBlock {
  type: "tool_use";
  id: string; // unique call ID, e.g. "toolu_01A..."
  name: string; // tool name, e.g. "Bash", "ReadFile"
  input: Record<string, unknown>; // JSON payload matching the tool's Zod schema
}

interface ModelResponse {
  content: (TextBlock | ToolUseBlock)[];
  stopReason: "end_turn" | "tool_use";
}

// This is the only interface to the LLM.
// Every other component in this post wraps or feeds this function.
async function callModel(messages: Message[]): Promise<ModelResponse> {
  // In production: HTTP POST to https://api.anthropic.com/v1/messages
  // with model, max_tokens, tools, and the messages array.
  // For this post, treat it as an opaque async function.
  return await anthropicAPI.createMessage({ messages });
}

Plan → Act → Observe → Repeat

class AgentLoop {
  private messages: Message[] = [];
  private toolRegistry: ToolRegistry;
  private permissionSystem: PermissionSystem;
  private hookRunner: HookRunner;
  private contextManager: ContextManager;

  constructor(
    toolRegistry: ToolRegistry,
    permissionSystem: PermissionSystem,
    hookRunner: HookRunner,
    contextManager: ContextManager,
  ) {
    this.toolRegistry = toolRegistry;
    this.permissionSystem = permissionSystem;
    this.hookRunner = hookRunner;
    this.contextManager = contextManager;
  }

  async run(userPrompt: string): Promise<string> {
    // Inject persistent context (CLAUDE.md, memory files) before anything else
    this.messages = this.contextManager.buildInitialContext();
    this.messages.push({ role: "user", content: userPrompt });

    // The core loop: call model, execute tools, repeat
    while (true) {
      // Compact context if approaching the token limit
      this.messages = this.contextManager.compactIfNeeded(this.messages);

      // 1. REASON: call the model
      const response = await callModel(this.messages);

      // Append the assistant's response to history
      this.messages.push({ role: "assistant", content: response.content });

      // 2. CHECK: did the model finish? (no tool calls)
      if (response.stopReason === "end_turn") {
        const textBlocks = response.content.filter(
          (b): b is TextBlock => b.type === "text",
        );
        return textBlocks.map((b) => b.content).join("\n");
      }

      // 3. ACT: execute each tool call
      const toolCalls = response.content.filter(
        (b): b is ToolUseBlock => b.type === "tool_use",
      );

      for (const toolCall of toolCalls) {
        const result = await this.executeTool(toolCall);
        // 4. OBSERVE: feed the result back as a tool_result message
        this.messages.push({
          role: "tool_result",
          content: JSON.stringify({
            tool_use_id: toolCall.id,
            content: result,
          }),
        });
      }
      // Loop continues — the model sees the tool results on the next iteration
    }
  }

  private async executeTool(toolCall: ToolUseBlock): Promise<string> {
    const tool = this.toolRegistry.get(toolCall.name);

    // Schema validation (Zod)
    const parsed = tool.inputSchema.safeParse(toolCall.input);
    if (!parsed.success) {
      return `Error: Invalid input — ${parsed.error.message}`;
    }

    // Permission check
    const allowed = await this.permissionSystem.evaluate(toolCall, tool);
    if (!allowed) {
      return `Error: Permission denied for tool "${toolCall.name}"`;
    }

    // Pre-tool hooks
    const hookResult = await this.hookRunner.runPreToolUse(toolCall);
    if (hookResult.blocked) {
      return `Blocked by hook: ${hookResult.reason}`;
    }

    // Execute
    const output = await tool.execute(parsed.data);

    // Post-tool hooks
    await this.hookRunner.runPostToolUse(toolCall, output);

    return output;
  }
}

import { z, ZodSchema } from "zod";
import * as fs from "fs/promises";
import { execSync } from "child_process";

// Tool permission categories
type PermissionCategory =
  | "read"
  | "write"
  | "destructive"
  | "network"
  | "spawn";

// Every tool implements this interface
interface Tool {
  name: string;
  description: string;
  permissionCategory: PermissionCategory;
  inputSchema: ZodSchema;
  execute(input: unknown): Promise<string>;
}

// The registry: a simple map of tool name → tool implementation
class ToolRegistry {
  private tools = new Map<string, Tool>();

  register(tool: Tool): void {
    this.tools.set(tool.name, tool);
  }

  get(name: string): Tool {
    const tool = this.tools.get(name);
    if (!tool) throw new Error(`Unknown tool: ${name}`);
    return tool;
  }

  // Returns tool definitions in the format the Anthropic API expects
  toAPIFormat(): object[] {
    return Array.from(this.tools.values()).map((tool) => ({
      name: tool.name,
      description: tool.description,
      input_schema: tool.inputSchema,
    }));
  }
}

// --- Example tool: ReadFile ---

const ReadFileTool: Tool = {
  name: "ReadFile",
  description: "Read the contents of a file at the given absolute path.",
  permissionCategory: "read",
  inputSchema: z.object({
    path: z.string().describe("Absolute path to the file"),
    startLine: z.number().optional().describe("1-indexed start line"),
    endLine: z.number().optional().describe("1-indexed end line"),
  }),

  async execute(input) {
    const { path, startLine, endLine } = input as {
      path: string;
      startLine?: number;
      endLine?: number;
    };
    const content = await fs.readFile(path, "utf-8");
    const lines = content.split("\n");

    const start = (startLine ?? 1) - 1;
    const end = endLine ?? lines.length;
    return lines.slice(start, end).join("\n");
  },
};

// --- Example tool: Bash ---

const BashTool: Tool = {
  name: "Bash",
  description: "Execute a shell command and return stdout/stderr.",
  permissionCategory: "destructive", // shell access is always high-risk
  inputSchema: z.object({
    command: z.string().describe("The shell command to execute"),
    timeout: z.number().optional().default(30000).describe("Timeout in ms"),
  }),

  async execute(input) {
    const { command, timeout } = input as { command: string; timeout: number };
    try {
      const stdout = execSync(command, {
        timeout,
        encoding: "utf-8",
        maxBuffer: 1024 * 1024, // 1 MB cap
      });
      return stdout;
    } catch (err: any) {
      return `Exit code ${err.status}\nstderr: ${err.stderr}\nstdout: ${err.stdout}`;
    }
  },
};

// --- Example tool: WriteFile (targeted edit, not full overwrite) ---

const EditFileTool: Tool = {
  name: "EditFile",
  description: "Replace a target string in a file with new content.",
  permissionCategory: "write",
  inputSchema: z.object({
    path: z.string(),
    targetContent: z.string().describe("Exact string to find and replace"),
    replacementContent: z.string().describe("Content to replace it with"),
  }),

  async execute(input) {
    const { path, targetContent, replacementContent } = input as {
      path: string;
      targetContent: string;
      replacementContent: string;
    };
    const content = await fs.readFile(path, "utf-8");
    if (!content.includes(targetContent)) {
      return `Error: target content not found in ${path}`;
    }

    const updated = content.replace(targetContent, replacementContent);
    await fs.writeFile(path, updated);
    return `Successfully edited ${path}`;
  },
};

// --- Registering tools ---

const registry = new ToolRegistry();
registry.register(ReadFileTool);
registry.register(BashTool);
registry.register(EditFileTool);

import * as readline from "readline";

type PermissionMode = "default" | "plan" | "auto-accept" | "auto";

interface PermissionPolicy {
  denyPatterns: RegExp[]; // e.g. [/rm\s+-rf/, /curl.*\|.*sh/]
  allowedPaths: string[]; // e.g. ["/Users/dev/project"]
}

class PermissionSystem {
  private mode: PermissionMode;
  private policy: PermissionPolicy;

  constructor(mode: PermissionMode, policy: PermissionPolicy) {
    this.mode = mode;
    this.policy = policy;
  }

  async evaluate(toolCall: ToolUseBlock, tool: Tool): Promise<boolean> {
    // Gate 1: Policy deny-list (always checked, regardless of mode)
    if (this.isDeniedByPolicy(toolCall)) {
      console.log(`🚫 Policy denied: ${toolCall.name}`);
      return false;
    }

    // Gate 2: Mode-based evaluation
    switch (this.mode) {
      case "auto":
        // Auto mode: allow everything that passes the policy
        return true;

      case "auto-accept":
        // Auto-accept: reads are fine, writes need approval
        if (tool.permissionCategory === "read") return true;
        return await this.promptUser(toolCall);

      case "plan":
        // Plan mode: reads are fine, any mutation needs approval
        if (tool.permissionCategory === "read") return true;
        return await this.promptUser(toolCall);

      case "default":
      default:
        // Default: everything except reads needs approval
        if (tool.permissionCategory === "read") return true;
        return await this.promptUser(toolCall);
    }
  }

  private isDeniedByPolicy(toolCall: ToolUseBlock): boolean {
    const inputStr = JSON.stringify(toolCall.input);

    // Check deny-list patterns (e.g., rm -rf, curl piped to sh)
    for (const pattern of this.policy.denyPatterns) {
      if (pattern.test(inputStr)) return true;
    }

    // Check path restrictions
    if ("path" in (toolCall.input as any)) {
      const path = (toolCall.input as any).path as string;
      const inAllowedPath = this.policy.allowedPaths.some((p) =>
        path.startsWith(p),
      );
      if (!inAllowedPath) return true;
    }

    return false;
  }

  private async promptUser(toolCall: ToolUseBlock): Promise<boolean> {
    const rl = readline.createInterface({
      input: process.stdin,
      output: process.stdout,
    });
    return new Promise((resolve) => {
      const preview = JSON.stringify(toolCall.input).slice(0, 200);
      rl.question(
        `\n⚠️  Tool: ${toolCall.name}\n   Input: ${preview}\n   Allow? (y/n): `,
        (answer) => {
          rl.close();
          resolve(answer.toLowerCase() === "y");
        },
      );
    });
  }
}

import { execSync } from "child_process";

type HookEvent = "PreToolUse" | "PostToolUse" | "Notification" | "Stop";

interface HookDefinition {
  event: HookEvent;
  command: string; // shell command to execute
}

interface HookResult {
  blocked: boolean;
  reason?: string;
}

class HookRunner {
  private hooks: HookDefinition[] = [];

  register(hook: HookDefinition): void {
    this.hooks.push(hook);
  }

  async runPreToolUse(toolCall: ToolUseBlock): Promise<HookResult> {
    const relevantHooks = this.hooks.filter((h) => h.event === "PreToolUse");

    for (const hook of relevantHooks) {
      try {
        // Pass tool call info as environment variables
        execSync(hook.command, {
          encoding: "utf-8",
          env: {
            ...process.env,
            TOOL_NAME: toolCall.name,
            TOOL_INPUT: JSON.stringify(toolCall.input),
            TOOL_ID: toolCall.id,
          },
          timeout: 5000,
        });
        // Exit code 0 → allowed
      } catch (err: any) {
        // Non-zero exit code → blocked
        return {
          blocked: true,
          reason: err.stdout?.trim() || `Hook blocked: ${hook.command}`,
        };
      }
    }

    return { blocked: false };
  }

  async runPostToolUse(
    toolCall: ToolUseBlock,
    toolOutput: string,
  ): Promise<void> {
    const relevantHooks = this.hooks.filter((h) => h.event === "PostToolUse");

    for (const hook of relevantHooks) {
      try {
        execSync(hook.command, {
          encoding: "utf-8",
          env: {
            ...process.env,
            TOOL_NAME: toolCall.name,
            TOOL_INPUT: JSON.stringify(toolCall.input),
            TOOL_OUTPUT: toolOutput,
          },
          timeout: 5000,
        });
      } catch {
        // PostToolUse hooks are advisory — failures are logged, not fatal
        console.warn(`PostToolUse hook failed: ${hook.command}`);
      }
    }
  }
}

// --- Example: registering hooks ---

const hookRunner = new HookRunner();

// Block modifications to lock files
hookRunner.register({
  event: "PreToolUse",
  command: `bash -c '
    if echo "$TOOL_INPUT" | grep -q "package-lock.json\\|yarn.lock"; then
      echo "BLOCKED: Lock file modifications are not allowed."
      exit 1
    fi
    exit 0
  '`,
});

// Log every tool execution to a file
hookRunner.register({
  event: "PostToolUse",
  command: `bash -c '
    echo "[$(date)] $TOOL_NAME: $TOOL_INPUT" >> /tmp/agent-audit.log
  '`,
});

import * as fs from "fs/promises";
import * as path from "path";

interface CompactionResult {
  messages: Message[];
  compacted: boolean;
}

class ContextManager {
  private maxTokens: number;
  private projectRoot: string;

  constructor(projectRoot: string, maxTokens: number = 200_000) {
    this.projectRoot = projectRoot;
    this.maxTokens = maxTokens;
  }

  // Load persistent, compaction-proof context
  buildInitialContext(): Message[] {
    const messages: Message[] = [];

    // 1. System-level: CLAUDE.md is always first (never compacted)
    const claudeMd = this.loadClaudeMd();
    if (claudeMd) {
      messages.push({ role: "system", content: claudeMd });
    }

    // 2. Memory files from ~/.claude/MEMORY.md
    const memory = this.loadMemoryFiles();
    if (memory) {
      messages.push({ role: "system", content: memory });
    }
    return messages;
  }

  // The multi-layer compaction pipeline
  compactIfNeeded(messages: Message[]): Message[] {
    const usage = this.estimateTokenUsage(messages);
    const ratio = usage / this.maxTokens;

    // Stage 1: Snip compact at 80% — evict cold messages from the middle
    if (ratio > 0.8) {
      messages = this.snipCompact(messages);
    }

    // Stage 2: Microcompact at 85% — shrink content, preserve cache keys
    if (ratio > 0.85) {
      messages = this.microcompact(messages);
    }

    // Stage 3: Auto compact at 95% — LLM-based summarization
    if (ratio > 0.95) {
      messages = this.autoCompact(messages);
    }

    return messages;
  }

  // Stage 1: Remove old tool results from the middle of conversation
  private snipCompact(messages: Message[]): Message[] {
    const keep = 5; // keep first N and last N messages
    if (messages.length <= keep * 2) return messages;

    const head = messages.slice(0, keep);
    const tail = messages.slice(-keep);
    const middle = messages.slice(keep, -keep);

    // Only remove tool_result messages from the middle (they're bulky)
    const filtered = middle.filter((m) => m.role !== "tool_result");

    return [...head, ...filtered, ...tail];
  }

  // Stage 2: Truncate long tool outputs while keeping cache-friendly prefix
  private microcompact(messages: Message[]): Message[] {
    return messages.map((msg) => {
      if (msg.role === "tool_result" && typeof msg.content === "string") {
        if (msg.content.length > 2000) {
          return {
            ...msg,
            content:
              msg.content.slice(0, 1000) +
              "\n... [truncated] ...\n" +
              msg.content.slice(-500),
          };
        }
      }
      return msg;
    });
  }

  // Stage 3: Summarize the conversation using the LLM itself
  private autoCompact(messages: Message[]): Message[] {
    const systemMessages = messages.filter((m) => m.role === "system");
    const conversationMessages = messages.filter((m) => m.role !== "system");

    // Ask the model to summarize the conversation so far
    // (In production this is a separate, cheaper model call)
    const summary = this.summarizeSync(conversationMessages);

    return [
      ...systemMessages,
      {
        role: "assistant" as const,
        content: `[SystemCompactBoundaryMessage] Summary of previous work:\n${summary}`,
      },
    ];
  }

  // Stage 4: Reactive compact — called when API returns prompt_too_long
  reactiveCompact(messages: Message[]): Message[] {
    // Emergency: aggressively summarize and retry
    const systemMessages = messages.filter((m) => m.role === "system");
    const summary = this.summarizeSync(
      messages.filter((m) => m.role !== "system"),
    );

    return [
      ...systemMessages,
      {
        role: "assistant" as const,
        content: `[ReactiveCompact] ${summary}`,
      },
    ];
  }

  private loadClaudeMd(): string | null {
    try {
      const filePath = path.join(this.projectRoot, "CLAUDE.md");
      // fs.readFileSync used here for simplicity in the initializer
      return require("fs").readFileSync(filePath, "utf-8");
    } catch {
      return null;
    }
  }

  private loadMemoryFiles(): string | null {
    try {
      const memoryPath = path.join(
        process.env.HOME || "~",
        ".claude",
        "MEMORY.md",
      );
      return require("fs").readFileSync(memoryPath, "utf-8");
    } catch {
      return null;
    }
  }

  private estimateTokenUsage(messages: Message[]): number {
    // Rough estimate: 1 token ≈ 4 characters
    const totalChars = messages.reduce((sum, m) => {
      const content =
        typeof m.content === "string" ? m.content : JSON.stringify(m.content);
      return sum + content.length;
    }, 0);
    return Math.ceil(totalChars / 4);
  }

  private summarizeSync(messages: Message[]): string {
    // In production, this calls the model with a summarization prompt.
    // Simplified here for illustration.
    const totalMessages = messages.length;
    const toolCalls = messages.filter(
      (m) => typeof m.content !== "string",
    ).length;
    return `Completed ${totalMessages} interaction steps including ${toolCalls} tool calls.`;
  }
}