claude-code-agent-harness-architecture

name	claude-code-agent-harness-architecture
description	Expert guidance on AI Agent architecture, harness design patterns, and building production-grade Agent systems based on Claude Code analysis
triggers	["how do I build an AI agent harness","explain agent architecture patterns","design a production agent system","implement agent tool calling system","build agent permission pipeline","create agent context management","design agent conversation loop","implement agent memory system"]

Claude Code Agent Harness Architecture

Skill by ara.so — Claude Code Skills collection.

What This Skill Covers

This skill provides deep architectural knowledge for building production-grade AI Agent systems (Agent Harness), based on the comprehensive analysis of Claude Code's architecture from the claude-code-book project. You'll learn:

• Core Agent Harness patterns: conversation loops, tool systems, permission pipelines
• Context & memory management: token budgeting, compression strategies, long-term memory
• Multi-agent orchestration: fork patterns, coordinator models, sub-agent spawning
• Integration patterns: MCP protocol, hooks system, skill/plugin architecture
• Production concerns: streaming, performance optimization, safety guardrails

Installation & Access

The knowledge base is available at:

• Online book: https://lintsinghua.github.io
• GitHub repository: https://github.com/lintsinghua/claude-code-book

# Clone for offline reference
git clone https://github.com/lintsinghua/claude-code-book.git
cd claude-code-book

# The book contains 15 chapters + 4 appendices with 139 architecture diagrams
# Key directories:
# - 第一部分-基础篇/ (Part 1: Fundamentals)
# - 第二部分-核心系统篇/ (Part 2: Core Systems)
# - 第三部分-高级模式篇/ (Part 3: Advanced Patterns)
# - 第四部分-工程实践篇/ (Part 4: Engineering Practice)
# - 附录/ (Appendices: tools, flags, terminology)

Core Architecture Patterns

1. Conversation Loop (Agent Heartbeat)

The fundamental while(true) async generator pattern that drives all Agent interactions:

// Core conversation loop structure
async function* conversationLoop(deps: QueryDeps): AsyncGenerator<QueryEvent> {
  while (true) {
    // 1. Prepare context window (token budget management)
    const context = await buildContext(deps);
    
    // 2. Call LLM with tools
    const response = await llmClient.chat({
      messages: context.messages,
      tools: context.availableTools,
      max_tokens: context.tokenBudget
    });
    
    // 3. Yield different event types
    if (response.type === 'text') {
      yield { type: 'text_delta', delta: response.content };
    } else if (response.type === 'tool_use') {
      // 4. Execute tool with permission check
      const result = await executeToolWithPermission(response.tool, deps);
      yield { type: 'tool_result', result };
    }
    
    // 5. Check termination conditions (10 types)
    if (shouldTerminate(response)) {
       { : , : response. };
      ;
    }
  }
}

Ten termination reasons:

• end_turn - Natural completion
• max_tokens - Token limit reached
• stop_sequence - Stop token encountered
• tool_use - Waiting for tool result
• content_filter - Safety filter triggered
• timeout - Time limit exceeded
• user_interrupt - User cancellation
• error - Fatal error
• rate_limit - API quota exceeded
• context_overflow - Context window exhausted

2. Tool System (Agent's Hands)

Tools follow a strict 5-element protocol:

// Tool<Input, Output, Permission> protocol
interface Tool<I, O, P extends PermissionLevel> {
  // 1. Schema: Zod v4 input validation
  schema: z.ZodType<I>;
  
  // 2. Handler: Core execution logic
  handler: (input: I, deps: QueryDeps) => Promise<O>;
  
  // 3. Metadata: LLM-visible description
  metadata: {
    name: string;
    description: string;
    parameters: JSONSchema; // Auto-generated from Zod
  };
  
  // 4. Properties: Execution characteristics
  properties: {
    readOnly: boolean;        // Safe to run speculatively
    destructive: boolean;     // Irreversible side effects
    concurrencySafe: boolean; // Can run in parallel
  };
  
  // 5. Permission: Required access level
  permission: P; // 'read' | 'write' | 'execute' | 'admin' | 'auto'
}

// buildTool: Fault-safe factory pattern
const readFileTool = buildTool({
  schema: z.object({
    path: z.string(),
    encoding: z.([, ]).()
  }),
  : ,
  : {
    : ,
    : ,
    : 
  },
  :  ({ path, encoding }, deps) => {
     absPath = deps..(path);
    
    
     (!deps..(absPath)) {
        (, { path });
    }
    
      deps..(absPath, encoding);
  }
});

Concurrent execution algorithm (partition-greedy):

// Divide tools into read-only vs. side-effecting partitions
async function executeConcurrently(tools: ToolCall[]): Promise<ToolResult[]> {
  const [readOnly, sideEffecting] = partition(
    tools,
    t => t.properties.readOnly && t.properties.concurrencySafe
  );
  
  // Execute read-only tools in parallel
  const readOnlyResults = await Promise.all(
    readOnly.map(t => t.handler(t.input, deps))
  );
  
  // Execute side-effecting tools sequentially
  const sideEffectingResults = [];
  for (const tool of sideEffecting) {
    sideEffectingResults.push(await tool.handler(tool.input, deps));
  }
  
  return [...readOnlyResults, ...sideEffectingResults];
}

3. Permission Pipeline (4-Stage Guardrails)

// Four-stage permission pipeline
type PermissionStage = 
  | 'classification'  // Speculative 2s pre-approval
  | 'validation'      // Schema + safety checks
  | 'authorization'   // User consent (if needed)
  | 'execution';      // Actual tool call

async function permissionPipeline(
  toolCall: ToolCall,
  mode: PermissionMode
): Promise<ToolResult> {
  // Stage 1: Classification (speculative, 2-second timeout)
  const classification = await Promise.race([
    classifyRisk(toolCall),
    timeout(2000, { risk: 'unknown' })
  ]);
  
  // Stage 2: Validation
  const validated = await validateToolCall(toolCall, {
    schema: toolCall.tool.schema,
    bashRules: mode === 'safe' ? SAFE_BASH_RULES : null,
    pathRestrictions: deps.workspace.boundaries
  });
  
  // Stage 3: Authorization (mode-dependent)
  if (requiresConsent(toolCall, mode, classification)) {
     consent =  deps..({
      : toolCall..,
      : toolCall.,
      : classification.,
      : classification.
    });
    
     (!consent.) {
        (consent.);
    }
  }
  
  
    toolCall..(validated., deps);
}


  = 
  |       
  |     
  |    
  |       
  | ;   


  = {
  : [, , , , , ],
  : [
    ,           
    ,               
    ,    
           
  ],
  : 
};

4. Context Management (Token Budget)

Effective window calculation and 4-level compression:

// Effective window formula
interface ContextWindow {
  total: number;              // Model's max context (200K for Claude 3.5)
  systemPrompt: number;       // ~2K tokens
  toolDefinitions: number;    // ~50 tokens per tool × N tools
  reserved: number;           // ~4K for output buffer
  effective: number;          // Available for conversation history
}

function calculateEffectiveWindow(deps: QueryDeps): ContextWindow {
  const total = deps.model.contextLimit; // 200_000
  const systemPrompt = estimateTokens(deps.systemPrompt);
  const toolDefinitions = deps.tools.length * 50;
  const reserved = 4_000;
  
  return {
    total,
    systemPrompt,
    toolDefinitions,
    reserved,
    effective: total - systemPrompt - toolDefinitions - reserved
  };
}

// Four-level progressive compression
async function compressContext(
  messages: Message[],
  targetTokens: number
): <[]> {
   compressed = messages;
   currentTokens = (compressed);
  
  
   (currentTokens > targetTokens) {
    compressed = (compressed, { :  });
    currentTokens = (compressed);
  }
  
  
   (currentTokens > targetTokens) {
    compressed = (compressed);
    currentTokens = (compressed);
  }
  
  
   (currentTokens > targetTokens) {
    compressed =  (compressed, {
      : , 
      : 
    });
    currentTokens = (compressed);
  }
  
  
   (currentTokens > targetTokens) {
    compressed =  (compressed, {
      : , 
      :  
    });
  }
  
   compressed;
}


  {
   failureCount = ;
   lastReset = .();
  
   attempt<T>(:  <T>): <T> {
     (. >= ) {
       (.() - . < ) {
          ();
      }
      .();
    }
    
     {
       result =  ();
      .();
       result;
    }  (error) {
      .++;
       error;
    }
  }
  
   () {
    . = ;
    . = .();
  }
}

5. Memory System (Long-term Memory)

Four closed-type memory categories:

// Memory types (closed set - only these four)
type MemoryType = 
  | 'code_patterns'    // Architecture decisions, idioms
  | 'user_preferences' // Settings, workflow habits
  | 'project_context'  // Goals, constraints, history
  | 'task_progress';   // Ongoing work state

interface Memory {
  type: MemoryType;
  key: string;           // Unique identifier
  content: string;       // Natural language
  metadata: {
    created: string;     // ISO timestamp
    accessed: string;    // Last retrieval
    confidence: number;  // 0-1, for pruning
  };
}

// "Only store what cannot be derived" principle
async function shouldStore(content: string, deps: QueryDeps): Promise<boolean> {
  // Don't store if:
  // - Can be read from files
  // - Can be inferred from code
  // - Is ephemeral state
  
  const derivable = [
    () => deps.workspace..(content), 
     .(content),  
     (content)                     
  ];
  
   !derivable.( ());
}





  (): <> {
   childDeps = {
    ...parentDeps,
    : {
      
      : (parentDeps..),
      
      : parentDeps...(
         [, ].(m.)
      ),
      
      : {}
    }
  };
  
    (childDeps);
}

6. Hook System (Lifecycle Extension)

26 lifecycle events across 5 categories:

// Five hook categories
type HookCategory = 
  | 'lifecycle'    // conversation_start, query_begin, query_end
  | 'tool'         // tool_before, tool_after, tool_error
  | 'content'      // message_sent, message_received, context_compressed
  | 'system'       // config_changed, skill_loaded, mcp_connected
  | 'agent';       // agent_forked, agent_terminated

interface Hook {
  event: string;        // e.g., 'tool_before_execute'
  handler: string;      // Path to executable
  config?: {
    priority: number;   // 0-5 (higher = earlier)
    async: boolean;     // Run without blocking
    timeout: number;    // Max execution time (ms)
  };
}

// JSON response protocol
interface HookResponse {
  allow?: boolean;        // For before_* hooks: veto execution
  modify?: {              // For content hooks: transform data
    input?: unknown;
    output?: unknown;
  };
  metadata?: Record<string, unknown>; 
}



    (): <> {
   (event. === ) {
     fs.(
      ,
      .({
        :  ().(),
        : event...,
        : event..,
        : process..
      }) + 
    );
  }
  
   { :  }; 
}

7. Sub-Agent Fork Pattern

Byte-level context inheritance with recursive protection:

// Three agent sources
type AgentSource = 
  | 'builtin'    // Four built-in agents: coordinator, worker, researcher, reviewer
  | 'skill'      // Defined in SKILL.md files
  | 'fork';      // Cloned from current agent

// Fork with context inheritance
async function forkCurrentAgent(
  purpose: string,
  deps: QueryDeps
): Promise<Agent> {
  // Recursive fork depth protection
  if (deps.forkDepth >= 3) {
    throw new Error('Max fork depth exceeded (prevents infinite recursion)');
  }
  
  const childAgent = new Agent({
    ...deps,
    forkDepth: deps.forkDepth + 1,
    
    // Inherit full message history (byte-level copy)
    context: {
      messages: structuredClone(deps.context.messages),
      tokenBudget: deps.context.tokenBudget * 0.8 // 80% of parent budget
    },
    
    // Inherit selective memory
    memory: forkMemory(deps., [, ]),
    
    
    : ,
    
    
    : deps.,
    : deps.
  });
  
   childAgent;
}


  = {
  : {
    : ,
    : [, , ],
    : [, ]
  },
  : {
    : ,
    : [], 
    : []
  },
  : {
    : ,
    : [, , , ],
    : []
  },
  : {
    : ,
    : [, , ],
    : []
  }
};

8. MCP Integration (External Protocol Bridge)

Model Context Protocol for external tool/resource integration:

// Eight transport protocols
type MCPTransport = 
  | 'stdio'      // Standard I/O pipes
  | 'http'       // REST API
  | 'websocket'  // WebSocket
  | 'grpc'       // gRPC
  | 'ipc'        // Inter-process communication
  | 'tcp'        // Raw TCP
  | 'udp'        // UDP datagrams
  | 'sse';       // Server-sent events

// Five-state connection management
type MCPConnectionState = 
  | 'disconnected'
  | 'connecting'
  | 'connected'
  | 'error'
  | 'reconnecting';

class MCPConnection {
  state: MCPConnectionState = 'disconnected';
  retryCount = 0;
  maxRetries = 3;
  
  async connect(config: MCPServerConfig) {
    this.state = 'connecting';
    
    try {
      const transport = createTransport(config.transport);
      await transport.initialize();
      
      // Handshake: Exchange capabilities
       serverInfo =  transport.({
        : ,
        : {
          : { : , :  },
          : [, , ]
        }
      });
      
      . = ;
       serverInfo;
    }  (error) {
      . = ;
      
       (. < .) {
        .++;
        . = ;
         ( * .); 
         .(config);
      }
      
       error;
    }
  }
}



 mcpTool = {
  : ,
  :  (input, deps) => {
     connection = deps..();
      connection.(, input);
  }
};


  {
  
   () {
     conn = ..(server);
      conn.({
      : ,
      : { : tool, : input }
    });
  }
  
  
   () {
     (notification. === ) {
      
       .(notification..);
    }
  }
}

Practical Patterns

Building a Custom Tool

import { buildTool } from './tool-factory';
import { z } from 'zod';

// Example: Jira integration tool
const createJiraIssueTool = buildTool({
  schema: z.object({
    project: z.string(),
    summary: z.string(),
    description: z.string(),
    issueType: z.enum(['Bug', 'Task', 'Story']).default('Task'),
    priority: z.enum(['Low', 'Medium', 'High']).default('Medium')
  }),
  
  permission: 'write', // Requires write access
  
  properties: {
    readOnly: false,
    destructive: false, // Can be undone (delete issue)
    concurrencySafe: true // Multiple issues can be created in parallel
  },
  
  handler: async (input, deps) => {
    // Use environment variables for secrets
    const jiraClient = new JiraClient({
      host: process..,
      : {
        : process..,
        : process..
      }
    });
    
     {
       issue =  jiraClient..({
        : {
          : { : input. },
          : input.,
          : input.,
          : { : input. },
          : { : input. }
        }
      });
      
       {
        : ,
        : issue.,
        : 
      };
    }  (error) {
        (, {
        : error.,
        : error.
      });
    }
  }
});

Implementing a Permission Strategy

// Custom permission strategy with role-based access
class RBACPermissionStrategy implements PermissionStrategy {
  private userRole: 'developer' | 'senior' | 'admin';
  
  constructor(role: string) {
    this.userRole = role as any;
  }
  
  async authorize(toolCall: ToolCall): Promise<AuthResult> {
    const permissions = {
      developer: {
        allowed: ['read_file', 'search', 'run_tests'],
        denied: ['execute_bash', 'write_file', 'git_push']
      },
      senior: {
        allowed: ['read_file', 'write_file', 'execute_bash', 'git_commit'],
        denied: ['git_push', 'delete_file', 'modify_settings']
      },
      admin: {
        allowed: ['*'], // All tools
        denied: []
      }
    };
    
    const config = permissions[.];
    
     (config..(toolCall..)) {
       { : , :  };
    }
    
     (config..() || config..(toolCall..)) {
      
       (toolCall...) {
         {
          : ,
          : . !== 
        };
      }
      
       { :  };
    }
    
     { : , :  };
  }
}

Context Compression Strategy

// Aggressive compression for long conversations
class AggressiveCompressionStrategy {
  async compress(messages: Message[], targetTokens: number): Promise<Message[]> {
    let result = messages;
    const steps = [
      { name: 'Remove images', fn: this.removeAllImages },
      { name: 'Summarize tool outputs', fn: this.summarizeToolOutputs },
      { name: 'Collapse redundant exchanges', fn: this.collapseRedundant },
      { name: 'Semantic compression', fn: this.semanticCompress }
    ];
    
    for (const step of steps) {
      const currentTokens = estimateTokens(result);
      
      if (currentTokens <= targetTokens) {
        break; // Target reached
      }
      
      console.log(`Compression step: ${step.name} (${currentTokens} → target ${targetTokens})`);
      result = await step.(result, targetTokens);
    }
    
     result;
  }
  
    (
    : [],
    : 
  ): <[]> {
    
     summary =  llmClient.({
      : [
        {
          : ,
          : 
        }
      ]
    });
    
     [
      {
        : ,
        : 
      },
      ...messages.(-) 
    ];
  }
}

Configuration

Setting Up Agent Harness

// .claude/config.json
{
  "version": "1.0",
  "agent": {
    "model": "claude-3-5-sonnet-20241022",
    "contextWindow": 200000,
    "permissionMode": "normal", // safe | normal | relaxed | auto
    "features": {
      "toolCalling": true,
      "memorySystem": true,
      "subAgents": true,
      "mcpIntegration": true
    }
  },
  "tools": {
    "enabled": [
      "read_file",
      "write_file",
      "execute_bash",
      "ripgrep_search",
      "git_*" // Wildcard pattern
    ],
    "disabled": [
      "delete_file" // Explicitly disabled
    ],
    "concurrency": {
      "maxParallel": 5,
      "partitionStrategy": "read-write-split"
    }
  },
  "context": {
    "compression": {
      "strategy": "progressive", // progressive | aggressive | minimal
      "levels": ["snip", "micro-compact", "collapse", "auto-compact"],
      "targetUtilization": 0.9 // 90% of effective window
    }
  },
  : {
    : , 
    : ,
    : {
      : ,
      : 
    }
  },
  : {
    : ,
    : ,
    : 
  },
  : {
    : {
      : {
        : ,
        : ,
        : {
          : ,
          :  
        }
      },
      : {
        : ,
        : ,
        : [, ],
        : {
          : 
        }
      }
    }
  }
}

Feature Flags (89 total)

// Runtime feature flags (13 categories)
const FEATURE_FLAGS = {
  // Core features
  'agent.tool_calling': true,
  'agent.sub_agents': true,
  'agent.memory_system': true,
  
  // Safety features
  'safety.permission_pipeline': true,
  'safety.bash_validation': true,
  'safety.path_restrictions': true,
  
  // Performance
  'perf.lazy_tool_loading': true,