File Editing

Precise, conflict-safe find-and-replace across files, safe by default against concurrent edits

File editing tools provide secure, workspace-scoped file operations with precise, conflict-safe find-and-replace that’s safe by default. Ambiguous matches fail loudly instead of editing the wrong occurrence. Read-modify-write on the same file is automatically serialised across parallel tools and multi-agent teams, and writes abort with a clear error if the file changed on disk since it was last read — no extra parameters required. A fuzzy matching ladder makes first-try edits succeed even when old_string drifts from the file by whitespace, indentation, or line endings.

from praisonaiagents import Agent

agent = Agent(
    name="coder",
    instructions="Edit files with safe find-and-replace tools",
)

agent.start("Rename the helper in src/utils.py")

The user requests a code change; the agent reads the file, matches uniquely, verifies the hash, then writes and returns a diff.

The user describes an edit; the agent reads, matches uniquely, and writes with conflict checks.

Quick Start

1. Agent edits a file safely (no boilerplate)

   from praisonaiagents import Agent
   
   agent = Agent(
       name="Code Editor",
       instructions="Edit code precisely. Re-read files before retrying after a stale error.",
       tools=["read_file", "edit_file", "search_files"],
   )
   
   agent.start("In src/user.js, replace getUserName() with getUserEmail().")
   # read_file records a hash; edit_file is auto-serialised and stale-aborted
   # with no extra params from the agent.

2. String-name resolution — no import needed

   from praisonaiagents import Agent
   
   agent = Agent(name="coder", tools=["edit_file", "apply_patch", "read_file"])
   agent.start("Refactor UserService to AccountService in src/user.py")

3. Direct SDK use (automatic protection)

   from praisonaiagents.tools.edit_tools import read_file, edit_file
   
   read_file("src/user.js")  # arms the automatic staleness guard
   
   edit_file(
       "src/user.js",
       old_string="def getUserName(self):",
       new_string="def getUserEmail(self):",
   )
   # Aborts with "file changed since it was read" if anything modifies the file
   # between the read and the edit. No expected_hash needed.

4. Replace all occurrences

   from praisonaiagents.tools.edit_tools import edit_file
   
   edit_file(
       "styles.css",
       old_string="color: blue",
       new_string="color: green",
       replace_all=True,
   )

How It Works

Safe by Default: Concurrency & Staleness

Every read-modify-write on the same file is serialised by a per-file lock, and every write checks whether the file changed since it was last read — both run automatically across FileTools, EditTools, and apply_patch.

Per-File Locking

graph TB
    subgraph "Per-File Lock — same path serialises, different paths parallel"
        A1[Agent A: edit_file file.py] --> L1[🔒 lock(file.py)]
        A2[Agent B: edit_file file.py] -.waits.-> L1
        A3[Agent C: edit_file other.py] --> L2[🔒 lock(other.py)]
        L1 --> W1[✏️ A writes]
        W1 --> R1[🔓 release]
        R1 --> A2W[✏️ B writes]
        L2 --> W3[✏️ C writes in parallel]
    end

    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef lock fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef ok fill:#10B981,stroke:#7C90A0,color:#fff

    class A1,A2,A3 agent
    class L1,L2 lock
    class W1,A2W,W3,R1 ok

Automatic Staleness Guard

Which Override Do I Need?

Precedence Ladder

The precedence order is: expected_hash > force=True > automatic last-read-hash guard.

force=True Examples

from praisonaiagents.tools.edit_tools import edit_file, apply_patch
from praisonaiagents.tools.file_tools import FileTools

# 1. Intentional blind edit
edit_file("rollback.txt", "v2", "v1", force=True)

# 2. Force an entire patch (overrides Update, Delete & Move staleness; per-file lock still applies)
apply_patch(patch_text, force=True)

# 3. Force a blind write through FileTools
FileTools().write_file("out.log", "snapshot", force=True)

How Fuzzy Matching Works

edit_file walks a deterministic ladder of matching strategies and stops at the first strategy that produces a confident match. Exact matches always win; fuzzy strategies only engage when an exact substring is not found. Existing code keeps behaving exactly as before — only previously-failing edits now succeed.

Confidence guards (block_anchor only):

• Similarity threshold: 0.7 (constant _BLOCK_ANCHOR_THRESHOLD in source)
• Disproportionate-length guard: rejects blocks more than 2× or less than half the old_string line count
• Tie-breaking: two equally-scored candidates are treated as ambiguous (not silently picked)

from praisonaiagents.tools.edit_tools import edit_file

# File uses tabs; old_string uses spaces — still succeeds
# because indentation_flexible normalises both
edit_file(
    "src/utils.py",
    old_string="    return value",
    new_string="    return processed_value",
)

Self-Correcting No-Match Hints

When the fuzzy ladder finds nothing, the error shows the most similar lines of the file so the agent can fix old_string and retry without re-reading.

Agent Quick Start

from praisonaiagents import Agent

agent = Agent(
    name="Self-Correcting Editor",
    instructions=(
        "Edit files precisely. If a 'String not found' error includes a "
        "'Closest match in the file' block, copy old_string from those lines "
        "and retry."
    ),
    tools=["read_file", "edit_file"],
)

agent.start("In src/compute.py, change `return x * 2` to `return x * 3`.")

How it plays out:

1. The agent sends an old_string that is slightly off (for example def compute(y): instead of def compute(x):).
2. edit_file fails and shows the closest lines with line numbers.
3. The agent copies those lines into old_string and retries — no extra read_file call.

What the hint looks like

Error: String not found in file: 'def compute(y):...'. Closest match in the file, lines 3-4:
    3| def compute(x):
    4|     total = x * 2
Adjust old_string to match these lines exactly, or re-read the file if it changed.

apply_patch Update and Move hunks use the same hint after Error: Hunk not found in '<path>': '<preview>'.

When the hint appears

The hint shows up to 10 lines (with ... if the region is longer), and each line is cut to 200 characters with ... [truncated]. Success and ambiguous-match messages are unchanged.

Multi-file Patches with apply_patch

apply_patch lets an agent Add, Update, Delete, and Move/rename multiple files in a single atomic call — all changes succeed together or none are committed.

1. Agent Quick Start

   from praisonaiagents import Agent
   
   agent = Agent(
       name="Refactor Agent",
       instructions="Refactor across files atomically. Use apply_patch for multi-file changes.",
       tools=["read_file", "search_files", "apply_patch", "edit_file"],
   )
   
   agent.start("Rename UserService to AccountService across src/ and update its tests.")

2. Direct SDK use

   from praisonaiagents.tools.edit_tools import apply_patch
   
   patch = """*** Update File: src/service.py
   @@
   class UserService:
   ===
   class AccountService:
   *** Update File: tests/test_service.py
   @@
   from src.service import UserService
   ===
   from src.service import AccountService
   *** Delete File: docs/old_userservice.md
   """
   
   result = apply_patch(patch)
   print(result)  # "Success: Applied patch to 3 file(s) ... <combined diff>"

Patch Format Reference

Optional sentinels Begin Patch / End Patch are accepted and stripped.

The Move File split is on the literal " -> " (space on both sides), so paths containing -> without surrounding spaces are unaffected. Both source and destination must be non-empty and resolve to different paths.

Update hunk syntax:

*** Update File: path/to/file
@@
<old block to find>
===
<new block to replace it with>
@@
<another old block>
===
<another new block>

Each @@ hunk runs through the same fuzzy ladder as edit_file, so whitespace/indentation drift in the old block is tolerated.

Move hunk syntax:

Rename only — the header stands on its own line:

*** Move File: src/user.py -> src/account.py

Rename and edit in one atomic op — add one or more @@ hunks after the header:

*** Move File: src/user.py -> src/account.py
@@
class User:
===
class Account:

Move hunks run through the same fuzzy ladder as Update, and BOM/CRLF are preserved from the source.

1. Agent rename-and-edit in one op

   from praisonaiagents import Agent
   
   agent = Agent(
       name="Refactor Agent",
       instructions="Rename files with apply_patch's Move File; combine with @@ hunks to edit in the same op.",
       tools=["read_file", "apply_patch", "edit_file"],
   )
   
   agent.start("Rename src/user.py to src/account.py and swap `class User` for `class Account`.")

2. Direct SDK use

   from praisonaiagents.tools.edit_tools import apply_patch
   
   result = apply_patch("""*** Move File: src/user.py -> src/account.py
   @@
   class User:
   ===
   class Account:
   """)
   print(result)  # "Renamed src/user.py -> src/account.py\n<diff>"

Atomicity Guarantees

Move commit flow:

apply_patch Error Messages

Post-edit Diagnostics

After a successful edit, edit_file and apply_patch can run a lightweight checker on the modified file and append concise diagnostics to the tool result — so the agent sees the problem and fixes it in the same loop.

Agent Quick Start

from praisonaiagents import Agent

agent = Agent(
    name="Self-correcting Editor",
    instructions=(
        "Edit code precisely. If a Diagnostics section appears in the tool "
        "result, fix the reported problems in your next edit."
    ),
    tools=["edit_file", "apply_patch", "read_file"],
)

agent.start("In src/calc.py, replace `total = a + b` with `total = a + b + c`.")

When a Diagnostics block appears, the agent self-corrects in the next turn — no separate “run the linter” task required.

Three modes

Configure the mode

from praisonaiagents.tools.edit_tools import create_edit_tools

edit_tools = create_edit_tools(post_edit_diagnostics="on")  # or "auto" / "off"

Which checker runs?

The first installed candidate for the file extension is used. Nothing installed → diagnostics are silently skipped and the tool returns the plain success string.

Output format

Success: Made 1 replacement(s) in src/calc.py

Diff:
@@ -1 +1 @@
-total = a + b
+total = a + b + c

Diagnostics (ruff):
src/calc.py:1:18: F821 Undefined name `c`

Guarantees

• Backward compatible — auto mode keeps the success string unchanged when the edit is clean.
• Never breaks an edit — a missing, slow, or crashing checker is silently skipped (logged at DEBUG).
• Bounded — 10-second timeout per file; output capped at 2000 characters and truncated cleanly beyond that.
• Sandbox-safe — eslint runs with --no-config-lookup so workspace-controlled configs/plugins cannot execute code; tsc runs per-file without a tsconfig.json.
• Zero overhead in off mode — all imports are deferred.

Post-edit Formatting

After a successful edit, EditTools can run a configured language-appropriate formatter on the touched file and persist the formatted result. Default is "off" — byte-for-byte identical to prior behaviour. A missing or failing formatter never turns a successful edit into a failure.

Agent Quick Start

from praisonaiagents import Agent
from praisonaiagents.tools.edit_tools import create_edit_tools

edit_tools = create_edit_tools(post_edit_format="auto")

agent = Agent(
    name="Code Editor",
    instructions="Edit files cleanly and let the formatter tidy up afterward.",
    tools=[edit_tools.edit_file, edit_tools.apply_patch],
)

agent.start("Refactor src/utils.py to use list comprehensions")

Three modes

Invalid values silently fall back to "off".

Built-in formatters

Relative commands (e.g. ./node_modules/.bin/prettier) resolve relative to the edited file’s directory, not CWD. Formatter runs under a 10-second timeout; timeouts are swallowed. The on-disk hash baseline is only refreshed when the formatter exits 0.

Custom formatter overrides

from praisonaiagents.tools.edit_tools import create_edit_tools

edit_tools = create_edit_tools(
    post_edit_format="auto",
    formatters={
        ".py": ("black", ["black", "--quiet"]),
        ".ts": ("local-prettier", ["./node_modules/.bin/prettier", "--write", "{path}"]),
    },
)

formatters maps lowercase extensions to (tool_name, argv_template). Use {path} in argv entries; if omitted, the path is appended.

Configuration Options

File Editing Functions

Edit Parameters

Constructor Parameters (EditTools / create_edit_tools)

Confining the no-workspace fallback

Pin the fallback base directory even when no Workspace object is wired up.

from praisonaiagents.tools.edit_tools import create_edit_tools

# Pin the fallback base to a specific project directory.
edit_tools = create_edit_tools(root="/srv/projects/demo")

# Reads inside the root work; anything outside is rejected.
content, meta = edit_tools.read_file("/srv/projects/demo/README.md")   # ok
content, meta = edit_tools.read_file("/etc/passwd")                    # Path traversal detected

# Single unique match — guard fires automatically after a prior read
edit_file("config.py", "DEBUG = False", "DEBUG = True")

# Multiple matches — replace_all required
edit_file("styles.css", "color: blue", "color: green", replace_all=True)

# Explicit hash (most precise — takes priority over automatic guard)
content, h = read_file("config.py")
edit_file("config.py", "DEBUG = False", "DEBUG = True", expected_hash=h)

# Intentional blind write — skip the staleness check
edit_file("rollback.txt", "v2", "v1", force=True)

Error Messages

Common Patterns

Code Refactoring

from praisonaiagents.tools.edit_tools import read_file, edit_file

read_file("src/utils.js")
edit_file(
    "src/utils.js",
    "function oldFunction(",
    "function newFunction(",
)

Configuration Updates

# Ambiguous if port: 3000 appears twice — add context or use replace_all=True
edit_file(
    "config.js",
    "server: {\n  port: 3000",
    "server: {\n  port: 8080",
)

Surviving Concurrent Edits

from praisonaiagents.tools.edit_tools import read_file, edit_file

# Automatic — the recorded read hash makes the edit safe.
read_file("config.py")
result = edit_file("config.py", "DEBUG = False", "DEBUG = True")
# If anything changed config.py between the read and the edit, the result is
# the staleness error; re-read and retry, or pass force=True for an intentional
# blind write.

# Same protection for write_file:
from praisonaiagents.tools.file_tools import FileTools
ft = FileTools()
ft.read_file("config.json")
ft.write_file("config.json", '{"debug": true}')  # refuses if config.json moved on us

If you already have a trusted hash:

from praisonaiagents.tools.edit_tools import read_file, edit_file

content, h = read_file("config.py")
# ... another process may edit the file here ...
result = edit_file("config.py", "DEBUG = False", "DEBUG = True", expected_hash=h)
# Returns stale-file error if content changed — re-read and retry

Atomic Multi-file Rename

Move the file and fix its importer in one lossless, atomic op — no need to restate the file body:

from praisonaiagents.tools.edit_tools import apply_patch

result = apply_patch("""*** Begin Patch
*** Move File: src/auth.py -> src/account.py
@@
class UserService:
===
class AccountService:
*** Update File: tests/test_auth.py
@@
from src.auth import UserService
===
from src.account import AccountService
*** End Patch
""")

Without Move File, the same rename needs a Delete + Add pair that restates the whole file body — heavier and not lossless.

Best Practices

Related