From Reactive Loops to Long-Horizon Agents

A reactive agent can be surprisingly capable:

Observe the current state.
Ask the model what to do next.
Execute a tool.
Feed the result back to the model.
Repeat until the model says it is done.

For a small task such as “find the version in package.json and report it,” this is enough. The agent reads one file, extracts one value and stops. Adding a planning system would only create more latency, cost and failure modes.

Now change the task:

Fix issue #417, update the implementation and tests, run the relevant checks, and produce a reviewable diff.

The same loop can still make progress, but progress is not the same as reliable completion. The agent must discover the repository, understand the issue, coordinate dependent changes, preserve partial work, diagnose failures and prove that the result satisfies the issue. The loop has memory of recent conversation, but it has no explicit representation of the work.

Long-horizon execution begins when success depends not only on choosing the next action, but also on maintaining control across many actions.

1. Reactive agents and task complexity

Imagine that issue #417 says:

The CLI accepts an invalid timeout. Reject zero and negative values, update the documentation and add regression tests.

A reactive agent might:

Search for timeout.
Edit the first validation function it finds.
run all tests;
see an unrelated integration failure;
modify more code in response;
forget the documentation;
stop after a passing unit test.

Every local action can look reasonable while the overall task remains incomplete.

The real source of difficulty

Task difficulty is not simply the number of steps. A ten-file rename may be easy if every edit is mechanical. A three-step migration may be hard if the second step changes what the third step should be.

Long-horizon difficulty grows with:

Breadth: how many files, tools and subsystems are involved?
Dependency depth: how many steps require earlier results?
Uncertainty: how much must be discovered while working?
Delayed feedback: how long before an incorrect decision becomes visible?
Failure probability: how many operations can fail or produce ambiguous results?
Irreversibility: how costly is a mistaken action?
Interruption risk: must execution survive process or human pauses?

A useful rule is:

Use explicit planning when later actions depend on facts, artifacts or guarantees produced by earlier actions.

The missing capability is not “more reasoning.” It is an external control structure that records what must happen, what has happened and what evidence supports completion.

2. Goal decomposition, structured plans and plan-and-execute

Failure: the goal is too large to execute directly

“Fix issue #417” describes an outcome, not an immediately executable action. If the agent treats it as a single task, it must repeatedly reconstruct the implicit subtasks from conversation history. This reconstruction is probabilistic: tests or documentation can disappear from attention as the context grows.

Mechanism: goal decomposition

Decompose the goal into independently understandable units:

Understand the issue and define acceptance criteria.
Locate timeout parsing and validation.
Identify existing tests and documentation.
Implement validation.
Add regression tests.
Update documentation.
Run targeted verification.
Review the final diff.

Decomposition is useful only when each task has a clear boundary. “Work on validation” is weak because neither completion nor failure can be observed. “Reject timeout values <= 0 in the CLI parser” is executable and verifiable.

Failure: a prose checklist is ambiguous

A model may produce a beautiful numbered list, but the runtime cannot reliably answer:

Which task is ready?
Which task is blocked?
What evidence completed it?
Which tasks became invalid after a discovery?
Can two tasks run independently?

Mechanism: a structured plan

Represent the plan as data:

{
  "goal": "Resolve issue #417",
  "acceptance_criteria": [
    "CLI rejects zero and negative timeout values",
    "positive timeout values still work",
    "regression tests pass",
    "user documentation states the constraint",
    "final diff contains no unrelated changes"
  ],
  "tasks": [
    {
      "id": "T1",
      "description": "Locate timeout parsing, tests and docs",
      "depends_on": [],
      "status": "ready",
      "verification": "Relevant files and current behavior are recorded"
    },
    {
      "id": "T2",
      "description": "Implement timeout validation",
      "depends_on": ["T1"],
      "status": "blocked",
      "verification": "Targeted invalid-input tests pass"
    },
    {
      "id": "T3",
      "description": "Add regression tests",
      "depends_on": ["T1"],
      "status": "blocked",
      "verification": "Tests fail before the fix and pass after it"
    },
    {
      "id": "T4",
      "description": "Update timeout documentation",
      "depends_on": ["T1"],
      "status": "blocked",
      "verification": "Documented rule matches implementation"
    },
    {
      "id": "T5",
      "description": "Run verification and review diff",
      "depends_on": ["T2", "T3", "T4"],
      "status": "blocked",
      "verification": "All acceptance criteria have recorded evidence"
    }
  ]
}

This is more than a model response. It is an interface between the planner and the execution runtime.

Separate planning from execution

The planner answers:

What outcome is required?
What facts are unknown?
What tasks produce those facts or artifacts?
What depends on what?
How will each result be verified?

The executor answers:

Which task is ready now?
Which allowed tool action advances it?
What actually happened?
What artifact or evidence was produced?

The planner should not pretend it knows repository details that have not been explored. Its first plan is a hypothesis. The executor turns unknowns into observations, and the planner revises the hypothesis when necessary.

3. Task dependencies, progress ledgers, todos and status models

Failure: list order is not dependency order

Suppose exploration reveals two CLI implementations: a legacy command and a new command. The agent cannot safely edit tests or documentation until it knows which path issue #417 concerns.

A numbered list suggests order but does not explain causality. If task 2 fails, the runtime does not know which later tasks are affected.

Mechanism: a dependency graph

Tasks become runnable only when their dependencies have satisfied outcomes:

Explore repository
├── Identify active CLI path
├── Identify regression-test location
└── Identify documentation location

Implementation + tests + docs
└── Final verification

Do not confuse “dependency completed” with “dependency attempted.” If exploration did not identify the active path, downstream implementation remains blocked.

When a dependency changes, invalidate only affected descendants. If the documentation location changes, the implementation does not need to be repeated. This is one reason explicit dependency edges are better than restarting the entire task.

Failure: the agent cannot distinguish pending, failed and finished work

Conversation text such as “I handled the tests earlier” is not a durable state transition. It may refer to tests being written, tests being run or tests passing.

Mechanism: a progress ledger

Use a small, enforced status model:

pending -> ready -> in_progress -> completed
                         |            |
                         v            v
                       failed     invalidated
                         |
                         v
                       ready

Useful terminal and non-terminal states include:

pending: known task whose dependencies are unresolved;
ready: eligible to execute;
in_progress: currently owned by an executor;
completed: verification succeeded;
failed: the latest attempt failed and evidence is recorded;
blocked: progress requires an unavailable fact, permission or human decision;
skipped: deliberately unnecessary, with a reason;
invalidated: previously completed work must be reconsidered after a changed assumption;
cancelled: execution was intentionally stopped.

Every transition should record:

{
  "task_id": "T3",
  "from": "in_progress",
  "to": "failed",
  "timestamp": "2026-07-28T12:10:00+05:30",
  "attempt": 1,
  "reason": "Test imports helper from a different package",
  "evidence_refs": ["artifacts/test-run-T3-a1.txt"]
}

The ledger answers what changed. It should be append-only or versioned so that a false completion cannot silently erase the history that produced it.

Todo list versus progress ledger

A todo list is a view of current intent. A progress ledger is a record of state transitions and evidence.

The agent may show:

Locate timeout code
Implement validation
Add tests

But the runtime should retain the structured task records, attempts, dependencies and evidence beneath that view.

4. Artifact-based state outside the conversation

Failure: context is being used as a database

After dozens of tool results, the conversation may contain old file contents, obsolete plans and repeated test output. Even if the entire history fits in the context window, the model must infer which statements are current.

Context length solves storage capacity, not state consistency.

Mechanism: separate authoritative state from working context

A long-horizon agent needs at least four kinds of state:

{
  "run": {
    "run_id": "run-417-01",
    "goal": "Resolve issue #417",
    "status": "running",
    "plan_version": 3,
    "started_at": "...",
    "budget": {
      "model_calls_remaining": 35,
      "tool_calls_remaining": 80,
      "wall_time_seconds_remaining": 2400
    }
  },
  "plan": {
    "acceptance_criteria": [],
    "tasks": []
  },
  "workspace": {
    "repository_revision": "abc123",
    "changed_files": [],
    "sandbox_id": "sandbox-9"
  },
  "artifacts": {
    "issue": "artifacts/issue-417.md",
    "exploration": "artifacts/repository-map.json",
    "test_runs": [],
    "diff": null
  }
}

The conversation becomes a temporary working set. The state store is authoritative.

Artifact-based state

Do not paste every large result into plan fields. Store durable artifacts and reference them:

normalized issue and acceptance criteria;
repository map;
relevant source excerpts;
patches;
test logs;
lint and type-check output;
final diff;
verification report;
human approval decisions.

Artifacts make the run inspectable and resumable. They also prevent repeated exploration: the agent can load the repository map rather than search the whole codebase after every interruption.

Artifacts require freshness metadata. A test result should identify the repository revision and diff it tested. “Tests passed” is unsafe if the code changed afterward.

{
  "artifact_id": "test-22",
  "kind": "test_result",
  "command": "pytest tests/cli/test_timeout.py",
  "exit_code": 0,
  "repository_revision": "abc123",
  "workspace_hash": "sha256:...",
  "created_at": "..."
}

5. Verification turns activity into completion

Failure: the model declares success after making a plausible edit

Editing the likely function is not proof that the issue is resolved. A syntactically valid change may affect the wrong CLI path. A passing test may never exercise zero. Documentation may contradict the code.

Mechanism: define verification before execution

Each task needs an observable completion condition. The overall goal needs acceptance criteria that can be traced to evidence.

For issue #417:

Criterion	Verification
Zero is rejected	Execute CLI with `--timeout 0`; assert non-zero exit and expected error
Negative values are rejected	Execute CLI with a negative timeout; assert rejection
Positive values still work	Run an existing valid-input test
Regression is covered	Demonstrate the new test fails against the old behavior and passes with the patch
Documentation is correct	Compare documented boundary with validation rule
Diff is reviewable	Inspect changed files and reject unrelated modifications

Verification should be independent of the action when possible. If the same model writes both the patch and a vague self-assessment, correlated mistakes can pass unnoticed. Executable assertions, type checkers, linters and tests provide stronger evidence.

The completion rule

The executor cannot mark a task completed merely because its action succeeded. Completion requires its verification predicate to succeed.

result = execute(task.action)

if not result.succeeded:
    mark_failed(task, result)
else:
    evidence = verify(task.verification)
    if evidence.passed:
        mark_completed(task, evidence)
    else:
        mark_failed(task, evidence)

The run stops successfully only when:

every required acceptance criterion has fresh evidence;
every required task is completed or explicitly skipped for a valid reason;
no task remains in_progress, failed or unexpectedly blocked;
the final diff passes scope and safety review;
the budget has not been exceeded;
no cancellation request is active.

Stopping is a runtime decision based on state, not merely a model-generated phrase such as “Done.”

6. Replanning, partial completion and failure recovery

Failure: the original plan becomes wrong

During implementation, the agent discovers that timeout validation lives in a shared configuration package used by both the CLI and API. Changing it globally would break API behavior.

Continuing with the original plan is unsafe. Restarting the entire run wastes valid exploration. The agent needs controlled revision.

Mechanism: replan from a recorded discrepancy

Replanning should be triggered by evidence, not by boredom:

an assumption is disproved;
a task fails repeatedly;
a dependency produces an unexpected result;
the repository changes;
verification fails;
a required permission is denied;
the remaining budget makes the plan infeasible;
a human changes the goal or constraints.

A replan operation should:

record the observation;
identify the invalid assumption;
determine which tasks and evidence are affected;
preserve unaffected completed work;
add, remove or rewrite tasks;
update dependencies and verification;
increment the plan version;
explain why the new plan is more likely to satisfy the same goal.

Example:

{
  "plan_version": 4,
  "trigger": {
    "task_id": "T2",
    "observation": "Shared validator also controls API timeouts"
  },
  "changes": [
    {
      "operation": "replace_task",
      "task_id": "T2",
      "new_description": "Add CLI-specific positive timeout validation"
    },
    {
      "operation": "add_task",
      "task_id": "T2b",
      "description": "Verify API timeout behavior is unchanged",
      "depends_on": ["T2"]
    }
  ],
  "invalidated": ["T5"],
  "preserved": ["T1", "T3", "T4"]
}

Partial completion

A failed task may still produce useful work. An integration test could fail after the unit tests pass. Record these as separate outcomes rather than collapsing the entire run into failed.

{
  "task_id": "T5",
  "status": "failed",
  "outcomes": [
    {"check": "unit_tests", "status": "passed"},
    {"check": "type_check", "status": "passed"},
    {"check": "integration_tests", "status": "failed"}
  ]
}

The next plan can preserve passing evidence if it is still fresh and unaffected.

Recovery after failure

Classify failures before retrying:

Transient: timeout, temporary service error or resource contention. Retry with bounded backoff.
Action error: malformed command or wrong path. Correct the action, then retry.
Plan error: missing task or false dependency assumption. Replan.
Environment error: missing tool, broken baseline or unavailable service. Block or escalate.
Permission error: action requires approval. Pause; never route around the boundary.
Goal ambiguity: acceptance criteria are unclear. Request human input.

Blind retries repeat mistakes and spend the budget. A safe retry requires:

a recorded failure;
a diagnosis;
a changed condition or action;
an attempt limit;
idempotent or reversible execution.

7. Checkpoints, budget-aware planning and human control

Failure: an interruption destroys the run

A repository task may outlive a model session or worker process. If state exists only in memory, resumption means repeating exploration and guessing which edits were already applied.

Mechanism: long-running checkpoints

Create a checkpoint:

after plan creation;
after every verified task;
before and after a risky action;
after replanning;
before human approval;
when the remaining budget is low;
on cancellation or graceful shutdown.

A checkpoint should atomically associate:

run status and plan version;
task statuses and ledger position;
repository revision and workspace identity;
artifact references and hashes;
consumed and remaining budget;
pending approvals;
the next eligible tasks.

On resume:

load the latest complete checkpoint;
verify that the sandbox and repository revision still match;
detect external workspace changes;
invalidate stale evidence;
convert abandoned in_progress work to ready or needs_review;
continue from the dependency graph.

Do not assume that an interrupted tool call failed. Inspect its effects first. Retrying a partly completed write can duplicate or corrupt work.

Failure: planning consumes more resources than execution

An agent can repeatedly refine the plan, explore every hypothetical branch and run broad test suites after each small edit. Reliability rises only if the extra control produces enough avoided failures.

Mechanism: budget-aware planning

Track multiple budgets:

model calls or tokens;
tool calls;
wall-clock time;
test runtime;
monetary cost;
retry count;
human attention.

Each task can have an expected value:

priority ≈ probability task is necessary
           × cost of missing it
           ÷ estimated execution cost

This is not required to be mathematically exact. Its purpose is to force trade-offs. Under a tight budget, run targeted tests before the full suite. Explore likely files before indexing the entire repository. Escalate rather than spending the final ten calls on uncertain retries.

Planning itself needs a limit:

maximum initial planning calls;
maximum plan revisions;
minimum evidence required to trigger replanning;
no replanning while the current plan remains valid and executable.

Cancellation

Cancellation is a state transition, not a process kill.

A cooperative cancellation flow:

stop scheduling new tasks;
allow safe, short operations to finish;
interrupt long operations when supported;
inspect partially applied effects;
checkpoint the workspace and ledger;
mark the run cancelled or paused;
report what completed, what remains and whether any cleanup is required.

Human intervention and destructive operations

The model may propose actions, but code must enforce capability boundaries.

For the repository agent:

read and search only inside the sandbox;
write only to the working tree;
prefer reversible patches;
never expose secrets;
require explicit approval before destructive operations such as deleting files, rewriting history, removing large dependency sets or discarding user changes;
pause when the correct target or desired behavior is ambiguous;
record the approval scope and result in the ledger.

A vague approval such as “go ahead” should authorize only the previewed operation, not future destructive actions.

8. Reflection and external evaluation

Failure: passing local checks hides a poor strategy

The patch can pass tests while the run is still inefficient or fragile. The agent may have edited unrelated files, used fifteen calls to discover an obvious path or passed because the new test asserted the implementation rather than the requirement.

Mechanism: reflection grounded in evidence

Reflection is a bounded review of the run:

Which assumption was wrong?
Which evidence changed the plan?
Were retries justified by changed conditions?
Did any completed task lack independent verification?
Did the final diff satisfy the original issue rather than merely the tests?
What should a future plan do differently?

Reflection should produce proposed improvements, not directly rewrite history or declare success.

External evaluation

Evaluation outside the executing agent reduces self-confirming errors. Possible evaluators include:

deterministic acceptance tests;
a separate diff-review model with a focused rubric;
static analysis and security scanning;
mutation testing to check whether regression tests detect the old bug;
a human reviewer for ambiguous product behavior;
replay against a benchmark of repository issues.

Evaluating plan quality

Plan quality cannot be measured only by whether the final task succeeded. A good executor may rescue a poor plan, and an environment failure may defeat a good one.

Measure:

Dimension	Example metric
Coverage	Percentage of acceptance criteria linked to tasks and verification
Validity	Percentage of planned tasks that were actually necessary
Dependency correctness	Incorrect or missing dependency edges
Executability	Tasks that required clarification before action
Adaptability	Time and cost to recover after a disproved assumption
Stability	Unnecessary replans per run
Efficiency	Planning cost as a share of total cost
Completion	Criteria satisfied with fresh evidence
Safety	Permission violations or destructive actions without approval
Resumability	Successful continuation from a checkpoint without repeated work

To decide whether planning is worth its cost, compare against a reactive baseline on the same task set:

task success rate;
verified completion rate;
cost and latency;
unnecessary file changes;
recovery rate after injected failures;
work repeated after interruption;
human interventions;
safety violations.

Planning is justified when the reliability, recovery or safety gain matters more than its additional cost.

9. Preventing planning overhead and knowing when not to plan

Planning is not automatically better.

Use the smallest control structure that matches the task:

Task shape	Sufficient mechanism
One safe, observable action	Direct tool call
Two or three obvious sequential actions	Reactive loop with a completion check
Fixed repeatable workflow	Deterministic workflow or state machine
Several dependent, uncertain tasks	Structured plan with ledger and verification
Long-running or interruptible work	Plan, artifacts, checkpoints and resumption
High-impact ambiguous work	Plan plus human approval and external evaluation

Do not plan when:

the next action is obvious and cheap;
the operation is easily reversible;
success is immediately observable;
there are no meaningful dependencies;
a deterministic program already describes the workflow;
plan creation would cost more than simply executing and checking;
the environment changes so quickly that a detailed plan becomes stale immediately.

A practical policy is progressive planning:

begin with the goal, acceptance criteria and only the next few tasks;
explore uncertain areas;
expand the plan when new dependencies become real;
avoid inventing distant steps based on facts not yet discovered.

This keeps the plan useful without turning it into speculative bureaucracy.

10. Practical architecture: a repository-maintenance agent

The final system contains a small set of explicit components.

flowchart TD
    A["Issue + constraints"] --> B["Planner"]
    B --> C["Plan and dependency graph"]
    C --> D["Scheduler"]
    D --> E["Sandboxed executor"]
    E --> F["Artifacts and ledger"]
    F --> G["Verifier"]
    G -->|pass| D
    G -->|unexpected result| H["Replanner"]
    H --> C
    F --> I["Checkpoint store"]
    J["Human approval"] <--> D

Component responsibilities

Issue normalizer

reads the issue;
extracts explicit requirements and constraints;
records ambiguities;
proposes measurable acceptance criteria.

Repository explorer

operates only inside the sandbox;
inspects repository instructions, structure, relevant code, tests and history;
produces a repository map artifact;
does not modify files.

Planner

creates typed tasks, dependencies and verification predicates;
marks assumptions and unknowns;
estimates cost and risk;
does not execute tools.

Scheduler

selects ready tasks whose dependencies are satisfied;
enforces budgets, cancellation and concurrency rules;
permits parallel work only when write sets do not conflict;
requests approval for protected actions.

Executor

receives one task and its relevant artifacts;
uses scoped read, edit and command tools;
records commands, results and changed files;
cannot mark its own task complete without verification.

Verifier

checks task predicates and overall acceptance criteria;
binds evidence to the current workspace hash;
detects unrelated diff changes and stale test results.

Replanner

consumes failed verification and changed assumptions;
preserves unaffected work;
updates tasks, dependencies and criteria;
versions every plan change.

Checkpoint store

persists run state, ledger position, plan version, artifact references, workspace identity, budget and approvals;
supports safe resumption after interruption.

Review output

summarizes the issue and implemented behavior;
lists changed files;
presents the reviewable diff;
reports commands and verification results;
discloses unresolved failures, skipped checks and assumptions.

The execution loop

while run.status == "running":
    if cancellation_requested(run):
        cancel_safely_and_checkpoint(run)
        break

    refresh_ready_tasks(run.plan)
    task = scheduler.next_task(run)

    if task is None:
        if completion_criteria_satisfied(run):
            run.status = "completed"
        elif has_blocked_or_failed_work(run):
            decision = diagnose_and_replan_or_escalate(run)
            if decision == "cannot_continue":
                run.status = "blocked"
        else:
            run.status = "failed"  # invalid plan state
        checkpoint(run)
        continue

    if task.requires_approval:
        approval = request_scoped_approval(task.preview)
        record_approval(approval)
        if not approval.granted:
            mark_blocked(task, "Approval denied")
            continue

    mark_in_progress(task)
    result = executor.execute(task)
    evidence = verifier.check(task, result, current_workspace())

    if evidence.passed:
        mark_completed(task, evidence)
    else:
        failure = classify_failure(result, evidence)
        mark_failed(task, failure)

        if failure.retryable and task.attempts < task.max_attempts:
            revise_action_and_mark_ready(task, failure)
        else:
            replan_or_escalate(run, failure)

    checkpoint(run)

The model can help create plans, choose actions, diagnose failures and propose revisions. The runtime owns status transitions, permissions, budgets, checkpoints and the final completion rule.

Safe retry rules

Before retrying a repository operation:

compare the current workspace with the pre-action checkpoint;
determine whether the earlier attempt changed any file;
keep correct partial changes;
revert only known agent-owned changes when rollback is necessary;
request approval before deleting or discarding uncertain user work;
change the command, input or assumption that caused the failure;
record the new attempt separately.

Resume scenario

Suppose the process stops after code and tests are complete but before documentation and final verification.

On resume, the agent:

loads the latest checkpoint;
confirms the repository revision and workspace hash;
sees T2 and T3 completed with fresh evidence;
converts the interrupted task, if any, to needs_review;
leaves T4 ready and T5 blocked on T4;
continues without repeating exploration or implementation;
performs final verification against the resumed workspace.

That behavior is impossible to guarantee if progress exists only in conversation text.

11. The complete mental model

A reactive loop answers:

Given what I see now, what should I do next?

A long-horizon architecture adds:

What outcome are we pursuing? What subgoals produce it? What depends on what? What is the authoritative state? What evidence proves progress? What changed? What should be retried, revised, preserved, paused or escalated? When is the run actually complete?

The architecture can be reconstructed as seven layers:

Goal layer: issue, constraints and measurable acceptance criteria.
Plan layer: tasks, dependencies, assumptions, risks and verification predicates.
Control layer: scheduler, budgets, cancellation, permissions and human gates.
Execution layer: sandboxed, scoped and preferably reversible tool actions.
Evidence layer: artifacts, test results, diffs and an append-only progress ledger.
Adaptation layer: failure classification, bounded retries, replanning and reflection.
Durability layer: checkpoints, workspace identity, resumption and final review output.

Planning is not asking a model to produce a longer chain of thought. It is creating an inspectable control system around uncertain execution.

The correct goal is also not maximum autonomy. It is the minimum autonomy that can complete the task reliably, recoverably and safely.

Mastery check

You understand long-horizon agents when you can answer these without relying on memorized definitions:

Why can every action in a reactive loop appear reasonable while the overall task still fails?
Which properties make a task long-horizon even when it has few steps?
What information belongs in a structured task rather than in prose?
Why is list order an inadequate replacement for dependency edges?
How does a progress ledger differ from a todo list?
Why is a large context window not an authoritative state store?
What makes test evidence stale?
When should verification failure cause a retry, a replan or human escalation?
How do you preserve valid partial work after one branch fails?
What must a checkpoint contain to support safe resumption?
Why must the runtime, rather than the model, enforce completion and approval?
How would you measure whether planning improved results enough to justify its cost?
When is a deterministic workflow better than a planning agent?
Reconstruct the seven-layer architecture from the goal through durable execution.

If any answer feels vague, return to the failure that forced that mechanism to exist. The mechanism is understood only when you can derive it from the failure.