The Execution Loop

Module 1 · Master Course — Harness Engineering

90 minutes · 4 sub-sections: Loop Architectures · Stop Conditions · Subagent Delegation · Observability

Prerequisite: Module 0 complete

The heartbeat

Module 0.1 defined the loop as one of the harness's three jobs. This module goes inside it.

Five architectures. Five ways out. Four subagent patterns. One per-turn payload. That's the module.

1.1 Loop Architectures

The five shapes

The five architectures

The shape predicts the failure mode: cycles can loop; lines can't recover; graphs can fight the model.

ReAct — the reference pattern

while (true) {
  const r = await model.complete(messages);
  if (r.stopReason === "end_turn") return r.content;
  if (r.toolUse) {
    const out = await executeTool(r.toolUse);
    messages.push({role:"tool",content:out});
  }
  messages.push({role:"assistant",content:r.content});
}

ReAct as an n8n workflow

Per the visual stack: n8n first. One full traversal of this ring = one TURN.

   Trigger → Assemble Context → Loop(maxIter:8)
                                  │
                                  ▼
                              Call Model ◀── back-edge = TURN BOUNDARY
                                  │
                          ┌───────┴───────┐
                        done            tool_use
                          │                │
                          ▼                ▼
                       Output      Route → read/write/bash
                                         │
                                         ▼
                              Append Observation to History ──┐
                                                         (back to Loop) ┘

The model is one node of seven. Thought = model reasoning; Action = tool_use; Observation = appended result.

Plan-then-Execute — the comparison

But: brittle if the early plan is wrong. Every subsequent step inherits the plan's error. No mid-execution recovery.

Neither universally better. Task predictability decides.

The same task, two shapes (n8n)

Context → Loop → Model → Stop?
                        ▲           │
                        │       tool│done→Output
                        │           ▼
                        └── Append Observation

Plan all steps → Step 1 → Step 2 → Step 3 → Output
   (no back-edge)

The structural difference between the two node graphs is the architectural lesson. The cycle can recover; the line is faster.

Graph-based (LangGraph)

graph = StateGraph(State)
graph.add_node("plan", plan_node)
graph.add_node("execute", execute_node)
graph.add_node("verify", verify_node)
graph.add_edge("plan", "execute")
graph.add_conditional_edges("verify",
    lambda s: "execute" if s.needs_work else "done")

Gains: explicit, testable state machine. Native checkpointing (Module 8). interrupt() for HITL (Module 6).

Costs: more code; fights model capability growth. A rigid graph encoding yesterday's best practice becomes tomorrow's constraint.

Right when the process is the product (regulated workflow). Wrong when you want the model to figure out the process.

The Dumb Loop

Gains: co-evolves with model improvements. Thin code surface (Pi: ~1,200 LOC). The Manus finding: refactored 5× in 6 months, each time getting thinner, performance improving each time.

Costs: debugging is harder. Reliability depends heavily on the model.

Conversation-driven (AutoGen)

Multiple agents converse. A manager decides who speaks next. Orchestration emerges from dialogue.

Gains: natural for multi-agent; emergent collaboration.

Costs: non-deterministic; hard to audit; can loop. The "who speaks next" decision is itself a failure mode.

Right for brainstorming/debate. Wrong for execution where determinism matters.

The choice, stated as a decision

A senior engineer can fill all five blanks for each of the five architectures. The rubric (Module 0.3) scores this as the Execution Loop decision.

1.2 Stop Conditions

Safety logic, not an afterthought

The five stop conditions

A production loop has all five. A toy loop has one or two. The difference between "demo" and "production" is largely this list.

The infinite loop problem

Three failure modes produce it:

1. Model hallucinates ongoing work — task is done, model doesn't recognize it. Cured by max-iter + verification (Module 9).
2. Tool keeps failing, model keeps retrying — cured by error threshold + stuck-loop detection (Module 7.2).
3. Context fills with noise, model loses the task — cured by context management (Module 3) + token budget.

The token budget must be cumulative across the session, not a per-call max_tokens. Per-call limits one completion; session limits the whole run.

1.3 Subagent Delegation

Who keeps control?

The four subagent patterns

The key decision: does the parent keep visibility after spawning? Agents-as-tools and worktree keep it; handoffs and fork lose it.

oh-my-opencode's hierarchy — case study

Prometheus (planner)
    │  agents-as-tools (Atlas returns structured summary)
    ▼
Atlas (orchestrator)
    │  worktree (Juniors execute in parallel, merge)
    ▼
Junior × N (workers) → merge → Atlas aggregates → Prometheus

Real systems mix patterns. Prometheus→Atlas is agents-as-tools; Atlas→Junior is worktree.

Which mix you choose is itself a design decision worth auditing. The rubric (Module 10, Subagent Orchestration) scores it.

Anti-pattern: unbounded subagent return

Cure: bound subagent returns to 1–2k tokens (Module 3). Summary-only by default; full output available via JIT retrieval.

This is the same pattern as the orchestrator-context-trap in Fleet Module F02 — orchestrator accumulates context from every worker; at 4+ workers it overflows.

1.4 Loop Observability

Without it, debugging is divination

The per-turn payload

A production loop emits this structured record at every turn. Memorize it.

Hashes, not full content: tool outputs are 67.6% of context (Module 0.3) and may contain secrets. Full content → separate access-controlled store.

Pi vs Claude Code: what gets logged

The observability wrapper

Add observability without modifying the harness core — wrap the model-call and tool-exec functions.

function withObservability(loop: Loop): Loop {
  return {
    ...loop,
    callModel: async (messages) => {
      const start = Date.now();
      const r = await loop.callModel(messages);
      emit({ trace_id, turn_number, latency_ms: Date.now()-start,
              token_delta: r.usage.total_tokens, stop_reason: r.stopReason });
      return r;
    },
    executeTool: async (tc) => {
      const start = Date.now();
      const result = await loop.executeTool(tc);
      emit({ trace_id, turn_number, tool_name: tc.name,
              input_hash: hash(tc.input), output_hash: hash(result),
              latency_ms: Date.now()-start });
      return result;
    }
  };
}

Same pattern you'll use in Module 6 (permission gates) and Module 11 (security checks). The loop's interface is the extension point.

Four anti-patterns

Takeaways

• Five architectures, each a distinct bet. Task predictability decides.
• Five stop conditions — a loop missing any is a production defect.
• Four subagent patterns differ in who keeps control.
• Per-turn observability is the floor, not a feature. 8 fields, every turn.
• The future-proof test: does performance improve when the model upgrades?

Next: Module 2 — Tool Design & the Tool Contract. Where most security vulnerabilities live.