pi-graphite 0.0.1 → 0.1.0

package/src/tools/branch.ts

@@ -0,0 +1,352 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { runGt } from "../lib/exec";
+import { formatResult, renderText } from "../lib/result";
+import {
+  CwdParam,
+  StageMode,
+  StringEnum,
+  Type,
+  requireConfirm,
+  stageArgs,
+  type ToolReturn,
+} from "../lib/schema";
+
+/* --------------------------- branch_inspect --------------------------- */
+
+export function registerBranchInspect(pi: ExtensionAPI) {
+  pi.registerTool({
+    name: "graphite_branch_inspect",
+    label: "Graphite: branch inspect",
+    description:
+      "Inspect a branch: parent, children, PR body, diff, and diffstat. Read-only.",
+    promptSnippet:
+      "graphite_branch_inspect: read-only branch metadata + diff/patch/stat",
+    parameters: Type.Object({
+      cwd: CwdParam,
+      branch: Type.Optional(Type.String({ description: "Branch to inspect (default current)." })),
+      include: Type.Optional(
+        Type.Array(StringEnum(["body", "diff", "patch", "stat"] as const), {
+          description:
+            "Pass to `gt info`. `diff` and `patch` are mutually exclusive (diff wins). `stat` modifies diff/patch.",
+        }),
+      ),
+      withParentChildren: Type.Optional(
+        Type.Boolean({ description: "Also run `gt parent` and `gt children`." }),
+      ),
+    }),
+    async execute(_id, p, signal): Promise<ToolReturn> {
+      const infoArgs = ["info"];
+      if (p.branch) infoArgs.push(p.branch);
+      const inc = new Set(p.include ?? []);
+      if (inc.has("body")) infoArgs.push("--body");
+      if (inc.has("diff")) infoArgs.push("--diff");
+      else if (inc.has("patch")) infoArgs.push("--patch");
+      if (inc.has("stat")) infoArgs.push("--stat");
+
+      const tasks: Promise<unknown>[] = [runGt(infoArgs, { cwd: p.cwd, signal })];
+      if (p.withParentChildren) {
+        tasks.push(runGt(["parent"], { cwd: p.cwd, signal }));
+        tasks.push(runGt(["children"], { cwd: p.cwd, signal }));
+      }
+      const [info, parent, children] = (await Promise.all(tasks)) as Awaited<
+        ReturnType<typeof runGt>
+      >[];
+
+      const blocks: string[] = [renderText(`gt ${infoArgs.join(" ")}`, formatResult(info))];
+      if (parent) blocks.push(renderText("gt parent", formatResult(parent)));
+      if (children) blocks.push(renderText("gt children", formatResult(children)));
+
+      return {
+        content: [{ type: "text", text: blocks.join("\n\n") }],
+        details: {
+          info: formatResult(info),
+          parent: parent ? formatResult(parent) : undefined,
+          children: children ? formatResult(children) : undefined,
+        },
+      };
+    },
+  });
+}
+
+/* --------------------------- branch_create --------------------------- */
+
+export function registerBranchCreate(pi: ExtensionAPI) {
+  pi.registerTool({
+    name: "graphite_branch_create",
+    label: "Graphite: branch create",
+    description:
+      "Create a new branch stacked on top of the current (or `onto`) branch and commit staged changes. Local mutation.",
+    promptSnippet:
+      "graphite_branch_create: `gt create` with explicit message + stage mode",
+    promptGuidelines: [
+      "When using graphite_branch_create, always provide `message` unless the user explicitly asked for AI-generated metadata.",
+    ],
+    parameters: Type.Object({
+      cwd: CwdParam,
+      message: Type.Optional(
+        Type.String({ description: "Commit message. Required unless ai=true." }),
+      ),
+      name: Type.Optional(Type.String({ description: "Branch name (default generated)." })),
+      stage: Type.Optional(StageMode),
+      onto: Type.Optional(Type.String({ description: "Create on top of this branch instead of HEAD (--onto)." })),
+      insert: Type.Optional(
+        Type.Boolean({ description: "Insert between current branch and its child (--insert)." }),
+      ),
+      ai: Type.Optional(
+        Type.Boolean({ description: "Use AI to generate branch name + message (--ai). Default false (--no-ai)." }),
+      ),
+    }),
+    async execute(_id, p, signal): Promise<ToolReturn> {
+      if (!p.ai && !p.message) {
+        throw new Error("graphite_branch_create requires `message` unless ai=true.");
+      }
+      const args = ["create"];
+      if (p.name) args.push(p.name);
+      if (p.message) args.push("--message", p.message);
+      args.push(...stageArgs((p.stage ?? "none") as "none" | "all" | "update" | "patch"));
+      if (p.onto) args.push("--onto", p.onto);
+      if (p.insert) args.push("--insert");
+      args.push(p.ai ? "--ai" : "--no-ai");
+      const r = await runGt(args, { cwd: p.cwd, signal });
+      const f = formatResult(r);
+      return {
+        content: [{ type: "text", text: renderText(`gt ${args.join(" ")}`, f) }],
+        details: { result: f },
+      };
+    },
+  });
+}
+
+/* --------------------------- branch_update --------------------------- */
+
+export function registerBranchUpdate(pi: ExtensionAPI) {
+  pi.registerTool({
+    name: "graphite_branch_update",
+    label: "Graphite: branch update",
+    description:
+      "Mutate the current (or named) branch: amend, add a new commit, absorb staged hunks, squash, pop, rename, or delete. Auto-restacks descendants where applicable.",
+    promptSnippet:
+      "graphite_branch_update: amend/new_commit/absorb/squash/pop/rename/delete on a branch",
+    promptGuidelines: [
+      "Use graphite_branch_update with action=absorb (dryRun:true first) to distribute staged hunks across downstack commits.",
+      "graphite_branch_update with action=delete and close:true requires confirmRemote.",
+    ],
+    parameters: Type.Object({
+      cwd: CwdParam,
+      action: StringEnum([
+        "amend",
+        "new_commit",
+        "absorb",
+        "squash",
+        "pop",
+        "rename",
+        "delete",
+      ] as const),
+      message: Type.Optional(Type.String()),
+      stage: Type.Optional(StageMode),
+      into: Type.Optional(
+        Type.String({ description: "action=amend: amend into a downstack branch (`gt modify --into`)." }),
+      ),
+      edit: Type.Optional(Type.Boolean({ description: "Open editor for commit message." })),
+      resetAuthor: Type.Optional(Type.Boolean({ description: "action=amend: reset commit author." })),
+      newName: Type.Optional(Type.String({ description: "action=rename: new branch name." })),
+      branch: Type.Optional(Type.String({ description: "action=delete: branch name to delete." })),
+      force: Type.Optional(Type.Boolean({ description: "action=delete or rename: force." })),
+      close: Type.Optional(
+        Type.Boolean({ description: "action=delete: also close associated PR (requires confirmRemote)." }),
+      ),
+      downstack: Type.Optional(Type.Boolean({ description: "action=delete: also delete ancestors." })),
+      upstack: Type.Optional(Type.Boolean({ description: "action=delete: also delete descendants." })),
+      dryRun: Type.Optional(
+        Type.Boolean({ description: "action=absorb: dry-run only (default true)." }),
+      ),
+      patch: Type.Optional(Type.Boolean({ description: "action=absorb: pick hunks (--patch)." })),
+      confirmRemote: Type.Optional(Type.Boolean()),
+    }),
+    async execute(_id, p, signal): Promise<ToolReturn> {
+      let args: string[];
+
+      switch (p.action) {
+        case "amend": {
+          args = ["modify"];
+          args.push(...stageArgs((p.stage ?? "none") as "none" | "all" | "update" | "patch"));
+          if (p.message) args.push("--message", p.message);
+          if (p.edit) args.push("--edit");
+          if (p.resetAuthor) args.push("--reset-author");
+          if (p.into) args.push("--into", p.into);
+          break;
+        }
+        case "new_commit": {
+          if (!p.message && !p.edit) {
+            throw new Error("action=new_commit requires `message` or edit=true.");
+          }
+          args = ["modify", "--commit"];
+          args.push(...stageArgs((p.stage ?? "none") as "none" | "all" | "update" | "patch"));
+          if (p.message) args.push("--message", p.message);
+          if (p.edit) args.push("--edit");
+          break;
+        }
+        case "absorb": {
+          const dryRun = p.dryRun !== false; // default true
+          args = ["absorb"];
+          if (dryRun) args.push("--dry-run");
+          else args.push("--force");
+          const stage = (p.stage ?? "none") as "none" | "all" | "update" | "patch";
+          if (stage === "all") args.push("--all");
+          if (p.patch) args.push("--patch");
+          break;
+        }
+        case "squash": {
+          args = ["squash"];
+          if (p.message) args.push("--message", p.message);
+          if (p.edit) args.push("--edit");
+          break;
+        }
+        case "pop": {
+          args = ["pop"];
+          break;
+        }
+        case "rename": {
+          if (!p.newName) throw new Error("action=rename requires `newName`.");
+          args = ["rename", p.newName];
+          if (p.force) args.push("--force");
+          break;
+        }
+        case "delete": {
+          if (p.close) requireConfirm(p.confirmRemote, "delete --close (closes PR on GitHub)");
+          args = ["delete"];
+          if (p.branch) args.push(p.branch);
+          if (p.force) args.push("--force");
+          if (p.close) args.push("--close");
+          if (p.downstack) args.push("--downstack");
+          if (p.upstack) args.push("--upstack");
+          break;
+        }
+      }
+
+      const r = await runGt(args, { cwd: p.cwd, signal });
+      const f = formatResult(r);
+      return {
+        content: [{ type: "text", text: renderText(`gt ${args.join(" ")}`, f) }],
+        details: { action: p.action, result: f },
+      };
+    },
+  });
+}
+
+/* --------------------------- branch_tracking --------------------------- */
+
+export function registerBranchTracking(pi: ExtensionAPI) {
+  pi.registerTool({
+    name: "graphite_branch_tracking",
+    label: "Graphite: branch tracking",
+    description:
+      "Track / untrack a branch with Graphite, or freeze / unfreeze to prevent local modifications.",
+    promptSnippet:
+      "graphite_branch_tracking: track/untrack/freeze/unfreeze a branch",
+    parameters: Type.Object({
+      cwd: CwdParam,
+      action: StringEnum(["track", "untrack", "freeze", "unfreeze"] as const),
+      branch: Type.Optional(Type.String()),
+      parent: Type.Optional(
+        Type.String({ description: "action=track: explicit parent branch." }),
+      ),
+      force: Type.Optional(Type.Boolean()),
+    }),
+    async execute(_id, p, signal): Promise<ToolReturn> {
+      let args: string[];
+      switch (p.action) {
+        case "track":
+          args = ["track"];
+          if (p.branch) args.push(p.branch);
+          if (p.parent) args.push("--parent", p.parent);
+          if (p.force) args.push("--force");
+          break;
+        case "untrack":
+          args = ["untrack"];
+          if (p.branch) args.push(p.branch);
+          if (p.force) args.push("--force");
+          break;
+        case "freeze":
+          args = ["freeze"];
+          if (p.branch) args.push(p.branch);
+          break;
+        case "unfreeze":
+          args = ["unfreeze"];
+          if (p.branch) args.push(p.branch);
+          break;
+      }
+      const r = await runGt(args, { cwd: p.cwd, signal });
+      const f = formatResult(r);
+      return {
+        content: [{ type: "text", text: renderText(`gt ${args.join(" ")}`, f) }],
+        details: { action: p.action, result: f },
+      };
+    },
+  });
+}
+
+/* --------------------------- branch_navigate --------------------------- */
+
+export function registerBranchNavigate(pi: ExtensionAPI) {
+  pi.registerTool({
+    name: "graphite_branch_navigate",
+    label: "Graphite: navigate",
+    description:
+      "Navigate the current stack: checkout a branch, move up/down N levels, or jump to top/bottom.",
+    promptSnippet:
+      "graphite_branch_navigate: checkout/up/down/top/bottom across the stack",
+    parameters: Type.Object({
+      cwd: CwdParam,
+      action: StringEnum(["checkout", "up", "down", "top", "bottom"] as const),
+      branch: Type.Optional(Type.String({ description: "action=checkout: branch to checkout." })),
+      steps: Type.Optional(Type.Integer({ minimum: 1, description: "action=up|down step count." })),
+      to: Type.Optional(
+        Type.String({ description: "action=up: target descendant when multiple children exist (--to)." }),
+      ),
+      showAllTrunks: Type.Optional(Type.Boolean({ description: "action=checkout: --all." })),
+      showUntracked: Type.Optional(Type.Boolean({ description: "action=checkout: --show-untracked." })),
+      stackOnly: Type.Optional(Type.Boolean({ description: "action=checkout: only stack branches (--stack)." })),
+      checkoutTrunk: Type.Optional(Type.Boolean({ description: "action=checkout: jump to trunk (--trunk)." })),
+    }),
+    async execute(_id, p, signal): Promise<ToolReturn> {
+      let args: string[];
+      switch (p.action) {
+        case "checkout":
+          args = ["checkout"];
+          if (p.branch) args.push(p.branch);
+          if (p.showAllTrunks) args.push("--all");
+          if (p.showUntracked) args.push("--show-untracked");
+          if (p.stackOnly) args.push("--stack");
+          if (p.checkoutTrunk) args.push("--trunk");
+          if (!p.branch && !p.checkoutTrunk) {
+            throw new Error(
+              "action=checkout requires `branch` or `checkoutTrunk:true` (interactive selector disabled).",
+            );
+          }
+          break;
+        case "up":
+          args = ["up"];
+          if (p.steps != null) args.push("--steps", String(p.steps));
+          if (p.to) args.push("--to", p.to);
+          break;
+        case "down":
+          args = ["down"];
+          if (p.steps != null) args.push("--steps", String(p.steps));
+          break;
+        case "top":
+          args = ["top"];
+          break;
+        case "bottom":
+          args = ["bottom"];
+          break;
+      }
+      const r = await runGt(args, { cwd: p.cwd, signal });
+      const f = formatResult(r);
+      return {
+        content: [{ type: "text", text: renderText(`gt ${args.join(" ")}`, f) }],
+        details: { action: p.action, result: f },
+      };
+    },
+  });
+}

package/src/tools/pr.ts

@@ -0,0 +1,179 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { runGt } from "../lib/exec";
+import { formatResult, renderText } from "../lib/result";
+import {
+  CwdParam,
+  StringEnum,
+  Type,
+  requireConfirm,
+  type ToolReturn,
+} from "../lib/schema";
+
+/* ------------------------------ pr_submit ------------------------------ */
+
+export function registerPrSubmit(pi: ExtensionAPI) {
+  pi.registerTool({
+    name: "graphite_pr_submit",
+    label: "Graphite: PR submit",
+    description:
+      "Submit branches as pull requests via `gt submit`. Defaults to a dry-run plan; set apply:true (with confirmRemote:true) to actually push and create/update PRs.",
+    promptSnippet:
+      "graphite_pr_submit: plan or apply `gt submit` for a branch or stack",
+    promptGuidelines: [
+      "Always call graphite_pr_submit with apply:false (default) first to see the dry-run plan, then call again with apply:true and confirmRemote:true to actually submit.",
+    ],
+    parameters: Type.Object({
+      cwd: CwdParam,
+      apply: Type.Optional(
+        Type.Boolean({
+          description: "false => --dry-run (default). true => actually push (requires confirmRemote).",
+        }),
+      ),
+      stack: Type.Optional(
+        Type.Boolean({
+          description:
+            "true => --stack (include descendants). false => --no-stack. Omitted => default (gt prompts based on config).",
+        }),
+      ),
+      branch: Type.Optional(Type.String({ description: "Run from this branch (--branch)." })),
+      updateOnly: Type.Optional(Type.Boolean({ description: "--update-only" })),
+      draft: Type.Optional(Type.Boolean({ description: "--draft for new PRs" })),
+      publish: Type.Optional(Type.Boolean({ description: "--publish all PRs" })),
+      mergeWhenReady: Type.Optional(Type.Boolean({ description: "--merge-when-ready" })),
+      rerequestReview: Type.Optional(Type.Boolean()),
+      reviewers: Type.Optional(Type.Array(Type.String(), { description: "User reviewers (--reviewers)." })),
+      teamReviewers: Type.Optional(Type.Array(Type.String())),
+      comment: Type.Optional(Type.String({ description: "--comment <msg>" })),
+      targetTrunk: Type.Optional(Type.String()),
+      editMode: Type.Optional(
+        StringEnum(["none", "cli", "web"] as const, {
+          description:
+            "none (default) => --no-edit; cli => --edit --cli; web => --web. Affects PR metadata prompting.",
+        }),
+      ),
+      ai: Type.Optional(
+        Type.Boolean({
+          description: "true => --ai (let gt generate PR title/body). Default false (--no-ai).",
+        }),
+      ),
+      forcePush: Type.Optional(
+        Type.Boolean({ description: "--force (instead of default --force-with-lease). Requires confirmRemote." }),
+      ),
+      ignoreOutOfSyncTrunk: Type.Optional(Type.Boolean()),
+      view: Type.Optional(Type.Boolean({ description: "--view (open PR in browser after submit)." })),
+      confirmRemote: Type.Optional(Type.Boolean()),
+    }),
+    async execute(_id, p, signal): Promise<ToolReturn> {
+      const apply = p.apply === true;
+      if (apply) requireConfirm(p.confirmRemote, "gt submit (push branches + create/update PRs)");
+      if (p.forcePush) requireConfirm(p.confirmRemote, "gt submit --force");
+
+      const args: string[] = ["submit"];
+      if (!apply) args.push("--dry-run");
+
+      if (p.stack === true) args.push("--stack");
+      else if (p.stack === false) args.push("--no-stack");
+
+      if (p.branch) args.push("--branch", p.branch);
+      if (p.updateOnly) args.push("--update-only");
+      if (p.draft) args.push("--draft");
+      if (p.publish) args.push("--publish");
+      if (p.mergeWhenReady) args.push("--merge-when-ready");
+      if (p.rerequestReview) args.push("--rerequest-review");
+
+      if (p.reviewers && p.reviewers.length)
+        args.push("--reviewers", p.reviewers.join(","));
+      if (p.teamReviewers && p.teamReviewers.length)
+        args.push("--team-reviewers", p.teamReviewers.join(","));
+      if (p.comment) args.push("--comment", p.comment);
+      if (p.targetTrunk) args.push("--target-trunk", p.targetTrunk);
+
+      const editMode = p.editMode ?? "none";
+      if (editMode === "none") args.push("--no-edit");
+      else if (editMode === "cli") args.push("--edit", "--cli");
+      else if (editMode === "web") args.push("--web");
+
+      args.push(p.ai ? "--ai" : "--no-ai");
+
+      if (p.forcePush) args.push("--force");
+      if (p.ignoreOutOfSyncTrunk) args.push("--ignore-out-of-sync-trunk");
+      if (p.view) args.push("--view");
+
+      const r = await runGt(args, { cwd: p.cwd, signal });
+      const f = formatResult(r);
+      return {
+        content: [{ type: "text", text: renderText(`gt ${args.join(" ")}`, f) }],
+        details: { apply, result: f },
+      };
+    },
+  });
+}
+
+/* ----------------------------- pr_lifecycle ----------------------------- */
+
+export function registerPrLifecycle(pi: ExtensionAPI) {
+  pi.registerTool({
+    name: "graphite_pr_lifecycle",
+    label: "Graphite: PR lifecycle",
+    description:
+      "PR lifecycle actions: open the PR/stack page in a browser, merge the stack via Graphite, or unlink a branch from its PR.",
+    promptSnippet:
+      "graphite_pr_lifecycle: open_url | merge | unlink for a PR/branch",
+    parameters: Type.Object({
+      cwd: CwdParam,
+      action: StringEnum(["open_url", "merge", "unlink"] as const),
+      branch: Type.Optional(Type.String({ description: "Branch name or PR number." })),
+      stack: Type.Optional(
+        Type.Boolean({ description: "action=open_url: open stack page (--stack)." }),
+      ),
+      apply: Type.Optional(
+        Type.Boolean({
+          description: "action=merge: false (default) => --dry-run; true => actually merge (requires confirmRemote).",
+        }),
+      ),
+      confirm: Type.Optional(
+        Type.Boolean({
+          description: "action=merge: pass --confirm so gt prompts before merging each branch.",
+        }),
+      ),
+      confirmRemote: Type.Optional(Type.Boolean()),
+    }),
+    async execute(_id, p, signal): Promise<ToolReturn> {
+      if (p.action === "open_url") {
+        const args = ["pr"];
+        if (p.branch) args.push(p.branch);
+        if (p.stack) args.push("--stack");
+        const r = await runGt(args, { cwd: p.cwd, signal });
+        const f = formatResult(r);
+        return {
+          content: [{ type: "text", text: renderText(`gt ${args.join(" ")}`, f) }],
+          details: { result: f },
+        };
+      }
+
+      if (p.action === "merge") {
+        const apply = p.apply === true;
+        if (apply) requireConfirm(p.confirmRemote, "gt merge (merges PRs on GitHub)");
+        const args = ["merge"];
+        if (!apply) args.push("--dry-run");
+        if (p.confirm) args.push("--confirm");
+        const r = await runGt(args, { cwd: p.cwd, signal });
+        const f = formatResult(r);
+        return {
+          content: [{ type: "text", text: renderText(`gt ${args.join(" ")}`, f) }],
+          details: { apply, result: f },
+        };
+      }
+
+      // unlink
+      const args = ["unlink"];
+      if (p.branch) args.push(p.branch);
+      const r = await runGt(args, { cwd: p.cwd, signal });
+      const f = formatResult(r);
+      return {
+        content: [{ type: "text", text: renderText(`gt ${args.join(" ")}`, f) }],
+        details: { result: f },
+      };
+    },
+  });
+}

package/src/tools/recovery.ts

@@ -0,0 +1,52 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { runGt } from "../lib/exec";
+import { formatResult, renderText } from "../lib/result";
+import { CwdParam, StringEnum, Type, type ToolReturn } from "../lib/schema";
+
+export function registerRecovery(pi: ExtensionAPI) {
+  pi.registerTool({
+    name: "graphite_recovery",
+    label: "Graphite: recovery",
+    description:
+      "Recover from conflicts or mistakes: continue a halted command, abort it, or undo the most recent Graphite mutation in this worktree.",
+    promptSnippet:
+      "graphite_recovery: continue / abort / undo Graphite commands",
+    promptGuidelines: [
+      "After resolving a rebase conflict, run graphite_recovery action=continue to resume the original gt command.",
+      "graphite_recovery action=undo only undoes commands run from the current worktree.",
+    ],
+    parameters: Type.Object({
+      cwd: CwdParam,
+      action: StringEnum(["continue", "abort", "undo"] as const),
+      stageAll: Type.Optional(
+        Type.Boolean({ description: "action=continue: stage all changes first (--all)." }),
+      ),
+      force: Type.Optional(
+        Type.Boolean({ description: "action=abort|undo: skip confirmation prompt (--force)." }),
+      ),
+    }),
+    async execute(_id, p, signal): Promise<ToolReturn> {
+      let args: string[];
+      switch (p.action) {
+        case "continue":
+          args = ["continue"];
+          if (p.stageAll) args.push("--all");
+          break;
+        case "abort":
+          args = ["abort"];
+          if (p.force) args.push("--force");
+          break;
+        case "undo":
+          args = ["undo"];
+          if (p.force) args.push("--force");
+          break;
+      }
+      const r = await runGt(args, { cwd: p.cwd, signal });
+      const f = formatResult(r);
+      return {
+        content: [{ type: "text", text: renderText(`gt ${args.join(" ")}`, f) }],
+        details: { action: p.action, result: f },
+      };
+    },
+  });
+}

package/src/tools/remote.ts

@@ -0,0 +1,107 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { runGt } from "../lib/exec";
+import { formatResult, renderText } from "../lib/result";
+import {
+  CwdParam,
+  StringEnum,
+  Type,
+  requireConfirm,
+  type ToolReturn,
+} from "../lib/schema";
+
+export function registerRemoteSync(pi: ExtensionAPI) {
+  pi.registerTool({
+    name: "graphite_remote_sync",
+    label: "Graphite: remote sync",
+    description:
+      "Sync local branches with remote: `gt sync` (pull trunk + restack + cleanup) or `gt get` (fetch a branch / PR locally).",
+    promptSnippet:
+      "graphite_remote_sync: `gt sync` for cleanup+restack, or `gt get` to import a branch/PR",
+    promptGuidelines: [
+      "Run graphite_remote_sync action=sync at the start of a session to update trunk and restack open stacks.",
+      "graphite_remote_sync action=sync with force=true or deleteAll=true is destructive; pass confirmDestructive:true.",
+    ],
+    parameters: Type.Object({
+      cwd: CwdParam,
+      action: StringEnum(["sync", "get"] as const),
+
+      // sync
+      allTrunks: Type.Optional(Type.Boolean({ description: "sync: --all" })),
+      deleteAll: Type.Optional(
+        Type.Boolean({
+          description:
+            "sync|get: delete all merged/closed branches without prompting (--delete-all). Requires confirmDestructive.",
+        }),
+      ),
+      force: Type.Optional(
+        Type.Boolean({
+          description:
+            "sync|get: overwrite local branches with remote (--force). Requires confirmDestructive.",
+        }),
+      ),
+      restack: Type.Optional(
+        Type.Boolean({
+          description: "sync|get: restack after fetching (default true; pass false for --no-restack).",
+        }),
+      ),
+
+      // get
+      target: Type.Optional(
+        Type.String({ description: "get: branch name or PR number to fetch." }),
+      ),
+      downstack: Type.Optional(
+        Type.Boolean({ description: "get: --downstack (don't sync upstack)." }),
+      ),
+      remoteUpstack: Type.Optional(
+        Type.Boolean({ description: "get: --remote-upstack (include remote-only upstack)." }),
+      ),
+      checkout: Type.Optional(
+        Type.Boolean({ description: "get: check out target after sync (default true; false => --no-checkout)." }),
+      ),
+      unfrozen: Type.Optional(
+        Type.Boolean({ description: "get: --unfrozen (new branches editable)." }),
+      ),
+
+      confirmDestructive: Type.Optional(Type.Boolean()),
+    }),
+    async execute(_id, p, signal): Promise<ToolReturn> {
+      const args: string[] = [p.action];
+
+      if (p.action === "sync") {
+        if (p.force || p.deleteAll) {
+          requireConfirm(
+            p.confirmDestructive,
+            "gt sync with --force/--delete-all (may overwrite branches)",
+          );
+        }
+        if (p.allTrunks) args.push("--all");
+        if (p.deleteAll) args.push("--delete-all");
+        if (p.force) args.push("--force");
+        if (p.restack === false) args.push("--no-restack");
+      } else {
+        if (!p.target) throw new Error("action=get requires `target` (branch name or PR number).");
+        args.push(p.target);
+        if (p.downstack) args.push("--downstack");
+        if (p.remoteUpstack) args.push("--remote-upstack");
+        if (p.force) {
+          requireConfirm(p.confirmDestructive, "gt get --force (overwrites local branches)");
+          args.push("--force");
+        }
+        if (p.deleteAll) {
+          requireConfirm(p.confirmDestructive, "gt get --delete-all");
+          args.push("--delete-all");
+        }
+        if (p.checkout === false) args.push("--no-checkout");
+        if (p.restack === false) args.push("--no-restack");
+        if (p.unfrozen) args.push("--unfrozen");
+      }
+
+      const r = await runGt(args, { cwd: p.cwd, signal });
+      const f = formatResult(r);
+      return {
+        content: [{ type: "text", text: renderText(`gt ${args.join(" ")}`, f) }],
+        details: { action: p.action, result: f },
+      };
+    },
+  });
+}