File Editing and Shell Execution: Exact-Match Replacement, Conflict Detection, and a Timeout-Killable Subprocess

Three editing approaches: where the model crashes in each

There are only three industry approaches to letting a model change a file.

Whole-file rewrite is the easiest to implement and the one you should least use. It has a subtle harm: while re-emitting the lines it was not supposed to touch, the model quietly changes a few it dislikes — a variable name, formatting, a comment. Mixed into one big diff, a human cannot review that. And rewriting long files is slow, expensive and may be truncated into half a file by the output limit.

Patches cost the fewest tokens and most resemble how a human engineer works, but they are unfriendly to models: line numbers and context lines must line up exactly, and one wrong line voids the hunk. Worse, failure offers no actionable hint — "patch failed: context mismatch at line 42" leaves the model to retry the same miscalculated reasoning.

Exact replacement is the best trade-off: the model outputs only the snippet to change and its replacement. Failure reasons are specific enough to translate into its next action: "that content cannot be found" means "you misremembered, read it again"; "that content appears 3 times" means "write more context." That is the real reason for choosing it — not that it costs fewer tokens, but that it fails more teachably.

Conflict detection: is the content it read still there?

Now the implementation. Its core is one sentence: count the occurrences before deciding whether to write.

const before = await fs.readFile(target, 'utf8')
 
// Count occurrences instead of replacing directly: both 0 and many must fail,
// each with an actionable reason
const occurrences = before.split(oldString).length - 1
if (occurrences === 0) {
  return {
    ok: false,
    content:
      `that old_string cannot be found in ${relative}; nothing was changed. ` +
      'Commonly the indentation or newlines differ, or the file already changed - read_file first and retry.',
  }
}
if (occurrences > 1) {
  return {
    ok: false,
    content:
      `that old_string appears ${occurrences} times in ${relative}, so the target is ambiguous; nothing was changed. ` +
      'Write more context so it becomes unique in the file.',
  }
}
 
const after = before.replace(oldString, newString)
await fs.writeFile(target, after, 'utf8')

before = target.read_text(encoding="utf-8")
 
# Count occurrences instead of replacing directly: both 0 and many must fail,
# each with an actionable reason
occurrences = before.count(old_string)
if occurrences == 0:
    return ToolResult(
        ok=False,
        content=(
            f"that old_string cannot be found in {relative}; nothing was changed. "
            "Commonly the indentation or newlines differ, or the file already changed - "
            "read_file first and retry."
        ),
    )
if occurrences > 1:
    return ToolResult(
        ok=False,
        content=(
            f"that old_string appears {occurrences} times in {relative}, so the target is "
            "ambiguous; nothing was changed. Write more context so it becomes unique."
        ),
    )
 
target.write_text(before.replace(old_string, new_string, 1), encoding="utf-8")

The most important part of that code is what it does not do: no fuzzy matching, no whitespace-insensitive comparison, no guessing which occurrence was meant.

The reason is that this rule doubles as conflict detection. Consider where the model's old_string came from: a read_file several turns ago. In between, the file may have been edited by you in your editor, changed by the previous replacement, or swapped by a git branch switch. "The original cannot be found" is then not the model's mistake but a genuine conflict signal — the world it read is no longer the world that exists. The only correct action is to abandon the write and say why. Any fuzzy matching is a gamble whose losing outcome is a silent overwrite.

That is why the starter's "just replace the first occurrence" implementation is the day's most dangerous bug: it is perfectly correct when the original is unique, silently changes the wrong place when it is not, and reports "changed" to the model. The tests may even stay green, because the place it changed happened not to matter.

An aside on the other approach to conflict detection: record the file's modification time or a content hash at read, and compare before writing. It is stricter (it even catches "changed and changed back") but unfriendly to models — the failure reason is "the file was modified externally," which the model can do nothing about except re-read. Content matching's advantage is that its failure reason is inherently actionable, so this course uses it. In real engineering the two can be stacked: content matching for the model, hash comparison for the human.

Creation and deletion are two special cases

With exact replacement in place, it is tempting to fold in creation and deletion: creation is an empty old_string, deletion an empty new_string. Do not.

Creation's problem is that it has no original to match — the protection disappears entirely. And this tool's whole safety rests on "the original must match," so allowing an empty original lets one slip overwrite an existing file with new content, and the diff will not show what was destroyed. So creation is its own tool, and must fail when the target already exists: to change an existing file, use the editing tool, where original matching protects you.

Deletion is more extreme: it is irreversible with no partial-success middle state. This course gives it no dedicated tool and routes it through the command tool, so day five's approval gate can stop it and a human can look before deciding. Passing an empty new_string to delete a snippet is fine — it still has original matching as protection, and it removes a piece of a file rather than the whole file.

A takeaway criterion: whatever premise a tool's safety rests on, do not let it accept input where that premise fails.

The shell tool's four gates

The command tool is the riskiest of the course: it can run anything, including things you did not think of. Four gates, none skippable.

One: a timeout. Thirty seconds by default, relaxable by parameter but with a ceiling. Without one, the command tool hangs the whole Agent on an interactive program waiting for input, and the user cannot see what it is waiting for. A small trick alongside: set the child's standard input to "ignore," and interactive commands hit end-of-file and exit on their own instead of waiting out the timeout.

Two: an output cap. Count standard output and standard error separately, four thousand characters each. Separation matters: one flood of warnings would otherwise squeeze out the real error. And cap while receiving, not after collecting — collecting first still holds those hundreds of thousands of characters in memory. In this lab, a command printing twenty thousand lines produces 208890 characters of standard output uncapped, and only 4000 with the cap, for a total fed-back result of 4085 characters.

const MAX_STREAM_CHARS = 4000
 
const capture = (which: 'out' | 'err') => (chunk: Buffer) => {
  const text = chunk.toString('utf8')
  // Cap while receiving: collecting first still holds those hundreds of thousands of chars
  if (which === 'out') {
    if (stdout.length < MAX_STREAM_CHARS) stdout += text.slice(0, MAX_STREAM_CHARS - stdout.length)
  } else if (stderr.length < MAX_STREAM_CHARS) {
    stderr += text.slice(0, MAX_STREAM_CHARS - stderr.length)
  }
}
child.stdout?.on('data', capture('out'))
child.stderr?.on('data', capture('err'))

MAX_STREAM_CHARS = 4000
 
 
async def capture(stream: asyncio.StreamReader, sink: list[str]) -> None:
    """Cap while receiving: each stream has its own cap so warnings cannot bury the error"""
    kept = 0
    while chunk := await stream.read(4096):
        if kept >= MAX_STREAM_CHARS:
            continue  # keep reading anyway, or a full pipe blocks the child on write
        text = chunk.decode("utf-8", "replace")[: MAX_STREAM_CHARS - kept]
        kept += len(text)
        sink.append(text)

That Python comment deserves a pause: keep reading even past the cap. Pipes have buffers, and if you stop reading, the child blocks once its buffer fills — the symptom is "the command inexplicably hangs," and only when output is large.

Three: the working directory. Pinned inside the sandbox repository. The command tool needs this more than file tools do, because escaping the boundary from a shell is far too easy.

Four: refuse obviously dangerous commands. Recursive deletion, shutdown, writing to a block device, downloading a script and executing it, pushing code to a remote — none of these can be rolled back once run. But be clear about this gate's nature: it prevents slips, not attacks. There are a hundred ways around a regex blacklist, and real isolation needs a sandbox (a container, a temporary directory, no network). Tomorrow's three preconditions for automatic mode return here.

The child process that will not die: process groups, signals and orphans

Implementing the timeout is harder than it looks. Write setTimeout and then call kill, and you find some commands are killed and do not stop.

The reason is the process tree. You start a shell, the shell starts the program that does the work, and that program may start more children. Killing only the shell leaves its grandchildren orphaned and running; worse, they still hold the output pipes, so the "child closed" event never arrives and this tool call's promise never resolves — the whole Agent hangs there.

The correct approach has two parts: make the child its own process group at spawn, and kill the whole group.

// detached: true makes the child its own process group - the key to actually killing it
const child = spawn(command, {
  cwd: ctx.cwd,
  shell: true,
  detached: true,
  stdio: ['ignore', 'pipe', 'pipe'], // stdin ignored: interactive commands hit EOF instead of hanging
})
 
const killTree = (): void => {
  if (child.pid === undefined) return
  try {
    process.kill(-child.pid, 'SIGTERM') // the minus sign kills the whole process group
  } catch {
    /* already gone */
  }
  // Grace period before force: SIGTERM lets it clean up temp files, SIGKILL does not
  setTimeout(() => {
    try {
      if (child.pid !== undefined) process.kill(-child.pid, 'SIGKILL')
    } catch {
      /* already gone */
    }
  }, 2000).unref()
}

# start_new_session=True is setsid: the child becomes its own process group,
# which is the key to actually killing it
proc = await asyncio.create_subprocess_shell(
    command,
    cwd=cwd,
    stdin=asyncio.subprocess.DEVNULL,  # interactive commands hit EOF instead of hanging
    stdout=asyncio.subprocess.PIPE,
    stderr=asyncio.subprocess.PIPE,
    start_new_session=True,
)
 
 
def kill_tree() -> None:
    try:
        os.killpg(proc.pid, signal.SIGTERM)  # killpg kills the whole process group
    except ProcessLookupError:
        return
    # Grace period before force: SIGTERM lets it clean up temp files, SIGKILL does not
    loop = asyncio.get_running_loop()
    loop.call_later(2.0, lambda: _force_kill(proc.pid))

The lab makes this certain with INJECT=timeout: the injected command never exits, and the shell is deliberately kept as its parent (the command ends with & wait), so "kill only the shell" and "kill the process group" differ visibly. The solution kills it within two seconds and moves on; the starter's shell-only kill hangs forever, and the seventh self-test item stalls to timeout — that is what "killed but not stopped" actually feels like.

As for the user's cancel key, today wires only one link: a cancellation signal also triggers the process-group kill. The full chain — key, signal, request, child process, where one broken link means nothing dies — is day six's subject.

The first closed loop: one sentence, from red to green

Attach today's two tools to yesterday's three read-only ones and the Agent completes a real coding task for the first time. The sandbox repository's divide lacks a divide-by-zero guard, and one test case is red. You say only "please fix the failing test":

Let me run the tests first and see which case is red.
> run_command({"command":"node --test"})
x run_command fed back 1373 chars - exit code 1 (68ms): node --test
The divide-by-zero case failed. Let me read divide's implementation.
> read_file({"path":"src/calc.js"})
v read_file fed back 248 chars - src/calc.js (lines 1-13 of 13)
divide returns a over b directly, so a zero divisor silently returns Infinity. I will add a guard.
> edit_file({"path":"src/calc.js","old_string":"export function divide(a, b) {\n  return a /...)
v edit_file fed back 36 chars - changed src/calc.js: 1 replacement from line 10, line delta +1
Done; let me run the tests again to confirm.
> run_command({"command":"node --test"})
v run_command fed back 520 chars - exit code 0 (89ms): node --test
All four cases are green.

Three details in that output are worth noting.

One: not a line of the loop layer changed. Yesterday's tool protocol assumed nothing about being read-only, so adding two mutating tools today only registers two more entries. That is the dividend of day three's boundary — adding a tool should touch no other layer.

Two: the model decided on its own to re-run the tests. We wrote no "verify after editing" logic; it inferred that from the tool descriptions and the failure messages. Which explains why failure messages must state the next step: they are the model's behavioural specification.

Three: four tool calls, two of them the same command. One proves red, one proves green. That "run before and after" pattern is the course's baseline task: day six demonstrates self-correction with it, day seven session recovery, day fourteen rollback, and day twenty makes it the benchmark set's first item.

Source Reading

Hands-On Lab

Today is the first time the course really edits files and really spawns child processes. The starter leaves four exercises, two of which (occurrence checking, killing the process group) correspond to this chapter's two most dangerous traps. Unmodified it passes three of seven.

1. Implement exact replacement: count occurrences first, fail on both 0 and many with an actionable reason, and confirm not one byte of the file changed on failure.
2. Implement the command tool's four gates: timeout, separate capped streams captured while receiving, a fixed working directory, and outright refusal of dangerous commands.
3. Hang a command with INJECT=timeout and confirm it is killed within two seconds and the loop continues instead of hanging.
4. Walk the offline script through run tests, read code, edit code, run tests again, and confirm the second exit code is 0.
5. Run the self-test: MOCK=1 SELFTEST=1 pnpm start should print 7/7 passed, with the tool call order and fed-back character counts both reproducible.

Acceptance is five ticks: the self-test prints 7/7 passed; one sentence produces four tool cards in order with a second test exit code of 0; both a non-matching and a non-unique original are refused with the file untouched; a command printing twenty thousand lines leaves only 4000 characters of standard output; and INJECT=timeout kills the command with the process really gone.

Interview Questions

Today's three questions are all answerable only by someone who has written write tools:

1. To let a model change files, do you choose whole-file rewrite, exact replacement or patches? Why?
2. How does an editing tool do conflict detection? What should it tell the model when detection fails?
3. What constraints would you place on running arbitrary shell commands inside an Agent? After a timeout, how do you actually kill it?

Full bilingual prompts, analyses and key points are in this course's day-four question bank. The second half of question three exposes people most — most can say "add a timeout" and cannot say why it was killed and did not stop.

Checklist and Tomorrow

• I can name the failure modes of the three editing approaches and the real reason for choosing exact replacement
• I know why "unique and exactly matching original" doubles as conflict detection
• I can explain why creation needs its own tool and why it must fail when the target exists
• I can name the command tool's four gates and know the fourth prevents slips, not attacks
• I can explain where an unkillable child process comes from, and what the process group and grace period each solve
• The self-test prints 7/7 passed, and I watched the tests go from red to green

Tomorrow is D5, "Permissions and Approval: Three-State Rules, Matching by Tool and Path, and the Boundary of Automatic Mode." Today gave it write access, but that dangerous-command blacklist only prevents slips; the real question is which operations it may perform alone and which need asking first. Tomorrow turns that judgment into a set of allow, ask and deny rules matched by tool name and path pattern, and makes approval a pause inside the loop rather than an exception — which is where day three's readOnly field finally earns its keep. The order is deliberate: an approval gate is empty talk until tools can cause real loss.