Edit & run tools in detail

Editing & execution introduced the Read → Edit → Run → Observe loop. This page covers how the edit and command tools should behave, and how the agent should read their results.

The tool names, contracts, and limits below are a proposed design for this guide, not a description of a particular product’s internals.

Edit: change the workspace, then confirm the write

Give the agent an edit tool such as apply_patch. A patch describes a small change (“replace these lines with those lines”). The tool applies it and reports the outcome.

Prefer a targeted patch over whole-file replacement. To fix one line, patch one line. With whole-file replacement, the model must reproduce every unrelated line exactly, and one slip breaks working code. New files can use a separate write_file tool or the same patch tool.
Reject stale edits. When the agent reads a file, the harness records its version (for example, a content hash). Before applying a patch, it checks that the file still matches. If the user edited session.ts in the meantime, the patch is stale: it would overwrite their work. The harness rejects it with a recoverable error, and the agent rereads the file and builds a fresh patch.
Report partial application. The result says which files changed and whether the whole patch applied or only some of it. Alternatively, apply each patch atomically: all of it or none. If an edit failed or only partly applied, the agent must not continue as if it succeeded.
Review the diff. The agent inspects the before-and-after diff for unintended changes, and confirms the user’s unrelated edits are still in place.

Run: choose a check that can detect the problem

Use a command tool to execute the project’s actual verification commands. Inspect its scripts or contributor instructions rather than guessing commands from the language alone. Each kind of check proves something different:

Check	What it helps establish	What it does not establish
Focused reproduction or regression test	The particular reported behavior is exercised.	All related behavior still works.
Relevant existing tests	Covered behavior remains consistent with assertions.	Untested cases are correct.
Type check or build	The changed code satisfies the checks performed by that tool.	Runtime behavior meets the user’s requirement.
Lint or formatting	The code follows configured rules.	The bug is fixed.
UI or integration check	The exercised flow works in that environment.	Every environment or interaction is covered.

Start with a check close to the change, then run broader checks required by the repository or justified by the affected area. A documentation edit and a shared authentication change need different verification depth.

The command tool contract

A proposed command interface should accept a working directory and timeout, return bounded stdout and stderr, and distinguish completion from a still-running process. If execution continues asynchronously, return a process handle so the agent can poll or cancel it. Keep larger logs retrievable without inserting all of them into model context.

Observe: turn results into the next decision

The harness returns structured facts; the model interprets them. An illustrative completed result might look like:

{
  "status": "exited",
  "exit_code": 1,
  "stdout": "2 passed, 1 failed",
  "stderr": "Expected session to be expired at the expiry boundary",
  "output_truncated": false
}

A nonzero exit code alone does not identify the cause. Read the failure details and distinguish a wrong implementation from a missing dependency, incorrect command, timeout, or unrelated existing failure. Likewise, exit code zero may mean no tests were discovered; inspect the runner’s summary before calling verification successful.

Observation	Appropriate next step
The patch did not apply	Reread current source and rebuild the patch.
An assertion contradicts the intended behavior	Inspect the implementation and test expectation; revise whichever is unsupported by the requirement.
The command cannot start	Diagnose the command or environment before changing application logic.
Execution is still running	Poll within the time budget; cancel if necessary.
Output is incomplete	Retrieve the relevant missing log segment.
Relevant checks pass	Review the final diff and assess the remaining acceptance conditions.

Design decision: Edits report exactly what applied, commands return bounded and structured results, and the agent chooses its next step from that evidence.

Get started

Tools

Tool design

Context

Cost

Planning

Subagents

Synthesis

Advanced

Reference

Edit & run tools in detail

Edit: change the workspace, then confirm the write

Run: choose a check that can detect the problem

The command tool contract

Observe: turn results into the next decision

Continue learning

Editing & execution

Context rot

​Edit: change the workspace, then confirm the write

​Run: choose a check that can detect the problem

​The command tool contract

​Observe: turn results into the next decision

​Continue learning

Editing & execution

Context rot

Edit: change the workspace, then confirm the write

Run: choose a check that can detect the problem

The command tool contract

Observe: turn results into the next decision

Continue learning