@really-knows-ai/foundry 2.3.2 → 3.0.1

package/dist/.opencode/plugins/foundry-tools/memory-helpers.js

@@ -0,0 +1,104 @@
+// withStore — shared memory-tool helper. Resolves store, vocabulary,
+// permissions and embedder from plugin context.
+
+import { getOrOpenStore, getContext } from '../../../scripts/lib/memory/singleton.js';
+import { syncStore } from '../../../scripts/lib/memory/store.js';
+import { getCycleDefinition } from '../../../scripts/lib/config.js';
+import { resolvePermissions } from '../../../scripts/lib/memory/permissions.js';
+import { embed as memEmbed } from '../../../scripts/lib/memory/embeddings.js';
+import { makeMemoryIO, makeIO } from './helpers.js';
+import { readActiveStage } from '../../../scripts/lib/state.js';
+
+// Resolve the cycle id to scope this memory call to. Prefers an explicit
+// `context.cycle` (used by orchestrate-driven dispatch); otherwise falls back
+// to `.foundry/active-stage.json` so that tool calls made inside an active
+// stage with a minimal context (e.g. `{ worktree }`) still respect cycle
+// permissions. Returns `{ cycleId, fromActiveStage }` where `cycleId` may be
+// null when neither source provides one (out-of-stage call → unscoped).
+function resolveCycleId(context) {
+  if (context.cycle) return { cycleId: context.cycle, fromActiveStage: false };
+  try {
+    const syncIo = makeIO(context.worktree);
+    const active = readActiveStage(syncIo);
+    if (active && active.cycle) return { cycleId: active.cycle, fromActiveStage: true };
+  } catch {
+    // Treat unreadable/corrupt active-stage as no active stage. The stage
+    // guard checks elsewhere already cover the integrity case for stage
+    // tools; memory tools continue with unscoped behaviour so unrelated
+    // direct calls stay available.
+  }
+  return { cycleId: null, fromActiveStage: false };
+}
+
+// Build an embedder function from the embeddings config, or null when
+// embeddings are disabled.
+function createEmbedder(embeddingsCfg) {
+  if (!embeddingsCfg || !embeddingsCfg.enabled) return null;
+  return (inputs) => memEmbed({ config: embeddingsCfg, inputs });
+}
+
+// Build a write-capable embedder. Requires both a working embedder and
+// schema-declared vector dimensions (provisioned by init-memory).
+function createWriteEmbedder(embedder, schemaEmbeddings) {
+  if (!embedder) return null;
+  if (!schemaEmbeddings || !schemaEmbeddings.dimensions) return null;
+  return embedder;
+}
+
+// Resolve cycle-scoped permissions. When the cycle definition cannot be
+// loaded and the call originated from an active stage, the error is
+// rethrown; otherwise permissions fall back to null (full access).
+async function resolveCyclePermissions(cycleId, fromActiveStage, io, vocabulary) {
+  try {
+    const cycleDef = await getCycleDefinition('foundry', cycleId, io);
+    return resolvePermissions({ cycleFrontmatter: cycleDef.frontmatter, vocabulary });
+  } catch (err) {
+    if (fromActiveStage) {
+      throw new Error(
+        `active stage references cycle '${cycleId}' but its definition could not be loaded: ${err.message ?? err}`,
+        { cause: err },
+      );
+    }
+    return null;
+  }
+}
+
+// Extract embeddings config and schema from a possibly-null context.
+function getContextEmbeddings(ctx) {
+  return {
+    embeddingsCfg: ctx ? ctx.config?.embeddings : null,
+    schemaEmbeddings: ctx ? ctx.schema?.embeddings : null,
+  };
+}
+
+// Build a sync callback that reconciles the store when the call is
+// unscoped (no active cycle).
+function makeSyncCallback(cycleId, store, io) {
+  return async () => {
+    if (!cycleId) await syncStore({ store, io });
+  };
+}
+
+export async function withStore(context) {
+  const io = makeMemoryIO(context.worktree);
+  const store = await getOrOpenStore({ worktreeRoot: context.worktree, io });
+  const ctx = getContext(context.worktree);
+  const { embeddingsCfg, schemaEmbeddings } = getContextEmbeddings(ctx);
+  const embedder = createEmbedder(embeddingsCfg);
+  const writeEmbedder = createWriteEmbedder(embedder, schemaEmbeddings);
+  const { cycleId, fromActiveStage } = resolveCycleId(context);
+  let permissions = null;
+  if (cycleId) {
+    permissions = await resolveCyclePermissions(cycleId, fromActiveStage, io, ctx.vocabulary);
+  }
+  const syncIfOutOfCycle = makeSyncCallback(cycleId, store, io);
+  return {
+    io,
+    store,
+    vocabulary: ctx.vocabulary,
+    permissions,
+    embedder,
+    writeEmbedder,
+    syncIfOutOfCycle,
+  };
+}

package/dist/.opencode/plugins/foundry-tools/memory-tools.js

@@ -0,0 +1,286 @@
+import { putEntity, relate as memRelate, unrelate as memUnrelate } from '../../../scripts/lib/memory/writes.js';
+import { getEntity, listEntities, neighbours as memNeighbours } from '../../../scripts/lib/memory/reads.js';
+import { runQuery } from '../../../scripts/lib/memory/query.js';
+import { checkEntityRead, checkEntityWrite, checkEdgeRead, checkEdgeWrite } from '../../../scripts/lib/memory/permissions.js';
+import { search as memSearch } from '../../../scripts/lib/memory/search.js';
+import { withStore } from './memory-helpers.js';
+import { errorJson, makeIO, branchIoFactory, asyncIoFactory, flowBranchGuard } from './helpers.js';
+import { guarded, notFailedGuard } from '../../../scripts/lib/guards.js';
+
+const gateNotFailed = notFailedGuard(makeIO);
+const MAX_NEIGHBOUR_DEPTH = 5;
+const MAX_SEARCH_K = 100;
+const SPECIAL_CHARS = { '#': 'line', '"': 'string', "'": 'string' };
+function skipLineComment(datalog, start) {
+  let end = start;
+  while (end < datalog.length && datalog[end] !== '\n') {
+    end += 1;
+  }
+  if (end < datalog.length) {
+    return { nextIndex: end + 1, output: '\n' };
+  }
+  return { nextIndex: end, output: '' };
+}
+function skipBlockComment(datalog, start) {
+  let out = '';
+  let i = start;
+  while (i < datalog.length) {
+    if (datalog[i] === '*' && datalog[i + 1] === '/') {
+      return { nextIndex: i + 2, output: out + ' ' };
+    }
+    if (datalog[i] === '\n') {
+      out += '\n';
+    }
+    i += 1;
+  }
+  return { nextIndex: i, output: out };
+}
+function readStringLiteral(datalog, start, quote) {
+  let out = quote;
+  let i = start + 1;
+  let escaped = false;
+  while (i < datalog.length) {
+    const ch = datalog[i];
+    out += ch;
+    if (escaped) {
+      escaped = false;
+    } else if (ch === '\\') {
+      escaped = true;
+    } else if (ch === quote) {
+      return { nextIndex: i + 1, output: out };
+    }
+    i += 1;
+  }
+  return { nextIndex: i, output: out };
+}
+function classifyChar(ch, next) {
+  if (ch in SPECIAL_CHARS) return SPECIAL_CHARS[ch];
+  if (ch === '/') {
+    if (next === '*') return 'block';
+  }
+  return 'normal';
+}
+function stripQueryComments(datalog) {
+  let out = '';
+  let i = 0;
+  while (i < datalog.length) {
+    const kind = classifyChar(datalog[i], datalog[i + 1]);
+    if (kind === 'line') {
+      const result = skipLineComment(datalog, i + 1);
+      out += result.output;
+      i = result.nextIndex;
+    } else if (kind === 'block') {
+      const result = skipBlockComment(datalog, i + 2);
+      out += result.output;
+      i = result.nextIndex;
+    } else if (kind === 'string') {
+      const result = readStringLiteral(datalog, i, datalog[i]);
+      out += result.output;
+      i = result.nextIndex;
+    } else {
+      out += datalog[i];
+      i += 1;
+    }
+  }
+  return out;
+}
+function referencedStoredRelations(datalog) {
+  const matches = stripQueryComments(datalog).matchAll(/\*([a-z][a-z0-9_]*)\s*\{/g);
+  const names = new Set();
+  for (const match of matches) {
+    const name = match[1];
+    if (name.startsWith('ent_') || name.startsWith('edge_')) names.add(name);
+  }
+  return [...names];
+}
+function validateNeighbourDepth(depth) {
+  if ((depth ?? 1) > MAX_NEIGHBOUR_DEPTH) {
+    throw new Error(`depth must be ≤ ${MAX_NEIGHBOUR_DEPTH}`);
+  }
+}
+function filterEdgeTypes(edgeTypes, permissions) {
+  if (!permissions) return edgeTypes;
+  return edgeTypes.filter((e) => checkEdgeRead(permissions, e));
+}
+function filterNeighbourResult(result, permissions) {
+  if (!permissions) return result;
+  return {
+    entities: result.entities.filter((e) => checkEntityRead(permissions, e.type)),
+    edges: result.edges.filter((e) =>
+      checkEntityRead(permissions, e.from_type) && checkEntityRead(permissions, e.to_type),
+    ),
+  };
+}
+function validateSearchK(k) {
+  if ((k ?? 5) > MAX_SEARCH_K) {
+    throw new Error(`k must be ≤ ${MAX_SEARCH_K}`);
+  }
+}
+function resolveSearchTypes(typeFilter, permissions, vocabulary) {
+  const types = typeFilter && typeFilter.length > 0
+    ? typeFilter
+    : Object.keys(vocabulary.entities);
+  if (!permissions) return types;
+  return types.filter((t) => checkEntityRead(permissions, t));
+}
+function createWriteTool(tool, name, description, ops) {
+  return tool({
+    description,
+    args: ops.makeArgs(tool),
+    execute: guarded(name, [flowBranchGuard, gateNotFailed], async (args, context) => {
+      try {
+        const { store, vocabulary, permissions, writeEmbedder, syncIfOutOfCycle } = await withStore(context);
+        if (permissions && !ops.checkPerm(permissions, args)) {
+          return errorJson(new Error(ops.errMsg(context.cycle, args)));
+        }
+        await ops.doOp(store, args, vocabulary, { embedder: writeEmbedder });
+        await syncIfOutOfCycle();
+        return JSON.stringify({ ok: true });
+      } catch (err) { return errorJson(err); }
+    }, { branchIo: branchIoFactory, io: asyncIoFactory }),
+  });
+}
+function createPutTool(tool) {
+  return createWriteTool(tool, 'foundry_memory_put', 'Upsert an entity into flow memory. Value must be ≤4KB.', {
+    makeArgs: (t) => ({
+      type: t.schema.string().describe('Entity type (must be declared)'),
+      name: t.schema.string().describe('Entity name (unique within type)'),
+      value: t.schema.string().describe('Free-text intrinsic description (≤4KB)'),
+    }),
+    checkPerm: (p, a) => checkEntityWrite(p, a.type),
+    doOp: (s, a, v, o) => putEntity(s, a, v, o),
+    errMsg: (c, a) => `cycle '${c}' does not have write permission on entity type '${a.type}'`,
+  });
+}
+function createRelateTool(tool) {
+  return createWriteTool(tool, 'foundry_memory_relate', 'Upsert an edge between two entities.', {
+    makeArgs: (t) => ({
+      from_type: t.schema.string(), from_name: t.schema.string(),
+      edge_type: t.schema.string(), to_type: t.schema.string(), to_name: t.schema.string(),
+    }),
+    checkPerm: (p, a) => checkEdgeWrite(p, a.edge_type),
+    doOp: (s, a, v) => memRelate(s, a, v),
+    errMsg: (c, a) => `cycle '${c}' does not have write permission on edge type '${a.edge_type}'`,
+  });
+}
+function createUnrelateTool(tool) {
+  return createWriteTool(tool, 'foundry_memory_unrelate', 'Delete an edge between two entities.', {
+    makeArgs: (t) => ({
+      from_type: t.schema.string(), from_name: t.schema.string(),
+      edge_type: t.schema.string(), to_type: t.schema.string(), to_name: t.schema.string(),
+    }),
+    checkPerm: (p, a) => checkEdgeWrite(p, a.edge_type),
+    doOp: (s, a, v) => memUnrelate(s, a, v),
+    errMsg: (c, a) => `cycle '${c}' does not have write permission on edge type '${a.edge_type}'`,
+  });
+}
+function createGetTool(tool) {
+  return tool({
+    description: 'Fetch a single entity by composite key (type, name).',
+    args: { type: tool.schema.string(), name: tool.schema.string() },
+    async execute(args, context) {
+      try {
+        const { store, permissions } = await withStore(context);
+        if (permissions && !checkEntityRead(permissions, args.type)) {
+          return JSON.stringify(null);
+        }
+        const ent = await getEntity(store, args);
+        return JSON.stringify(ent);
+      } catch (err) { return errorJson(err); }
+    },
+  });
+}
+function createListTool(tool) {
+  return tool({
+    description: 'List all entities of a given type.',
+    args: { type: tool.schema.string() },
+    async execute(args, context) {
+      try {
+        const { store, permissions } = await withStore(context);
+        if (permissions && !checkEntityRead(permissions, args.type)) {
+          return JSON.stringify([]);
+        }
+        const out = await listEntities(store, args);
+        return JSON.stringify(out);
+      } catch (err) { return errorJson(err); }
+    },
+  });
+}
+function createNeighboursTool(tool) {
+  return tool({
+    description: 'Bounded graph traversal from an entity. Returns entities and edges within `depth` hops.',
+    args: {
+      type: tool.schema.string(), name: tool.schema.string(),
+      depth: tool.schema.number().optional().describe('Default 1'),
+      edge_types: tool.schema.array(tool.schema.string()).optional().describe('Restrict traversal to named edges'),
+    },
+    async execute(args, context) {
+      try {
+        validateNeighbourDepth(args.depth);
+        const { store, vocabulary, permissions } = await withStore(context);
+        if (permissions && !checkEntityRead(permissions, args.type)) {
+          return JSON.stringify({ entities: [], edges: [] });
+        }
+        const edgeTypesInput = args.edge_types ?? Object.keys(vocabulary.edges);
+        const filteredEdgeTypes = filterEdgeTypes(edgeTypesInput, permissions);
+        const result = await memNeighbours(store, { ...args, edge_types: filteredEdgeTypes }, vocabulary);
+        return JSON.stringify(filterNeighbourResult(result, permissions));
+      } catch (err) { return errorJson(err); }
+    },
+  });
+}
+function createQueryTool(tool) {
+  return tool({
+    description: 'Arbitrary read-only Cozo Datalog query. Rejects :put, :rm, :create, ::remove. Returns {headers, rows}.',
+    args: { datalog: tool.schema.string().describe('Cozo Datalog query (read-only)') },
+    async execute(args, context) {
+      try {
+        const { store, vocabulary, permissions } = await withStore(context);
+        if (permissions) {
+          const allowed = new Set([
+            ...[...permissions.readTypes].map((t) => `ent_${t}`),
+            ...Object.keys(vocabulary.edges).filter((e) => checkEdgeRead(permissions, e)).map((e) => `edge_${e}`),
+          ]);
+          const referenced = referencedStoredRelations(args.datalog);
+          for (const r of referenced) {
+            if (!allowed.has(r)) {
+              return errorJson(new Error(`cycle '${context.cycle}' cannot query relation '${r}' (not in read permissions)`));
+            }
+          }
+        }
+        const out = await runQuery(store, args.datalog);
+        return JSON.stringify(out);
+      } catch (err) { return errorJson(err); }
+    },
+  });
+}
+function createSearchTool(tool) {
+  return tool({
+    description: 'Semantic nearest-neighbour search over entity values. Requires embeddings enabled. Performance: fetches k results from each entity type then merges to global top-k (N×k amplification). Use type_filter to limit search to specific types when possible.',
+    args: {
+      query_text: tool.schema.string(),
+      k: tool.schema.number().optional().describe('Default 5'),
+      type_filter: tool.schema.array(tool.schema.string()).optional(),
+    },
+    async execute(args, context) {
+      try {
+        validateSearchK(args.k);
+        const { store, permissions, embedder, vocabulary } = await withStore(context);
+        if (!embedder) return errorJson(new Error('embeddings are disabled in memory config'));
+        const types = resolveSearchTypes(args.type_filter, permissions, vocabulary);
+        const out = await memSearch({
+          store, query_text: args.query_text, k: args.k ?? 5, type_filter: types, embedder,
+        });
+        return JSON.stringify(out);
+      } catch (err) { return errorJson(err); }
+    },
+  });
+}
+export function createMemoryTools({ tool }) {
+  return {
+    foundry_memory_put: createPutTool(tool), foundry_memory_relate: createRelateTool(tool),
+    foundry_memory_unrelate: createUnrelateTool(tool), foundry_memory_get: createGetTool(tool),
+    foundry_memory_list: createListTool(tool), foundry_memory_neighbours: createNeighboursTool(tool),
+    foundry_memory_query: createQueryTool(tool), foundry_memory_search: createSearchTool(tool),
+  };
+}

package/dist/.opencode/plugins/foundry-tools/orchestrate-tool.js

@@ -0,0 +1,159 @@
+import path from 'path';
+import { execFileSync } from 'child_process';
+import { randomUUID } from 'node:crypto';
+import { readFileSync, writeFileSync } from 'fs';
+import { signToken } from '../../../scripts/lib/token.js';
+import { readOrCreateSecret } from '../../../scripts/lib/secret.js';
+import { getCycleDefinition, getArtefactType } from '../../../scripts/lib/config.js';
+import { addArtefactRow } from '../../../scripts/lib/artefacts.js';
+import { stageBaseOf } from '../../../scripts/lib/stage-guard.js';
+import { finalizeStage } from '../../../scripts/lib/finalize.js';
+import { commitWithPolicy } from '../../../scripts/lib/git-bridge.js';
+import { makeIO, makeExec, buildCyclePromptExtras } from './helpers.js';
+import { requireNotFailed } from '../../../scripts/lib/failed-flow.js';
+import { requireOnFlowBranch } from '../../../scripts/lib/branch-guard.js';
+
+function createMint(secret, pending) {
+  return ({ route, cycle, exp }) => {
+    const nonce = randomUUID();
+    const payload = { route, cycle, nonce, exp };
+    pending.add(nonce, payload);
+    return signToken(payload, secret);
+  };
+}
+
+function createGitBridge(cwd) {
+  const runGit = (argv) => execFileSync('git', argv, { cwd, encoding: 'utf8' });
+  return {
+    commit: (msg, opts = {}) => {
+      const sha = commitWithPolicy({
+        message: msg,
+        allowedPatterns: opts.allowedPatterns ?? [],
+        execFile: runGit,
+      });
+      return sha;
+    },
+    status: () => {
+      const out = execFileSync('git', ['status', '--porcelain'], { cwd, encoding: 'utf8' }).trim();
+      return { clean: out === '', dirty: out.split('\n').filter(Boolean) };
+    },
+  };
+}
+
+function makeRegisterArtefact(cwd, cycleId) {
+  const workPath = path.join(cwd, 'WORK.md');
+  return ({ file, type, status }) => {
+    const text = readFileSync(workPath, 'utf-8');
+    const updated = addArtefactRow(text, { file, type, cycle: cycleId, status });
+    writeFileSync(workPath, updated, 'utf-8');
+  };
+}
+
+async function createFinalize(cwd, io) {
+  return async ({ cycleId, stage, baseSha }) => {
+    let cycleDoc;
+    try {
+      cycleDoc = await getCycleDefinition('foundry', cycleId, io);
+    } catch (e) {
+      return { ok: false, error: e.message };
+    }
+    const outputType = cycleDoc.frontmatter['output-type'];
+    const cycleDef = { outputArtefactType: outputType };
+    const artefactTypes = {};
+    if (outputType) {
+      try {
+        const artDoc = await getArtefactType('foundry', outputType, io);
+        artefactTypes[outputType] = { filePatterns: artDoc.frontmatter['file-patterns'] || [] };
+      } catch (e) {
+        return {
+          ok: false,
+          error: `missing_artefact_type: ${outputType} (${e.message})`,
+        };
+      }
+    }
+    const result = finalizeStage({
+      cwd,
+      baseSha,
+      stageBase: stageBaseOf(stage),
+      cycleDef,
+      artefactTypes,
+      io,
+      registerArtefact: makeRegisterArtefact(cwd, cycleId),
+    });
+    return result;
+  };
+}
+
+function getCycleId(result) {
+  if (result.cycle) return result.cycle;
+  if (typeof result.stage !== 'string') return null;
+  return result.stage.split(':')[1];
+}
+
+async function injectDispatchPromptExtras(result, cwd) {
+  if (!result) return;
+  if (result.action !== 'dispatch') return;
+  if (typeof result.prompt !== 'string') return;
+  const cycleId = getCycleId(result);
+  const extras = await buildCyclePromptExtras({ worktree: cwd, cycleId, stage: result.stage });
+  if (!extras) return;
+  result.prompt = `${result.prompt}\n\n${extras}`;
+}
+
+export function createOrchestrateTool({ tool, pending }) {
+  return {
+    foundry_orchestrate: tool({
+      description: 'Run the next step of the current cycle. Call with no args on first invocation; call with lastResult={ok,error?} after a dispatch/human_appraise completes. Returns {action, ...} describing what the caller should do next.',
+      args: {
+        lastResult: tool.schema.object({
+          ok: tool.schema.boolean(),
+          error: tool.schema.string().optional(),
+        }).optional(),
+        cycleDef: tool.schema.string().optional().describe('Test-mode cycle definition override (path to cycle file)'),
+      },
+
+      async execute(args, context) {
+        const { runOrchestrate } = await import('../../scripts/orchestrate.js');
+        const io = makeIO(context.worktree);
+        const cwd = context.worktree;
+        const secret = readOrCreateSecret(context.worktree);
+
+        try {
+          // Branch guard. Kept inline because the orchestrate tool surfaces all errors through its violation
+          // envelope (see comment on the failed-flow guard below). A
+          // wrong-branch refusal is a more fundamental error than failed
+          // flow, so it runs first.
+          const branchGuard = requireOnFlowBranch({ exec: makeExec(cwd) });
+          if (!branchGuard.ok) return JSON.stringify({ error: `foundry_orchestrate: ${branchGuard.error}` });
+
+          // Failed-flow guard. Kept inline to preserve the violation envelope.
+          // because requireNotFailed parses WORK.md frontmatter, which throws
+          // on malformed YAML. The surrounding try/catch (line 30) converts
+          // that throw into a violation-shaped envelope per the contract
+          // exercised by tests/plugin/orchestrate-wrapper.test.js. A guarded()
+          // wrapper would let the throw escape to a plain { error } envelope
+          // and break that contract. orchestrate-tool is the one Phase 1.5
+          // exception to the inline-gate refactor.
+          const failedGuard = requireNotFailed(io);
+          if (!failedGuard.ok) return JSON.stringify({ error: `foundry_orchestrate: ${failedGuard.error}` });
+
+          const mint = createMint(secret, pending);
+          const git = createGitBridge(cwd);
+          const finalize = await createFinalize(cwd, io);
+
+          const result = await runOrchestrate({
+            cwd, cycleDef: args.cycleDef, git, mint, finalize,
+            now: () => Date.now(),
+            lastResult: args.lastResult ?? null,
+          }, io);
+
+          await injectDispatchPromptExtras(result, cwd);
+
+          return JSON.stringify(result);
+        } catch (e) {
+          return JSON.stringify({ action: 'violation', details: `orchestrate threw: ${e.message}`, recoverable: false, affected_files: [] });
+        }
+      },
+    }),
+  };
+}

package/dist/.opencode/plugins/foundry-tools/snapshot-tools.js

@@ -0,0 +1,104 @@
+// Meta tools for inspecting and managing forensic snapshots produced by
+// dry-run finishes. These tools are branch-agnostic per spec §11.6 — they
+// carry only the foundational guards (gitRepo, foundryRoot) so authors
+// can list/show/delete/prune snapshots from any branch including main.
+
+import {
+  listSnapshots,
+  showSnapshot,
+  deleteSnapshot,
+  pruneSnapshots,
+} from '../../../scripts/lib/snapshot/inspect.js';
+import { requireGitRepo, requireFoundryRoot } from '../../../scripts/lib/foundational-guards.js';
+import { guarded } from '../../../scripts/lib/guards.js';
+import { makeIO, makeAsyncIO, errorJson, branchIoFactory, asyncIoFactory } from './helpers.js';
+
+// --- guard helpers ---------------------------------------------------------
+
+function gitRepoGuard(_args, context) {
+  return requireGitRepo(makeIO(context.worktree));
+}
+
+function foundryRootGuard(_args, context) {
+  return requireFoundryRoot(makeIO(context.worktree));
+}
+
+const GUARDS = [gitRepoGuard, foundryRootGuard];
+const TRACE_OPTS = { branchIo: branchIoFactory, io: asyncIoFactory };
+
+// --- execute handlers -------------------------------------------------------
+
+function makeListExecute() {
+  return guarded('foundry_snapshot_list', GUARDS, async (_args, context) => {
+    try {
+      return JSON.stringify(await listSnapshots({ io: makeAsyncIO(context.worktree) }));
+    } catch (err) {
+      return errorJson(err);
+    }
+  }, TRACE_OPTS);
+}
+
+function makeShowExecute() {
+  return guarded('foundry_snapshot_show', GUARDS, async (args, context) => {
+    try {
+      return JSON.stringify(await showSnapshot({ runId: args.runId, io: makeAsyncIO(context.worktree) }));
+    } catch (err) {
+      return errorJson(err);
+    }
+  }, TRACE_OPTS);
+}
+
+function makeDeleteExecute() {
+  return guarded('foundry_snapshot_delete', GUARDS, async (args, context) => {
+    try {
+      return JSON.stringify(await deleteSnapshot({
+        runId: args.runId, io: makeAsyncIO(context.worktree), confirm: args.confirm === true,
+      }));
+    } catch (err) {
+      return errorJson(err);
+    }
+  }, TRACE_OPTS);
+}
+
+function makePruneExecute() {
+  return guarded('foundry_snapshot_prune', GUARDS, async (args, context) => {
+    if (!Number.isInteger(args.olderThanDays) || args.olderThanDays <= 0) {
+      return JSON.stringify({ ok: false, error: 'olderThanDays must be a positive integer' });
+    }
+    try {
+      return JSON.stringify(await pruneSnapshots({
+        olderThanDays: args.olderThanDays, io: makeAsyncIO(context.worktree),
+        confirm: args.confirm === true, now: Date.now(),
+      }));
+    } catch (err) {
+      return errorJson(err);
+    }
+  }, TRACE_OPTS);
+}
+
+// --- tool factory ----------------------------------------------------------
+
+export function createSnapshotTools({ tool }) {
+  return {
+    foundry_snapshot_list: tool({
+      description: 'List forensic snapshots from past dry-run finishes.',
+      args: {},
+      execute: makeListExecute(),
+    }),
+    foundry_snapshot_show: tool({
+      description: 'Show a structured summary of one forensic snapshot.',
+      args: { runId: tool.schema.string() },
+      execute: makeShowExecute(),
+    }),
+    foundry_snapshot_delete: tool({
+      description: 'Delete a forensic snapshot directory. Requires {confirm: true} to actually remove.',
+      args: { runId: tool.schema.string(), confirm: tool.schema.boolean().optional() },
+      execute: makeDeleteExecute(),
+    }),
+    foundry_snapshot_prune: tool({
+      description: 'Prune forensic snapshots older than `olderThanDays`. Requires {confirm: true} to actually remove.',
+      args: { olderThanDays: tool.schema.number(), confirm: tool.schema.boolean().optional() },
+      execute: makePruneExecute(),
+    }),
+  };
+}