Skip to main content

​
Tool Change Management

Every tool execution in X21 is tracked so you can preview, apply, revert, and audit changes with confidence. This is powered by the orchestrator’s stateManager and the Excel API’s ability to capture both forward and reverse diffs.

​
Lifecycle of a Tool Change

  1. Pending – When Claude proposes a tool, the backend stores its payload in toolChangeHistory with pending: true, applied: false, approved: false.
  2. View – Selecting View runs the tool and applies changes in Excel while keeping the status pending. The backend records inputDataRevert, enabling fast undo.
  3. Approve – Marks the change as approved: true, applied: true, and updates the conversation history with the tool result.
  4. Reject – Reverts any staged edits, logs the user message, and sets the change to pending: false.
Each change entry stores the tool ID, tool name, timestamp, workbook, and raw input/output so you can inspect exactly what happened.

​
Reverting Changes

  • Use Revert from the UI or tool:revert programmatically. The backend calls revertToolChangesForWorkbookFromToolIdOnwards, which iterates through the tool chain in reverse order, applying saved inputDataRevert payloads.
  • Reverting updates conversation history with a clarification that the tool output is no longer applied, helping Claude avoid relying on stale results.

​
Reapplying Changes

  • After reverting, you can reapply with tool:apply. This is useful when experimenting with alternative prompts but ultimately sticking with the original change set.
  • The backend calls applyFromToolIdOnwards, re-runs the stored tool inputs, and logs the operation in Langfuse with a dedicated trace.

​
Auditing & Observability

  • Langfuse spans mark each approval (tool_approval), rejection (tool_rejection), and revert operation. Metadata includes user email, workbook, and tool IDs.
  • The UI displays a chronological history so analysts can follow the sequence of decisions.
  • Log files capture “before” and “after” snapshots for debugging, especially for write operations where data integrity matters.

​
Best Practices

  • Preview complex operations (batch writes, structural changes) before approving so revert data is available.
  • Reject tools with clear feedback if they do not meet requirements; Claude will reference the message when proposing alternatives.
  • Periodically clear tool history by restarting the conversation when you switch tasks to avoid replaying stale changes accidentally.
With granular change management, X21 ensures governed collaboration between AI suggestions and human oversight.