Skip to content

Coding-Agent CLIs: What the Vendor Harness Does, and What the End User Actually Owns

Research date: Aug 9, 2026. This guide applies the session / harness / sandbox decomposition described by Anthropic and Shopify, plus the agent-loop and CLI benchmark research in this workspace, to the question: what should an end user focus on to maximize a coding-agent CLI? The classifications and recommendations are synthesis.

TL;DR

OpenAI, Anthropic, and the OpenCode project already built the harness for you: the agent loop, tool routing, prompt assembly, context management, permission/sandbox gates, session/history, error handling, and caching. As an end user you inherit that machinery — rebuilding any of it is wasted work.

Your actual levers split into two buckets:

  • Context assembly and prompt generation (the dominant, daily craft). Everything that shapes what the model sees and is asked: AGENTS.md, skills, curated memory, tool selection, task framing, and evidence selection. This is prompt engineering applied to the context window — the harness just executes it.
  • Thin harness engineering (optional, only when the CLI's defaults fall short). The governance you add around the CLI: verification gates, worktree/sandbox isolation, durable task state, and managed-context hooks.

So the end-user focus, in order:

  1. Pick the harness once, well. Your single biggest harness decision is which CLI you adopt — the same model across CLIs shows a ~30x token spread and 2x task-performance gaps from the harness alone.
  2. Do excellent context assembly. Highest leverage per hour, and the most durable advantage you can build.
  3. Add thin governance in this order: verification gates → isolation → task state → policy/audit → orchestration — only when your needs exceed the CLI defaults.
  4. Skip heavy machinery (event stores, sandbox planes, queues, SDK agents) until a team-scale problem exists.

1. The layering: the vendor ships the harness, you sit downstream

A harness is the operational control plane around an agent: how work starts, what context and tools the agent receives, where it runs, what it may do, how it recovers, and how success is checked. It is the whole controlled execution path, not one file or one product.

The decomposition comes from the companies that built the big ones:

Component Role Who ships it
Session "The append-only log of everything that happened"; durable context object outside the model's context window Vendor (you can add your own sink on top)
Harness "The loop that calls Claude and routes Claude's tool calls to the relevant infrastructure" Vendor
Sandbox "An execution environment where Claude can run code and edit files" Vendor default; you can wrap it

Anthropic is explicit: the harness is stateless and disposable, and "the harness doesn't know whether the sandbox is a container, a phone, or a Pokémon emulator" (https://www.anthropic.com/engineering/managed-agents). Shopify derives the three properties that force the harness out of the sandbox — safety, replaceability, observability (https://shopify.engineering/under-the-river).

The end-user consequence: you are downstream of this machinery. The loop and its surrounding harness engineering are the vendor's problem — which is exactly why OpenAI's guidance frames the loop as "at the heart of every AI agent" while the real craft lives in what the CLI does around it (prompt assembly, context management, caching, exit conditions, permission gates) (https://openai.com/index/unrolling-the-codex-agent-loop/). As an end user you neither build nor tune that craft; you feed it.

2. What the vendor already built — harness engineering you inherit

Know this machinery exists so you don't rebuild it, and so you know what your context files are feeding into.

Vendor-built harness component Where it lives End-user takeaway
Agent loop + tool routing Every CLI implements the same six stages: prompt assembly → inference → parse tool calls → execute → append results → re-query → exit (https://openai.com/index/unrolling-the-codex-agent-loop/); a basic loop is "a few dozen lines of code" (https://simonwillison.net/guides/agentic-engineering-patterns/how-coding-agents-work/) Don't rebuild the loop. Its power is the machinery around it, and you didn't build that either.
Prompt assembly System/instructions + tool schemas + memory files + environment + history + your message are composed into one prompt each turn Your AGENTS.md, skills, and memory feed this stage directly — this is your point of influence.
Context management Compaction, trimming, and prompt-cache-friendly organization; Anthropic pushes context transformation into the harness so the raw session log stays lossless You don't implement compaction. You supply well-scoped input so it compacts well.
Permissions / sandbox gates Approval prompts, permission rules, checkpoints (Claude Code documents permissions/checkpoints instead of OS sandboxing: https://code.claude.com/docs/en/how-claude-code-works) Configure, don't reimplement.
Session / history OpenCode is a headless server with a full session API (POST /session, GET /session/:id/message, GET /event SSE, resume/fork/abort: https://opencode.ai/docs/server/); Codex has non-interactive codex exec Resumable, durable session state is provided out of the box.
Error handling, cross-session memory, tool schemas, token economics The five harness decisions identified when the same model was forked across CLIs (file-edit tools, command sandboxing, context management, error handling, cross-session memory): https://news.ycombinator.com/item?id=46991089 Baked in by the vendor.

Why awareness matters: the harness sets the ceiling. The same model run on the same benchmark through different harnesses differs by ~15+ points (an evolved single harness reached 76.4% on Terminal-Bench 2.0 with Claude Opus 4.6, harness choice alone: https://github.com/stanford-iris-lab/meta-harness-tbench2-artifact), and the token spread across six harnesses for identical tasks with the same model was roughly 30x (5.07M down to 173K tokens: https://news.ycombinator.com/item?id=49135257). You can't capture those gains by editing prompts — you capture them by choosing which harness you adopt, and then by feeding your chosen harness good context.

3. What you own: context assembly and prompt generation

Your day-to-day work answers the asset-side question — "what can the agent know, use, or be asked?" — not the governance question. That is prompt engineering.

Work Example Why it is prompt engineering
Repository instructions AGENTS.md / CLAUDE.md per repo or zone; auto-loaded and injected at prompt-assembly time Instructions, not execution; the vendor's discovery/loading is harness, the content is context
Skills A SKILL.md with name + description, body loaded on demand (https://pydantic.dev/docs/ai/harness/skills/ shows the same pattern) A reusable procedure, prompt, or domain capability — instruction-shaped
Curated memory Approved decisions, architecture records, durable facts; retrieval policy chooses what is fresh, permitted, relevant Selection and injection policy — prompt content
Tool selection Which MCP servers and tools are exposed at all A narrower, better-chosen tool surface reduces ambiguity and token waste
Task framing The initial prompt: objective, constraints, acceptance criteria The single highest-leverage prompt you write
Evidence selection Choose relevant files and architecture records to inject; avoid injecting every past transcript Inclusion/exclusion and ordering is prompt craft

Why this stays prompt engineering even though machinery handles it: the vendor auto-loads your AGENTS.md, scopes it, validates skills, and compacts history. The content and selection of what the model sees is entirely yours. That is the definition of the asset side of the boundary: it "supplies knowledge, a capability, an environment, or an individual worker" — it does not "govern the reliable, bounded, observable execution of agent work."

This is your durable advantage. Shopify's companion work makes the point directly: "The most durable advantage you can develop is a harness tuned to the particularities of your software development ecosystem... You'll keep this part as new models come and go" (https://shopify.engineering/under-the-river). For an end user, tuning the harness means writing knowledge as files — AGENTS.md, skills, curated decisions — and letting the vendor machinery load them.

4. The thin slice that is harness engineering for end users

A small amount of your work legitimately crosses into harness engineering: governance added around the CLI when its defaults don't cover your reliability, safety, integration, or governance needs. It shows up in three places:

  1. Verification gates. Defining "done" before you delegate: required tests, lint/build checks, review rules, acceptance criteria. The CLI executes your tools; it does not decide what counts as a completed task.
  2. Isolation and state. A worktree convention or sandbox wrapper, and durable task state (task → branch → result → evidence) so work can resume or be handed off.
  3. Managed-context hooks. A hook that only writes records is telemetry or a history log. It becomes harness behavior when it participates in managed context: redacting secrets, labeling task state, selecting relevant prior decisions, compacting them, and returning a bounded context package before the next agent step. The raw history stays session data; the selection and injection policy is harness.

Everything else you might label "harness" is actually an asset the harness coordinates — valuable, but not a harness:

Item What it is When it becomes a harness component
AGENTS.md Repository instructions and conventions A runtime discovers the applicable file, validates/scopes it, and injects it for an execution
Agent skill A reusable procedure or domain capability The runtime authorizes, loads, invokes, evaluates, and retries the skill
Sandbox or container An isolated execution environment The control plane provisions it and applies resource/access policy
Curated memory Approved knowledge or durable facts Retrieval policy chooses what is fresh, permitted, relevant
Past query/output log Historical data or telemetry A governed system redacts, summarizes, and injects relevant material
SDK-built agent / workflow graph An application or orchestration definition A surrounding runtime controls its inputs, permissions, state, verification, audit

"Not a harness" does not mean "do not build it." The distinction prevents you from expecting a single file, skill, or container to deliver reliability and governance that require coordination across the lifecycle — and it keeps you from doing vendor work.

5. What to focus on: an ordered end-user playbook

Step 0 — Choose the harness once. Because the harness sets the ceiling and you can't tune a vendor's, your single most important harness engineering decision is which CLI to adopt. Compare the harness engineering, not the brand: context management, sandboxing, tool schemas, token economics, and error handling (the five decisions that produced the 2x same-model gap: https://news.ycombinator.com/item?id=46991089). Then stop re-deciding.

Step 1 — Make context assembly your daily craft. Highest leverage per hour. Maintain AGENTS.md, a small high-quality skill library, and curated decisions; be deliberate about what evidence you inject and what you leave out. This compounds as the model changes.

Step 2 — Add verification gates first. The first harness extension worth owning: encode what "done" means (tests, lint, review rules) so a plausible patch and an acceptable one are distinguishable.

Step 3 — Add isolation and task state only when needed. Worktrees or a sandbox when tasks can damage the workspace or need reproducibility; task state when work must resume or be handed off.

Step 4 — Add policy, audit, orchestration last. Permission boundaries, approvals, traces, and redaction for teams; queues, retries, workers, and SDK agents only for long-running or concurrent workflows. Avoid building a platform before a problem exists.

6. Boundary test

Use this test for any proposed feature, and ask which bucket it falls in:

  • Context assembly / prompt generation: "What can the agent know, use, or be asked?" — the content, selection, and framing you author.
  • Harness engineering (vendor): "How is the loop run, context managed, and execution gated?" — already built by Codex, Claude Code, OpenCode.
  • Harness engineering (yours, thin): "For this task, under what authority and constraints may it use it; how is its use observed; and how is the result verified?" — only where the CLI defaults fall short.

For example, a sandbox answers "where can code run?" A harness additionally answers when to create it, which repository and credentials it receives, whether network is allowed, when it expires, what is retained, and what happens after a failed command. The vendor provides most of that answer; you supply the parts specific to your workflow.