Coding Agent Harness

The Harness Is The Product

• The most critical component of a coding agent is often the ‘harness’ — the runtime system that manages file state, tool execution, and context — rather than the underlying language model.
• The harness owns the full lifecycle: input routing, message design, prompt assembly, tool validation, permission policy, execution, and state update.
• It acts as a boundary between the model’s proposal and real-world effect, ensuring reliability and safety in file and workspace modifications.

Six Core Responsibilities of a Coding Agent Harness

• Maintain live repo context with accurate workspace, file, and project documentation.
• Enforce structured tool contracts with schema validation, path safety, and permission policies.
• Implement context reduction to prevent information overload and hallucination.
• Maintain transcripts and memory to track what has happened and what is relevant now.
• Enable delegation of tasks to subagents with scoped tools and isolated state for better parallelism and error containment.
• Ensure file truth is preserved by tracking file baselines and detecting stale reads.

The Stale Read Trap

• A critical bug where the model continues to use outdated file content from a transcript, even after the file has been modified externally.
• The harness must distinguish between transcript text and file truth, and enforce a ‘file state’ record that reflects the actual disk state.
• When a file is read, the harness must record its baseline (path, hash, timestamp, content) and compare it against the current disk state to detect staleness.

Tool Contracts as Safety Mechanisms

• Tools are not just functions — they are contracts that define risk, path policies, and execution boundaries.
• Every tool call must undergo validation before approval: path safety, schema compliance, baseline freshness, and human approval when necessary.
• Tool output must be bounded in size and content to prevent context flooding and ensure model reasoning quality.

Input Routing and Slash Commands

• User input should be routed through an input router that distinguishes between regular work requests and control-plane commands (e.g., /status, /reset, /goal).
• Slash commands (e.g., /goal, /tools, /audit) should be handled locally by the harness to provide runtime diagnostics and session control without involving the model.
• The /goal command is particularly important as it defines a session-level objective that can be paused, resumed, or cleared independently of the model’s reasoning.

Markdown as Context Interface

• AGENTS.md and SKILL.md files provide workspace-specific rules and task procedures, respectively, and should be loaded by the harness at appropriate times to shape behavior.
• AGENTS.md is loaded early to establish workspace-wide rules, while SKILL.md is loaded on-demand to provide task-specific workflows and tool expectations.
• This enables progressive disclosure and prevents the model from being overwhelmed by irrelevant or outdated documentation.

Context as a Projection

• Context is not a simple append of all past interactions — it is a curated projection of the most relevant and bounded evidence for the current task.
• The harness applies four key projection strategies: large-result preview, idle-gap microcompact, old-span collapse, and auto-compact near the limit.
• This ensures the model receives a clean, focused working set while preserving audit trails and state for debugging and resumption.

Subagent Architecture and Runtime Management

• A subagent is a child runtime spawned from a parent session, inheriting shared resources like tools and permissions but operating in its own isolated context.
• Subagents can be ‘fresh’, ‘forked’, or ‘partial forked’ depending on the task — with partial forks being most practical for complex workflows.
• The harness must manage subagent lifecycle, including context inheritance, result aggregation, and integration back into the parent session.

Key Takeaways

• The coding agent’s true value lies in its runtime system — the harness — which ensures reliability, safety, and consistency in file and workspace operations.
• A robust harness must manage file truth, detect stale reads, and enforce tool contracts to prevent accidental or malicious modifications.
• Input routing and slash commands provide user control over the agent’s runtime, separating control plane from model reasoning.
• Context is a projection, not a dump — the harness curates and filters evidence to prevent context flooding and improve model performance.
• Subagents extend the agent’s capabilities through parallel, isolated workspaces, but require careful management to avoid uncontrolled complexity.

Related Articles

• Warfare Mode is Changing: Is It Gradual Evolution or a Total Revolution?
• Wayve’s AI Car Drives London Streets, Challenging Tesla and Waymo
• 蘋果祭出“熱核”反擊，迎戰OpenAI威脅
• Elite Students Abandon Wall Street to Chase AI Startup Dreams

---

Topics: Coding Agent Harness
Tags: ai agent coding-agent ai-robotics tooling runtime