Start with a dictionary entry.harness, as a noun, has a first definition that has nothing to do with software engineering. It means equipment for a working animal: the complete set that lets an ox or horse pull a cart without running out of control. More precisely, a harness is the equipment used for pulling and working; saddles and stirrups for riding do not count. The word was made for working animals. Reins control direction, a bit provides an emergency stop, shafts transfer force to the cart, and protective gear guards against accidents. Calling the system around a model a Harness, as the industry has done over the past two years, is remarkably honest: in an earlier articlewe called an Agent that works for you around the clock a cyber workhorse. Before a workhorse can work, it needs a harness.
Why give this layer its own article? Because of a fact that rarely gets stated plainly: the model's intelligence is rented.You and your competitors call the same few APIs. The ceiling of model capability is the same for everyone. What you own is the harness around the model. It determines whether that model becomes a chat box or a system you trust with real work. The industry now expresses this as an equation: Agent = Model + Harness. The overview article cited a LangChain experiment in which the model stayed unchanged and only the Harness changed: the terminal-task score rose from 52.8% to 66.5%. That entire difference came from the harness.
So this article examines the harness, not the model. It is organized around a user's concern rather than a maintainer's component list: what gives me the confidence to let it work?That breaks down into four smaller questions: what can it touch, what happens when it fails, who watches it, and where does it work? HexClaw's engine source provides an answer to each.
Prompt (finale) → Context (previous article) → Harness ▸ This article → Loop (overview)
For the memory side of Context, see Agent Memory That Dreams
(A map of the harness. Each corner answers one trust question; the rented engine sits in the middle. The protective layer has just had a major overhaul.)
Question 1: What Can It Touch? Tools and Permission Gates
The first strap is the rein. HexClaw's engine uses a unified tool loop, following the mainstream Agent approach: every round presents the full tool list to the model. If the model returns tool calls, they run and the loop continues; otherwise, the response is the answer. The ordinary path does not branch on whether this round should expose tools. The boundary is enforced by gates, not by hiding tools. Some protocol-specific cases do narrow the tool surface, forcing one tool or applying a source-dependent minimum tool set. Those are routing and error-prevention mechanisms, not an attempt to make invisibility a security boundary.
There are two gates. The first is permission approval, enabled by default. Each tool has one of three risk levels: safe / sensitive / dangerous . Consequential actions—running shell commands, writing files, sending messages, or changing capabilities—become an approval request in the frontend, with the tool name, arguments, and reason, and wait for your consent. An approval can be remembered for the current session so the same tool need not keep interrupting you. It resembles a bank's second-person check: the action itself cannot judge intent, but having consequences is enough reason to pause. In an interactive session, code execution, file changes, and capability changes all ask first, without exceptions.
The second gate sits at the filesystem boundary and is more interesting. To import local files into the knowledge base in bulk, the Agent calls knowledge_ingest_path. Notice that it accepts only paths, not file contents. Code reads the files itself: at most 200 per call, valid UTF-8 text only, with paths passing safe resolution. Symlink escapes and .. traversal are rejected. Every directory entry is resolved again during enumeration to prevent symlink detours. The implication is worth considering: what the model says it read is not evidence; what the code actually reads is.Taking data acquisition out of the model's hands is a more fundamental gate than an approval popup.
The tool surface creates another, more recent problem: it is not fixed at release. MCP can connect third-party tools at any time, and Skills can be installed or created. HexClaw provides a direct route through its built-in Skill / MCP marketplace, which fetches a catalog from the official hub repository for search, browsing, and one-click installation. New parts can always be attached to the harness, and the supply channel remains open. That creates a self-referential requirement: changing the harness must itself pass through the harness's gates.HexClaw classifies create_skill, manage_skill, and manage_mcp_server as sensitive and requires approval. The code calls these actions capability injection / capability changes; the regression test's English name is even more vivid: capability mutation. The difficult case is unattended execution: nobody is there to click Allow. How is the gate maintained? HexClaw does not hide these tools from the toolbox. That was the old approach: a hardcoded stripping list, now reduced to a compatibility no-op. A visible, configurable automatic-approval matrix replaces it. In the default profile, called function-first in the source, unattended scheduled jobs and webhooks automatically allow routine reading, browsing, execution inside a sandbox, file editing, and external delivery. Running shell commands directly on the host remains outside that boundary and always goes to approval. Two categories are held back: capability changes—the three tools above—and scheduling new jobs for itself. The comment calls the latter a self-replication loop: jobs creating jobs. A workhorse cannot alter its own harness or hire another workhorse. The refusal now comes from the gate, not from hiding tools. This returns to the point at the beginning of this section: enforce boundaries with gates, not concealment。
Are these gates a rigid blanket rule, or can you adjust them? The Automation Permissionssettings page answers that by exposing the matrix as a control panel. You can choose Function First / Strict Approval / Full Capability . The engine also recognizes a balanced state, but the desktop does not give it a separate card, avoiding too many profiles. Each profile explains which capabilities run automatically and which require approval; installing / modifying capabilities even gets its own row. Unsure about a newly connected Webhook? Start with Strict Approval, let every automatic job ask first, and observe before relaxing it. Finer than a global profile is per-job authorization. Instead of relaxing the global default for one job, authorize only the capabilities that job needs. Deleting the job revokes its authorization automatically. MCP connector tools without a built-in category use this route for unattended execution.Trusting an Agent with work therefore becomes a graduated control, rather than an all-or-nothing bet.One boundary with the next article: a Markdown Skill is different. It contains instructions for the model, not a tool, and belongs in the finale.
Question 2: What Happens When It Fails? Controlled Failure
Workhorses stumble; tools time out. A harness cannot guarantee no fall, but it can make a fall survivable. HexClaw wraps tool execution in a retry layer. The parameters are modest, and each has a reason:
The last line is the key. The policy comment states it plainly: retry only clearly transient errors; treat unknown errors conservatively. A network hiccup merits another try. Invalid arguments remain invalid after a hundred attempts. Retries address bad luck, not bugs. Browsers get 120 seconds and code execution 60 seconds according to their actual runtime distributions, rather than one arbitrary global timeout.
A task that never ends needs more control than a single failure. The tool loop has a round budget: 25 by default. The comment explains that this allows normal tasks enough space, and reaching the limit is normal termination rather than an error. Budget mode adds an absolute safety cap of 50 rounds. These numbers appeared in the overview, but read differently here: a budget gives an unfinished task a clean stopping point. A runaway long task costs much more than a failed short task.
Question 3: Who Watches It? Judges That Do Not Trust the Executor
This is the section I most want to examine, because it corresponds to the most counterintuitive piece of equipment: a supervisor outside the workhorse's control. Financial systems call this maker/checker: the person handling a transaction and the person checking it must be different. HexClaw's engine has an entire family of judges with one shared rule: never accept the executor's own report as proof。
The first judge provides an optional stricter admission checkfor unattended work. The matrix from Question 1 normally determines what unattended tasks may touch. Above it, the engine offers a pluggable, stricter judge: an independent risk reviewer. It receives a task description and a prompt asking for one word—low / medium / high. Its MaxTokens is only 16; the comment says a one-word verdict should stay cheap. Its decision rule is strict: only low passes; medium, high, classification failure, or even an unconfigured judge all reject. Anything other than an explicit low is treated toward high. The source is clear that this does not replace the matrix by default; it is an extra tightening option for deployments needing a more conservative policy. The design itself is a textbook fail-closed gate: if the gate breaks, it locks rather than opens.
The second judge scores quality. An LLM-as-judge samples Agent tool-call performance, and poor performance becomes a Skill improvement draft. Its tradeoff is described directly in the source:
Scoring every tool call consumes LLM quota, so use sampling (default 0.1 = 10%)… On LLM failure, timeout, or parsing failure, return 10 points (fail-open), so judge instability does not generate false-positive draft noise。"
— from the header comment in skill_judge.go. The quotations in this article come from code comments, not conference stages.
Together, these judges reveal an easy-to-miss symmetry. A broken risk review returns high, failing closed; broken quality scoring returns full marks, failing open. Two gates in the same system deliberately fail in opposite directions. That is a consistent design: a gatekeeper must lock when broken, while an optional enhancement must get out of the way. Before adding a gate, decide which direction it should fall when it fails.
The third judge handles independently checkable work such as mathematics. After the solving Agent gives an answer, a verifier subrole recalculates it with code in a fresh context and compares the results. It has only one tool, code_exec , and cannot see the solving process, so it must calculate independently. The fourth judge is simpler and sharper: it checks whether claimed work actually occurred. A scheduled job says it saved material to the knowledge base? Check the tool-call record:
The job claims ingestion succeeded, but its tool-call list contains no knowledge_ingest call. The result is failure, with a blunt reason: success was reported without ever invoking the ingestion tool; nothing was stored. Those seven lines capture the entire family's worldview: a claim does not count; the invocation and its side effects do.Another judge maintains order: multi-Agent spawning has a dedicated fan-out guard. Once the total across the tree reaches its limit, new subtasks are rejected. That belongs to the Loop overview, so I will not repeat it here.
Question 4: Where Does It Work? The Recently Overhauled Sandbox
HexClaw has complete answers to the first three questions. The fourth needs a more qualified discussion. Start with what exists: code_exec uses an independent sandbox abstraction. Its configuration can be hot-reloaded: changed limits rebuild the sandbox instance without a restart. macOS applies a Seatbelt profile. The scheduled-job script sandbox was covered in the cyber workhorse article: a Starlark interpreter, an 8 MiB cap per HTTP fetch, a 100-million-step instruction limit, and a 300-second timeout. Self-healing scripts are compiled into that cage.
This protective layer has just had a major overhaul. The old code_exec was closer to a snippet executor: submit code, obtain a result. The overhaul adds four execution modes—snippet / file / module / project—covering a snippet, a file in a repository, a module, and project commands in a workspace. Artifact files such as charts, CSVs, and logs can come back; long output has enforced bounds. Unauthorized host paths stay out of isolated runs: project mode exposes only explicitly authorized project roots, with secrets-deny rules taking precedence over that exposure. Entry-point inference also accommodates weaker tool-using models, guiding a model that can emit only mode=file toward the correct execution mode. Most tellingly, the sandbox now has its own dedicated CI, with a cross-operating-system matrix. The old problem of apparent cross-platform support is now checked continuously. All four pieces of the harness are in place. Protective equipment always has another layer to add—more complete dependency installation and deeper platform isolation remain on the roadmap—but the work we trust it with has expanded from running a snippet to operating on a project。
The most overlooked layer is not a resource limit. It is that the sandbox keeps your secrets outside. Even if project mode receives your entire $HOME as a workspace, default deny rules still take precedence over several path classes: external credential directories ~/.ssh、~/.aws, gcloud, and gnupg, plus HexClaw's own critical files: the master key master.key that can decrypt all credentials encrypted at rest, the configuration file hexclaw.yaml containing provider API keys, and the encrypted store data.db. Another rule is DenyLoopback. Code may fetch web pages and call APIs, but cannot reach local loopback. This prevents an unattended Agent from probing local administration ports to escalate its privileges, a textbook SSRF self-escalation surface. One platform boundary needs stating honestly: macOS enforces loopback blocking at the Seatbelt layer. Linux currently does not isolate the network namespace, so loopback remains reachable. That is a known capability gap requiring higher-level or deployment-side controls.The cage controls more than how long code runs: it also controls what it can read and where it can connect.
The Leading Vendors Are Building the Same Layer Under Different Names
Look at leading model vendors' Agent documentation and many of the longest chapters concern the harness. Harness is the now-common name for this layer; the working-animal metaphor follows its literal dictionary meaning. Individual product documents use different terms. OpenAI's Agents SDK makes input/output guardrails first-class features. Codex's local sandbox varies by platform: Seatbelt on macOS, bubblewrap on the main Linux/WSL2 path, with Landlock/seccomp terminology for the CLI sandbox helper, and a native Windows sandbox. Anthropic documents permissions and sandboxing for its Claude Agent system and has open-sourced its sandbox runtime. That announcement describes the same threat model as the secrets-deny rules above: without network isolation, a compromised Agent could send out your SSH key. Google's ADK inserts checks around tool calls through callbacks. The terminology differs, but the direction agrees: even the model vendors repeatedly say a model alone is not ready for the road. It is strong support for Agent = Model + Harness: the people supplying the first term work hard on the second. A paper this year makes the point explicit in its title, Harness as an Asset. Treating the harness as an asset is the academic formulation of rented model, owned harness.
A terminology distinction helps here. Two groups are pulling Harness Engineering in different directions. OpenAI's February article about Codex and Martin Fowler's article of the same name use it for a software-development paradigm. Engineers write constraints—AGENTS.md, lint rules, or self-running loops such as Ralph—instead of writing the code directly, and the Agent writes the codebase. That harness faces the development bench. This article concerns the runtime layer around the model that lets an Agent inside your product act without causing trouble. Both meanings are real and growing; they should not be conflated. This series covers the latter. The former is closer to our Claude Code SOP article and could merit a separate discussion.
Back to the series: the previous article explained how retrieval makes what the Agent sees each round trustworthy. This article explains how what it does afterward stays controlled. Together, trustworthy evidence and controlled action give trusting it with work an engineering meaning.
But the harness is not the whole story. Everything here has been a hard gate: approval, timeouts, verdicts, and cages enforced by code. Each round's system prompt also contains thousands of words of softer constraints: its personality, discipline, and when to ask instead of acting. Hard gates contain failure; soft constraints define expectations. The industry calls that soft, foundational layer Prompt, the first of the four paradigms. The finale explains why it did not die, but settled into a protocol.
The Four-Paradigm Series
▸ Loop · Overview Tracing the Four Paradigms from Prompt to Loop Through an Open-Source Agent
▸ Context · Documents The Hard Part of RAG Is Keeping Answer-Shaped Noise Out of the Loop
▸ Context · Memory Agent Memory That Dreams: HexClaw Dreams on Your Machine
▸ Prompt · Finale Prompt Engineering Became the Agent's Foundational Protocol (finale, coming soon)
More Articles
▸ The HexClaw Cyber Workhorse: Compiling a Sentence into a Self-Healing Sandbox Script
▸ The Claude Code SOP Behind HexClaw: Design, Testing, and Multi-Agent Collaboration
References
· OpenAI, Agents SDK — official Guardrails documentation; Codex sandbox documentation (macOS Seatbelt / Linux and WSL2 bubblewrap, Landlock + seccomp for the CLI helper / native Windows sandbox, with restricted-token unelevated fallback)
· Anthropic, Claude Agent permissions and sandboxing documentation; open-source sandbox-runtime
· Google, Agent Development Kit (ADK) — callbacks
· LangChain, Terminal-Bench 2.0 comparison with a fixed model (GPT-5.2-Codex) and a changed Harness (52.8% → 66.5%; see the series overview)
· Harness as an Asset: Enforcing Determinism via the Convergent AI Agent Framework (CAAF), arXiv:2604.17025 — an academic treatment of the harness as an asset
· Terminology: OpenAI, Harness engineering: leveraging Codex in an agent-first world (2026-02), and Martin Fowler's article of the same name refer to a development paradigm in which humans write constraints and Agents write code, distinct from the runtime harness discussed here
· Maker/checker (the four-eyes principle), the banking industry's standard two-person review control
· All HexClaw mechanisms and constants cited here were checked against the repositories' main branches on 2026-07-04. the code_exec sandbox upgrade, the four execution modes snippet / file / module / project, and cross-platform CI had all been merged into main