Coding Harnesses, Adapters, and Agent Protocols
Coding harnesses expose different tools, permission models, session formats, hooks, subagents, context behavior, output events, sandboxes, and completion semantics. A factory that shells out to a CLI may appear provider neutral while silent
A rapid review of the chapter’s existing Quick Read, principles, definitions, lessons, and review material.
Reconstruct and defend this chapter’s architecture.
Reconstruct the architecture, name each boundary, and defend the tradeoffs.
Open the source exercise
Draw a factory using a web UI, control plane, outer harness, two interchangeable coding harnesses, a development environment, MCP tools, and one remote A2A specialist. Add an ACP editor client and AG-UI event stream. Mark authentication, authority, lifecycle events, cancellation, evidence, and every place protocol compatibility does not imply trust.
3. Enduring Principle
Separate the inner harness from the outer harness
The inner harness owns one model-tool loop. It prepares model input, manages context, exposes tools, executes tool calls under its local permission model, streams observations, compacts or resumes the session, and identifies when the loop stops.
The outer harness makes that loop operable inside the factory. It validates the frozen manifest, provisions the environment, starts or resumes the inner harness, converts native events into the factory schema, enforces budgets and timeouts, requests policy decisions, captures artifacts, classifies completion, and tears down resources.
Neither harness owns Mission approval, WorkOrder acceptance, independent verification, publication authority, merge, or release.
Define a portable harness lifecycle
A factory adapter should support or explicitly reject:
- capability discovery and version negotiation;
- preflight and configuration validation;
- start, attach, resume, pause, cancel, drain, and terminate;
- user input and structured human-decision requests;
- model, tool, file, command, subagent, progress, warning, and cost events;
- permission and policy-decision callbacks;
- checkpoints, compaction, and session identity;
- structured terminal completion and unresolved-work reporting;
- artifact and receipt export;
- timeout, crash, malformed-output, and unavailable-provider classification;
- secret redaction and content-retention controls; and
- environment teardown and reconciliation.
Unsupported behavior must be visible in a Harness Capability Manifest. Adapters should fail closed when a WorkOrder requires a capability the harness cannot prove.
Prefer structured programmatic execution over terminal scraping
Headless or non-interactive execution should emit typed events or a stable structured stream such as JSON Lines. Terminal text may remain a diagnostic artifact, but should not be the authoritative completion contract.
The factory should retain the adapter version, native session identity, harness configuration, model route, instructions, tool grants, context digest, environment digest, event ordering, exit state, and raw artifact references. Never assume that process exit zero means the engineering task is complete.
Treat hooks as integration points, not authority
Lifecycle hooks can observe or intercept session start, tool calls, file changes, subagents, permissions, stop, and completion. They are useful for logging, policy callbacks, credential injection, validation, notifications, and cleanup.
A native hook is not automatically trustworthy. The factory must know whether the hook is synchronous, bypassable, ordered, retryable, authenticated, and covered by the harness's own configuration hierarchy. Consequential policy belongs in an external authoritative control path or a qualified enforcement point, not solely in a user-editable hook.
Map protocols to their actual boundaries
| Protocol | Primary boundary | Useful for | Does not establish |
|---|---|---|---|
| MCP | Agent or host to tools, resources, prompts, and extensions | Tool discovery and invocation | Business authority, trustworthy tools, or acceptance |
| Agent Client Protocol (ACP) | Coding agent to editor or client | Portable agent/editor sessions and interaction | Factory workflow, environment qualification, or release governance |
| AG-UI | Agent backend to user-facing application | Bidirectional event streaming, state, tool, and user interaction | Durable domain authority or independent verification |
| Agent2Agent (A2A) | Independent agent application to agent application | Capability discovery, delegation, messaging, and remote task coordination | Permission to delegate factory authority or trust a remote agent |
The acronym ACP is ambiguous in the wider ecosystem. This guide uses it for the Agent Client Protocol associated with editor-agent interoperability and must pin the specification or implementation version whenever behavior matters.
Protocols may coexist. An editor can communicate with a coding agent through ACP; that agent can reach tools through MCP; a factory UI can receive events through AG-UI; and a remote specialist can be contacted through A2A. The control plane still authenticates principals, scopes authority, freezes contracts, reconciles state, and evaluates evidence.
Test adapters through behavior, not product names
A conformance suite should test:
- capability truthfulness and unsupported features;
- event ordering, duplication, loss, and redaction;
- cancellation before, during, and after tool effects;
- timeout and process-crash recovery;
- permission denial and human-decision waits;
- context compaction and session resume;
- out-of-scope filesystem and network attempts;
- output-schema violations and false completion;
- model or provider fallback visibility;
- teardown and orphan detection; and
- exact lineage from native session to factory Attempt.
Two adapters are substitutable only for a specified workload and policy set. One may be eligible for read-only analysis and ineligible for code mutation or long-running recovery.
Keep product comparisons dated
Codex and Claude Code are useful coding-harness case studies. Their model, local/cloud, CLI, SDK, hooks, tools, permissions, session, and automation features must be verified against current official documentation and a pinned runtime before use. The durable lesson is that the product name may describe a suite of experiences while the factory integrates with one exact harness and version.
8. Notes and lessons learned
- A protocol standardizes messages at one boundary; it does not standardize the whole factory.
- Hooks are capabilities whose enforcement and failure behavior must be qualified.
- Portability means preserving required behavior and controls, not merely starting a process with a different command.
- Product names belong in dated case studies; contract vocabulary belongs in the canon.
9. Interview and discussion questions
- How do inner and outer harness responsibilities differ?
- What must a headless coding harness emit for reliable orchestration?
- How do MCP, ACP, AG-UI, and A2A solve different problems?
- Why can a native lifecycle hook be an unsafe policy boundary?
- What would prove that two harnesses are safely substitutable?
- When is a thick adapter preferable to a thin adapter?
Review this chapter.
Challenge a claim, boundary, missing failure mode, unclear term, or unsupported evidence statement.
- Claim
- Boundary
- Failure
- Evidence