patch

patch_tool() exposes a patch tool for precise edits to existing UTF-8 text files. It is backed by llm-patch-tool, which handles parsing SEARCH/REPLACE blocks, exact-then-fuzzy matching, all-or-nothing application, and atomic writes.

Parameters:

1. path: str
2. edits: str

Permissions

patch resolves path from its captured cwd in the selected filesystem and checks ToolOperation.MODIFY_FILE before parsing or applying edits. A denied request returns:

permission denied: patch is not allowed for `/workspace/private.txt`

SideEffectApprovalToolPermissionPolicy and workspace_tool_policy(require_approval_for_side_effects=True) request approval for patch operations before the file is modified.

An approval-required request returns:

approval required: patch requires application approval for `/workspace/notes.txt` before execution

path is structured tool input and resolves in the selected filesystem. edits should contain one or more bare SEARCH/REPLACE blocks without path lines:

<<<<<<< SEARCH
old text already present in the file
=======
replacement text
>>>>>>> REPLACE

Example tool result:

Applied 1 edit to /workspace/notes.txt.

Use patch after reading the file when you need targeted changes. Each SEARCH block must match exactly one location. If the text is missing, appears more than once, overlaps another edit, has an empty SEARCH block, or would not change the file, the tool returns a stable recoverable message and leaves the file unchanged. Use write instead for new files or full-file rewrites.

The tool returns clear text errors for empty paths, paths containing null bytes, missing files, directory targets, malformed SEARCH/REPLACE blocks, invalid UTF-8 edit text, invalid UTF-8 files, permission failures, and failed writes. Unexpected implementation errors return a stable generic failure message so the agent loop can continue.

Injected Storage

Pass reader=storage, writer=storage for one storage namespace. Supply both capabilities together in the same namespace. Paths use that namespace and cwd defaults to its root. Mounted filesystems accept rooted virtual paths; relative paths resolve from the captured cwd. Plain injected backends retain relative POSIX syntax. The tool checks MODIFY_FILE before reading the target. The patch engine applies all edits to content and preserves matching, BOMs, line endings, and error behavior. The tool opens a writer only after all edits succeed. No remote-to-local copy is made.

The writer context completes replacement on success and preserves the target on failure. One tool instance serializes the complete read-edit-write operation. Separate tool instances and external writers require application coordination of the whole operation; serialized commits alone do not prevent lost updates. Started writes settle before cancellation propagates and the lock is released. See File I/O interfaces.