When an agent file edit fails, the error should carry recovery state

Patchloom 0.27.0, released on August 4, 2026, adds structured information for two points where an AI agent's file operation can fail. A host can now recover a backup session identifier from some failed writes. It can also receive a documented operation suggestion when a single-path document command targets more than one node. These details matter because a host must decide whether to restore, stop, or prepare a different operation after the normal path ends.

For the two failure cases covered by the release, the answer is yes: the host can act on typed fields instead of interpreting an English error message. The answer has firm limits. A backup identifier exists only when the failed write created a backup, and an operation suggestion does not run a retry or prove that the intended edit is correct. This article explains the dependency between refusal, recovery, and validation, then gives operators a small fixture suite for testing their own integration.

Patchloom sits between an agent's intent and a structured file write

The Patchloom repository describes the project as a structured file-editing layer for AI agents, rather than a general filesystem server. Its stated scope includes parser-backed JSON, YAML, and TOML edits; Markdown and abstract syntax tree operations; dry runs; batch and transaction operations; undo; and a Model Context Protocol (MCP) server. These are project scope claims. They do not establish adoption or production maturity.

A host is the application that calls the library, command, transaction, or MCP tool and decides what happens next. The host may be an agent runtime, an editor integration, or an internal automation service. This article stays with that host-to-tool decision after a file operation. Portable plugin packaging and local runtime trust are separate concerns, covered in our analysis of the Agent Plugins package boundary.

The release exposes two different facts that a host needs after failure

The first fact is recovery state. Successful Patchloom edits already exposed EditResult.backup_session. Version 0.27.0 adds api::backup_session_from_error, which lets a library host extract the backup session identifier from an error when a write failed after a backup was created. The release includes a post-write formatting failure as one example. It does not say that every error has a backup session.

That scope changes the correct branch. If the helper returns a session identifier, the host has a specific recovery reference and can start the documented restore path. If it returns no identifier, the host must not invent one or assume that a restorable backup exists. The typed result makes the distinction available to code without requiring code to search the error text for phrases about sessions or restoration.

The second fact is the operation that can express a multi-match intent. A selector identifies a location in a structured document. Predicates select nodes by a condition, while wildcards can select more than one node. Patchloom's single-path doc set, doc ensure, and doc delete operations still reject predicate or wildcard selectors that can match multiple nodes. The failure remains error_kind: invalid_input, so the command does not silently widen a one-target write.

For JSON output, that refusal can now include suggested_op. The documented value is doc.update for doc set and doc ensure, or doc.delete_where for doc delete. An intermediate predicate parent uses the same mapping as a predicate at the final selector segment. Move has no corresponding multi-match operation, so Patchloom omits the suggestion. Plan and transaction output, along with MCP JSON, preserve the field.

The suggestion guides the host; it does not perform the next operation. A host still has to check whether a multi-match write matches the user's intent and its own policy. If the field is absent, code should stop instead of guessing from the wording of the message.

An illustrative mechanics example shows the required order

The following is an illustrative mechanics example based on the release's typed contract. It is not a reported customer incident, and it does not reproduce unverified JSON.

1. A host asks a single-path document operation to act on a selector that matches several nodes. The request is internally inconsistent: the operation promises one path, while the selector describes a set.

2. Patchloom refuses the request with error_kind: invalid_input. The refusal preserves the one-path meaning of the original command. The host now knows that no valid multi-match operation has been authorized merely because several nodes matched.

3. The same structured error may include suggested_op. For a set or ensure request, the value can be doc.update; for a delete request, it can be doc.delete_where. The host can use that field to prepare a new, explicit operation, subject to an intent check and a dry-run review. It must not scrape the prose or retry automatically.

4. Consider a separate write attempt that proceeds far enough to create a backup and then fails, such as a post-write formatting failure. The host can pass that error to api::backup_session_from_error. If the helper returns an identifier, the host can use the identified backup session for restoration before it attempts more work.

5. After either path, the host still needs evidence about the file. It should inspect the exact diff and run the parser, schema, unit, integration, or application tests that apply to the edited file. A typed refusal explains why one operation could not run. A backup identifier locates recovery state. Neither field proves that a later edit expresses the intended business change.

This order prevents two common control-flow errors. The host does not turn a one-path request into a many-path write without a new decision, and it does not continue after a failed write while assuming the file is unchanged. Refusal comes before operation selection. Restoration comes before another write when a backup exists. Validation comes after any applied or restored state.

Structured errors improve control flow, not acceptance evidence

Machine-readable fields remove an avoidable source of ambiguity. English messages remain useful for people, but automation should not depend on their wording. A stable error_kind, an optional suggested_op, and an optional backup session identifier let the host branch on the condition that the tool reports.

Those fields describe tool state. They do not decide whether a change is acceptable. A multi-match operation can be valid for the selector and still touch the wrong records. A restore can complete and still leave generated files, caches, or external side effects that the backup did not cover. The integration owner must define what the restore includes and which checks establish an acceptable result.

The same separation applies to successful writes. As our review of AI-generated security patches explains in a different context, a generated change is a candidate until downstream evidence supports acceptance. For a configuration or document edit, that evidence usually starts with the exact diff and parser validity. It can also include schema checks, application tests, policy checks, and review by the person who owns the affected behavior.

A disposable fixture suite should exercise each decision branch

BaristaLabs recommends testing the integration with small disposable fixtures before connecting it to live project files. Create representative JSON, YAML, and TOML files, plus a Markdown file for Patchloom's separate Markdown operations. Keep each fixture small enough that a reviewer can predict the complete diff. Store a pristine copy so every case starts from the same bytes and can end with an unchanged-file check.

Start with a known single target in each structured format. Run the intended one-path operation in preview mode, compare the complete diff with the expected diff, then apply it and parse the result again. Run any schema or application test that gives the field meaning. For Markdown, use a known heading or table target and apply the same preview, exact-diff, and application-specific checks without assuming that document-selector hints apply to Markdown operations.

Next, add a predicate and a wildcard that each match multiple document nodes. Confirm that the single-path operation fails with error_kind: invalid_input, that the file remains unchanged, and that suggested_op has the documented value for set, ensure, or delete. Include an intermediate predicate parent, because the release says the same mapping applies there. Also include a move case and confirm that no multi-match suggestion appears.

Add a malformed selector as a separate case. It should fail without changing the file, and the harness should branch on typed output rather than the error sentence. Do not treat every invalid_input as permission to use doc.update. The new field is optional, and the release documents cases where no suggestion is available.

Finally, create a controlled post-write failure after backup creation. Configure a disposable write so its post-write formatter fails after the backup exists. Confirm that the host can extract the backup session identifier, restore from that session, and compare the restored file with the pristine fixture. Then run the relevant parsers and application tests again. The unchanged-file check verifies restoration of the fixture; the tests check whether the surrounding application still accepts that state.

Automate these cases in the same layer that will operate Patchloom. A CLI wrapper should inspect CLI JSON. An MCP host should inspect the preserved MCP field. A library host should call the typed helper. This avoids a test that passes at one interface while the deployed integration loses the information during error wrapping.

Host policy must decide when a suggestion is allowed to become a new write

A useful host policy has a small number of explicit branches. On invalid_input, inspect suggested_op. If it is present and the original request clearly permits a multi-match change, construct the documented sibling operation and require a preview or exact-diff review before apply. If the suggestion is absent, stop and return the typed failure to the agent or operator.

On a failed write, check for a backup session identifier before another mutation. If one is present, restore and verify the restored state. If none is present, stop and use the failure handling defined for that operation; do not report that rollback is available. The policy should also record the original operation, the typed error, the chosen next action, and the validation result in the system's existing run log.

Patchloom reports a project badge of more than 4,100 tests. That figure describes project-reported test volume. It is not an independent benchmark, a coverage result, a pass rate for a specific host integration, or evidence about production outcomes. The fixture suite above tests the narrower question that an operator can answer locally: does this host preserve the typed state and make the intended decision at each failure branch?

Test recovery as part of the workflow, not after deployment

Patchloom 0.27.0 gives hosts better inputs for refusal and recovery decisions. The practical gain appears only when the surrounding automation uses those inputs, preserves them across interfaces, and checks the file after the operation. A reliable file-editing workflow needs a defined response when the requested operation is too broad, when a write fails after backup, and when the resulting diff does not pass validation.

For teams adding agent-driven document changes to a business process, BaristaLabs can help audit one process-automation workflow from request through write, restore, review, and application validation. The useful outcome is a bounded first implementation with typed failure branches and a disposable fixture suite that the team can run before live files are in scope.