privateer-agent 0.1.0

package/src/tools/context.ts

@@ -0,0 +1,114 @@
+import { resolve, isAbsolute, relative, sep } from "node:path";
+import type { PermissionGate, PermissionKind } from "../permissions/gate.ts";
+import type { TodoStore } from "./todoStore.ts";
+import type { AgentDefinition } from "../agents/loader.ts";
+import type { ProcessRegistry } from "./processRegistry.ts";
+import type { AttachmentStore } from "../util/attachmentStore.ts";
+
+// A finished sub-agent's result: its final text answer plus run metrics (how many
+// tools it called and how many tokens it spent), so the UI can show a per-agent
+// summary in the grouped "N agents finished" view.
+export interface SubAgentResult {
+  text: string;
+  toolUses: number;
+  tokens: number;
+}
+
+// Runs a child agent and resolves to its final text answer + metrics. With no `agent`
+// it runs the default read-only sub-agent; with one it uses that agent's
+// tools/model/instructions. Supplied by the session (which has the model + config);
+// absent in bare tool contexts.
+export type SubAgentRunner = (input: {
+  description: string;
+  prompt: string;
+  agent?: AgentDefinition;
+}) => Promise<SubAgentResult>;
+
+// Shared state handed to every tool's execute().
+export interface ToolContext {
+  cwd: string;
+  gate: PermissionGate;
+  // When true (the default), the tools confine file access to `cwd`: a path that
+  // resolves outside it (an absolute path elsewhere, or a `../` escape) is only
+  // touched after the user explicitly approves it via the gate. Set false to let the
+  // agent roam (e.g. the user launched with --no-confine / set confineToCwd:false).
+  confineToCwd?: boolean;
+  // Out-of-cwd directories the user has approved this session ("always" on an outside
+  // prompt). A shared array, also held by the gate, so an approved sibling directory
+  // isn't re-prompted on every file inside it. Paths under any of these count as
+  // in-scope.
+  allowedOutsideRoots?: string[];
+  todos?: TodoStore; // session todo list, for the `todo` tool + TUI panel
+  runSubAgent?: SubAgentRunner; // spawns a `task` sub-agent
+  // Reports a finished `task` sub-agent's run metrics, keyed by the originating
+  // tool-call id, so the TUI can annotate the grouped agents view with each agent's
+  // tool-use and token counts. Best-effort; absent outside the interactive session.
+  onSubAgentMetrics?: (toolCallId: string, m: { toolUses: number; tokens: number }) => void;
+  // Called by write/edit just before they mutate a file, so the checkpoint store
+  // can capture its pre-modification state for /rewind.
+  recordMutation?: (abs: string) => void;
+  // Background-shell registry, for bash run_in_background + bash_output/kill_shell.
+  processes?: ProcessRegistry;
+  // Session attachment store (decoded bytes of pasted/dropped files, by "#n"), for the
+  // save_attachment tool to write one back to disk.
+  attachments?: AttachmentStore;
+}
+
+// Resolve a possibly-relative path against the session cwd. The cwd is a *soft*
+// anchor: relative paths are interpreted from it, but absolute paths and `../`
+// escapes are allowed through — the model is nudged (via the system prompt) to
+// stay inside cwd rather than being walled in here.
+export function resolveInCwd(ctx: ToolContext, p: string): string {
+  return isAbsolute(p) ? p : resolve(ctx.cwd, p);
+}
+
+// Display a path relative to cwd when possible (nicer for tool output / UI).
+export function displayPath(ctx: ToolContext, abs: string): string {
+  const rel = relative(ctx.cwd, abs);
+  return rel === "" ? "." : rel;
+}
+
+// Is `abs` the directory `root` itself, or contained within it? Uses the resolved
+// relative path so `..` escapes are caught regardless of how the path was written.
+export function isInsideDir(root: string, abs: string): boolean {
+  if (abs === root) return true;
+  const rel = relative(root, abs);
+  return rel !== "" && !rel.startsWith("..") && !isAbsolute(rel);
+}
+
+// Does this path fall outside the agent's working-directory scope? True only when
+// confinement is on and the path is neither inside cwd nor inside a directory the
+// user already approved this session.
+export function isOutsideScope(ctx: ToolContext, abs: string): boolean {
+  if (ctx.confineToCwd === false) return false;
+  if (isInsideDir(ctx.cwd, abs)) return false;
+  return !(ctx.allowedOutsideRoots ?? []).some((root) => isInsideDir(root, abs));
+}
+
+// Gate access to a path that may sit outside cwd. Returns null when the path is in
+// scope or the user approves the out-of-scope access; returns an error string (for the
+// tool to hand back to the model) when confinement blocks it. In-scope paths never
+// prompt, so ordinary work inside cwd is untouched.
+export async function guardScope(
+  ctx: ToolContext,
+  abs: string,
+  opts: { kind: PermissionKind; title: string },
+): Promise<string | null> {
+  if (!isOutsideScope(ctx, abs)) return null;
+  const decision = await ctx.gate.request({
+    tool: opts.kind,
+    kind: opts.kind,
+    title: opts.title,
+    detail: abs,
+    path: abs,
+    outside: true,
+  });
+  if (decision === "deny") {
+    return (
+      `Error: ${abs} is outside the working directory (${ctx.cwd}). ` +
+      `By default I stay within the working directory; access here was declined. ` +
+      `Ask me explicitly to work in this location to allow it.`
+    );
+  }
+  return null;
+}

package/src/tools/edit.ts

@@ -0,0 +1,67 @@
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { tool } from "ai";
+import { z } from "zod";
+import type { ToolContext } from "./context.ts";
+import { resolveInCwd, displayPath, isOutsideScope } from "./context.ts";
+import { PermissionDeniedError } from "../permissions/gate.ts";
+import { isProtectedPath } from "../permissions/protected.ts";
+
+// Count occurrences of a substring (non-overlapping).
+function countOccurrences(haystack: string, needle: string): number {
+  if (needle === "") return 0;
+  let count = 0;
+  let i = haystack.indexOf(needle);
+  while (i !== -1) {
+    count++;
+    i = haystack.indexOf(needle, i + needle.length);
+  }
+  return count;
+}
+
+export function editTool(ctx: ToolContext) {
+  return tool({
+    description:
+      "Replace an exact string in a file. old_string must match uniquely unless replace_all is set. " +
+      "Include enough surrounding context to make the match unique.",
+    inputSchema: z.object({
+      path: z.string().describe("File to edit."),
+      old_string: z.string().describe("Exact text to replace."),
+      new_string: z.string().describe("Replacement text."),
+      replace_all: z.boolean().optional().describe("Replace every occurrence."),
+    }),
+    execute: async ({ path, old_string, new_string, replace_all }) => {
+      const abs = resolveInCwd(ctx, path);
+      if (!existsSync(abs)) return `Error: file not found: ${displayPath(ctx, abs)}`;
+      if (old_string === new_string) return `Error: old_string and new_string are identical.`;
+
+      const original = readFileSync(abs, "utf8");
+      const occ = countOccurrences(original, old_string);
+      if (occ === 0) return `Error: old_string not found in ${displayPath(ctx, abs)}.`;
+      if (occ > 1 && !replace_all) {
+        return `Error: old_string matches ${occ} places in ${displayPath(ctx, abs)}. Add context or set replace_all.`;
+      }
+
+      const updated = replace_all
+        ? original.split(old_string).join(new_string)
+        : original.replace(old_string, new_string);
+
+      const removed = old_string.split("\n").length;
+      const added = new_string.split("\n").length;
+      const outside = isOutsideScope(ctx, abs);
+      const decision = await ctx.gate.request({
+        tool: "edit",
+        kind: "edit",
+        title: outside ? "Edit outside working directory" : "Edit file",
+        detail: `${outside ? abs : displayPath(ctx, abs)} (${replace_all ? occ + "×, " : ""}-${removed} +${added})`,
+        protected: isProtectedPath(abs),
+        outside,
+        path: abs,
+      });
+      if (decision === "deny") throw new PermissionDeniedError("edit");
+
+      ctx.recordMutation?.(abs);
+      writeFileSync(abs, updated, "utf8");
+      return `Edited ${displayPath(ctx, abs)} (${replace_all ? occ + " replacements" : "1 replacement"}).`;
+    },
+  });
+}

package/src/tools/exec.ts

@@ -0,0 +1,60 @@
+import { spawn } from "node:child_process";
+
+export interface ExecResult {
+  stdout: string;
+  stderr: string;
+  code: number | null;
+  timedOut: boolean;
+}
+
+const MAX_OUTPUT = 30_000; // chars per stream, to keep tool results bounded
+
+// Run a command and capture output with a timeout. When `shell` is true the
+// command string is interpreted by the shell (used by the bash tool); otherwise
+// args are passed directly (used for ripgrep).
+export function exec(
+  cmd: string,
+  args: string[],
+  opts: { cwd: string; timeoutMs: number; shell?: boolean; input?: string },
+): Promise<ExecResult> {
+  return new Promise((resolveP) => {
+    const child = spawn(opts.shell ? cmd : cmd, opts.shell ? [] : args, {
+      cwd: opts.cwd,
+      shell: opts.shell ?? false,
+      env: process.env,
+    });
+
+    // Feed the optional payload on stdin (used by hooks), then close it.
+    if (opts.input !== undefined) {
+      child.stdin?.on("error", () => {});
+      child.stdin?.write(opts.input);
+      child.stdin?.end();
+    }
+
+    let stdout = "";
+    let stderr = "";
+    let timedOut = false;
+
+    const timer = setTimeout(() => {
+      timedOut = true;
+      child.kill("SIGKILL");
+    }, opts.timeoutMs);
+
+    child.stdout?.on("data", (d) => {
+      if (stdout.length < MAX_OUTPUT) stdout += d.toString();
+    });
+    child.stderr?.on("data", (d) => {
+      if (stderr.length < MAX_OUTPUT) stderr += d.toString();
+    });
+    child.on("error", (err) => {
+      clearTimeout(timer);
+      resolveP({ stdout, stderr: stderr + String(err), code: null, timedOut });
+    });
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      const cap = (s: string) =>
+        s.length > MAX_OUTPUT ? s.slice(0, MAX_OUTPUT) + "\n… (output truncated)" : s;
+      resolveP({ stdout: cap(stdout), stderr: cap(stderr), code, timedOut });
+    });
+  });
+}

package/src/tools/glob.ts

@@ -0,0 +1,39 @@
+import { statSync } from "node:fs";
+import picomatch from "picomatch";
+import { tool } from "ai";
+import { z } from "zod";
+import type { ToolContext } from "./context.ts";
+import { resolveInCwd, guardScope } from "./context.ts";
+import { walkFiles } from "./walk.ts";
+
+// Pure-Node glob: walk the tree and match relative paths with picomatch. No
+// external binary dependency, so it works anywhere Privateer is installed.
+export function globTool(ctx: ToolContext) {
+  return tool({
+    description:
+      "Find files matching a glob pattern (e.g. '**/*.ts', 'src/**/test_*.py'). " +
+      "Skips node_modules/.git/build dirs. Returns matching file paths. Read-only.",
+    inputSchema: z.object({
+      pattern: z.string().describe("Glob pattern to match file paths (relative to the search dir)."),
+      path: z.string().optional().describe("Directory to search in (default: working directory)."),
+    }),
+    execute: async ({ pattern, path }) => {
+      const root = path ? resolveInCwd(ctx, path) : ctx.cwd;
+      const blocked = await guardScope(ctx, root, { kind: "read", title: "Search outside working directory" });
+      if (blocked) return blocked;
+      try {
+        if (!statSync(root).isDirectory()) return `Error: ${path} is not a directory.`;
+      } catch {
+        return `Error: directory not found: ${path}`;
+      }
+
+      const isMatch = picomatch(pattern, { dot: true });
+      const files = walkFiles(root).filter((f) => isMatch(f));
+      if (files.length === 0) return "No files matched.";
+      files.sort();
+      const shown = files.slice(0, 200);
+      const more = files.length > shown.length ? `\n… (${files.length - shown.length} more)` : "";
+      return shown.join("\n") + more;
+    },
+  });
+}

package/src/tools/grep.ts

@@ -0,0 +1,86 @@
+import { readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import picomatch from "picomatch";
+import { tool } from "ai";
+import { z } from "zod";
+import type { ToolContext } from "./context.ts";
+import { resolveInCwd, guardScope } from "./context.ts";
+import { walkFiles } from "./walk.ts";
+
+const MAX_MATCHES = 200;
+
+// Treat a file as binary (and skip it) if an early chunk contains a NUL byte.
+function looksBinary(buf: string): boolean {
+  const head = buf.slice(0, 1024);
+  for (let i = 0; i < head.length; i++) {
+    if (head.charCodeAt(i) === 0) return true;
+  }
+  return false;
+}
+
+// Pure-Node content search. Walks files, optionally filtered by a glob, and reports
+// regex matches as "file:line:text". No external binary dependency.
+export function grepTool(ctx: ToolContext) {
+  return tool({
+    description:
+      "Search file contents with a regular expression. Returns matching lines as " +
+      "file:line:text. Optionally restrict to files matching a glob. Read-only.",
+    inputSchema: z.object({
+      pattern: z.string().describe("Regex pattern to search for (JavaScript regex syntax)."),
+      path: z.string().optional().describe("File or directory to search (default: working directory)."),
+      glob: z.string().optional().describe("Only search files matching this glob, e.g. '**/*.ts'."),
+      ignore_case: z.boolean().optional().describe("Case-insensitive search."),
+    }),
+    execute: async ({ pattern, path, glob, ignore_case }) => {
+      let re: RegExp;
+      try {
+        re = new RegExp(pattern, ignore_case ? "i" : "");
+      } catch (err) {
+        return `Error: invalid regex: ${(err as Error).message}`;
+      }
+
+      const root = path ? resolveInCwd(ctx, path) : ctx.cwd;
+      const blocked = await guardScope(ctx, root, { kind: "read", title: "Search outside working directory" });
+      if (blocked) return blocked;
+      let files: string[];
+      let baseDir: string;
+      try {
+        if (statSync(root).isFile()) {
+          baseDir = ctx.cwd;
+          files = [root];
+        } else {
+          baseDir = root;
+          const rel = walkFiles(root);
+          const isMatch = glob ? picomatch(glob, { dot: true }) : () => true;
+          files = rel.filter((f) => isMatch(f)).map((f) => join(root, f));
+        }
+      } catch {
+        return `Error: path not found: ${path}`;
+      }
+
+      const results: string[] = [];
+      for (const file of files) {
+        if (results.length >= MAX_MATCHES) break;
+        let content: string;
+        try {
+          content = readFileSync(file, "utf8");
+        } catch {
+          continue;
+        }
+        if (looksBinary(content)) continue;
+        const rel = file.startsWith(baseDir) ? file.slice(baseDir.length).replace(/^[/\\]/, "") : file;
+        const lines = content.split("\n");
+        for (let i = 0; i < lines.length; i++) {
+          if (re.test(lines[i])) {
+            results.push(`${rel}:${i + 1}:${lines[i].slice(0, 300)}`);
+            if (results.length >= MAX_MATCHES) break;
+          }
+        }
+      }
+
+      if (results.length === 0) return "No matches.";
+      const capped = results.length >= MAX_MATCHES ? "\n… (more matches truncated)" : "";
+      return results.join("\n") + capped;
+    },
+  });
+}

package/src/tools/index.ts

@@ -0,0 +1,69 @@
+import type { ToolSet } from "ai";
+import type { ToolContext } from "./context.ts";
+import { readTool } from "./read.ts";
+import { writeTool } from "./write.ts";
+import { editTool } from "./edit.ts";
+import { globTool } from "./glob.ts";
+import { grepTool } from "./grep.ts";
+import { bashTool, bashOutputTool, killShellTool } from "./bash.ts";
+import { todoTool } from "./todo.ts";
+import { taskTool } from "./task.ts";
+import { webFetchTool, webSearchTool } from "./web.ts";
+import { saveAttachmentTool } from "./saveAttachment.ts";
+import { memoryTool } from "./memory.ts";
+
+export type { ToolContext } from "./context.ts";
+
+// Build the full toolset bound to a session context (cwd + permission gate + todo store).
+export function createTools(ctx: ToolContext): ToolSet {
+  return {
+    read: readTool(ctx),
+    write: writeTool(ctx),
+    edit: editTool(ctx),
+    glob: globTool(ctx),
+    grep: grepTool(ctx),
+    bash: bashTool(ctx),
+    bash_output: bashOutputTool(ctx),
+    kill_shell: killShellTool(ctx),
+    todo: todoTool(ctx),
+    task: taskTool(ctx),
+    web_fetch: webFetchTool(ctx),
+    web_search: webSearchTool(ctx),
+    save_attachment: saveAttachmentTool(ctx),
+    memory: memoryTool(ctx),
+  };
+}
+
+// The read-only subset given to `task` sub-agents: search + inspect, no mutation, no
+// recursion (no `task`/`todo`). Safe to run with an auto-approve gate.
+export function createReadOnlyTools(ctx: ToolContext): ToolSet {
+  return {
+    read: readTool(ctx),
+    glob: globTool(ctx),
+    grep: grepTool(ctx),
+  };
+}
+
+// Factories a sub-agent may be granted. Deliberately excludes `task` and `todo` so
+// sub-agents can't recurse or mutate the parent's todo list.
+const AGENT_TOOL_FACTORIES: Record<string, (ctx: ToolContext) => ToolSet[string]> = {
+  read: readTool,
+  write: writeTool,
+  edit: editTool,
+  glob: globTool,
+  grep: grepTool,
+  bash: bashTool,
+  web_fetch: webFetchTool,
+  web_search: webSearchTool,
+};
+
+// Build a sub-agent's toolset from a list of tool names; unknown names are ignored.
+// Falls back to the read-only set when the list is empty or yields nothing.
+export function createToolSubset(ctx: ToolContext, names?: string[]): ToolSet {
+  const set: ToolSet = {};
+  for (const n of names ?? []) {
+    const factory = AGENT_TOOL_FACTORIES[n];
+    if (factory) set[n] = factory(ctx);
+  }
+  return Object.keys(set).length > 0 ? set : createReadOnlyTools(ctx);
+}

package/src/tools/memory.ts

@@ -0,0 +1,53 @@
+import { tool } from "ai";
+import { z } from "zod";
+import type { ToolContext } from "./context.ts";
+import { saveMemory, deleteMemory } from "../memory/auto.ts";
+
+// Records durable facts across runs (auto-memory). Unlike write/edit this is not gated:
+// memory lives in the agent's own store, and the returned string surfaces in the
+// transcript as a visible notice of what was saved.
+export function memoryTool(ctx: ToolContext) {
+  return tool({
+    description:
+      "Record or remove a durable memory that persists across sessions. Use it for facts " +
+      "worth remembering long-term — user preferences, stable project conventions, and " +
+      "feedback on how to work — not transient details. Memories are recalled into your " +
+      "context automatically via the memory index. Prefer updating an existing memory " +
+      "(same name) over creating a near-duplicate.",
+    inputSchema: z.object({
+      action: z.enum(["write", "delete"]).describe("Write/update a memory, or delete one."),
+      name: z
+        .string()
+        .describe("Short kebab-case identifier, e.g. 'user-prefers-tabs'. Reuse to update."),
+      description: z
+        .string()
+        .optional()
+        .describe("One-line summary (required for write). Shown in the recalled index."),
+      type: z
+        .enum(["user", "feedback", "project", "reference"])
+        .optional()
+        .describe("user=about the user, feedback=how to work, project=ongoing work, reference=pointer."),
+      scope: z
+        .enum(["project", "global"])
+        .optional()
+        .describe("project (default) recalls only here; global recalls in every project."),
+      content: z
+        .string()
+        .optional()
+        .describe("The fact to remember (required for write). Link others with [[name]]."),
+    }),
+    execute: async ({ action, name, description, type, scope, content }) => {
+      if (action === "delete") {
+        const removed = deleteMemory(ctx.cwd, name);
+        return removed
+          ? `Deleted memory "${removed.name}" (${removed.scope}).`
+          : `No memory named "${name}" to delete.`;
+      }
+      if (!description || !content) {
+        return 'To write a memory, provide both "description" and "content".';
+      }
+      const rec = saveMemory(ctx.cwd, { name, description, type, scope, body: content });
+      return `Saved memory "${rec.name}" (${rec.scope}, ${rec.type}).`;
+    },
+  });
+}

package/src/tools/processRegistry.ts

@@ -0,0 +1,77 @@
+import { spawn, type ChildProcess } from "node:child_process";
+
+export interface BgProcess {
+  id: string;
+  command: string;
+  status: "running" | "exited";
+  code: number | null;
+  startedAt: number;
+}
+
+const MAX_OUTPUT = 200_000; // cap retained output per process
+
+// Tracks background shells started by the bash tool (run_in_background). Output
+// accumulates as it streams; `read` returns only what's new since the last read so
+// the model can poll a long-running command.
+export class ProcessRegistry {
+  private procs = new Map<string, { meta: BgProcess; child: ChildProcess; output: string; offset: number }>();
+  private seq = 0;
+
+  spawn(command: string, cwd: string): string {
+    const id = `bash_${++this.seq}`;
+    const child = spawn(command, [], { cwd, shell: true, env: process.env });
+    const entry: { meta: BgProcess; child: ChildProcess; output: string; offset: number } = {
+      meta: { id, command, status: "running", code: null, startedAt: Date.now() },
+      child,
+      output: "",
+      offset: 0,
+    };
+    const append = (d: Buffer) => {
+      if (entry.output.length < MAX_OUTPUT) entry.output += d.toString();
+    };
+    child.stdout?.on("data", append);
+    child.stderr?.on("data", append);
+    child.on("error", (e) => {
+      entry.output += `\n[error] ${e.message}`;
+      entry.meta.status = "exited";
+    });
+    child.on("close", (code) => {
+      entry.meta.status = "exited";
+      entry.meta.code = code;
+    });
+    this.procs.set(id, entry);
+    return id;
+  }
+
+  // New output since the last read, plus current status.
+  read(id: string): { output: string; status: BgProcess["status"]; code: number | null } | null {
+    const e = this.procs.get(id);
+    if (!e) return null;
+    const fresh = e.output.slice(e.offset);
+    e.offset = e.output.length;
+    return { output: fresh, status: e.meta.status, code: e.meta.code };
+  }
+
+  kill(id: string): boolean {
+    const e = this.procs.get(id);
+    if (!e) return false;
+    e.child.kill("SIGTERM");
+    e.meta.status = "exited";
+    return true;
+  }
+
+  list(): BgProcess[] {
+    return [...this.procs.values()].map((e) => e.meta);
+  }
+
+  // Best-effort teardown of all background shells (called on app exit).
+  killAll(): void {
+    for (const e of this.procs.values()) {
+      try {
+        e.child.kill("SIGKILL");
+      } catch {
+        /* already gone */
+      }
+    }
+  }
+}

package/src/tools/read.ts

@@ -0,0 +1,42 @@
+import { readFileSync, existsSync, statSync } from "node:fs";
+import { tool } from "ai";
+import { z } from "zod";
+import type { ToolContext } from "./context.ts";
+import { resolveInCwd, displayPath, guardScope } from "./context.ts";
+
+const MAX_LINES = 2000;
+const MAX_LINE_LEN = 2000;
+
+export function readTool(ctx: ToolContext) {
+  return tool({
+    description:
+      "Read a file from the working directory. Returns the contents with line numbers. " +
+      "Use offset/limit for large files. Read-only.",
+    inputSchema: z.object({
+      path: z.string().describe("File path, absolute or relative to the working directory."),
+      offset: z.number().int().min(1).optional().describe("1-based line to start from."),
+      limit: z.number().int().positive().optional().describe("Max lines to read."),
+    }),
+    execute: async ({ path, offset, limit }) => {
+      const abs = resolveInCwd(ctx, path);
+      const blocked = await guardScope(ctx, abs, { kind: "read", title: "Read outside working directory" });
+      if (blocked) return blocked;
+      if (!existsSync(abs)) return `Error: file not found: ${displayPath(ctx, abs)}`;
+      if (statSync(abs).isDirectory()) return `Error: ${displayPath(ctx, abs)} is a directory.`;
+
+      const start = (offset ?? 1) - 1;
+      const max = limit ?? MAX_LINES;
+      const lines = readFileSync(abs, "utf8").split("\n");
+      const slice = lines.slice(start, start + max);
+      const body = slice
+        .map((line, i) => {
+          const n = start + i + 1;
+          const text = line.length > MAX_LINE_LEN ? line.slice(0, MAX_LINE_LEN) + "…" : line;
+          return `${String(n).padStart(6)}\t${text}`;
+        })
+        .join("\n");
+      const more = start + max < lines.length ? `\n… (${lines.length - (start + max)} more lines)` : "";
+      return body + more;
+    },
+  });
+}

package/src/tools/saveAttachment.ts

@@ -0,0 +1,53 @@
+import { writeFileSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { tool } from "ai";
+import { z } from "zod";
+import type { ToolContext } from "./context.ts";
+import { resolveInCwd, displayPath, isOutsideScope } from "./context.ts";
+import { PermissionDeniedError } from "../permissions/gate.ts";
+import { isProtectedPath } from "../permissions/protected.ts";
+
+export function saveAttachmentTool(ctx: ToolContext) {
+  return tool({
+    description:
+      "Save a user-attached file (image, PDF, audio, or video — shown in the prompt as a " +
+      '"[Image #n]" / "[PDF #n]" / etc. chip) to a path on disk. Use this to persist a pasted ' +
+      "or dragged-in attachment instead of trying to copy it from a temp or drop path, which is " +
+      "unreliable and may be an empty placeholder. `ref` is the number n from the chip.",
+    inputSchema: z.object({
+      ref: z
+        .number()
+        .int()
+        .describe("The attachment reference number n, taken from its [Kind #n] chip."),
+      path: z.string().describe("Destination file path to write the attachment to."),
+    }),
+    execute: async ({ ref, path }) => {
+      const store = ctx.attachments;
+      const entry = store?.get(ref);
+      if (!entry) {
+        const avail = store?.refs() ?? [];
+        return avail.length
+          ? `No attachment #${ref}. Available this session: ${avail.map((n) => `#${n}`).join(", ")}.`
+          : `No attachment #${ref}: nothing has been attached this session.`;
+      }
+      const abs = resolveInCwd(ctx, path);
+      const outside = isOutsideScope(ctx, abs);
+      const decision = await ctx.gate.request({
+        tool: "save_attachment",
+        kind: "write",
+        title: outside ? "Save attachment outside working directory" : "Save attachment",
+        detail: `[#${ref}] → ${outside ? abs : displayPath(ctx, abs)} (${entry.mediaType})`,
+        protected: isProtectedPath(abs),
+        outside,
+        path: abs,
+      });
+      if (decision === "deny") throw new PermissionDeniedError("save_attachment");
+
+      ctx.recordMutation?.(abs);
+      mkdirSync(dirname(abs), { recursive: true });
+      const bytes = readFileSync(entry.path);
+      writeFileSync(abs, bytes);
+      return `Saved attachment #${ref} to ${displayPath(ctx, abs)} (${bytes.length} bytes).`;
+    },
+  });
+}