@dynamicagents/plugins 0.12.0 → 0.14.0

package/dist/computer/index.js

@@ -1,189 +1,42 @@
-var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
-    if (value !== null && value !== void 0) {
-        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
-        var dispose, inner;
-        if (async) {
-            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
-            dispose = value[Symbol.asyncDispose];
-        }
-        if (dispose === void 0) {
-            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
-            dispose = value[Symbol.dispose];
-            if (async) inner = dispose;
-        }
-        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
-        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
-        env.stack.push({ value: value, dispose: dispose, async: async });
-    }
-    else if (async) {
-        env.stack.push({ async: true });
-    }
-    return value;
-};
-var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
-    return function (env) {
-        function fail(e) {
-            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
-            env.hasError = true;
-        }
-        var r, s = 0;
-        function next() {
-            while (r = env.stack.pop()) {
-                try {
-                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
-                    if (r.dispose) {
-                        var result = r.dispose.call(r.value);
-                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
-                    }
-                    else s |= 1;
-                }
-                catch (e) {
-                    fail(e);
-                }
-            }
-            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
-            if (env.hasError) throw env.error;
-        }
-        return next();
-    };
-})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
-    var e = new Error(message);
-    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
-});
-import { definePlugin } from "@dynamicagents/core";
-import { getWorkspace } from "@cloudflare/computer";
-import { cancelledNote } from "./render.js";
-import { computerContext, DEFAULT_CWD, DEFAULT_TIMEOUT_MS } from "./context.js";
-import { withShell } from "./shell.js";
+import { definePlugin, PluginSetupError } from "@dynamicagents/core";
+import { openWorkspace, openWorkspaceFs } from "../workspace/open.js";
+import { workspaceRoute } from "./proxy.js";
+import { computerContext } from "./context.js";
 import { execTools } from "./tools-exec.js";
 import { fileTools } from "./tools-file.js";
-import { findTools } from "./tools-find.js";
+import { grepTools } from "./tools-grep.js";
 /**
- * `@dynamicagents/plugins/computer` — a Linux container whose filesystem outlives it.
+ * `@dynamicagents/plugins/computer` — an agent's tools over a container
+ * workspace: `bash`, `grep` and `edit`, and `computerWorkspace`, the agent's own
+ * `this.workspace`, which Think's `read`, `write`, `delete`, `find` and `list`
+ * go through.
  *
- * The filesystem **is** a Durable Object's SQLite, mounted into the container
- * over FUSE by `computerd`. Commands see a normal `/workspace`; the Worker reads
- * the same tree over RPC; and when the container is replaced the tree is pushed
- * back into the new one.
+ * The workspace itself — the Durable Object, its container, its git, its
+ * install — is `@dynamicagents/plugins/workspace`. This plugin reaches it only
+ * through that subpath's client modules, never its object, so an agent that
+ * holds the tools carries no container backend and no isomorphic-git.
  *
- * Not to be confused with `@dynamicagents/plugins/workspace`, which is a virtual
- * filesystem with no processes and nothing to run. Install exactly one
- * filesystem plugin — an agent holding two gives the model no way to know which
- * one a path refers to.
+ * The agent's own workspace has to be this one — `computerWorkspace` — or
+ * Think's `read` and `write` would work on a different tree from `bash`. The
+ * plugin refuses to start otherwise; see `./proxy.ts`.
  *
  * ## The dependency tree is not in the workspace
  *
  * The one thing to internalise before reading further. A package root's
  * `node_modules` is a bind mount of the container's disk, so installs never
- * sync, and a new container reinstalls — see `./host/container-deps.ts`. The file tools read
- * the workspace, so they refuse it; `sb_exec` reaches it. `paths.ts` owns what a
- * path may be and what walks drop.
- *
- * Requires the Workers **Paid** plan (containers) and a Durable Object binding
- * whose class owns the workspace — see the README for the wrangler block.
- */
-/**
- * How a repository installs its dependencies — the mechanical half.
- *
- * Re-exported from the plugin's one entry point rather than given a subpath of
- * its own: `verify:exports` treats each subpath as an isolated realm, and a host
- * needs the resolver and the tools together anyway.
+ * sync, and a new container reinstalls — see `/workspace`'s
+ * `container-deps.ts`. The file tools read the workspace, so they refuse it;
+ * `bash` reaches it. `paths.ts` owns what a path may be and what walks drop.
  */
-export { DEFAULT_INSTALL_PLAN, installFingerprint, resolveInstallCommand } from "./install.js";
 /**
- * The helpers this plugin's own tests and hosts reach for, re-exported from the
- * one entry point.
- *
- * They live in sibling modules — `paths.ts`, `render.ts`, `gate.ts` — because
- * this file was 1,900 lines and the seams were obvious. The subpath is the unit a
- * consumer imports, so what it exports must not move when the files behind it do:
- * `verify:exports` treats `./computer` as one realm, and everything below stays
- * inside `dist/computer/`.
+ * The helpers this plugin's own tests reach for, re-exported from the one
+ * entry point. `verify:exports` treats `./computer` as one realm, so what it
+ * exports must not move when the files behind it do.
  */
-export { isGitInternal, WALK_SKIPS } from "./paths.js";
-export { cancelledNote, packBlocks, renderGrepMatches, renderResult, syncPendingNote, truncateOutput } from "./render.js";
+export { isGitInternal, SESSION_STATE_DIR, WALK_SKIPS } from "./paths.js";
+export { packBlocks, renderGrepMatches, renderResult, syncPendingNote } from "./render.js";
 export { execGate, needsDependencies, writeGate } from "./gate.js";
-/**
- * The workspace-advisory vocabulary, which a host needs all of: the type to
- * return over RPC, `deriveAdvisories` to build it from what it already knows,
- * and `sessionAdvisory` for a host driving a whole session rather than one
- * command. `shapeOf` and `renderAdvisory` are exported for the specs that hold
- * their exhaustiveness — a host has no reason to call either, since calling them
- * would mean writing policy or wording that has one home already.
- */
-export { deriveAdvisories, renderAdvisory, sessionAdvisory, shapeOf } from "./advisory.js";
-// A host implementing `InstallProbe` needs exactly this, and hand-rolling it
-// loses the fast path: across a Durable Object boundary `fs` is a stub carrying
-// `exists`, which a `stat`-only probe never asks for.
-export { pathExists } from "./read.js";
-/**
- * This plugin's tool-family name, as a recipe's `toolFamilies` lists it.
- *
- * `"sandbox"` names the capability — a shell and a filesystem — rather than the
- * package providing it, and it appears in recipes, souls and allowlists that
- * have nothing to do with either. Renaming it would have `validateRecipe`
- * silently drop the family from every recipe that still says `sandbox`: a
- * subagent with no tools and no error explaining why.
- */
-export const SANDBOX_FAMILY = "sandbox";
-/**
- * Where a parent puts the workspace name so its subagents reach the same one.
- *
- * A subagent cannot compute this itself. The name is derived from the verified
- * caller and the repository, and core deliberately gives a subagent execution a
- * `callerKey` thunk that **throws** — "a subagent execution has no caller
- * identity". So a facet running a `code` subtask would fail at its first tool
- * call, with the parent's checkout sitting in a workspace it cannot name.
- *
- * `resolveRuntime` runs on the parent, where the name resolves, and its return
- * value reaches every tool family as `ToolFamilyContext.runtime`. That is the
- * channel core built for exactly this, and it is emphatically *not* `params`,
- * which are declared in the subtask type's schema and rendered to the delegating
- * model — a workspace name there would be model-authored, and a model naming
- * another caller's workspace would get that caller's files.
- */
-export const WORKSPACE_RUNTIME_KEY = "workspaceName";
-/**
- * Read a parent-resolved workspace name off a subtask's runtime state.
- *
- * Returns `undefined` rather than throwing on anything unexpected: the main
- * agent's tools have no runtime at all, and falling back to the configured thunk
- * is right there.
- */
-export function workspaceNameFromRuntime(runtime) {
-    const value = runtime?.[WORKSPACE_RUNTIME_KEY];
-    return typeof value === "string" && value.length > 0 ? value : undefined;
-}
-export { withShell, withShellTranscript } from "./shell.js";
-/**
- * Open the workspace behind a Durable Object stub.
- *
- * The cast is unavoidable, and narrow enough to be worth isolating here rather
- * than repeating. `getWorkspace` wants a handle whose `__getWorkspaceStub()`
- * resolves to a `WorkspaceStub` — the concrete class, private fields and all.
- * Across a Durable Object boundary Workers RPC hands back a structural
- * `Stub<WorkspaceStub>`, which forwards every method faithfully but carries none
- * of the class's private brand: runtime-compatible, type-incompatible. This is
- * the only place in the plugin that gap is crossed.
- */
-export function openWorkspace(host) {
-    return getWorkspace(host);
-}
-/**
- * The same workspace, opened for filesystem work alone.
- *
- * `getWorkspace` calls exactly one method on what it is handed, so the host is
- * wrapped in an object answering it from the other side of the seam — see
- * {@link WorkspaceHost.__getWorkspaceFsStub}. Everything past that is identical.
- *
- * **Only the file tools take this.** `sb_exec` and {@link computerExec} need the
- * container started and its CA installed, so they open it the other way.
- */
-export function openWorkspaceFs(host) {
-    return getWorkspace({
-        __getWorkspaceStub: () => host.__getWorkspaceFsStub()
-    });
-}
+export { computerWorkspace, isComputerWorkspace } from "./proxy.js";
 /**
  * @param workspace Opens the workspace for a command: container started, CA
  *   installed.
@@ -198,164 +51,58 @@ export function buildComputerTools(workspace, config, advisories, fsWorkspace =
     return {
         ...execTools(ctx),
         ...fileTools(ctx),
-        ...findTools(ctx)
+        ...grepTools(ctx)
     };
 }
+const CONTEXT = [
+    "You have a Linux container with a shell, a package manager and network access:",
+    "- `bash` runs any shell command — builds, tests, installs, git.",
+    "- `read` / `write` / `edit` / `delete` work on files; `edit` replaces an exact unique string and is the right tool for a small change.",
+    "- `grep` searches file contents; `list` lists a directory; `find` finds files by glob.",
+    // The reason to prefer them is the one thing the model cannot infer from a
+    // tool description: these read the durable workspace directly, so they are
+    // the only tools that still answer while the container is unavailable.
+    "Search with `grep` and `find` rather than running them through `bash`. They read the workspace directly, so they keep working while the container is restarting or an install is still running, and they come back with line numbers and a bounded result instead of a wall of text.",
+    "Command output is truncated from the middle when large, so run targeted commands and read specific files rather than printing everything.",
+    // Both halves of this matter and they pull in opposite directions, which
+    // is why they are stated together rather than left for the model to work
+    // out from a confusing result.
+    "The checkout is durable: it survives between tasks and is still there after the container restarts, so it may already contain work from an earlier task — check before assuming it is empty.",
+    "`node_modules` is not durable: it lives on the container's disk, so a new container reinstalls it, and the file tools cannot see inside it — use `bash` there. It is a mount point, so `rm -rf node_modules` fails; `npm ci` clears it itself.",
+    // Stated up front rather than left to a refusal, so the model does not spend
+    // a turn discovering it. The destination matters as much as the rule: a
+    // prohibition with nowhere to go gets worked around.
+    "`.git` is off limits to these tools, and searches and recursive listings skip it. It is git's internal state — reading it tells you less than the repository tools do, and writing it corrupts the checkout. Repository work goes through the repo tools (`repo_status`, `repo_diff`, `repo_commit`, `repo_push`); if a task needs git state you cannot get that way, say so in your result rather than reaching into `.git` yourself."
+].join("\n");
 /**
- * An `exec` bound to this workspace, for plugins that need a shell but should
- * not own a container.
- *
- * `@dynamicagents/plugins/repo` is the reason this exists: it needs `git` on a real
- * shell, but depending on this module would weld the two together and stop a
- * host from pointing it at its own container. Structurally typed for the same
- * reason — the two plugins compose without either importing the other.
- *
- * ## {@link ComputerConfig.env} is deliberately **not** merged here
- *
- * {@link buildComputerTools} merges it into every command; this does not.
- *
- * What this hands out is a raw shell to *another plugin*, whose commands this
- * module neither writes nor sees. `/repo` runs its unauthenticated git through
- * it and pins the environment those need — `GIT_TERMINAL_PROMPT=0` plus the
- * model-authored values it passes as variables. A host environment merged
- * underneath lets through every key it does *not* pin: `http_proxy`,
- * `GIT_PROXY_COMMAND`, `GIT_SSL_CAINFO`, `GIT_CONFIG_GLOBAL`, `GIT_EXEC_PATH` —
- * the last two redirect the config git reads and relocate its helper binaries.
- *
- * No token is at stake, since the credentialed operations do not run here at
- * all. The point is that changing what git does inside another plugin's commands
- * should not be something a container plugin's config field does by accident,
- * from a host that only meant to set a registry. A host that wants it composes
- * it where the merge is visible:
- *
- * ```ts
- * exec: (command, options) =>
- *   computerExec(config)(command, {
- *     ...options,
- *     env: { ...mine, ...options?.env }
- *   });
- * ```
+ * The container plugin. Its tools reach the workspace through the agent's own
+ * `computerWorkspace` — the one Think's `read` and `write` use — so the two can
+ * never resolve different ones. `config` answers everything else: the shell,
+ * the limits, the environment.
  */
-export function computerExec(config) {
-    return async (command, options) => {
-        const env_1 = { stack: [], error: void 0, hasError: false };
-        try {
-            // The caller forwards its execution's runtime state opaquely; only this side
-            // knows the key it might carry. That is what lets `/repo` reach a subagent's
-            // shared workspace without importing anything from here.
-            const name = workspaceNameFromRuntime(options?.runtime) ?? config.workspaceName();
-            const ws = __addDisposableResource(env_1, await openWorkspace(config.binding.get(config.binding.idFromName(name))), false);
-            const env = options?.env
-                ? Object.fromEntries(Object.entries(options.env).filter((entry) => entry[1] !== undefined))
-                : undefined;
-            // Named rather than inlined, because the note below has to state it: a
-            // ceiling the model cannot see is one it cannot work within.
-            const timeoutMs = options?.timeout ?? config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-            // `withShell`, never `withShellTranscript`: the caller reads this result in
-            // code. `/repo` compares `stdout` against a URL, tests it for emptiness to
-            // decide a tree is clean, and reads a sha out of it to push — all of which
-            // need `stdout` to carry the answer alone, with git's diagnostics on the
-            // channel git put them on.
-            const handle = __addDisposableResource(env_1, await ws.runtime.exec(withShell(command, config.shell), {
-                cwd: options?.cwd ?? config.cwd ?? DEFAULT_CWD,
-                encoding: "utf8",
-                timeoutMs,
-                ...(env ? { env } : {})
-            }), false);
-            const result = await handle.result();
-            const killed = cancelledNote(result.status, result.exitCode, timeoutMs);
-            return {
-                // `/repo` branches on `success`, which this runtime does not report — it
-                // has `status` and `exitCode`. Derived from the exit code rather than the
-                // status, because a command that runs and fails is `completed` here.
-                success: result.exitCode === 0,
-                stdout: result.stdout,
-                // Appended rather than substituted: a command killed at the ceiling may
-                // well have written plenty first, and that output is the more useful half.
-                // This is the only field the note can travel on — `stdout` is a data
-                // channel the caller parses, and the four fields are the whole contract.
-                stderr: killed
-                    ? [result.stderr, killed].filter(Boolean).join("\n")
-                    : result.stderr,
-                exitCode: result.exitCode
-            };
-        }
-        catch (e_1) {
-            env_1.error = e_1;
-            env_1.hasError = true;
-        }
-        finally {
-            __disposeResources(env_1);
-        }
-    };
-}
 export function computer(config) {
-    // Resolved per call, not memoized: `workspaceName` is a thunk precisely
-    // because the name is not knowable at construction, and a stale stub would
-    // silently route a second caller's commands into the first caller's files.
-    const nameOf = (runtime) => workspaceNameFromRuntime(runtime) ?? config.workspaceName();
-    const host = (runtime) => config.binding.get(config.binding.idFromName(nameOf(runtime)));
-    const tools = (runtime) => buildComputerTools(() => openWorkspace(host(runtime)), config, 
-    // No try/catch here: `buildComputerTools` fails the gate open itself, so
-    // wrapping again would only make it look like the guarantee lives in two
-    // places.
-    () => host(runtime).advisories(), () => openWorkspaceFs(host(runtime)), () => nameOf(runtime));
     return definePlugin({
-        key: "computer",
-        mainAgentTools: () => tools(),
-        // `ctx.runtime` is what makes a delegated subtask land in the workspace its
-        // parent prepared — see {@link WORKSPACE_RUNTIME_KEY}. Without it the
-        // fallback thunk runs, and on a subagent that throws.
-        toolFamilies: {
-            [SANDBOX_FAMILY]: (ctx) => ({ tools: tools(ctx.runtime) })
+        name: "computer",
+        tools: (ctx) => {
+            // Here, not in `execute`: the start check builds every plugin's tools,
+            // so a missing workspace fails the start rather than a turn.
+            const route = workspaceRoute(ctx.workspace());
+            if (!route)
+                throw new PluginSetupError(`plugin "computer" runs \`bash\` in a container, but ${ctx.agentName}'s ` +
+                    "workspace is not that container's, so Think's `read` and `write` " +
+                    "would work on a different tree. Set it on the agent class: " +
+                    "`override workspace = computerWorkspace(config, () => this.pluginContext().runtime())`.");
+            // Resolved per call, not memoized: the name belongs to the turn — a
+            // sub-agent's comes from `runtime()`, see `/workspace`'s `WORKSPACE_RUNTIME_KEY` —
+            // and a stale stub would silently route a second caller's commands into
+            // the first caller's files.
+            const host = () => route.host(route.name());
+            return buildComputerTools(() => openWorkspace(host()), config, 
+            // No try/catch here: `buildComputerTools` fails the gate open itself,
+            // so wrapping again would only make it look like the guarantee lives in
+            // two places.
+            () => host().advisories(), () => openWorkspaceFs(host()), route.name);
         },
-        capability: [
-            "You have a Linux container with a shell, a package manager and network access:",
-            "- `sb_exec` runs any shell command — builds, tests, installs, git.",
-            "- `sb_read` / `sb_write` / `sb_edit` work on files; `sb_edit` replaces an exact unique string and is the right tool for a small change.",
-            "- `sb_grep` searches file contents; `sb_ls` lists a directory, or finds files by glob with `pattern`; `sb_exists` checks a path.",
-            // The reason to prefer them is the one thing the model cannot infer from a
-            // tool description: these read the durable workspace directly, so they are
-            // the only tools that still answer while the container is unavailable.
-            "Search with `sb_grep` and `sb_ls` rather than running `grep` or `find` through `sb_exec`. They read the workspace directly, so they keep working while the container is restarting or an install is still running, and they come back with line numbers and a bounded result instead of a wall of text.",
-            "Command output is truncated from the middle when large, so run targeted commands and read specific files rather than printing everything.",
-            // Both halves of this matter and they pull in opposite directions, which
-            // is why they are stated together rather than left for the model to work
-            // out from a confusing result.
-            "The checkout is durable: it survives between tasks and is still there after the container restarts, so it may already contain work from an earlier task — check before assuming it is empty.",
-            "`node_modules` is not durable: it lives on the container's disk, so a new container reinstalls it, and the file tools cannot see inside it — use `sb_exec` there. It is a mount point, so `rm -rf node_modules` fails; `npm ci` clears it itself.",
-            // Stated up front rather than left to a refusal, so the model does not spend
-            // a turn discovering it. The destination matters as much as the rule: a
-            // prohibition with nowhere to go gets worked around.
-            "`.git` is off limits to these tools, and searches and recursive listings skip it. It is git's internal state — reading it tells you less than the repository tools do, and writing it corrupts the checkout. Repository work goes through the repo tools (`repo_status`, `repo_diff`, `repo_commit`, `repo_push`), which the main agent holds; if a task needs git state beyond what you can see in the working tree, say so in your result rather than reaching into `.git` yourself."
-        ].join("\n")
+        context: [{ provider: { get: async () => CONTEXT } }]
     });
 }
-// --- the host half ----------------------------------------------------------
-/**
- * The Durable Object everything above talks to.
- *
- * `./host/` is a directory rather than a subpath of its own, and that is the
- * point: one capability is one import path, so a consumer cannot install the
- * tools and miss the object they address. The two halves have opposite bundle
- * costs — an agent that only calls `sb_exec` carries no container backend and no
- * isomorphic-git — and `"sideEffects": false` is what keeps that true, since
- * nothing here references the host unless the consumer does.
- *
- * The dependency runs one way for a mechanical reason: `./host/` imports the
- * leaf modules beside this file, never this barrel, because this barrel
- * re-exports `./host/` and a cycle through a module that builds a class at
- * import time is a base that evaluates `undefined`.
- */
-export { WorkspaceObjectBase, WORKSPACE_DIR, workspaceName } from "./host/workspace.js";
-// The dependency install, exported because a host that wants to report on one —
-// or a spec that drives it — needs the type, not because anything but
-// `./host/workspace.ts` constructs it.
-export { InstallJob } from "./host/install-job.js";
-// The pull the library owns no alarm for. Its constants are exported because a
-// host deferring to a drain has to back off at the same rate this does.
-export { WorkspaceSync, SYNC_DRAIN_BUDGET_MS, SYNC_DRAIN_RESUME_MS, SYNC_DRAIN_MAX_BACKOFF_MS, syncRetryDelayMs } from "./host/sync.js";
-// `TRUST_CA_COMMAND` is exported so a host can assert what its image will be
-// asked to run — see the file for why this cannot live in an entrypoint.
-export { ContainerTrust, TRUST_CA_COMMAND } from "./host/ca-trust.js";
-export { WorkspaceGitHost } from "./host/git-host.js";

package/dist/computer/paths.d.ts

@@ -1,10 +1,11 @@
 /**
  * Which paths these tools act on, and the sentence a refused one gets.
  *
- * Both refused directories are also skipped by every walk. `.git` is refused as
+ * Each refused directory is also skipped by every walk, though the walk steps
+ * over more than it refuses — see {@link WALK_SKIPS}. `.git` is refused as
  * policy: a model that edits `.git/HEAD` corrupts a checkout in a way that
  * surfaces much later. `node_modules` is refused as a fact: it lives on the
- * container's disk (see `./host/container-deps.ts`), so these tools, which read
+ * container's disk (see `../workspace/container-deps.ts`), so these tools, which read
  * the workspace, would find it empty.
  *
  * Everything here is a string comparison: no filesystem, no `await`, which is
@@ -21,16 +22,35 @@
  */
 export declare function isGitInternal(path: string): boolean;
 /**
- * What every walk steps over. `find` prunes these in the store; `grep` takes no
- * exclusion, so `sb_grep` filters its results instead.
+ * Where a session's own state lives inside a workspace, as a directory name.
+ *
+ * Every Claude Code session keeps its `CLAUDE_CONFIG_DIR` in a directory of
+ * this name at the workspace root — the Durable Object's storage, so a
+ * conversation outlives its container and a later session can continue it. See
+ * {@link file://../claude-code/run.ts SESSION_CONFIG_DIR}.
+ *
+ * **Spelled here as well as in the plugin that sets the variable**, because the
+ * module that has to step over it is the walk below, and neither may import the
+ * other: `/computer` reaching into `/claude-code` would pull a whole plugin into
+ * every agent that installs the file tools, and `/claude-code` reaches no other
+ * subpath — `verify:exports` refuses both. A spec in `/claude-code` holds the
+ * two spellings to one.
+ */
+export declare const SESSION_STATE_DIR = ".claude-sessions";
+/**
+ * What every walk steps over, as directory names. Both the workspace's `glob`
+ * and the `grep` tool hand these to the store as `**\/<name>` exclusions, which
+ * prunes them: no directory named here is descended into, so none costs a read.
+ *
+ * {@link SESSION_STATE_DIR} is here for a reason the refused directories do not
+ * share: a transcript is a verbatim record of everything a session read, so a
+ * walk that descended into it would answer a `grep` for a line of source with
+ * the session that quoted it.
  */
-export declare const WALK_SKIPS: readonly [".git", "node_modules"];
-/** Whether a walk carrying `skips` steps over `path`. */
-export declare function isSkipped(skips: readonly string[], path: string): boolean;
-/** The skipped directories, for a sentence: "`.git` and `node_modules`". */
-export declare function skipNames(skips: readonly string[]): string;
+export declare const WALK_SKIPS: readonly [".git", "node_modules", ".claude-sessions"];
 /**
- * The path check every file tool makes, before it opens anything.
+ * The path check every file tool and every workspace call makes, before it
+ * opens anything.
  *
  * Returns the sentence to hand back, or `undefined` to proceed. One string
  * comparison — no `stat`, no round trip — which is why every file tool can
@@ -41,15 +61,15 @@ export declare function skipNames(skips: readonly string[]): string;
  * The note names the tools repository work belongs to, because the case that
  * actually happens is a model reaching into `.git/HEAD` to fix a merge.
  *
- * It is not containment, and this is the only place worth saying so. `sb_exec`
- * is in the same tool family, granted per family rather than per tool, so every
- * agent holding these file tools also holds a shell that reads and writes `.git`
- * directly.
+ * It is not containment, and this is the only place worth saying so. An agent
+ * that can write files here almost always holds `bash` too, which reads and
+ * writes `.git` directly.
  *
  * Symlinks are not resolved, for the same reason: a tracked
  * `docs/notes.md -> ../.git/config` only matters to an agent given these tools
- * *without* the shell, which the family granularity makes unbuildable. If that
- * ever becomes buildable, the **write** path is the half to restore —
+ * *without* the shell. A read-only install — `restrictTools` down to `grep`,
+ * with Think's writing tools left out — is that agent, and it cannot write. If a writing agent
+ * without the shell ever exists, the **write** path is the half to restore —
  * `.git/config` is an input to the credentialed push, and a planted hook runs
  * under a container-side `repo_commit`. Reading `.git` discloses nothing that is
  * not already readable, so the read half is not worth an `lstat` per call. The

package/dist/computer/paths.js

@@ -1,10 +1,11 @@
 /**
  * Which paths these tools act on, and the sentence a refused one gets.
  *
- * Both refused directories are also skipped by every walk. `.git` is refused as
+ * Each refused directory is also skipped by every walk, though the walk steps
+ * over more than it refuses — see {@link WALK_SKIPS}. `.git` is refused as
  * policy: a model that edits `.git/HEAD` corrupts a checkout in a way that
  * surfaces much later. `node_modules` is refused as a fact: it lives on the
- * container's disk (see `./host/container-deps.ts`), so these tools, which read
+ * container's disk (see `../workspace/container-deps.ts`), so these tools, which read
  * the workspace, would find it empty.
  *
  * Everything here is a string comparison: no filesystem, no `await`, which is
@@ -27,25 +28,36 @@ export function isGitInternal(path) {
     return hasSegment(path, ".git");
 }
 /**
- * What every walk steps over. `find` prunes these in the store; `grep` takes no
- * exclusion, so `sb_grep` filters its results instead.
+ * Where a session's own state lives inside a workspace, as a directory name.
+ *
+ * Every Claude Code session keeps its `CLAUDE_CONFIG_DIR` in a directory of
+ * this name at the workspace root — the Durable Object's storage, so a
+ * conversation outlives its container and a later session can continue it. See
+ * {@link file://../claude-code/run.ts SESSION_CONFIG_DIR}.
+ *
+ * **Spelled here as well as in the plugin that sets the variable**, because the
+ * module that has to step over it is the walk below, and neither may import the
+ * other: `/computer` reaching into `/claude-code` would pull a whole plugin into
+ * every agent that installs the file tools, and `/claude-code` reaches no other
+ * subpath — `verify:exports` refuses both. A spec in `/claude-code` holds the
+ * two spellings to one.
  */
-export const WALK_SKIPS = [".git", "node_modules"];
-/** Whether a walk carrying `skips` steps over `path`. */
-export function isSkipped(skips, path) {
-    return skips.some((segment) => hasSegment(path, segment));
-}
-/** The skipped directories, for a sentence: "`.git` and `node_modules`". */
-export function skipNames(skips) {
-    const quoted = skips.map((segment) => `\`${segment}\``);
-    return quoted.length > 1
-        ? `${quoted.slice(0, -1).join(", ")} and ${quoted[quoted.length - 1]}`
-        : (quoted[0] ?? "");
-}
+export const SESSION_STATE_DIR = ".claude-sessions";
+/**
+ * What every walk steps over, as directory names. Both the workspace's `glob`
+ * and the `grep` tool hand these to the store as `**\/<name>` exclusions, which
+ * prunes them: no directory named here is descended into, so none costs a read.
+ *
+ * {@link SESSION_STATE_DIR} is here for a reason the refused directories do not
+ * share: a transcript is a verbatim record of everything a session read, so a
+ * walk that descended into it would answer a `grep` for a line of source with
+ * the session that quoted it.
+ */
+export const WALK_SKIPS = [".git", "node_modules", SESSION_STATE_DIR];
 /** The sentence a `node_modules` path gets. */
 function dependencyTreeNote(path, verb) {
     return (`${path} is inside node_modules, which lives on the container's disk rather ` +
-        `than in the workspace ${verb} works on. Use sb_exec there — ` +
+        `than in the workspace ${verb} works on. Use bash there — ` +
         `\`cat\`, \`ls\`, \`rg\`.`);
 }
 /**
@@ -54,9 +66,9 @@ function dependencyTreeNote(path, verb) {
  * Names a route deliberately: a refusal with no destination is worse than no
  * refusal, because the model retries and then works around it.
  *
- * What it must never name is `sb_exec`. That hands back the exact capability
+ * What it must never name is `bash`. That hands back the exact capability
  * being withheld, in the one place the model is already looking for a way around
- * it, with the tool's own authority behind it. `sb_exec` is unguarded because a
+ * it, with the tool's own authority behind it. `bash` is unguarded because a
  * shell takes an opaque command string and pattern-matching git out of one is
  * neither reliable nor this guard's job — a fact about the implementation, not a
  * route to advertise.
@@ -65,12 +77,13 @@ function gitInternalNote(path, verb) {
     return (`${path} is inside .git — git's internal state, which ${verb} does not touch. ` +
         `Reading it tells you less than the repository tools do, and writing it ` +
         `corrupts the checkout. Repository work goes through the repo tools ` +
-        `(\`repo_status\`, \`repo_diff\`, \`repo_commit\`, \`repo_push\`), which the ` +
-        `main agent holds. If this task needs git state you cannot get that way, say ` +
-        `so in your result rather than reaching into .git yourself.`);
+        `(\`repo_status\`, \`repo_diff\`, \`repo_commit\`, \`repo_push\`). If this ` +
+        `task needs git state you cannot get that way, say so in your result rather ` +
+        `than reaching into .git yourself.`);
 }
 /**
- * The path check every file tool makes, before it opens anything.
+ * The path check every file tool and every workspace call makes, before it
+ * opens anything.
  *
  * Returns the sentence to hand back, or `undefined` to proceed. One string
  * comparison — no `stat`, no round trip — which is why every file tool can
@@ -81,15 +94,15 @@ function gitInternalNote(path, verb) {
  * The note names the tools repository work belongs to, because the case that
  * actually happens is a model reaching into `.git/HEAD` to fix a merge.
  *
- * It is not containment, and this is the only place worth saying so. `sb_exec`
- * is in the same tool family, granted per family rather than per tool, so every
- * agent holding these file tools also holds a shell that reads and writes `.git`
- * directly.
+ * It is not containment, and this is the only place worth saying so. An agent
+ * that can write files here almost always holds `bash` too, which reads and
+ * writes `.git` directly.
  *
  * Symlinks are not resolved, for the same reason: a tracked
  * `docs/notes.md -> ../.git/config` only matters to an agent given these tools
- * *without* the shell, which the family granularity makes unbuildable. If that
- * ever becomes buildable, the **write** path is the half to restore —
+ * *without* the shell. A read-only install — `restrictTools` down to `grep`,
+ * with Think's writing tools left out — is that agent, and it cannot write. If a writing agent
+ * without the shell ever exists, the **write** path is the half to restore —
  * `.git/config` is an input to the credentialed push, and a planted hook runs
  * under a container-side `repo_commit`. Reading `.git` discloses nothing that is
  * not already readable, so the read half is not worth an `lstat` per call. The