patch as a Mutating Operation: Trust Boundary Moves

+15 Mana ✨
Hermes File Tools Reference(DOCUMENTATION)

Introduction

patch looks innocent. It is a targeted find-and-replace tool with fuzzy matching, designed to make small, surgical edits to a file. But the moment the agent calls it, the trust boundary moves: state on your disk has changed, and that state is now whatever the model decided to write. Treat patch (and write_file) as the second tier of the risk gradient.

Key Concepts

  • Mutating operation: A tool call that changes state. The file is no longer the same after the call as it was before.
  • Trust boundary: After a mutation, the new state is whatever the agent produced. You are trusting the agent's judgment, not just observing it.
  • Reversibility: Some mutations are easily undone (a clean git tree makes patch reversible); some are not (mutating an untracked file is harder to undo).

Real World Context

A common Hermes flow is: read the file, plan a change, patch the file, run the tests. The patch step is the moment risk increases. Until that call, the agent could be completely wrong with no consequences. After it, your code now contains whatever the agent decided was correct. The whole reason git is the agent's best friend is that it makes mutations reversible.

Deep Dive

patch is Hermes's preferred edit tool. It works by:

  1. Taking an old_string (the text to replace) and a new_string (the replacement).
  2. Searching the file using fuzzy matching across multiple strategies, so the call still works if whitespace or surrounding context shifted slightly.
  3. Applying the replacement and writing the file back.

Compared to write_file (which overwrites the entire file) or running sed through terminal, patch is the safest mutating option because:

  • It only touches the matched region. Everything else is preserved.
  • It refuses if old_string is ambiguous (matches in multiple places), preventing accidental over-edits.
  • The diff is visible in the conversation, so you can audit before continuing.

But patch is still mutating. The risk class is write. That means:

  • The new state is whatever the agent produced. If the agent misread the file, the patch could break it.
  • The action is harder to reverse than read_file. You may need git checkout, a backup, or an undo flow.
  • It may interact with approval gates in some configurations (Section 3.5), especially if writing to sensitive paths.

The correct mental model: reads are free, writes cost trust. Use patch deliberately, after the agent has read enough to be confident.

Common Pitfalls

  1. Patching files without reading them first: The agent should always read before patching. If you see a patch without a preceding read_file, the patch is probably wrong.
  2. Treating patch as equivalent to write_file: Both mutate, but write_file replaces everything. patch is surgical and almost always preferable.

Best Practices

  1. Work on a clean git tree: Make mutations reversible by default. git status before, git diff after.
  2. Prefer patch over terminal for edits: Running sed -i through the terminal bypasses the safety properties of patch (ambiguity checks, visible diff).

Summary

  • patch is the standard tool for making targeted file edits in Hermes.
  • It is a mutating operation: state on disk changes after the call.
  • Mutating operations are the second tier of the risk gradient, above reads but below execution.
  • Always read before patching, and keep a clean git tree to make mutations reversible.

Code Examples

yaml
# A surgical patch: rename one identifier in one file
tool_call:
  name: patch
  arguments:
    path: src/auth/login.ts
    old_string: const token = signJwt(user)
    new_string: const accessToken = signJwt(user)

# Hermes:
# 1. Locates old_string using fuzzy matching
# 2. Refuses if old_string matches in multiple places (forces disambiguation)
# 3. Writes the file back with the replacement
✓ Completed