Files
archie/internal/tools/builtin/write.go
T
sam e10d862f6a feat(tools): checkpoint files before mutating write and edit
The built-in workspace write and edit tools replaced file content with
no recoverable pre-state. Each now snapshots its target immediately
before the write and refuses the mutation when the snapshot cannot be
taken, so a checkpoint is never silently skipped.

Checkpoints land in .git/archie-checkpoints inside the workspace, the
same per-task state directory that already holds the task brief and the
prepared sentinel: nothing under .git can be swept onto the task branch
by go-git's Add{All:true}. A checkpoint records either the file's bytes
or its absence, so creating a file restores by removing it;
RestoreLatest returns the most recent pre-state for a path.

Shell, Go-script, MCP and plugin tools are deliberately not covered:
the set of files they can touch is not enumerable from the call.
2026-10-02 09:18:47 +10:00

167 lines
5.3 KiB
Go

// Lifted from tau internal/agent/tools/write.go
// tau commit f5289ea3782c099339c2d26fe3af8ebcf42ba52d (2026-07-27).
//
// Mutations from upstream:
// - package renamed tools -> builtin (archie-core already has an
// internal/tools package holding the registry these are registered into).
//
// Refresh by diffing against that path at a newer tau commit. Do not
// edit without recording the change above.
package builtin
import (
"context"
"encoding/json"
"errors"
"fmt"
"os"
"path/filepath"
)
// WriteParams are the parameters for the write tool.
type WriteParams struct {
Path string `json:"path"`
Content string `json:"content"`
Overwrite bool `json:"overwrite,omitempty"`
}
var writeSchema = Schema{
Name: "write",
Description: "Create or overwrite a file with the given content. Creates parent directories as needed. Set overwrite to true to replace an existing file; otherwise the tool will refuse to overwrite.",
Parameters: json.RawMessage(`{
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "Absolute or relative file path to write"
},
"content": {
"type": "string",
"description": "The full file content to write"
},
"overwrite": {
"type": "boolean",
"description": "Allow overwriting an existing file. Defaults to false - the tool will error if the file already exists unless this is true."
}
},
"required": ["path", "content"]
}`),
}
// NewWriteTool creates the built-in write tool.
func NewWriteTool(cwd string, mq *MutationQueue, rt *ReadTracker) Tool {
return Tool{
Schema: writeSchema,
Source: "builtin",
Emoji: "📝",
Execute: makeWriteExecutor(cwd, mq, rt, NewCheckpointStore(cwd)),
}
}
func makeWriteExecutor(cwd string, mq *MutationQueue, rt *ReadTracker, cp *CheckpointStore) Executor {
return func(ctx context.Context, params json.RawMessage, _ UIBridge) (Result, error) {
var p WriteParams
if err := json.Unmarshal(params, &p); err != nil {
return Result{Content: fmt.Sprintf("invalid parameters: %v", err), IsError: true}, nil
}
if len(p.Content) > maxWriteBytes {
return Result{Content: fmt.Sprintf("content too large (%s > %s)", FormatSize(len(p.Content)), FormatSize(maxWriteBytes)), IsError: true}, nil
}
path := resolvePath(cwd, p.Path)
if !isConfined(cwd, path) {
return Result{Content: "path escapes working directory", IsError: true}, nil
}
writeCtx, cancel := context.WithTimeout(ctx, DefaultToolTimeout)
defer cancel()
var result Result
err := runWithContext(writeCtx, func() error {
// Check for accidental overwrite and enforce read-before-write.
// Both checks only apply when the file already exists; new files
// are always allowed.
oldContent, block := checkExistingFile(path, cwd, p.Path, p.Overwrite, rt)
if block != nil {
result = *block
return nil
}
release := mq.Acquire(path)
defer release()
// Snapshot before the first byte changes. If the checkpoint cannot
// be taken the write is refused: proceeding would produce a
// mutation with nothing to restore from.
if _, err := cp.Snapshot(path); err != nil {
result = Result{Content: fmt.Sprintf("refusing to write %s: %v", path, err), IsError: true, ErrorKind: "checkpoint_failed"}
return nil
}
dir := filepath.Dir(path)
if err := os.MkdirAll(dir, 0o755); err != nil {
result = Result{Content: fmt.Sprintf("error creating directory: %v", err), IsError: true}
return nil
}
if err := writeFileAtomic(path, []byte(p.Content), 0o644); err != nil {
result = Result{Content: fmt.Sprintf("error writing file: %v", err), IsError: true}
return nil
}
result = Result{
Content: fmt.Sprintf("wrote %d bytes to %s", len(p.Content), path),
Details: DiffDetails{Path: path, OldContent: oldContent, NewContent: p.Content},
}
return nil
})
if err != nil {
if errors.Is(err, context.DeadlineExceeded) {
return Result{Content: fmt.Sprintf("write timed out after %v", DefaultToolTimeout), IsError: true}, nil
}
return Result{Content: fmt.Sprintf("write failed: %v", err), IsError: true}, nil
}
return result, nil
}
}
// isRegularFile reports whether path exists and is a regular file. A missing
// file, a directory, a symlink, or any other non-regular entry returns false,
// which lets new files skip the overwrite and read-before-write checks.
func isRegularFile(path string) bool {
info, err := os.Stat(path)
return err == nil && info.Mode().IsRegular()
}
// checkExistingFile returns the prior content of an existing regular file and,
// when a write should not proceed, a blocking error result. It enforces the
// read-before-write rule and overwrite opt-in, returning nil when the file may
// be written. Non-regular or missing paths return an empty content and no
// block.
func checkExistingFile(path, cwd, relPath string, overwrite bool, rt *ReadTracker) (string, *Result) {
if !isRegularFile(path) {
return "", nil
}
if rt != nil {
if err := rt.CheckRead(cwd, relPath); err != nil {
return "", &Result{Content: err.Error(), IsError: true}
}
}
if !overwrite {
return "", &Result{
Content: fmt.Sprintf(
"file %q already exists - set overwrite to true to replace it, or use the edit tool for partial changes",
path,
),
IsError: true,
}
}
if data, err := os.ReadFile(path); err == nil {
return string(data), nil
}
return "", nil
}