What is an agent harness (and how do you secure one)?

An agent harness is the software shell that turns a language model into a working agent: the loop that plans and retries, the tool and shell executors, context and memory management, the approval prompts, and the sandbox. The model decides. The harness acts.

That division also settles a common argument about AI agent security. When a coding agent wipes a database or leaks a credential, many people ask what the model was thinking. The more useful question is what the harness allowed. Across our own testing of coding agents, open source agent frameworks and skill scanners, the exploitable flaws concentrate in the harness layer, and hardly any of them require the model to be broken at all.

What an agent harness is

Because the term is new, we lean on Wikipedia’s definition: an agent harness, also known as agent scaffolding, is the software infrastructure surrounding a large language model that enables it to operate as an AI agent. It manages tool use, memory and state persistence, execution environments, feedback loops, context management, and guardrails such as scoped permissions, approval tiers and monitoring.

A simpler way to say the same thing: the model reasons through a problem and decides what to do next, and the harness turns those decisions into actions. LangChain’s version of the definition is blunter. If you are not the model, you are the harness.

One naming collision that could arise stems from a “family relationship”. A test harness is a framework of scripts, tools and data that provides a controlled environment for automated test execution, and the AI usage descends directly from it. Related scaffolding ideas exist in LLM benchmarking, where an evaluation harness runs a model against a fixed task set, and in reinforcement learning environments and wrappers. The pattern is the same in every case: build the rig that lets the thing under test do work and be observed doing it.

Where the term came from

“Harness engineering” is recent vocabulary for a practice that predates it. Mitchell Hashimoto used the phrase in a February 2026 blog post, describing the habit of changing the environment around an agent so a given mistake cannot recur, instead of retrying the prompt and hoping. OpenAI published its own harness engineering report days later, covering five months of building with Codex agents and roughly a million lines of code, none of it handwritten. The back-to-back publication pushed the term into general use.

Attribution is contested. Some credit LangChain’s Vivek Trivedy and his “Anatomy of an Agent Harness” post, which derives the components from the Agent = Model + Harness formula. However, the direction of travel is not contested. Once models got good enough that prompt quality stopped being the bottleneck, attention moved to the code around them.

Which tools are agent harnesses

The agent harness category is wider than the coding agents that made it popular.

Every coding agent you have heard of is a harness. Claude Code, Codex CLI, Gemini CLI, Cursor, Antigravity, OpenCode, aider and Grok Build CLI are harnesses in the strict sense: a loop, executors, context management, approval prompts and some notion of a sandbox, wrapped around a model API.

OpenClaw and Hermes are harnesses too, though with a different shape, built as a gateway with registered nodes (a macOS companion app, iOS devices, other machines) that expose capabilities like running system commands, camera access and reading contacts.

Frameworks count as well, when they ship the runtime rather than just the abstractions. Anthropic describes its Claude Agent SDK as a general-purpose agent harness. LangChain’s Deep Agents ships a planning tool, a virtual filesystem, subagent spawning, automatic context compaction and middleware for human-in-the-loop approval, and connects out to sandbox providers including Modal, Runloop and Daytona. Read that feature list again and you will spot the anatomy above.

Evaluation harnesses are the same word doing an older job: the rig that runs a model against a benchmark.

The anatomy of an agent harness

A typical AI agent harness consists of five distinct parts.

The loop is the control structure that keeps the agent going: reason, act, observe, repeat, with retries and stopping conditions. The canonical academic reference is ReAct (Yao et al., ICLR 2023).

Executors are the parts that actually run things: the shell executor, the file tools, MCP servers, and any custom tools you have registered.

Context and memory management decides what the model sees each turn, from instruction files and retrieved documents through to compaction and state that survives between sessions.

Approval gates provide an interface for a human in the loop. They display the prompts asking whether the agent may run this command or edit that file.

Finally, the sandbox allows containing the agent within its isolated working space. Depending on OS and other execution environment specifics, it can include such features as process isolation, filesystem scoping, network communication rules, and scoped credentials.

Anthropic’s engineering post on effective harnesses for long-running agents is the clearest worked example of the context and memory piece in production. Agents work in discrete sessions with no memory of what came before, so the harness supplies one. An initializer agent sets up the environment on the first run, and a coding agent makes incremental progress in each subsequent session. The environment artifacts do the remembering: a JSON feature list where the agent may only modify the pass/fail field, a progress file, an init script, and git commits as the handoff mechanism between sessions.

Figure: A general diagram of an agent harness.

Why the agent harness is the security boundary

A model that declines a malicious instruction is expressing a preference. The same prompt on the next run may not produce the same refusal. A harness that will not execute it is enforcing a control. That makes the harness the right place to put security.

Getting it right there is another matter. A harness is an assembly of IDE features, agent tools, config files and MCP servers, and an attacker can combine them freely to achieve their goals.

Marzouk’s IDEsaster research found over 30 such vulnerabilities and left every AI IDE and coding assistant he tested exploitable. The common mechanism: take a prompt injection primitive, combine it with the agent’s tools, and use them to activate legitimate IDE features until you get data leakage or command execution.

Our own results point the same way. In SymJack we tested six coding agents and every one fell for the same approval bypass. In GuardFall we surveyed 11 open source agents and 10 left the boundary between agent and shell exploitable. In our skill scanner survey, a malicious skill got past all eight scanners we could run. Different layers, same finding: the model is not where the boundary broke.

How agent harnesses break

Nine attack classes cover most of the published work. Each one targets a part of the harness anatomy.

SymJack attacks the approval prompt, the control every one of these products leans on for safety. A booby-trapped repository ships an instructions file telling the agent to copy what looks like a media file, using a raw shell copy rather than the agent’s own write tools, because the native tools flag sensitive paths and a raw copy does not. The destination is a symlink committed into the repo, pointing at the agent’s own configuration. The developer approves a video file copy. The kernel follows the link and writes attacker-controlled MCP server definitions into the config, and the payload runs on the next restart with full user privileges. The permission prompt inspects command text, not resolved effect, so the user approves what the screen shows while the filesystem does something else.

GuardFall attacks the executor’s guard. Most agents gate shell access behind a matcher that compares the command string against dangerous patterns. But the string being inspected is not the string that runs, because bash expands, unquotes and rewrites text afterward. We tested 11 open source coding and computer use agents with roughly 548,000 combined GitHub stars, and 10 left the boundary exploitable in one of four ways.

TrustFall attacks config trust. All four CLIs we tested (Claude Code, Gemini CLI, Cursor CLI, Copilot CLI) execute project defined MCP servers the moment the folder trust prompt is accepted. The prompt is not informative and undersells the risks though: “Quick safety check”.

The remaining attack classes are well documented by others. On trust boundary carryover, tool permissions, sandbox isolation and shared workspaces each judge “trusted work” differently, so a restriction that is valid at one step stops applying at the next. Novee Security showed what that costs at Black Hat USA 2026. In Gemini CLI, GitHub tokens and API keys were stripped from child processes but stayed readable in the parent, where the injected instructions run. In Codex, two runs share a workspace, so a compromised first run can write the AGENTS.md that the second run reads automatically. If you want a single citation for treating the harness as the boundary, that is the one.

Exfiltration is the step that turns access into loss. Researchers turned Hugging Face’s public download counter into a side channel that leaked an API key one character at a time (CVE-2026-54316). IDEsaster included a variant where the agent writes a JSON file referencing an attacker-controlled schema URL, which the IDE then fetches automatically. Neither needs a network tool. Both use a feature.

How to secure an agent harness

Agent harness security starts by assuming the model can be compromised by the content it reads, and puts the controls somewhere it cannot argue with them: process boundaries, credential isolation, egress filtering, human gates on irreversible actions, and an audit trail.

There is promising academic and practical work in the field, structural fixes like the CaMeL framework among them. But no production grade implementation exists as of September 2026, and no mainstream agent harness we know of has adopted one. Contain the damage. Do not wait for the architecture that prevents it.

Two frameworks give you a decision rule you can apply today. Simon Willison’s lethal trifecta (June 2025) says the dangerous combination is private data, untrusted content and external communication in one system: any two are manageable, all three are not. Our own AI Risk Quadrant Report found the lethal trifecta in 98% of the 100 AI agents it rated.

Meta generalized the finding in October 2025 as the Agents Rule of Two, which says an agent should satisfy no more than two of three conditions in a single session: processing untrustworthy inputs, accessing sensitive systems, and changing state or communicating externally. If a task needs all three, it does not run autonomously. Applied to a coding agent, that immediately flags the common setup: cloned repo (untrusted input), local credentials (sensitive systems), shell and network access (state change and communication). Most teams are running all three by default.

Allowlist, do not blocklist. This is the direct lesson of GuardFall, and it applies to tools, secrets and network destinations alike. Blocklisting commands is a losing game, because the shell will always have another way to say the same thing, and because blocking ps still leaves cat /proc/*/cmdline. Decide what the agent is allowed to run, which credentials it can see, and which hosts it can reach, then deny the rest. Treat the agent like a new hire and ask what the role actually needs.

Treat agent configuration as executable code. Project scoped settings, instruction files, MCP definitions and hooks all reach execution without a tool call, which is exactly what TrustFall and the IDEsaster settings overwrite cases exploit. Pin agent config through managed settings that a repository cannot override, deny project scope for anything that can spawn a process, and review MCP definitions, project settings files, AGENTS.md and .cursor/rules/ in code review the way you would review a CI workflow file. In CI, do not trust the workspace automatically on pull request branches.

Do not treat the approval prompt as a boundary. SymJack exists because that prompt inspects command text rather than resolved effect. If your process depends on a developer reading a dialog, assume it will be defeated by anything that changes meaning between display and execution: symlinks, long commands that scroll off screen, nested deeplinks, argument injection.

Watch the chain of events. Every individual step in the attacks above is legitimate. Reading a file is fine. Copying a file is fine. An MCP server starting is fine. A network call is fine. The sequence is the attack, which is why detection has to correlate model conversation, tool calls and endpoint behavior into one view rather than alerting on isolated actions. This is the capability the AI detection and response (AIDR) category is forming around, and it is what our own coding agent security platform is built to do: see agent activity across model calls, tool executions, file access and outbound connections, correlate it into a decision graph, and stop dangerous chains before they complete.

For mapping to a standard, the OWASP Top 10 for Agentic Applications (launched December 2025) lines up cleanly with the classes above. ASI01 Agent Goal Hijack covers class one, ASI02 Tool Misuse runs through classes two, three and six, ASI03 Identity and Privilege Abuse covers classes four and five, ASI04 Agentic Supply Chain Vulnerabilities covers seven and eight, and ASI06 Memory and Context Poisoning covers nine. ASI05 Unexpected Code Execution is where most of them end up, with data exfiltration as the other terminal state.

The short version to act on this week: inventory which harnesses your developers actually run and at what versions, get agent config under managed policy so repositories cannot set it, replace command blocklists with tool and credential allowlists, cut egress to an allowlist, check whether any agent in your fleet is listening on a network interface, and put session level logging in place before you need it for an incident.

The harness is software, and it ships weekly

One consequence gets missed in the strategy conversation. An agent harness is a versioned software product with a release cadence measured in days, running on developer laptops and CI runners with full user privileges, and it is currently accumulating CVEs faster than most teams are patching it. Several of the fixes referenced above landed in point releases no one was tracking closely.

So the boring controls matter more than the exotic ones. Know which harnesses are in your environment, know their versions, subscribe to their release notes, and treat an overnight self-update as a change that needs review. The agent security problem is new. The vulnerability management problem underneath it is not.

FAQ

Is an agent harness the same thing as an agent framework?

Overlapping but not identical. A framework gives you abstractions for building agents; a harness is the runtime that actually executes one. Frameworks that ship a loop, executors, memory and sandboxing, like LangChain’s Deep Agents or the Claude Agent SDK, are harnesses. A library that only helps you compose prompts is not.

Do I need a harness to use an LLM?

Not for a single prompt and a single response. The harness starts to matter the moment a task becomes multi-step, uses tools, or runs long enough to need memory across sessions. That is also the moment it starts to matter for security.

Is the model or the harness responsible for agent security?

Both, but not equally. Model level defenses reduce how often an agent is tricked. Harness level controls determine what happens when it is. Since prompt injection has no reliable general fix today, the harness is where the enforceable boundary has to sit.

How is harness engineering different from prompt engineering and context engineering?

Harness engineering is the broader layer that contains both. Prompt engineering shapes what you ask, context engineering shapes what the model sees, and harness engineering changes the environment around the agent, including its tools, permissions and feedback loops, so a given failure cannot happen again.

Is Harness.io related to agent harnesses?

No connection at all. Harness.io is a CI/CD company founded in 2017. The AI usage of “harness” descends from the software testing sense of the word, not from the vendor.

Further reading

Our own research on the failure classes above:

• SymJack: the approval prompt is lying to you, symlink hijack RCE in six AI coding agents
• GuardFall: a universal shell injection vulnerability in open source AI agents, 10 of 11 agents surveyed
• TrustFall: 1-click coding agent RCE, project scoped settings as an execution vector
• Claude Code deny rules silently bypassed, the validation/execution mismatch class in one product
• A hole in every one: bypassing the open source AI skill scanners, eight scanners, eight bypasses
• The Cursor deeplink vulnerability, one click to an attacker-controlled MCP server
• Nine AI coding agent incidents that ended with deleted data

External primary sources:

• Agent harness (Wikipedia)
• My AI adoption journey (Mitchell Hashimoto)
• The anatomy of an agent harness (Vivek Trivedy, LangChain)
• Effective harnesses for long-running agents (Anthropic Engineering)
• Harness engineering (Böckeler, Thoughtworks)
• Code execution deception in Gemini CLI (Tracebit)
• Black Hat 2026: critical flaws found in Anthropic, Google and OpenAI coding agents (eSecurity Planet, on Novee Security’s research)
• The lethal trifecta (Simon Willison)
• Agents Rule of Two (Meta)
• CaMeL: defeating prompt injections by design (Debenedetti et al., 2025)
• OWASP Top 10 for Agentic Applications (OWASP GenAI Security Project)
• ReAct: Synergizing Reasoning and Acting in Language Models (Yao et al., ICLR 2023)