Architecture Evolution

1. Reading Guide and Positioning

1.1. The Three Questions This Document Answers

01-Introduction.md established the definition and six-layer capability model of AI Harness, and 02-Development History.md established the timeline of the three-generation evolution. This document is the intersection of the two, and it answers three questions:

1. What a contemporary (third-generation) Harness actually looks like — which components make up each layer, and how these components connect to one another;
2. Why the engineering design of each layer has its current shape — what failures it has to overcome, and what price was paid for that;
3. How an organization can judge what level its own Harness is at — providing an actionable self-assessment tool.

1.2. Boundaries with Prior Documents

1.3. Convention on Source Tiers for Technical Parameters

This document cites many engineering parameters published by vendors. Every citation is labeled with a source tier, following the rules in README.md section 5.2:

• Tier A: vendor official primary sources (Anthropic / OpenAI / Google / Linux Foundation / MCP official, etc.), can be cited directly;
• Tier B: authoritative secondary sources (Wikipedia, AI Wiki, TechCrunch, GIGAZINE, etc.), must be noted as paraphrases;
• Tier C: community and self-media interpretations; their numbers are uniformly flagged as unverified.

All numbers appearing in this document can only serve as directional references and must not be used as the basis for selection or decision-making.

2. Overview of the Third-Generation Architecture

2.1. The Basis for Layering: From "Capability Zoning" to "Bottleneck Zoning"

The reason the third-generation Harness can be stably divided into six layers is not that six layers is some a priori functional division, but that each layer corresponds to a class of independently emergent bottleneck. This can be worked backwards from roll-the-DAG-style failure attribution: when a long-cycle agent task fails, the engineer's attribution almost always falls into one of the following six categories—

Layers are defined by failures, not by feature lists. This is the practical criterion for judging which layer a new component should belong to.

2.2. Layered Design Overview Diagram

图 2-1｜第三代架构总览：六层分层设计

┌──────────────────────────────────────────────────────────────────┐
│  L6  治理与安全层    Governance & Safety                          │
│      权限 · 沙箱策略 · 凭据保护 · 架构约束 · 熵治理 · 预算护栏    │
│      （横向切面，对 L1~L5 全部施加约束并记录审计）                │
└──────────────────────────────────────────────────────────────────┘
   ▲               ▲               ▲               ▲
   │ 约束           │ 约束           │ 约束           │ 审计
┌──┴────────┐  ┌───┴────────┐  ┌───┴─────────┐  ┌──┴──────────┐
│ L1 上下文  │─►│ L2 工具与   │─►│ L3 编排与    │─►│ L5 评估与    │
│ 工程层     │  │ 执行层      │  │ 控制层       │  │ 观测层       │
│ 看到什么   │  │ 能做什么    │  │ 按什么顺序做 │  │ 做得好不好   │
└───────────┘  └────────────┘  └─────────────┘  └─────────────┘
        ▲                              │                   │
        │  反馈：改变下次看到什么       │                   │
        └──────────────────────────────┴───────────────────┘
        ▲
   ┌────┴───────────────────────────────────────────┐
   │  L4  记忆与状态层   Memory & State              │
   │       会话态 · 长期记忆 · 检查点 · 工件         │
   │       （时间维度的横向支撑层）                  │
   └────────────────────────────────────────────────┘

It should be emphasized that the feedback edge between L5 and L1 in the diagram is the structural difference between the third and second generations: in the second generation evaluation is bolted on (run a benchmark once, glance at the score), while in the third generation the output of evaluation flows back to change the next round of context assembly, forming a closed loop.

2.3. Responsibilities, Boundaries, and Data Flow of the Six Layers

The main execution chain is L1 → L2 → L3, the lateral supports are L4 (temporal dimension) and L6 (constraint dimension), and the closed loop is L5 → L1.

2.4. Comparison Against the Three-Generation Evolution

The maturity differences of the six layers described in this document across the three generations are as follows (looking at each layer vertically, you can see that the engineering focus of the third generation falls on L1, L2, L5, and L6):

3. The L1 Context Engineering Layer

3.1. Positioning of the Layer

The question L1 answers is: before this step of reasoning, which tokens should the model see. It is the only layer in the entire Harness that acts directly on the model's input interface, and therefore has always occupied the most central position across the three generations of evolution.

The official definition given by Anthropic in "Effective context engineering for AI agents" (2025, Tier A) is: during LLM inference, the full set of strategies for curating and maintaining that optimal set of Tokens (information).

The definition given by Andrej Karpathy on 2025-06-25 is widely cited:

"Context engineering is the delicate art and science of filling the context window with just the right information for the next step."

But his immediately following supplement is more valuable—he says context engineering is only a small part of "an emerging thick layer of non-trivial software that coordinates individual LLM calls into full LLM apps". This sentence precisely defines L1's position among the six layers: it is a necessary layer, but far from the whole.

3.2. The Official Problem Statement: context rot and the attention budget

Two concepts erected by Anthropic officially constitute the theoretical foundation of the L1 layer:

Together these two yield a counterintuitive but repeatedly verified engineering conclusion: cramming more information into the context is usually a negative optimization. Section 3.10 presents the corresponding failure modes.

3.3. Key Component One: Compaction

The official documentation divides compression into several tiers, of which the "safest and lightest" tier is tool result clearing, a capability already live on the Claude Developer Platform (Tier A).

The tuning order given officially is an important engineering discipline:

Maximize recall first, then improve precision.

Reversing the order loses critical constraints that later steps still need—because once compressed content cannot be restored, the model will make irreversible wrong decisions in later steps based on incomplete information.

3.4. Key Component Two: Structured Notes and Agentic Memory

The second official strategy is to persist notes outside the context window and pull them back when needed. Official cases include:

• Claude Code's to-do list;
• A custom agent's NOTES.md;
• The precise counting Claude maintained across thousands of steps while playing Pokémon.

The official team also released the Memory tool (entered public beta on the Claude Developer Platform alongside Sonnet 4.5, Tier A), turning externalized notes into a platform capability.

The selection principle given officially is worth quoting directly as a team norm:

3.5. Key Component Three: Sub-Agent Context Isolation

The third official strategy is Sub-agent architectures, whose official parameters (Tier A) are:

A sub-agent can explore deeply using tens of thousands of tokens, but returns only a condensed summary of 1,000~2,000 tokens.

This is a typical architectural trade-off of "exchanging context for parallelism / for depth": the main agent's context window stays clean, at the price of information loss in the summarization process. When selecting in this layer one must consider explicitly: is the summary loss acceptable.

3.6. Key Component Four: Skills and Progressive Disclosure

Agent Skills (Anthropic, released 2025-10-16, converted to an open standard on 2025-12-18, Tier A) pushes L1 from "how to cram in more" to "how to load on demand".

Anthropic's official claim is:

"the amount of context that can be bundled into a skill is effectively unbounded"

This design effectively alleviates the "more capabilities, more crowded context" contradiction. At the same time the official documentation gives the economic argument for replacing tokens with code: sorting a list costs far more in generated tokens than running a sorting algorithm once, and code is deterministic, making workflows consistently reproducible.

3.7. Another Industry Taxonomy: The Four Pillars

Besides Anthropic's official four-way split, another widely used one in the industry is the LangChain four pillars (Harrison Chase, "The Rise of Context Engineering", 2025-06-23, organized per Lance Martin's taxonomy, Tier B):

The two taxonomies map onto each other: Anthropic's "first three strategies" largely cover the first three of Write / Select / Compress / Isolate, and sub-agent corresponds to Isolate.

3.8. Comparison of Representative Implementations

3.9. Design Trade-offs

Three core trade-offs of the L1 layer:

3.10. Failure Modes

Four classes of context failure have been identified at the L1 layer (Tier B, LangChain's categorization per multiple paraphrases):

Quantitative supplement (Tier C): 2025 research found that "semantically consistent but irrelevant data can degrade performance by more than 45%"; Chroma Research tested 18 frontier models in 2025-07, and every one degraded as the context grew.

Engineering implication: the construction priority of the L1 layer is not "retrieve more" but "delete more". Vercel's subtraction experiment in section 4.4 (tool count 15 → 2, flagged as unverified) is on the same logic as this section's "one external rehearsal"—reducing supply is often more effective than increasing it.

4. The L2 Tooling and Execution Layer

4.1. Positioning of the Layer

The question L2 answers is: what actions the model can apply to the environment, and where those actions execute. The layer contains three classes of components:

4.2. MCP: The Connection Standard of Layer 2

MCP adopts a Host / Client / Server three-role architecture (Tier A):

Transport: local uses stdio, remote uses Streamable HTTP, and messages are based on JSON-RPC 2.0.

Google officially gave a clear division of labor between MCP and A2A ("A year of open collaboration", 2026-04-16, Tier A):

"MCP manages internal tool integration, while A2A handles the vital external coordination between autonomous entities."

That is: MCP manages internal tool integration, and A2A manages external coordination between agents. The two are not in competition; they are connection protocols in different directions inside the Harness.

4.3. The Five-Version Spec Evolution Chain of MCP

The following version chain is first-hand parameters (MCP Ruby SDK Protocol Versions page + mcpkit docs.rs + Klu entry, Tier A) and can be cited in full:

From this evolution chain, three clear orientations of the third-generation Harness at the protocol layer can be read:

1. From stateful sessions to stateless requests—the 2026-07-28 removal of the handshake and session ID lets a remote MCP server scale horizontally like an ordinary web service;
2. From "good enough" to "evolvable"—the 12-month minimum deprecation window is a marker of mature standardization governance, meaning users can safely plan their dependencies;
3. From "tools only" to "agents on the server side too"—the 2025-11-25 server-side agent loop sinks part of the L3 responsibilities inside the L2 boundary (the server-side execution domain).

Version status note: Wikipedia and some sources say "2024-11-05 initial release / 2024-11-25 public announcement", which differs from the MCP Ruby SDK listing only 2024-11-05 as the "Initial protocol revision"; the two statements can coexist. See section 13 for details.

4.4. Tool Design Guidelines

Anthropic's official documentation gives three tool design guidelines (Tier A), usable directly as a checklist for team toolset review:

1. Self-contained, robust to errors, extremely clear in purpose;
2. Avoid feature overload and ambiguous decision points—a tool that does many things makes the model hesitate when choosing, and makes failure causes hard to attribute;
3. Few-shot examples should be "diverse and typical", not a list of edge cases.

Echoing this is the "right altitude" principle for system prompts: they must neither be written as fragile hard-coded logic nor be so vague that only high-level guidance remains, but should be "specific enough to effectively guide behavior, yet flexible enough to leave the model room for strong-heuristic judgment".

4.5. Sandbox: The Official Implementation in Claude Code

The Claude Code sandbox is the most completely publicly disclosed agent sandbox design to date ("Sandboxing: a safer and more autonomous approach" + official documentation, Tier A). The following parameters can be cited in full.

Core security axiom (Tier A original text): filesystem isolation and network isolation are both indispensable—

• Without network isolation, a compromised agent can exfiltrate SSH keys;
• Without filesystem isolation, a compromised agent can escape easily and obtain network access.

Platform implementation and default policies

Two operating modes

Even in auto-allow mode, deny rules, rm -rf-class commands targeting / or the home directory, and content-scoped ask rules still take effect.

Escape hatch and strict mode: a dangerouslyDisableSandbox retry is provided; it can be disabled via allowUnsandboxedCommands: false, i.e. Strict sandbox mode.

Credential protection (requires Claude Code v2.1.187+): sandbox.credentials can deny access to files (e.g. ~/.aws/credentials, ~/.ssh) and environment variables (e.g. GITHUB_TOKEN, NPM_TOKEN); v2.1.199+ supports mode: "mask".

Process-level sandbox (@anthropic-ai/sandbox-runtime): wraps the entire Claude Code process (including built-in tools, MCP servers, and hooks) in the same isolation layer; by default it denies writes to .git/hooks, .git/config, .mcp.json, .claude/commands, .claude/agents, and shell startup files.

Configuration paths: .claude/settings.local.json (project level) / ~/.claude/settings.json (user level) / managed settings (organization level); sandbox.failIfUnavailable can be set to a hard failure.

Quantified effect (Tier A, the core number repeatedly cited in this module): Anthropic's internal use found that sandboxing safely reduced permission prompts by 84%.

4.6. Cross-Comparison of Sandbox Implementations

Supplement (Tier B): Codex CLI was rewritten from Node.js to Rust in the second half of 2025; by early 2026 roughly 95% of the codebase is Rust; the official rationale is static single-file distribution, no GC, low memory footprint, and direct invocation of OS sandbox primitives. In 2026-04 an Auto-review mode was added; internal sessions stopping for human approval occur at roughly 1/200 the rate of the manual mode, with an approver pass rate of about 99%.

4.7. Design Trade-offs

4.8. Failure Modes

5. The L3 Orchestration and Control Layer

5.1. Positioning of the Layer

The question L3 answers is: in what order to act, who does what, and how to recover after an interruption. The main orchestration forms and their applicability:

5.2. The Agent Loop and the Dual-Agent Architecture for Long-Running

Anthropic's "Effective harnesses for long-running agents" (Tier A) disclosed the first-generation official solution for long-running tasks: the dual-agent division of labor of Initializer Agent + Coding Agent.

Artifacts of the Initializer Agent (the handoff package)

One hard rule established by that generation of architecture: removing or modifying tests is unacceptable.

The three opening steps of the Coding Agent's session (officially stipulated, Tier A)

1. Run pwd to confirm the current working directory;
2. Read the git log and the progress file;
3. Read the feature list and select the highest-priority unfinished item.

Session-end constraint: the environment must be left in a mergeable clean state.

5.3. Plan-and-Execute and the Three-Agent Architecture

Anthropic's "Harness design for long-running application development" (2026, Tier A) disclosed the second-generation official solution: the Planner / Generator / Evaluator three roles, whose design inspiration clearly comes from generative adversarial networks (GANs).

Three key mechanisms

1. Sprint Contract: before coding, the Generator proposes "what to build + how to verify success", and the Evaluator reviews and reaches consensus. Agree on the definition of "done" before starting — this is the most important process design in this layer.
2. self-evaluation bias (self-praise): officials observed that agent self-evaluation will "confidently praise" work that is clearly mediocre in human eyes. This is precisely the fundamental reason for separating the Evaluator (see section 7.2 for details).
3. context anxiety: when an agent's context approaches its limit, it tends to wrap up hastily and declare completion early.

Open question (officially acknowledged, Tier A): Anthropic explicitly states that "whether a single general-purpose coding agent is always optimal, or a multi-agent architecture split into specialized agents for testing, QA, cleanup, etc. is better — this is currently unclear".

5.4. Sub-agent Dispatch

The multi-agent research system (Anthropic "How we built our multi-agent research system", 2025, Tier-A project, URL flagged as unverified) provides the official dispatch pattern:

• The main agent holds the high-level plan and is responsible for coordination;
• Sub-agents do deep technical work or information retrieval within clean context windows;
• Sub-agents only return 1,000~2,000-token summaries (same-source parameter as section 3.5);
• Significantly outperforms a single agent on complex research tasks.

The trade-off against kernel-level variability (uncertainty) is: parallelism in exchange for summary loss.

5.5. State Machines and Deterministic Workflows

Google ADK (released 2025-04-09, Apache 2.0, Python first, v1.0.0 on 2025-05-20, Tier A) provides another route: making orchestration into declarable primitives.

An important feature of ADK is the coexistence of determinism and dynamism:

• Deterministic workflow agents: SequentialAgent / ParallelAgent / LoopAgent;
• LLM-driven dynamic routing: the transfer mechanism of LlmAgent.

ADK also has a built-in evaluation harness (AgentEvaluator.evaluate()), capable of dual-scoring the final response and the step-by-step trajectory, and consuming third-party framework tools via LangchainTool / CrewaiTool adapters, supporting MCP, A2A, and OpenAPI.

5.6. Interruption and Recovery

Both the community and officials have isomorphic practices of "letting agents iterate continuously". Anthropic's engineering blog mentions methods for letting agents iterate continuously via hooks or scripts; the community practice (such as the Ralph Wiggum Loop, Tier B) works as follows:

Intercept the model's exit attempts via hooks, re-inject the original prompt in a clean context window, and force the agent to continue working around the completion goal.

The premise for this method to hold is the file system: each iteration starts from a fresh context, but reads the state left behind by the previous one. This is essentially the same "external state + clean context" idea as the dual-Agent architecture in section 5.2; the only difference is whether the driver is another agent or a hook.

5.7. Design Trade-offs

5.8. Failure Modes

6. The L4 Memory and State Layer

6.1. Positioning of the Layer

The question L4 answers is: how state is handed off across sessions and across context windows.

Anthropic's official statement of this challenge is highly evocative (Tier A):

Imagine a software project staffed by engineers working shifts, where every new engineer, on arriving for their shift, has no memory of what happened on the previous shift.

This statement also explains why L4 only became an independent concern in the third generation: first- and second-generation task durations still fit within a single context window, so the problem simply does not arise.

6.2. State Handoff Across Context Windows

The complete official handoff scheme (Tier A):

Health check (officially stipulated): before the Coding Agent starts implementing a new feature, it must first run an end-to-end test to confirm the environment is healthy. The official rationale is that the model "tends to declare a feature complete without adequate testing".

Human-level verification (officially recommended): equip the agent with browser automation tools (such as Playwright MCP) so it can verify products like a real person — officials explicitly state this significantly improved performance.

6.3. The Division of Labor Between Compaction and Context Reset

The two are often conflated; officials (Tier A) clearly distinguish them:

The relationship between the two can be understood as: Compaction is symptomatic treatment (slowing decay); Reset is radical treatment (complete debridement), but Reset's cost is transferred to the quality of the handoff in the L4 layer.

6.4. Checkpoints and Artifacts

A distinctive feature of third-generation Harness is: treat Git as the carrier of state and memory, rather than starting a separate memory database. The benefit of this choice is inheriting the entire toolkit already used by human engineering teams (diff, blame, revert, CI); the cost is needing extra conventions on commit granularity and branching strategy.

Anthropic's official approach is to put three things — "ticket + log + code" — together: claude-progress.txt (log) + feature list (ticket) + git (code + version).

6.5. Design Trade-offs

6.6. Failure Modes

7. The L5 Evaluation and Observability Layer

7.1. Positioning of the Layer

The question L5 answers is: how well it was done, how to judge it, how to regress-test it.

This layer received the highest status elevation in the third generation — the reason can be summarized in one official judgment (Anthropic, Tier A):

"Harness design is key to performance at the frontier of agentic coding."

And the evaluation layer is precisely the only part of the Harness that can answer "did this Harness change actually help". Without L5, Harness engineering cannot form a closed loop and can only tune parameters by intuition.

7.2. First Principle: Separate the Evaluator from the Evaluated

The phenomenon observed by Anthropic officially (Tier A) is the most important design basis for the L5 layer:

When an agent evaluates its own work, it will "confidently praise" it — even when human observers clearly see mediocre quality. This is especially pronounced on subjective tasks without binary criteria (such as design).

The rationale and source of inspiration given officially are worth quoting in full:

Training an independent Evaluator to be skeptical is far easier than making the Generator self-critical. (Inspired by GAN)

Implementation: the Evaluator sets hard thresholds separately for four dimensions — product depth, functionality, visual design, code quality; if any falls below its threshold the iteration fails, and the detailed failure reasons are fed back to the Generator.

Transfer suggestion: this principle also holds for non-coding scenarios. For any subjective-quality agent task, one should set up a judge isolated from the generator, whether it is a rule, a script, or another model.

7.3. External Benchmarks and the Built-in Evaluation Loop

The L5 layer has two mutually irreplaceable components:

The relationship between the two is irreplaceable: external benchmarks prevent self-congratulation (you can make your own eval all green yet have no competitiveness); the built-in loop prevents regression (external benchmarks can only be run a few times a year and cannot cover private business).

SWE-bench (2023-10-10, 2,294 task instances, 12 Python open-source repositories, ICLR 2024 Oral, Tier A) established the principle of programmatic scoring: pass the tests to pass, "no partial credit for nice-looking code that fails the tests". Terminal-Bench's principle is likewise "either the automated tests pass or they do not".

7.4. Open Observability to the Agent

OpenAI gave a highly inspiring L5 practice in "Harness engineering" (2026-02-11, Tier A): open the observability stack to the agent itself.

The engineering significance of this approach is: feed L5's observability capability back to L1 as context. The agent is no longer a blind-writing black box; it can, like an engineer, look at logs, query metrics, and verify whether its own changes meet the standard.

7.5. The scaffold Effect: Quantifying Harness Differences

The evidence that best demonstrates the value of L5 is quantitative data for the phenomenon "same model, different Harness, different score".

Terminal-Bench (Stanford + Laude Institute, released 2025, Tier-A project) states directly in its methodology:

"Terminal-Bench does not score a model in isolation. Every result is a model plus an agent harness... the leaderboard is a ranking of systems, not of models."

Its v2.0 (released late 2025 to early 2026, 89 tasks, migrated to the Harbor framework, Tier-A project / specific numbers flagged as unverified) has each task reviewed by 3 independent human reviewers; accuracy drops from about 65% at easy difficulty to about 16% at hard, a cross-level drop of about 49% (Tier B).

The following comparison data all come from Tier-B/C sources and are uniformly flagged as unverified, serving only as directional reference:

The five-item change list behind LangChain's "52.8% → 66.5%" is one of the most transferable pieces of content in the entire document (Tier C, unverified numbers, but the changes themselves have engineering reference value):

1. Force checklist-style self-verification before allowing "done" to be said;
2. Scan the directory structure before startup and inject environment context;
3. Anti-drift detection — warn when repeatedly editing the same file;
4. Adjust the reasoning budget — think more for planning and verification, less for implementation;
5. Automated failure-mode analysis.

All five items involve no model swap and all belong to Harness engineering. They can be directly ported to other scenarios.

7.6. Design Trade-offs

7.7. Failure Modes

8. The L6 Governance and Safety Layer

8.1. Positioning of the Layer

The question L6 answers is: what must not be done, how to discover it if done, and what is the spending ceiling. It contains four categories of components — permission model (RBAC), guardrail models, audit logs, and budget guardrails — and acts as a cross-cutting aspect applying constraints to all of L1~L5.

A common misconception that must be clarified: governance slows things down. Anthropic's sandbox evidence gives the opposite conclusion — permission prompts reduced by 84% with improved safety (Tier A). Constraints are not the opposite of autonomy; they are the precondition of autonomy.

8.2. Permission Model and Sandbox Strategy

Layered configuration of governance policy (taking Claude Code as an example, Tier A):

Key switches include sandbox.enabled, sandbox.failIfUnavailable, allowUnsandboxedCommands, filesystem.allowWrite / denyWrite / denyRead / allowRead. Among these, sandbox.failIfUnavailable can be set to hard failure — if the sandbox cannot start, refuse to run, rather than quietly degrading to non-sandbox mode. This is an important lesson in governance robustness: do not give safety mechanisms a silent degradation path.

8.3. Credential Protection

sandbox.credentials provides protection on two dimensions — files and environment variables (requires v2.1.187+; v2.1.199+ supports mode: "mask"):

Recommended default deny list: ~/.aws/credentials, ~/.ssh/*, GITHUB_TOKEN, NPM_TOKEN, and various cloud vendor environment variables.

8.4. Mechanical Enforcement of Architectural Constraints

The environment governance practice given by OpenAI in "Harness engineering" (2026-02-11, Tier A) is the most systematic official case for the L6 layer.

Layered dependency rule (unidirectional dependency): within each business domain, code can only depend "forward" —

Types  →  Config  →  Repo  →  Service  →  Runtime  →  UI

Cross-cutting concerns can only enter through the single Providers interface. This rule is mechanically enforced, rather than relying on verbal code review conventions.

Taste Invariants: statically enforced via a custom linter — structured logging, schema and type naming conventions, file size limits, platform-specific reliability requirements.

The most critical engineering trick among them is: because the linter is self-built, error messages are written as repair instructions injected into the agent context. In other words, the linter does not just "report an error" but "reports an error + teaches the agent how to fix it". This directly converts L6's failure signal into L1's context input, forming a closed loop.

The official summary can be quoted directly:

In human-first workflows, these rules may feel pedantic; with agents, they become multipliers — once codified, they take effect everywhere immediately.

The governance philosophy is analogized as "leading a large engineering platform organization: the center enforces boundaries, the periphery allows autonomy".

8.5. Garbage Collection: Countering Entropy Growth

OpenAI named the third pillar of Harness engineering Garbage Collection, targeting the entropy growth problem after large-scale agent output. Anthropic also explicitly lists "context still decays" as an issue the third pillar must handle.

Specific mechanisms (Tier A):

• doc-gardening agent: periodically scans outdated documentation and automatically initiates repair PRs;
• Four major failure modes (officially summarized): ① context is a scarce resource; ② too much guidance becomes no guidance; ③ immediate decay (rot immediately); ④ hard to verify mechanically.

Among these, "too much guidance becomes no guidance" is especially noteworthy: when AGENTS.md is written too long, the agent skips reading it, just like a human. This directly leads to the "AGENTS.md changed from encyclopedia to table of contents" decision in section 10.2.

8.6. Design Trade-offs

8.7. Failure Modes

9. Harness Loop: The Engineering Structure of the Main Loop

9.1. Definition and Positioning: The Loop is the Heart of the Harness

The previous three chapters dissected the components and trade-offs of each of the six layers layer by layer; this chapter assembles them back into the runtime's overall form: Harness Loop (the agent main loop based on the Harness). The unified definition follows this repository's parameter card and must not be rewritten:

Harness Loop: the agent main loop carried by the Harness — the agent iterates within the runtime provided by the Harness as "goal assembly (L1) → planning (L3) → tool execution (L2) → observation feedback (L5) → state update (L4) → re-planning", until the termination condition is met or the governance boundary (L6) is triggered.

Three official statements from the two leading vendors, Anthropic and OpenAI, are highly consistent with this definition (Tier A):

The core proposition of this chapter is: the Loop is the heart of the Harness, not an attribute of the Agent. A bare loop detached from the Harness (bare ReAct) only has L2 tool execution; the characteristic of the Harness Loop is that every turn is assembled by L1, observed by L5, booked by L4, and constrained by L6. This correspondence is shown in Figure 9-1.

图 9-1｜Harness Loop 单圈结构与六层模型对应

示意图：基于本文分析，机制依据三家官方循环描述（A 级，信息截止 2026-09-12）。

9.2. Single-Turn Structure: Isomorphism of the Three Official Implementations

Whether Claude Code, Codex, or Gemini CLI, a single turn (one iteration) has the same structure: context assembly → model reasoning → tool invocation → result verification and backflow. This is the direct engineering embodiment of "the Loop is the heart of the Harness" — the heart beats in an isomorphic way; the differences lie only in the valves (confirmation gates, approval gates) and the loop's exit conditions.

Anthropic Claude Agent SDK's official five-step definition ("How the agent loop works", Tier A):

1. Receive the prompt (including system prompt, tool definitions, session history);
2. Claude evaluates and responds (text or tool invocation);
3. The SDK executes tools and collects results;
4. Steps 2~3 repeat; each completed full cycle is one turn;
5. Output the final response containing no tool invocations, together with the ResultMessage (including token usage, cost, session ID).

Loop termination criterion = producing a response containing no tool invocations.

OpenAI Codex's official loop description ("Unrolling the Codex agent loop", Tier A): user input → assemble prompt → reason → the model either produces a final assistant message (loop termination signal) or requests a tool invocation → the Agent executes the tool and appends the output to the prompt → re-query. A single turn can contain multiple rounds of "reasoning—tool" iteration; officials explicitly point out that context window management is one of the agent's (harness's) responsibilities — this is precisely the evidence that L1 is written into the loop.

Gemini CLI's ReAct loop (Tier B, official repository documentation consistent with multiple sources): the cli initiates reasoning → the model returns a ToolCallRequest → CoreToolScheduler four steps (queue / validate / confirm / execute; sensitive operations are suspended at the confirmation gate awaiting user UI confirmation) → tool results are packaged back to the model via the callback chain → a new round of reasoning. Loop termination: the model invokes the explicit complete_task tool, or a termination condition such as timeout / error is triggered.

Difference points within the isomorphism (Tier B, community source-code-level dissection):

9.3. Cross-Turn Mechanisms: Five Classes of Control Flow

Above the single turn, the Harness Loop relies on five classes of cross-turn mechanisms to maintain the sustainability of long tasks (based on Anthropic's official engineering blog and each framework's documentation; annotations inline):

Two key mechanisms are institutionalized in Anthropic's "Harness design for long-running application development" (2026, Tier A): Sprint Contract — before coding, the Generator and Evaluator negotiate the definition of "done", giving each turn's observational verification (L5) a basis; Context Reset — replacing "summarize + continue" with "clear + hand off", transferring the cost to the quality of the L4 handoff (for the detailed division of the two mechanisms, see section 6.3).

The quantified benefits of cross-turn mechanisms are supported by official hard data: OpenAI's "Codex as a platform" (2026, Tier A) disclosed that on the ARC-AGI-3 benchmark, retained reasoning + context compression raised GPT-5.6 Sol's score from 13.3% to 38.3%, while reducing output tokens by 6× — this is the most forceful official number for "Harness design directly changes outcomes" (information as of 2026-09-12).

The overall shape of cross-turn control flow and the tiering of termination conditions is shown in Figure 9-2.

图 9-2｜跨圈控制流与终止条件分级

示意图：基于本文分析，终止条件口径沿用本库参数卡统一分级（信息截止 2026-09-12）。

9.4. Termination Condition Tiering and the Triple Hard Limits

"When does the loop stop" is not an implementation detail but the core contract of the Harness. The unified criterion divides termination conditions into five tiers (corresponding to Figure 9-2):

Beyond the tiering, industry practice has distilled a set of triple hard-limit empirical values (Tier C, industry practice compilation, directional reference only):

The triple hard limits each connect to a different failure form; none can be missing; when exceeded, partial results (a progress summary) should be returned rather than a bare error. There is also one structural conclusion (industry practice, Tier C): the kill switch must be placed at the gateway layer with a unique ID — an escaped agent will not honor the limits in its own code.

9.5. Framework Loop Semantics Comparison

Beyond the generic Harness, there is a clear genealogy across frameworks' loop semantics: from "structure decides when to stop" (bounded loops on visualization platforms) to "the model decides when to stop + governance as backstop" (autonomous loops in coding Agents).

Three semantic differences worth expanding on (source tiers annotated in the table):

1. LangGraph: exceeding the limit is not death but a recoverable pause (Tier B, source-code corroboration). The GraphRecursionError triggered by recursion_limit, together with the Checkpointer, can recover from the last persisted state or raise the budget to continue — "a circuit breaker rather than business logic".
2. AutoGen → MAF: from implicit message loop to explicit graph loop (Tier B). AutoGen's GroupChat has unpredictable loops and ambiguous termination conditions due to LLM speaker selection, allowing infinite loops — this is the direct driver of the "implicit message loop → explicit typed graph" evolution; MAF's Workflow provides typed loop steps, checkpointing, HITL, and a middleware pipeline (including token budget enforcement). Community comparison data show MAF's explicit conversion reduces LLM calls by 23% versus GroupChat (Tier B, third-party paraphrase).
3. Dify: iteration decided by data, looping decided by conditions (Tier B, source-code-level documentation). The Iteration node traverses an array, materializing an independent sub-engine per element; parallelism defaults to 10, per-node maximum iteration defaults to 100, with three-tier error handling (TERMINATED / CONTINUE_ON_ERROR / REMOVE_ABNORMAL_OUTPUT); the Loop node consists of loop_count maximum count + break_conditions stopping criteria + loop_variables inherited across rounds. The visualization platform is a representative sample of replacing "the LLM decides when to stop" with structural bounded loops; n8n / Coze loop nodes belong to the same pattern (their official first-hand loop documentation was not directly obtained; see section 13's gap statement).

9.6. Failure Modes and Governance

Loop failure modes named officially (Anthropic engineering blog, Tier A): doing too much at once (one-shot), premature completion declaration (premature completion), context anxiety, self-evaluation bias (self-praise), and early multi-agent systems' "50 sub-agents + infinite searching for nonexistent sources + progress inflation among themselves". Most of these failure modes were already expanded from the L3 perspective in section 5.8; this section focuses on the distinctive form of overall loop loss of control.

Representative incident: multi-agent ping-pong loss of control (Tier B, source annotated verified: partial — multiple posts consistent but no named victim company; for reference as a representative case only): an incident post-mortem circulating in the industry recorded a loss of control in a four-agent market research pipeline (LangChain + A2A): the Analyzer and Verifier agents fell into a "produce—nitpick—revise" ping-pong loop; with no shared budget and no round-trip counting, weekly API spend rose from $127 to $891, $6,240, $18,400 in sequence, and was manually shut down at $47,000 after 264 hours. The post-mortem identified two root causes: no per-agent budget cap; no mechanism to terminate the session before the next API call. The common lesson is: the party making the invocation decision cannot see the cost of the next invocation.

Three failures of application-layer throttling (industry practice, Tier C): ① framework bypass — code calls the LLM API directly, circumventing framework limits; ② exception swallowing — MaxIterationsExceeded is silently swallowed by except and the loop continues; ③ process restart resets counters — after a crash-restart, the loop accumulates cost across lifecycles. The conclusion drawn aligns with section 8.5's sandbox.failIfUnavailable hard failure: hard boundaries should sit at the infrastructure layer (gateway / proxy), not in the agent's own code.

Loop telemetry: Codex natively supports OpenTelemetry log export (Tier A); exported events include user prompts, approval decisions, tool execution results, MCP usage, and network proxy allow / block events, integrable with SIEM and compliance log platforms; on the Anthropic side, the ResultMessage carries token usage, cost, and session ID, and /usage, /goal with no arguments, and /workflows provide skill / sub-agent / MCP-level usage observability (Tier A). The community observability scheme (Tier B) gives a generic model: OTel span tree = session → step → LLM call, with core metrics of per-step latency percentiles (P50 / P95 / P99), per-session tokens, cost split by model and step, and error rate and retry frequency; a common heuristic alarm is "suspected loop after more than 10 steps".

Governance practice checklist (mainly Tier A):

10. Key Leaps from Second to Third Generation

10.1. The Six-Item Leap List

Synthesizing the six layers above, the third generation underwent six structural leaps relative to the second:

The sixth item is the philosophical core of the whole leap: human work moves up from "operating" to "designing environments, feedback loops, and control systems" (OpenAI original: "Our most difficult challenges now center on designing environments, feedback loops, and control systems.").

10.2. Complete Paradigm Sample: OpenAI's Million-Line Code Experiment

The most complete public evidence of the third-generation Harness is the internal experiment disclosed in OpenAI's "Harness engineering" (2026-02-11, Tier A). The following numbers are all first-hand and can be quoted in full:

Note a counterintuitive observation: throughput actually rose after the team expanded from 3 to 7 people — this contradicts the traditional software engineering intuition that "adding people worsens PR conflicts", indicating that this Harness's coordination overhead is lower than the output brought by the added headcount.

Six key engineering decisions and their corresponding layers

There is also one technology-selection principle worth remembering separately: prefer "boring technology" (composability, API stability, widespread presence in training corpora). The official example is self-building map-with-concurrency rather than introducing p-limit — the rationale is that models handle "things widely present in training corpora" better.

This principle is universal for all Harness design: in systems where agents write code, the technology's "model familiarity" is a real selection metric, alongside performance and ecosystem.

10.3. The Parts of the Leap Not Yet Completed

The third generation is far from the endpoint. The following problems are officially acknowledged as unresolved (Tier A):

1. The single-Agent vs multi-Agent debate is undecided — Anthropic explicitly states "currently unclear";
2. Cross-domain generalization unverified — whether the above experience can generalize to other long-cycle tasks such as scientific research or financial modeling; "the answer is still being explored";
3. The Harness itself lacks evaluation methods — the open question raised on martinfowler.com: we need Harness coverage and quality evaluation methods analogous to code coverage and mutation testing (not yet appeared);
4. Entropy governance still relies on patches — doc-gardening is a remedy for decay, not a root cure for decay.

11. Harness Capability Maturity Self-Assessment Table

11.1. Construction Notes for the Self-Assessment Framework

Important note: the table below is an analysis framework constructed independently by this project based on the aforementioned public materials, not a specification published by any standards organization, nor an official model from any vendor. Its value lies in providing an actionable yardstick to help organizations locate their own Harness capability and perform generational alignment. Please do not use it as a compliance basis or an industry benchmark.

The framework defines five levels (0~4) for each of the L1~L6 layers and gives the identifiable characteristics of each level.

11.2. Five-Level Definitions

11.3. Self-Assessment Table

11.4. Result Interpretation

The item inter-layer gap ≥ 2 levels is especially important. The Harness's overall output is limited by the weakest layer, not the strongest — this is consistent with the bucket effect in software systems. For example, a system whose L1 is only at level L1 (manually pasting context) but whose L2 reaches level L3 will often perform worse than a system where both are at level L2.

11.5. Usage Recommendations

1. Self-assess once every six months, and record the results for comparison — the value of the self-assessment itself lies in longitudinal comparison, not horizontal scores.
2. Give specific evidence layer by layer during assessment; do not write abstract "medium"; write "our context compaction relies on XXX".
3. Prioritize the weakest layer, not the average score.
4. Be wary of "evaluation inflation": when a layer is rated L3 but has no regression-testable evidence (e.g., no Golden Dataset), it should be downgraded back to L2.

12. Conclusion

The architecture of the third-generation Harness can be summarized in one sentence: it is a system that narrows the model's output distribution, through a six-layer structure, into the engineeringly acceptable interval.

• L1 decides what the model sees — the key bottleneck is the attention budget; the core means is deletion, not addition;
• L2 decides what the model can do — MCP solved the connection standard; the sandbox solved the side-effect boundary;
• L3 decides in what order to act — from a single loop to the division of labor among Planner / Generator / Evaluator;
• L4 decides what to remember — Git became the mainstream state carrier; cross-window handoff is the lifeline of long tasks;
• L5 decides how well it was done — the first principle is separating the evaluator from the evaluated;
• L6 decides what must not be done — governance is not the enemy of speed; official evidence is an 84% reduction in permission prompts.

And what strings the six layers together is nine characters: visible, stable, regressable.

The question for the next stage is: will this architecture be directly absorbed by stronger models? For the two-sided answer to this question, see section 2.1 of 04-Future Development.md; for a comprehensive judgment on the entire development stage, see 05-Conclusion.md.

13. Information Gap Statement

This section summarizes the information gaps involved in this document; they have been marked in the corresponding places in the body or explained with source tiers.

Gaps already existing in this research, reusable across sources

1. The exact URL and publication date of Anthropic's "How we built our multi-agent research system": cited only in link form in the context engineering blog; unverified.
2. Differing wording on MCP's "first public specification version": two criteria coexist — 2024-11-05 (the Ruby SDK records it as Initial protocol revision) and 2024-11-25 (public announcement and ecosystem launch); this document presents them in parallel.

Numbers with insufficient source tiers; already flagged in this document

1. Section 3.10: context degradation's "performance drop exceeding 45%" and Chroma Research's "all 18 frontier models degraded".
2. Section 4.6: Codex CLI's "about 95% Rust in early 2026", Auto-review's "1/200" and "99%", and the review model type "GPT-5.4 Thinking".
3. Section 4.7: Vercel's tool count 15 → 2 accuracy 80% → 100%, Token −37%, speed 3.5×.
4. Section 5.7: the comparison experiment numbers for Anthropic single Agent (20 minutes / $9 / unusable) vs three Agent (6 hours / $200 / complete and playable).
5. Section 7.5: all Terminal-Bench 2.0 leaderboard numbers (77.3% / 75.1% / 74.7% / 71.9%), LangChain 52.8% → 66.5%, and the easy about 65% → hard about 16% difficulty gradient.
6. Section 7.5: the Terminal-Bench official site's (tbench.ai) current leaderboard data was not directly scraped; all are third-party paraphrases.

Items not covered in this document but belonging to this module's common gaps

1. ISO/IEC agent interconnection international standard number: no authoritative information currently.
2. First appearance of the term "Agent Harness": no authoritative information currently.
3. Claude models' 2026 version timeline: seen only in third-party GitHub timeline repositories; flagged as unverified.

Newly added this round (Chapter 9, Harness Loop)

1. The specific publication dates of OpenAI official blog posts such as "Unrolling the Codex agent loop", "Unlocking the Codex harness", and "Codex as a platform" were not directly returned in the search results (sections 9.2 / 9.3).
2. The $47,000 multi-agent ping-pong loss-of-control case is verified: partial (multiple posts consistent, no named victim company); the body has phrased it as "a representative incident post-mortem circulating in the industry" and retained the numbers (section 9.6).
3. The industry triple hard-limit empirical values (iteration cap 10 / 25 / 50~100, token budget 10× the mean, wall-clock timeout 2~3× the p95) are an industry practice compilation (Tier C); directional reference only (section 9.4).
4. n8n / Coze loop nodes lack independent first-hand official documentation; only indirectly covered via the common bounded-loop pattern of visualization workflows (section 9.5).
5. MAF reducing LLM calls by 23% versus AutoGen GroupChat is a third-party paraphrase (Tier B); the official first-hand manuscript was not directly hit (section 9.5).

For the complete list, see section 9 of 06-References.md.

14. References

1. Effective context engineering for AI agents — Anthropic, 2025. https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents
2. Effective harnesses for long-running agents — Anthropic, 2025. https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents
3. Harness design for long-running application development — Anthropic, 2026. https://www.anthropic.com/engineering/harness-design-long-running-apps
4. Equipping agents for the real world with Agent Skills — Anthropic, 2025-10-16. https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills
5. Introducing Agent Skills — Anthropic, 2025-10-16 (2025-12-18 open standard update). https://www.anthropic.com/news/skills
6. Sandboxing: a safer and more autonomous approach — Anthropic, 2025. https://www.anthropic.com/engineering/claude-code-sandboxing
7. Claude Code official documentation · Sandboxing (Chinese edition) — Anthropic, 2026. https://code.claude.com/docs/zh-TW/sandboxing
8. Claude Code official documentation · Choose a sandbox environment — Anthropic, 2026. https://code.claude.com/docs/en/sandbox-environments
9. Introducing the Model Context Protocol — Anthropic, 2024-11-25. https://www.anthropic.com/news/model-context-protocol
10. Harness engineering: leveraging Codex in an agent-first world — OpenAI, 2026-02-11. https://openai.com/index/harness-engineering/
11. Harness engineering (Chinese edition) — OpenAI, 2026-02-11. https://openai.com/zh-Hans-CN/index/harness-engineering/
12. New tools for building agents (Responses API + Agents SDK) — OpenAI, 2025-03-11. https://openai.com/blog/new-tools-for-building-agents
13. Agent Development Kit: Making it easy to build multi-agent applications — Google, 2025-04-09. https://googledevelopers.blogspot.com/en/agent-development-kit-easy-to-build-multi-agent-applications/
14. A year of open collaboration: Celebrating the anniversary of A2A — Google Open Source Blog, 2026-04-16. https://opensource.googleblog.com/
15. Agent Development Kit — AI Wiki, 2026. https://aiwiki.ai/wiki/google_adk
16. Model Context Protocol official site and specification — MCP / AAIF, 2024—2026. https://modelcontextprotocol.io/; https://modelcontextprotocol.io/specification/2026-07-28/
17. MCP Protocol Versions (version evolution table) — MCP Ruby SDK, 2026. https://ruby.sdk.modelcontextprotocol.io/protocol-versions/
18. MCP Rust-layer protocol version enumeration — mcpkit (docs.rs). https://docs.rs/mcpkit/latest/enum.ProtocolVersion.html
19. Model Context Protocol entry (including specification evolution) — Klu. http://klu.ai/glossary/model-context-protocol
20. Linux Foundation Announces the Formation of the AAIF — Linux Foundation / AAIF, 2025-12-09. https://aaif.io/
21. Harness engineering for coding agent users — Birgitta Böckeler, martinfowler.com, 2026. https://martinfowler.com/articles/harness-engineering.html
22. SWE-bench: Can Language Models Resolve Real-World GitHub Issues? — Jimenez, Yang et al. (Princeton), 2023-10 (ICLR 2024 Oral). https://www.swebench.com/
23. Terminal-Bench — Stanford / Laude Institute, 2025. https://www.tbench.ai/
24. Context engineering entry (naming chain and four pillars) — AI Wiki, 2025—2026. https://aiwiki.ai/wiki/context_engineering
25. OpenAI Codex entry (sandbox primitives, approval modes, Rust rewrite) — AI Wiki, 2026. https://aiwiki.ai/wiki/codex
26. Agent Harness: the core paradigm of AI engineering in 2026 — 腾讯云开发者社区, 2026. https://developer.cloud.tencent.com/article/2698416
27. Terminal-Bench: The CLI Autonomy Standard — AgentMarketCap, 2026-04-09. https://agentmarketcap.ai/blog/2026/04/09/terminal-bench-cli-autonomy-standard-coding-agents
28. The evolution of Anthropic's Harness engineering architecture (Chinese overview) — 阿里云开发者社区, 2026. https://developer.aliyun.com/article/1724413
29. How the agent loop works — Anthropic, 2026. https://docs.anthropic.com/en/docs/agent-sdk/agent-loop
30. Building agents with the Claude Agent SDK — Anthropic, 2025. https://claude.com/blog/building-agents-with-the-claude-agent-sdk
31. Loop engineering: Getting started with loops — Claude Code team, Anthropic, 2026-06-30. https://claude.com/blog/getting-started-with-loops
32. A harness for every task: dynamic workflows in Claude Code — Anthropic, 2026. https://claude.com/blog/a-harness-for-every-task-dynamic-workflows-in-claude-code
33. How we built our multi-agent research system — Anthropic, 2025. https://www.anthropic.com/engineering/multi-agent-research-system
34. Unrolling the Codex agent loop — OpenAI, 2025—2026 (publication date unverified, see section 13). https://openai.com/index/unrolling-the-codex-agent-loop/
35. Codex as a platform: build on the open agent harness — OpenAI Developers, 2026. https://developers.openai.com/blog/codex-as-a-platform
36. Running agents — OpenAI Agents SDK official documentation, 2026. https://openai.github.io/openai-agents-python/running_agents/
37. Running Codex safely at OpenAI — OpenAI, 2026. https://openai.com/index/running-codex-safely/
38. Agent approvals & security — Codex official documentation, 2026. https://developers.openai.com/codex/sandbox
39. gemini-cli (open-source repository and ReAct loop documentation) — Google, 2025—2026. https://github.com/google-gemini/gemini-cli
40. What does recursionLimit actually count in createAgent? — LangChain official forum, 2025—2026. https://forum.langchain.com/t/what-does-recursionlimit-actually-count-in-createagent-langchain-js/3460
41. Dify node system documentation (Iteration / Loop nodes) — LangGenius, 2026 (via DeepWiki structured index). https://deepwiki.com/langgenius/dify-docs/1.3-node-system-overview
42. Iteration Node — Agent Patterns Catalog, 2026. https://www.agentpatternscatalog.org/patterns/iteration-node
43. Runaway Tool Loops — PolicyLayer, 2026 (case occurred in 2025-11, verified: partial). https://policylayer.com/attacks/runaway-tool-loops