@dynamicagents/plugins 0.12.0 → 0.14.0

package/dist/repo/tools-review.js

@@ -1,11 +1,12 @@
+import { action } from "@cloudflare/think";
 import { tool } from "ai";
 import { z } from "zod";
-import { FORGE_PAGE_SIZE } from "./context.js";
+import { actionTask, GITHUB_ACTION_TIMEOUT_MS, GITHUB_PAGE_SIZE, sha256 } from "./context.js";
 /** A review as a conversation: whether it landed, what it said, and answering it. */
 /**
  * How many pages of review threads one `repo_pr_threads` call will walk.
  *
- * A bound rather than a full walk, for the reason {@link FORGE_PAGE_SIZE} is one
+ * A bound rather than a full walk, for the reason {@link GITHUB_PAGE_SIZE} is one
  * — but unlike the single page everything else here takes, threads genuinely
  * have to page: a review long enough to spill one puts its newest threads on the
  * last page, and those are exactly the ones an agent was sent to answer. So this
@@ -35,7 +36,7 @@ const REVIEW_THREADS_QUERY = `
   query($owner:String!,$repo:String!,$number:Int!,$after:String){
     repository(owner:$owner,name:$repo){
       pullRequest(number:$number){
-        reviewThreads(first:${FORGE_PAGE_SIZE},after:$after){
+        reviewThreads(first:${GITHUB_PAGE_SIZE},after:$after){
           pageInfo{hasNextPage endCursor}
           nodes{
             id isResolved isOutdated path line
@@ -60,7 +61,7 @@ const REVIEW_REQUESTS_QUERY = `
   query($owner:String!,$repo:String!,$number:Int!){
     repository(owner:$owner,name:$repo){
       pullRequest(number:$number){
-        reviewRequests(first:${FORGE_PAGE_SIZE}){
+        reviewRequests(first:${GITHUB_PAGE_SIZE}){
           nodes{
             requestedReviewer{
               ... on User{login}
@@ -120,7 +121,7 @@ function renderThread(t) {
 /**
  * The owner and repository as their own names, rather than as REST path segments.
  *
- * {@link file://./context.ts forgeRepo} percent-encodes both, because that is
+ * {@link file://./context.ts githubRepo} percent-encodes both, because that is
  * what makes a path safe. A GraphQL *variable* is not a path — it is compared
  * against the repository's actual name — so an encoded one would silently stop
  * matching the moment a name contains a character worth encoding.
@@ -162,7 +163,7 @@ function sameReviewer(a, b) {
     return COPILOT_LOGIN.test(x) && COPILOT_LOGIN.test(y) ? true : x === y;
 }
 export function reviewTools(ctx) {
-    const { bounded, forge, forgeGraphql, forgeRepo } = ctx;
+    const { bounded, github, githubGraphql, githubRepo } = ctx;
     return {
         repo_pr_review_status: tool({
             description: "Say whether a reviewer has finished reviewing a pull request in the repository you have checked out. Use it before reading review comments: a review that has not landed has left no comments, and an empty thread list means nothing yet.",
@@ -175,7 +176,7 @@ export function reviewTools(ctx) {
                     .describe('The reviewer to ask about, as their login. Defaults to "Copilot".')
             }),
             execute: async ({ dir, number, reviewer }) => {
-                const target = await forgeRepo(dir);
+                const target = await githubRepo(dir);
                 if ("refusal" in target)
                     return target.refusal;
                 const { owner, repo } = target;
@@ -186,7 +187,7 @@ export function reviewTools(ctx) {
                 // asked for, so "still requested" is true now and "has reviewed" is
                 // about the past. Reading them the other way round reports a re-review
                 // as finished the moment it is asked for.
-                const requested = await forgeGraphql("repo_pr_review_status", REVIEW_REQUESTS_QUERY, { owner, repo, number });
+                const requested = await githubGraphql("repo_pr_review_status", REVIEW_REQUESTS_QUERY, { owner, repo, number });
                 if (!requested.ok)
                     return bounded(requested.message);
                 const waiting = requested.data.repository?.pullRequest?.reviewRequests;
@@ -198,7 +199,7 @@ export function reviewTools(ctx) {
                 });
                 if (pending)
                     return `${who} has been asked to review #${number} and has not finished.`;
-                const reviews = await forge("repo_pr_review_status", `/repos/${owner}/${repo}/pulls/${number}/reviews?per_page=${FORGE_PAGE_SIZE}`);
+                const reviews = await github("repo_pr_review_status", `/repos/${owner}/${repo}/pulls/${number}/reviews?per_page=${GITHUB_PAGE_SIZE}`);
                 if (!reviews.ok)
                     return bounded(reviews.message);
                 const all = reviews.data;
@@ -216,8 +217,8 @@ export function reviewTools(ctx) {
                     // review being waited for. So a truncated read cannot answer the
                     // question at all, and must not answer it with "waiting will not help":
                     // that is the one reply a caller ends its polling on.
-                    if (all.length >= FORGE_PAGE_SIZE)
-                        return bounded(`#${number} has at least ${FORGE_PAGE_SIZE} reviews and only the oldest were read, ` +
+                    if (all.length >= GITHUB_PAGE_SIZE)
+                        return bounded(`#${number} has at least ${GITHUB_PAGE_SIZE} reviews and only the oldest were read, ` +
                             `so whether ${who} has reviewed it is unknown. Read the pull request itself with repo_pr_view, ` +
                             `or look for threads with repo_pr_threads.`);
                     return bounded(`#${number} has no review from ${who}, and none is pending. ` +
@@ -239,7 +240,7 @@ export function reviewTools(ctx) {
                     .describe("Include threads already resolved. Defaults to false.")
             }),
             execute: async ({ dir, number, includeResolved }) => {
-                const target = await forgeRepo(dir);
+                const target = await githubRepo(dir);
                 if ("refusal" in target)
                     return target.refusal;
                 const { owner, repo } = decoded(target);
@@ -256,7 +257,7 @@ export function reviewTools(ctx) {
                         truncated = true;
                         break;
                     }
-                    const answered = await forgeGraphql("repo_pr_threads", REVIEW_THREADS_QUERY, {
+                    const answered = await githubGraphql("repo_pr_threads", REVIEW_THREADS_QUERY, {
                         owner,
                         repo,
                         number,
@@ -295,45 +296,64 @@ export function reviewTools(ctx) {
                 const rendered = shown.map((t) => renderThread(t)).join("\n\n");
                 return bounded(rendered + unread);
             }
-        }),
-        repo_pr_thread_reply: tool({
-            description: "Answer one review thread on a pull request in the repository you have checked out, and resolve it. Reply with what you changed and where, or with why you did not — either way the thread ends resolved unless you say otherwise.",
-            inputSchema: z.object({
-                dir: z.string().describe("The checkout directory"),
-                number: z.number().int().positive().describe("Pull request number"),
-                threadId: z
-                    .string()
-                    .describe("The thread's id, exactly as repo_pr_threads printed it"),
-                body: z
-                    .string()
-                    .optional()
-                    .describe("The reply, as markdown. Leave it out to resolve a thread you have already replied to."),
-                resolve: z
-                    .boolean()
-                    .optional()
-                    .describe("Resolve the thread after replying. Defaults to true.")
-            }),
+        })
+    };
+}
+/**
+ * Answering a thread, as a Think action — see
+ * {@link file://./tools-pr.ts prActions} for why every failure is
+ * thrown. The one outcome returned short of success is a reply that landed on
+ * a thread that did not resolve: that reply must never be sent again, so it is
+ * settled, and the resolve-only call it asks for is a different key.
+ */
+export function reviewActions(ctx) {
+    const { bounded, githubGraphql, githubRepo } = ctx;
+    const replyInput = z.object({
+        dir: z.string().describe("The checkout directory"),
+        number: z.number().int().positive().describe("Pull request number"),
+        threadId: z
+            .string()
+            .describe("The thread's id, exactly as repo_pr_threads printed it"),
+        body: z
+            .string()
+            .min(1)
+            .optional()
+            .describe("The reply, as markdown. Leave it out to resolve a thread you have already replied to."),
+        resolve: z
+            .boolean()
+            .optional()
+            .describe("Resolve the thread after replying. Defaults to true.")
+    });
+    return {
+        repo_pr_thread_reply: action({
+            description: "Answer one review thread on a pull request in the repository you have checked out, and resolve it. Reply with what you changed and where, or with why you did not — either way the thread ends resolved unless you say otherwise. The same reply to one thread twice in one task is sent once.",
+            inputSchema: replyInput,
+            timeoutMs: GITHUB_ACTION_TIMEOUT_MS,
+            // The thread and the resolve flag as well as the body, or the same reply
+            // to two threads — "Fixed." — would be one key.
+            idempotencyKey: async ({ input, ctx: turn }) => `${actionTask(turn)}:${input.dir}#${input.number}:${input.threadId}:` +
+                `${await sha256(input.body ?? "")}:${input.resolve ?? true}`,
             execute: async ({ dir, number, threadId, body, resolve }) => {
-                const target = await forgeRepo(dir);
+                const target = await githubRepo(dir);
                 if ("refusal" in target)
-                    return target.refusal;
+                    throw new Error(target.refusal);
                 const { owner, repo } = decoded(target);
                 // A thread id is a global node id, so unlike every other tool here this
                 // one takes something that can name a pull request in a repository
-                // nobody checked out — the reach `forgeRepo` exists to prevent. Checked
+                // nobody checked out — the reach `githubRepo` exists to prevent. Checked
                 // rather than trusted: the id came from a tool result the model read,
                 // and a model that misremembers one must not write into a stranger's
                 // review.
-                const belongs = await forgeGraphql("repo_pr_thread_reply", THREAD_OWNER_QUERY, { id: threadId });
+                const belongs = await githubGraphql("repo_pr_thread_reply", THREAD_OWNER_QUERY, { id: threadId });
                 if (!belongs.ok)
-                    return bounded(belongs.message);
+                    throw new Error(bounded(belongs.message));
                 const node = belongs.data.node;
                 if (!node?.pullRequest)
-                    return `${threadId} is not a review thread — read the ids with repo_pr_threads`;
+                    throw new Error(`${threadId} is not a review thread — read the ids with repo_pr_threads`);
                 const at = node.pullRequest.repository?.nameWithOwner ?? "";
                 if (at.toLowerCase() !== `${owner}/${repo}`.toLowerCase() ||
                     node.pullRequest.number !== number)
-                    return (`${threadId} belongs to ${at}#${node.pullRequest.number}, not ${owner}/${repo}#${number}. ` +
+                    throw new Error(`${threadId} belongs to ${at}#${node.pullRequest.number}, not ${owner}/${repo}#${number}. ` +
                         `Read the ids for this pull request with repo_pr_threads.`);
                 // Resolve-only. The reply and the resolve are two calls, so they fail
                 // independently — and the tool that tells a caller "the reply landed,
@@ -341,19 +361,19 @@ export function reviewTools(ctx) {
                 // only route back is a second reply the reviewer has already read.
                 if (body === undefined) {
                     if (resolve === false)
-                        return "nothing to do: give a body to reply, or leave resolve unset to resolve the thread";
-                    const only = await forgeGraphql("repo_pr_thread_reply", THREAD_RESOLVE_MUTATION, { id: threadId });
-                    return only.ok
-                        ? `resolved ${threadId}`
-                        : bounded(`resolving the thread failed: ${only.message}`);
+                        throw new Error("nothing to do: give a body to reply, or leave resolve unset to resolve the thread");
+                    const only = await githubGraphql("repo_pr_thread_reply", THREAD_RESOLVE_MUTATION, { id: threadId });
+                    if (!only.ok)
+                        throw new Error(bounded(`resolving the thread failed: ${only.message}`));
+                    return `resolved ${threadId}`;
                 }
-                const replied = await forgeGraphql("repo_pr_thread_reply", THREAD_REPLY_MUTATION, { id: threadId, body });
+                const replied = await githubGraphql("repo_pr_thread_reply", THREAD_REPLY_MUTATION, { id: threadId, body });
                 if (!replied.ok)
                     // The hazard `repo_pr_comment` names, and worse here: a reply that
                     // landed and an answer that did not arrive look identical, and the
                     // retry leaves the reviewer two of them.
-                    return bounded(`${replied.message}\nIf this was a timeout rather than a rejection the ` +
-                        `reply may exist anyway — read the thread back with repo_pr_threads before retrying.`);
+                    throw new Error(bounded(`${replied.message}\nIf this was a timeout rather than a rejection the ` +
+                        `reply may exist anyway — read the thread back with repo_pr_threads before retrying.`));
                 const url = replied.data.addPullRequestReviewThreadReply?.comment?.url ?? "(no url)";
                 if (resolve === false)
                     return `replied: ${url} (left unresolved)`;
@@ -361,7 +381,7 @@ export function reviewTools(ctx) {
                 // thread that was answered and not resolved needs resolving, and one
                 // that was never answered needs answering. Saying "it failed" covers
                 // both and tells the model to do the wrong one.
-                const resolved = await forgeGraphql("repo_pr_thread_reply", THREAD_RESOLVE_MUTATION, { id: threadId });
+                const resolved = await githubGraphql("repo_pr_thread_reply", THREAD_RESOLVE_MUTATION, { id: threadId });
                 if (!resolved.ok)
                     return bounded(`replied: ${url}\nbut resolving the thread failed: ${resolved.message}\n` +
                         `The reply has landed — do not send it again. Call repo_pr_thread_reply on the same ` +

package/dist/repo/tools-worktree.js

@@ -4,7 +4,7 @@ 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, logFailure, plain, origin, pushBranch } = ctx;
+    const { author, bounded, config, fetchOrigin, logFailure, plain, origin, pushBranch } = ctx;
     return {
         repo_status: tool({
             description: "Show which files changed in the checkout.",
@@ -22,26 +22,72 @@ export function worktreeTools(ctx) {
             }
         }),
         repo_diff: tool({
-            description: "Show the current diff. Read this before committing — it is the cheapest way to catch an edit that did more than you intended. 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.",
+            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 }) => {
+            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(" ");
-                const result = await plain(`diff ${flags}`, dir);
+                // `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);
-                    return bounded(`could not read the diff in ${dir}: ${result.stderr || result.stdout}`);
+                    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
@@ -59,7 +105,7 @@ export function worktreeTools(ctx) {
             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 round reports a commit that quietly
+                // 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) {
@@ -89,13 +135,41 @@ export function worktreeTools(ctx) {
                 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. Refuses to push to a protected branch and refuses to force-push — open a pull request instead.",
+            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("Branch name to create and push, e.g. 'coder/add-json-flag'")
+                    .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
@@ -111,7 +185,7 @@ export function worktreeTools(ctx) {
                 // 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 two probes further down, and the reason
+                // 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)
@@ -124,6 +198,62 @@ export function worktreeTools(ctx) {
                     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
@@ -131,11 +261,6 @@ export function worktreeTools(ctx) {
                 // 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 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}`);
                 const checkout = await plain(exists.success
                     ? `checkout "$REPO_BRANCH"`
                     : `checkout -b "$REPO_BRANCH"`, dir, { REPO_BRANCH: branch });
@@ -143,56 +268,15 @@ export function worktreeTools(ctx) {
                     logFailure("repo_push", checkout);
                     return bounded(`could not switch to branch "${branch}": ${checkout.stderr || checkout.stdout}`);
                 }
-                // Nothing to push is a bug upstream of here, not a no-op.
-                //
-                // A branch level with the default branch means the commit went
-                // somewhere else, or was never made. Pushing it succeeds, `repo_open_pr`
-                // opens an empty pull request, and the round reports a URL as if the
-                // work had landed — the one outcome worse than an error.
-                //
-                // The guard is skipped only when there is no baseline to compare
-                // against: a repository with no `origin/HEAD` is unusual but legitimate,
-                // and guessing is worse than not guarding. Once there *is* one, a
-                // comparison that fails is an unanswered question rather than a pass —
-                // the same rule the three probes around this one follow.
-                if (defaultBranch) {
-                    const ahead = await plain(`rev-list --count "origin/$REPO_BASE..HEAD"`, dir, {
-                        REPO_BASE: defaultBranch
-                    });
-                    if (ahead.unreachable)
-                        return bounded(`could not push "${branch}": ${ahead.stderr}`);
-                    if (!ahead.success) {
-                        logFailure("repo_push", ahead);
-                        return bounded(`could not tell whether "${branch}" has anything to push: comparing it ` +
-                            `against origin/${defaultBranch} failed with ` +
-                            `${ahead.stderr || ahead.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 (ahead.stdout.trim() === "0") {
-                        return (`refusing to push "${branch}" — it has no commits that origin/${defaultBranch} ` +
-                            `does not already have, so the pull request would be empty. Check repo_status ` +
-                            `and repo_diff: either the change was never committed, or it was committed on ` +
-                            `a different branch.`);
-                    }
-                }
-                // A pre-flight check, not a value anyone downstream consumes: `push`
-                // takes the branch *name* and resolves it itself, against the same
-                // files. What this buys is the failure arriving here, where the sentence
-                // can name the branch and the checkout, instead of surfacing as a push
-                // that rejects a ref nobody can see.
-                const tip = await plain(`rev-parse --verify "refs/heads/$REPO_BRANCH"`, dir, { REPO_BRANCH: branch });
-                if (!tip.success || !tip.stdout.trim()) {
-                    logFailure("repo_push", tip);
-                    return bounded(`could not resolve "${branch}" to a commit: ${tip.stderr || tip.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 subagent reaching
+                // 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.
                 //
@@ -208,13 +292,13 @@ export function worktreeTools(ctx) {
                     // "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 ${branch}, but could not record what it tracks: ` +
+                    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 `pushed ${branch}`;
+                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