> ## Documentation Index
> Fetch the complete documentation index at: https://agent-harness101.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Edit & run tools in detail

> Contracts for the edit, command, and observation steps of the agent loop.

[Editing & execution](/tools/editing-and-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.

> [!NOTE]
>
> 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:

```json theme={null}
{
  "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. |

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

## Continue learning

> **[Editing & execution](/tools/editing-and-execution)**
>
> Return to the loop and the worked example.

> **[Context rot](/context/context-rot)**
>
> Continue the core walkthrough with topic 3.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.