Operate

SmartPatch tool

Use SmartPatch for small, targeted file updates when a full editing engine would be unnecessary or unavailable.

What it is

SmartPatch applies a stripped-down, Codex-style update patch to one existing file. It verifies that the patch targets the expected relative path and writes the updated file through the Buffaly tooling layer.

Update-only

It does not create, delete, or rename files.

Context-based

It matches old/context lines and optional anchors instead of unified-diff line numbers.

Narrow by design

Use it for known, local edits that are easy to inspect and validate.

Why SmartPatch exists

Small source edits are easy to express badly with shell string replacement. PowerShell or ad hoc text mutation can hide escaping problems, accidentally rewrite too much, or make it unclear which old text the agent intended to replace.

SmartPatch gives agents a structured alternative: name the existing file, show the old/context lines, show the new lines, and let the applicator perform matching, backup, write, and error reporting.

Agent-facing tools

ToApplySmartPatchToProjectFile

Updates one existing file under the current Buffaly agent project root. Use it for project-local edits under the active agent project directory.

ToApplySmartPatchToFileUnderRoot

Updates one existing file under an explicit root directory. Use it when the target file is outside the current agent project root.

Both tools accept relativePath and patchText. The explicit-root version also accepts rootDirectory. The *** Update File: header must match the provided relative path exactly after normal relative-path normalization.

Patch format

SmartPatch uses an update-only subset of the Codex patch mini-language. Each chunk body line must start with a single space for unchanged context, - for removed text, or + for inserted text. Every chunk must include at least one changed line.

*** Begin Patch
*** Update File: relative/path.ext
@ optional anchor text
 context line
-old line
+new line
 context line
*** End Patch

Use exactly one update section per patch.
Do not use add, delete, rename, or unified-diff line-number hunks.
Do not use a standalone @ chunk as a navigation marker.

Examples

Basic one-line edit

*** Begin Patch
*** Update File: src/Sample.cs
@ void Run()
     void Run()
     {
-        Console.WriteLine("A");
+        Console.WriteLine("B");
     }
*** End Patch

Multiple chunks in one file

*** Begin Patch
*** Update File: sample.cs
@
 class Sample
 {
-    int A = 1;
+    int A = 10;
     int B = 2;
@
-    int C = 3;
+    int C = 30;
 }
*** End Patch

SmartPatch computes replacements against the original line list and applies them in reverse order, so earlier replacements do not shift later chunk positions.

Anchors and matching

The @ line can be bare or include anchor text. Anchor text narrows where SmartPatch starts searching for the chunk's old/context lines, which matters when repeated blocks appear in the same file.

Good anchor

@ class ServiceToolRegistrar
-bool autoInitialize = oldValue;
+bool autoInitialize = true;

Avoid anchor-only chunks

Do not create a chunk that only navigates and contains no + or - lines. Move the navigation text onto the changed chunk header instead.

Common error messages

Anchor-only chunk: the patch used @ as a section separator. Merge the context into the following changed chunk or move navigation text onto the @ header.

Old/context lines not found: the file changed or the context is not specific enough. Read the current file around the target and regenerate the patch with exact current lines.

Invalid hunk line prefix: one body line is missing its prefix. Unchanged context lines must begin with a single space.

Backups and validation

For file-based application, SmartPatch creates a rolling backup before writing the target file. The tool result includes the backup path for visibility.

Backups are a safety net, not a substitute for review. After meaningful edits, inspect the diff, run relevant builds or tests, and commit only intentional files.

How SmartPatch differs from Codex editing

SmartPatch	Codex editing
Update-only deterministic tool call.	Full editing-session delegate.
Caller supplies exact patch text.	Can synthesize edits from higher-level instructions.
Best for small known changes.	Best for complex changes, refactors, or codebase-level reasoning.
Preferable to PowerShell for narrow structured edits.	Can create, delete, rename, and reorganize files when appropriate.

Best practices

Use SmartPatch only when the edit is small, local, and easy to validate.
Inspect the current file first with search and file-reading tools.
Include enough surrounding context and add anchors when repeated text appears.
Do not retry a failed patch unchanged; re-read the file and adjust old/context lines.
For source changes, run the relevant build or tests; update companion .cs.md or .pts.md docs for non-trivial source edits.

Codex workflows Safety rules Tools and action loading