@dynamicagents/plugins 0.11.1 → 0.13.0

package/dist/repo/tools-worktree.js

@@ -0,0 +1,305 @@
+import { tool } from "ai";
+import { z } from "zod";
+import { PROTECTED_BRANCHES, UNSAFE_BRANCH } from "./url.js";
+import { resolveDefaultBranch } from "./checkout.js";
+/** Reading the working tree, committing it, and publishing the branch. */
+export function worktreeTools(ctx) {
+    const { author, bounded, config, fetchOrigin, logFailure, plain, origin, pushBranch } = ctx;
+    return {
+        repo_status: tool({
+            description: "Show which files changed in the checkout.",
+            inputSchema: z.object({ dir: z.string().describe("Checkout directory") }),
+            execute: async ({ dir }) => {
+                const result = await plain("status --short", dir);
+                // "(no changes)" is a claim about the tree. A command that failed
+                // supports no claim about anything, and reporting one as the other sends
+                // the model on to commit against a repository it cannot read.
+                if (!result.success) {
+                    logFailure("repo_status", result);
+                    return bounded(`could not read the status of ${dir}: ${result.stderr || result.stdout}`);
+                }
+                return bounded(result.stdout.trim()) || "(no changes)";
+            }
+        }),
+        repo_diff: tool({
+            description: "Show a diff. With no ref, the uncommitted changes in the checkout — read this before committing, it is the cheapest way to catch an edit that did more than you intended. With a ref, everything that ref adds, which is how you review work that arrived on a branch rather than in your own tree. Pass stat:true first on a large change to see which files moved and by how much, then read the full diff of what matters.",
+            inputSchema: z.object({
+                dir: z.string().describe("Checkout directory"),
+                staged: z.boolean().optional().describe("Show staged changes instead"),
+                ref: z
+                    .string()
+                    .optional()
+                    .describe("Review a ref instead of the working tree — e.g. 'origin/coder/add-json-flag'. Fetch it first; a ref this checkout has never seen cannot be diffed."),
+                base: z
+                    .string()
+                    .optional()
+                    .describe("Review what this checkout's own commits add since a ref — e.g. 'origin/main' — the other direction from `ref`. For a branch a sub-agent committed in a worktree you have switched into."),
+                stat: z
+                    .boolean()
+                    .optional()
+                    .describe("Summarise as a per-file changed-line count instead of the full patch")
+            }),
+            execute: async ({ dir, staged, stat, ref, base }) => {
+                if (ref !== undefined && base !== undefined)
+                    return "pass `ref` or `base`, not both — `ref` is what another ref adds, `base` is what this checkout's commits add";
+                if (base !== undefined && (base === "" || UNSAFE_BRANCH.test(base)))
+                    return `"${base}" is not a plain ref — pass something like "origin/main"`;
+                // Shape-checked for the same reason `repo_push` checks a branch: a ref is
+                // model-authored, and `git diff -x` reads a leading `-` as an option
+                // rather than a name. `UNSAFE_BRANCH` already refuses that and the
+                // traversal spellings.
+                // Empty is refused with the rest: it reads as "no ref" below, and the
+                // working tree's diff would be reported as the ref's.
+                if (ref !== undefined && (ref === "" || UNSAFE_BRANCH.test(ref)))
+                    return `"${ref}" is not a plain ref — pass something like "origin/coder/add-json-flag"`;
+                const flags = [staged ? "--staged" : "", stat ? "--stat" : ""]
+                    .filter(Boolean)
+                    .join(" ");
+                // `HEAD...<ref>`, and the order is the whole point: `git diff A...B`
+                // compares the merge base of the two to **B**, so the reviewed ref has to
+                // be on the right. Reversed, this reports what the reviewer's own HEAD
+                // gained since the branch diverged — which is the "the branch reverted
+                // things" reading it exists to avoid, printed with confidence.
+                //
+                // The ref goes in an env var and is never interpolated — see `shell`'s
+                // `vars`, which carries why. A `--` would not be enough on its own here,
+                // because the injection this prevents is a second shell command.
+                const result = ref
+                    ? await plain(`diff ${flags} HEAD..."$REPO_REF" --`, dir, {
+                        REPO_REF: ref
+                    })
+                    : base
+                        ? // The same rule from the other side: the checkout's HEAD on the
+                            // right, so what is reported is what its commits add.
+                            await plain(`diff ${flags} "$REPO_BASE"...HEAD --`, dir, {
+                                REPO_BASE: base
+                            })
+                        : await plain(`diff ${flags}`, dir);
+                // Same reasoning as `repo_status`: "(no diff)" and "the diff could not
+                // be read" are opposite answers, and this is the tool a reviewing agent
+                // trusts most.
+                if (!result.success) {
+                    logFailure("repo_diff", result);
+                    const named = ref ?? base;
+                    return bounded(named
+                        ? // Names the ref and the likely cause: the common failure is a ref
+                            // this checkout has never fetched, and "unknown revision" on its
+                            // own does not say that.
+                            `could not diff "${named}" in ${dir} — fetch it first if it has not ` +
+                                `been fetched: ${result.stderr || result.stdout}`
+                        : `could not read the diff in ${dir}: ${result.stderr || result.stdout}`);
+                }
+                // Truncated from the middle rather than the end: the head of a diff and
+                // its tail are both informative, and the middle of a large one rarely
+                // is. A model that needs the part that was dropped can ask for `stat`
+                // and then read the file.
+                return bounded(result.stdout.trim()) || "(no diff)";
+            }
+        }),
+        repo_commit: tool({
+            description: "Stage everything and commit. Write the message for a reviewer reading it in the log a year from now: what changed and why, not how.",
+            inputSchema: z.object({
+                dir: z.string().describe("Checkout directory"),
+                message: z.string().describe("Commit message")
+            }),
+            execute: async ({ dir, message }) => {
+                // Checked rather than fired and forgotten. A failed `add` leaves the
+                // index holding less than the model believes, and the commit that
+                // follows still succeeds — so the turn reports a commit that quietly
+                // does not contain the change.
+                const staged = await plain("add -A", dir);
+                if (!staged.success) {
+                    logFailure("repo_commit", staged);
+                    return bounded(`could not stage the changes in ${dir}: ${staged.stderr || staged.stdout}`);
+                }
+                // The message is model-authored free text — quotes, backticks, newlines,
+                // `$(…)`. Expanded from the environment inside the container, all of
+                // that is inert; interpolated into the command string, none of it is.
+                const result = await plain(`commit -m "$GIT_COMMIT_MESSAGE"`, dir, {
+                    GIT_COMMIT_MESSAGE: message,
+                    // On the commit as well as in the checkout's config, and this is
+                    // the copy that is current: config is written when a checkout is set
+                    // up, and the environment is read at the commit. A workspace that
+                    // outlived a change of identity commits under the new one.
+                    GIT_AUTHOR_NAME: author.name,
+                    GIT_AUTHOR_EMAIL: author.email,
+                    GIT_COMMITTER_NAME: author.name,
+                    GIT_COMMITTER_EMAIL: author.email
+                });
+                if (!result.success && /nothing to commit/i.test(result.stdout))
+                    return "nothing to commit — the working tree is clean";
+                if (!result.success) {
+                    logFailure("repo_commit", result);
+                    return bounded(`commit failed: ${result.stderr || result.stdout}`);
+                }
+                return bounded(result.stdout.trim());
+            }
+        }),
+        /**
+         * Bring the remote's branches into a checkout without touching its tree.
+         *
+         * `repo_clone` fetches too, but it resets the tree afterwards and only ever
+         * reaches the checkout it clones into — so work pushed to a branch by
+         * somebody else, a submodule's included, had no way into a checkout that
+         * already existed. Nothing here writes to the working tree, so there is no
+         * refusal path for uncommitted work.
+         */
+        repo_fetch: tool({
+            description: "Fetch every branch from a checkout's own origin, without touching its working tree. This is how a branch someone else pushed becomes a ref you can review: after it, repo_diff with ref 'origin/<branch>'. Pass the directory of the repository the branch was pushed to — in a superproject, that is the submodule's directory.",
+            inputSchema: z.object({ dir: z.string().describe("Checkout directory") }),
+            execute: async ({ dir }) => {
+                // The checkout's own origin, for the reason `repo_push` reads it: it has
+                // already passed the allowlist, and a URL named here would not have.
+                const { remote, unreachable } = await origin(dir);
+                if (unreachable)
+                    return bounded(`could not fetch in ${dir}: ${unreachable}`);
+                if (!remote)
+                    return `${dir} has no origin on an allowed host — clone it with repo_clone first`;
+                const fetched = await fetchOrigin(dir, remote.url);
+                if (!fetched.success) {
+                    logFailure("repo_fetch", fetched);
+                    return bounded(`fetch failed: ${fetched.stderr || fetched.stdout}`);
+                }
+                return `fetched ${remote.url} into ${dir}; its branches are under origin/ — review one with repo_diff and ref "origin/<branch>"`;
+            }
+        }),
+        repo_push: tool({
+            description: "Push a branch to the remote: one this checkout holds, or a new one created at its current commit. Refuses a protected branch, a force-push, and a branch that adds no commit the remote does not already have — open a pull request instead.",
+            inputSchema: z.object({
+                dir: z.string().describe("Checkout directory"),
+                branch: z
+                    .string()
+                    .describe("The branch your commits are on, or a new name to create at the current commit, e.g. 'coder/add-json-flag'")
+            }),
+            execute: async ({ dir, branch }) => {
+                // Enforced here rather than in the prompt: a guardrail a model can talk
+                // itself out of is not a guardrail.
+                //
+                // Shape first, then the name. `git push origin <name>` reads `<name>`
+                // as a refspec, so `+x:main` is a force push to main that the name
+                // check below would wave through — it only ever sees a literal string.
+                if (UNSAFE_BRANCH.test(branch))
+                    return `"${branch}" is not a plain branch name — use something like "coder/add-json-flag"`;
+                if (PROTECTED_BRANCHES.has(branch))
+                    return `refusing to push to "${branch}" — push a work branch and open a pull request`;
+                // The repository's *own* default, which is often none of the four names
+                // above: a repo whose trunk is `release` deserves the same protection.
+                // A command that never ran stops here rather than standing the guards
+                // down — the same rule as the probes further down, and the reason
+                // {@link resolveDefaultBranch} reports the two separately.
+                const head = await resolveDefaultBranch(plain, dir);
+                if (head.unreachable)
+                    return bounded(`could not push "${branch}": ${head.unreachable}`);
+                const defaultBranch = head.branch;
+                if (defaultBranch && defaultBranch === branch)
+                    return `refusing to push to "${branch}" — it is this repository's default branch; push a work branch and open a pull request`;
+                const { remote, unreachable } = await origin(dir);
+                if (unreachable)
+                    return bounded(`could not push "${branch}": ${unreachable}`);
+                if (!remote)
+                    return `${dir} has no origin on an allowed host — clone it with repo_clone first`;
+                const exists = await plain(`rev-parse --verify --quiet "refs/heads/$REPO_BRANCH"`, dir, { REPO_BRANCH: branch });
+                // Same reasoning as the probe in `repo_clone`: `!success` means "no such
+                // branch, create it" only when git was there to say so.
+                if (exists.unreachable)
+                    return bounded(`could not push "${branch}": ${exists.stderr}`);
+                // The commit the push would publish: the branch's own, or HEAD for a
+                // branch this creates, which is where `checkout -b` puts it.
+                const tip = await plain(`log -1 --format=%H%n%s "$REPO_REF" --`, dir, {
+                    REPO_REF: exists.success ? `refs/heads/${branch}` : "HEAD"
+                });
+                if (tip.unreachable)
+                    return bounded(`could not push "${branch}": ${tip.stderr}`);
+                const [commit = "", subject = ""] = tip.stdout.trim().split("\n");
+                if (!tip.success || !commit) {
+                    logFailure("repo_push", tip);
+                    return bounded(`could not resolve "${branch}" to a commit: ${tip.stderr || tip.stdout}`);
+                }
+                const short = commit.slice(0, 7);
+                // Nothing to push is refused — the README's "Guardrails" says why — and
+                // measured against every remote branch, since a pull request's base need
+                // not be the default. The branch's own remote ref is left out so a landed
+                // push can be retried: `--exclude` wants it without `refs/remotes/`, and
+                // with that prefix excludes nothing. Checked before the branch is
+                // created, so a refusal leaves none behind for a retry to find.
+                const fresh = await plain(`rev-list --count "$REPO_TIP" --not --exclude="origin/$REPO_BRANCH" --remotes=origin`, dir, { REPO_TIP: commit, REPO_BRANCH: branch });
+                if (fresh.unreachable)
+                    return bounded(`could not push "${branch}": ${fresh.stderr}`);
+                const count = fresh.stdout.trim();
+                // A comparison with no answer is not a pass, and an empty one is not 0.
+                if (!fresh.success || !/^\d+$/.test(count)) {
+                    logFailure("repo_push", fresh);
+                    return bounded(`could not tell whether "${branch}" has anything to push: comparing it ` +
+                        `against the remote's branches failed with ` +
+                        `${fresh.stderr || fresh.stdout || "no output"}\n` +
+                        `Nothing was pushed. Pushing without that answer risks an empty pull ` +
+                        `request reported as success, so check repo_status and repo_diff first.`);
+                }
+                if (count === "0") {
+                    // Where the work went is the host's to say, when it keeps worktrees:
+                    // a writing sub-agent's commits are on its worktree's branch.
+                    let held;
+                    try {
+                        held = await config.worktrees?.list();
+                    }
+                    catch (err) {
+                        console.warn("[repo] worktrees.list failed", { err: String(err) });
+                    }
+                    return bounded(`refusing to push "${branch}" — ` +
+                        (exists.success
+                            ? ""
+                            : `it is not a branch in ${dir}, so it would be created at the current commit, and `) +
+                        `${short} adds no commit the remote does not already have, so the pull ` +
+                        `request would be empty. Either the change was never committed, or it was ` +
+                        `committed on a different branch` +
+                        (held ? `.\n\n${held}` : ` — check repo_status and repo_diff.`));
+                }
+                // Switch to the branch, or create it — but never *reset* it.
+                //
+                // `-b`, never `-B`: `-B` is create-or-reset, so on a branch that already
+                // holds the commit it force-moves it to wherever HEAD is now. The commit
+                // survives only as an unreferenced object, and what gets pushed is an
+                // empty branch with a pull request opened on it — a complete loss
+                // dressed up as success.
+                const checkout = await plain(exists.success
+                    ? `checkout "$REPO_BRANCH"`
+                    : `checkout -b "$REPO_BRANCH"`, dir, { REPO_BRANCH: branch });
+                if (!checkout.success) {
+                    logFailure("repo_push", checkout);
+                    return bounded(`could not switch to branch "${branch}": ${checkout.stderr || checkout.stdout}`);
+                }
+                const result = await pushBranch(dir, remote.url, branch);
+                if (!result.success) {
+                    logFailure("repo_push", result);
+                    return bounded(`push failed: ${result.stderr || result.stdout}`);
+                }
+                const pushed = `pushed ${branch} at ${short} "${subject}", ${count} ` +
+                    `${count === "1" ? "commit" : "commits"} no other branch on the remote has`;
+                // What `--set-upstream` would do as a side effect of the push, written
+                // here because the push happens on the host's side: a sub-agent reaching
+                // for a bare `git push` in the shell should still find the branch
+                // tracking something.
+                //
+                // Checked, but *reported* rather than raised: this is the one place in
+                // the plugin where a failed command is not a failed operation. The push
+                // has landed, saying so is the important half, and all that is lost is
+                // the convenience these two keys buy.
+                const remoteSet = await plain(`config "branch.$REPO_BRANCH.remote" origin`, dir, { REPO_BRANCH: branch });
+                const mergeSet = await plain(`config "branch.$REPO_BRANCH.merge" "refs/heads/$REPO_BRANCH"`, dir, { REPO_BRANCH: branch });
+                const untracked = [remoteSet, mergeSet].find((r) => !r.success);
+                if (untracked) {
+                    // Named apart from the push, which succeeded — a log line reading
+                    // "repo_push failed" next to a branch that is on the remote is worse
+                    // than no log line.
+                    logFailure("repo_push (upstream tracking)", untracked);
+                    return bounded(`${pushed}, but could not record what it tracks: ` +
+                        `${untracked.stderr || untracked.stdout}\n` +
+                        `The push itself landed. The only consequence is local: a bare ` +
+                        `\`git push\` from the shell will not know where to send this ` +
+                        `branch, and needs \`git push -u origin ${branch}\` once.`);
+                }
+                return bounded(pushed);
+            }
+        })
+    };
+}

package/dist/repo/tools-worktrees.d.ts

@@ -0,0 +1,12 @@
+import type { ToolSet } from "ai";
+import type { RepoWorktrees } from "./index.js";
+/**
+ * Moving between the host's worktrees — not to be confused with
+ * `./tools-worktree.ts`, which reads and writes the one checkout the tools point
+ * at.
+ *
+ * Thin by design: which worktrees exist and what a switch reaches are the host's
+ * facts — see {@link RepoWorktrees} — so these tools check a branch's shape and
+ * pass the host's sentence through.
+ */
+export declare function worktreesTools(worktrees: RepoWorktrees): ToolSet;

package/dist/repo/tools-worktrees.js

@@ -0,0 +1,48 @@
+import { tool } from "ai";
+import { z } from "zod";
+import { UNSAFE_BRANCH } from "./url.js";
+/**
+ * Moving between the host's worktrees — not to be confused with
+ * `./tools-worktree.ts`, which reads and writes the one checkout the tools point
+ * at.
+ *
+ * Thin by design: which worktrees exist and what a switch reaches are the host's
+ * facts — see {@link RepoWorktrees} — so these tools check a branch's shape and
+ * pass the host's sentence through.
+ */
+export function worktreesTools(worktrees) {
+    const refuse = (branch) => `"${branch}" is not a plain branch name — pass it as the sub-agent's report named it`;
+    const unsafe = (branch) => branch === "" || UNSAFE_BRANCH.test(branch);
+    return {
+        repo_worktrees: tool({
+            description: "List the worktrees your writing sub-agents committed in: each one's branch, whether a session is still working in it, and whether its commits are pushed. Pass `release` with a branch to give up its worktree once you have decided not to keep that work — unpushed commits in it are lost.",
+            inputSchema: z.object({
+                release: z
+                    .string()
+                    .optional()
+                    .describe("A branch whose worktree to give up")
+            }),
+            execute: async ({ release }) => {
+                if (release === undefined)
+                    return await worktrees.list();
+                if (unsafe(release))
+                    return refuse(release);
+                return await worktrees.release(release);
+            }
+        }),
+        repo_worktree: tool({
+            description: "Point every repo tool and your file reads at the worktree holding a branch a writing sub-agent reported, to read what it did. They stay there until you call this again; call it with no branch to come back to your own checkout.",
+            inputSchema: z.object({
+                branch: z
+                    .string()
+                    .optional()
+                    .describe("The branch a sub-agent's report named, e.g. 'claude-coordinator/<task>/<n>'; omit to go back to your own checkout")
+            }),
+            execute: async ({ branch }) => {
+                if (branch !== undefined && unsafe(branch))
+                    return refuse(branch);
+                return await worktrees.use(branch);
+            }
+        })
+    };
+}

package/dist/repo/url.d.ts

@@ -6,7 +6,7 @@
  * naming it": every pattern here turns away a string that resolves to something
  * other than what it appears to name.
  */
-/** The forges a clone URL may name. `RepoConfig.allowedHosts` overrides it. */
+/** The hosts a clone URL may name. `RepoConfig.allowedHosts` overrides it. */
 export declare const DEFAULT_ALLOWED_HOSTS: string[];
 /** Branch names a push must never target, whatever the model believes. */
 export declare const PROTECTED_BRANCHES: Set<string>;
@@ -50,7 +50,7 @@ export declare function sameRepoUrl(a: string, b: string): boolean;
  *
  * Anchored on the **parsed host** rather than matched in the string, so
  * `https://evil.example.com/github.com/owner/repo` is not a github.com URL.
- * Both names are then checked against {@link isForgeName}, so a name that could
+ * Both names are then checked against {@link isGitHubName}, so a name that could
  * traverse a path or split somebody else's key never gets as far as being one.
  *
  * `undefined` is a refusal at every caller, never a reason to carry on with a

package/dist/repo/url.js

@@ -6,7 +6,7 @@
  * naming it": every pattern here turns away a string that resolves to something
  * other than what it appears to name.
  */
-/** The forges a clone URL may name. `RepoConfig.allowedHosts` overrides it. */
+/** The hosts a clone URL may name. `RepoConfig.allowedHosts` overrides it. */
 export const DEFAULT_ALLOWED_HOSTS = ["github.com"];
 /** Branch names a push must never target, whatever the model believes. */
 export const PROTECTED_BRANCHES = new Set([
@@ -88,7 +88,7 @@ export function sameRepoUrl(a, b) {
     return canonical(a) === canonical(b);
 }
 /**
- * A name a forge would actually issue — and one that is safe to use as a path
+ * A name GitHub would actually issue — and one that is safe to use as a path
  * segment and as a key.
  *
  * GitHub's rule for an owner and a repository alike is alphanumerics, `-`, `_`
@@ -101,17 +101,17 @@ export function sameRepoUrl(a, b) {
  * is a separator in somebody else's key format, which is how two callers end up
  * sharing one workspace.
  */
-const FORGE_NAME = /^[A-Za-z0-9._-]+$/;
-function isForgeName(name) {
+const GITHUB_NAME = /^[A-Za-z0-9._-]+$/;
+function isGitHubName(name) {
     // `.` and `..` pass the character class and are exactly the two that must not.
-    return name !== "." && name !== ".." && FORGE_NAME.test(name);
+    return name !== "." && name !== ".." && GITHUB_NAME.test(name);
 }
 /**
  * `owner/repo` out of a repository URL, or `undefined` if it is not one.
  *
  * Anchored on the **parsed host** rather than matched in the string, so
  * `https://evil.example.com/github.com/owner/repo` is not a github.com URL.
- * Both names are then checked against {@link isForgeName}, so a name that could
+ * Both names are then checked against {@link isGitHubName}, so a name that could
  * traverse a path or split somebody else's key never gets as far as being one.
  *
  * `undefined` is a refusal at every caller, never a reason to carry on with a
@@ -125,7 +125,7 @@ export function parseRepo(url, allowedHosts = DEFAULT_ALLOWED_HOSTS) {
     if (!match)
         return undefined;
     const [, owner, repo] = match;
-    if (!isForgeName(owner) || !isForgeName(repo))
+    if (!isGitHubName(owner) || !isGitHubName(repo))
         return undefined;
     return { owner, repo };
 }

package/dist/scratch/index.d.ts

@@ -42,7 +42,7 @@ import type { AgentPlugin } from "@dynamicagents/core";
 /** Where a scratchpad lives, unless the host says otherwise. */
 export declare const DEFAULT_SCRATCH_DIR = "/workspace/scratch";
 /**
- * Run one command in the host's container. Matches `computerExec`'s shape.
+ * Run one command in the host's container. Matches `workspaceExec`'s shape.
  *
  * Injected rather than imported, like `/repo`'s: `npm run verify:exports` fails
  * any subpath whose module graph reaches a sibling's, and a scratchpad that
@@ -54,7 +54,7 @@ export type ScratchExec = (command: string, options?: {
     env?: Record<string, string | undefined>;
     timeout?: number;
     /**
-     * The executing subtask's runtime state, forwarded **opaquely** — the same
+     * The running sub-agent's `runtime()`, forwarded **opaquely** — the same
      * pass-through `/repo` does, for the same reason. This plugin never looks
      * inside it.
      */
@@ -96,7 +96,7 @@ export interface ScratchConfig {
      * Runs commands in the container holding the workspace.
      *
      * Uncredentialed, and nothing here ever needs a credential: a scratchpad has
-     * no remote, so no operation in this plugin talks to a forge.
+     * no remote, so no operation in this plugin talks to GitHub.
      */
     exec: ScratchExec;
     /** Where the scratchpad lives. Defaults to {@link DEFAULT_SCRATCH_DIR}. */
@@ -153,6 +153,6 @@ export interface ScratchConfig {
  * carries the same copy for the same reason.
  */
 export declare function truncateOutput(text: string, max: number): string;
-/** The tool name, exported so a host restricting its main agent can name it. */
+/** The tool name, exported so a host restricting the plugin can name it. */
 export declare const SCRATCH_OPEN_TOOL = "scratch_open";
 export declare function scratch(config: ScratchConfig): AgentPlugin;

package/dist/scratch/index.js

@@ -68,10 +68,10 @@ export function truncateOutput(text, max) {
         return text.slice(0, Math.max(0, max));
     return (text.slice(0, half) + marker(text.length - half * 2) + text.slice(-half));
 }
-/** The tool name, exported so a host restricting its main agent can name it. */
+/** The tool name, exported so a host restricting the plugin can name it. */
 export const SCRATCH_OPEN_TOOL = "scratch_open";
 /**
- * What the delegating agent is told.
+ * What the model is told.
  *
  * The mixing rule at the end is the line worth its tokens. A host that keys one
  * workspace selection per caller — which is what makes a scratchpad routable at
@@ -294,19 +294,20 @@ export function scratch(config) {
             .filter(Boolean)
             .join(" "), maxChars);
     };
+    const context = capabilityFor(dir);
     return definePlugin({
-        key: "scratch",
+        name: "scratch",
         /**
-         * The main agent's, and no tool family — which is a decision rather than an
-         * omission.
+         * For a parent, never a sub-agent — which the host decides by installing it
+         * on one and not the other.
          *
          * Opening a scratchpad *selects a workspace*, exactly as `repo_clone` does.
-         * A subagent holding this could re-point the workspace its parent prepared
+         * A sub-agent holding this could re-point the workspace its parent prepared
          * half-way through its own run, which is the hazard a host's per-caller
-         * selection already has to document. A delegated run works in whatever it
-         * was given.
+         * selection already has to document. A sub-agent works in whatever it was
+         * given.
          */
-        mainAgentTools: () => ({
+        tools: (ctx) => ({
             [SCRATCH_OPEN_TOOL]: tool({
                 description: "Open a scratchpad: a git repository with no remote, in your container, " +
                     "for work that does not need a cloned repository. Use it before " +
@@ -318,9 +319,9 @@ export function scratch(config) {
                         .optional()
                         .describe("Discard everything in the scratchpad first, including files an earlier task left")
                 }),
-                execute: ({ reset }) => open(reset, undefined)
+                execute: ({ reset }) => open(reset, ctx.runtime())
             })
         }),
-        capability: capabilityFor(dir)
+        context: [{ provider: { get: async () => context } }]
     });
 }

package/dist/{computer → workspace}/advisory.d.ts

@@ -9,21 +9,20 @@ import type { InstallState } from "./install.js";
  * and the generation marker. It is right for that and unchanged by this file.
  *
  * Every *reader*, though, is asking a different question: **can I rely on this
- * workspace right now?** The two diverge, and where they did the old code either
- * overloaded a variant or invented a record:
+ * workspace right now?** The two diverge, and expressing the second through the
+ * first goes wrong in ways that are each easy to reintroduce:
  *
- * - A workspace at its storage ceiling was written as `skipped` — the same
- *   variant that means "this checkout has nothing to install". One is a hard
- *   wall about the Durable Object, the other is routine and about the
- *   repository, and they were told apart only by reading prose. Both readers
- *   missed the first.
- * - Capacity therefore travelled through a channel gated by
- *   {@link file://./gate.ts needsDependencies}, so a full workspace said nothing
+ * - A workspace at its storage ceiling is not `skipped`. That variant means
+ *   "this checkout has nothing to install" — routine, and about the repository.
+ *   A ceiling is a hard wall about the Durable Object, and the two are then told
+ *   apart only by reading prose.
+ * - Capacity must not travel through a channel gated by
+ *   {@link file://../computer/gate.ts needsDependencies}, or a full workspace says nothing
  *   at all to `echo hi > file.txt` — the command whose write is being lost.
- * - "The tree is fine now", after a subagent installed by hand, had no way to be
- *   said except by fabricating a `done` with an invented exit code — and the
- *   probe it rested on, a bare `test -d node_modules`, is satisfied by the
- *   wreckage of the very install it was overriding.
+ * - "The tree is fine now", after an agent installed by hand, has no honest
+ *   spelling as a job record: fabricating a `done` rests on the presence of a
+ *   `node_modules` directory, which the wreckage of the very install being
+ *   overridden already satisfies.
  *
  * So an advisory is **derived at read time** and describes the workspace, not a
  * job. Its absence is the good case, which is what removes the need to invent
@@ -57,7 +56,7 @@ export type WorkspaceAdvisory = {
      * Reported rather than acted on, because its presence proves nothing in
      * either direction. A half-finished `npm ci` leaves the directory behind
      * with an incomplete tree, so treating existence as success hides the
-     * common failure outright; and a subagent that re-ran the install by hand
+     * common failure outright; and an agent that re-ran the install by hand
      * leaves a record the host cannot update, since the host cannot see an
      * install it did not start. Both look identical from here, so the reader
      * is told which way the ambiguity runs rather than being handed a guess.
@@ -139,11 +138,11 @@ export interface AdvisoryInput {
     /**
      * Whether a `node_modules` directory exists — **existence only, not health**.
      *
-     * Named for what it can actually observe. A host probes this with the
-     * equivalent of `test -d`, and that answers a narrower question than
-     * "are the dependencies fine": a `npm ci` that died partway leaves the
-     * directory behind holding an incomplete tree, so a `true` here is entirely
-     * consistent with the install having failed for real.
+     * Named for what it can actually observe. A host answers it by looking for the
+     * directory in the workspace, and that is a narrower question than "are the
+     * dependencies fine": an `npm ci` that died partway leaves the directory
+     * behind holding an incomplete tree, so a `true` here is entirely consistent
+     * with the install having failed for real.
      *
      * So it never suppresses a proven failure. It travels onto the advisory as
      * {@link WorkspaceAdvisory} `treePresent` and the reader is told which way the
@@ -152,6 +151,20 @@ export interface AdvisoryInput {
      * mode it was recording.
      */
     dependencyTreePresent: boolean;
+    /**
+     * A reinstall the host has already queued, as the moment it was queued.
+     *
+     * The difference between "your dependencies are broken" and "your
+     * dependencies are being rebuilt", and the two read identically from the
+     * durable record alone — an install whose container was replaced writes
+     * `failed`, and the arming that will repair it is a separate fact the record
+     * does not carry.
+     *
+     * A production session was briefed `deps-broken` six seconds before the
+     * armed reinstall it did not know about finished, and spent its own turns
+     * re-running `npm ci` on top of a tree that was already landing.
+     */
+    reinstallArmedAt?: number;
 }
 /**
  * Everything currently true about a workspace, from what the host can see.
@@ -168,7 +181,7 @@ export declare function deriveAdvisories(input: AdvisoryInput): readonly Workspa
 /**
  * Everything a session should know before it starts, or `undefined` for silence.
  *
- * The counterpart to {@link file://./gate.ts execGate}, for the reader that is a
+ * The counterpart to {@link file://../computer/gate.ts execGate}, for the reader that is a
  * whole run rather than one command. It cannot be blocked and does not need to
  * be: it can install dependencies itself, and the only thing it must not do is
  * work silently against a workspace that is not what it assumes.