pi-graphite 0.1.1 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-graphite",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Structured pi tools for the Graphite (gt) CLI.",
   "keywords": [
     "pi",

package/src/lib/exec.ts

@@ -28,6 +28,14 @@ export function stripAnsi(s: string): string {
   return s.replace(ANSI, "");
 }
 
+/**
+ * Replace Graphite's internal product name "Charcoal" with "Graphite" so
+ * users and the LLM see a consistent product name. Casing is preserved.
+ */
+export function sanitizeBranding(s: string): string {
+  return s.replace(/charcoal/gi, (m) => (m[0] === m[0].toUpperCase() ? "Graphite" : "graphite"));
+}
+
 export function truncateOutput(s: string): string {
   if (s.length <= MAX_BYTES) {
     const lines = s.split("\n");
@@ -109,8 +117,8 @@ export async function runGt(
         args,
         cwd,
         exitCode: -1,
-        stdout: stripAnsi(stdout),
-        stderr: stripAnsi(stderr),
+        stdout: sanitizeBranding(stripAnsi(stdout)),
+        stderr: sanitizeBranding(stripAnsi(stderr)),
         timedOut: false,
         spawnError: err.message,
       });
@@ -123,8 +131,8 @@ export async function runGt(
         args,
         cwd,
         exitCode: code ?? -1,
-        stdout: truncateOutput(stripAnsi(stdout)),
-        stderr: truncateOutput(stripAnsi(stderr)),
+        stdout: truncateOutput(sanitizeBranding(stripAnsi(stdout))),
+        stderr: truncateOutput(sanitizeBranding(stripAnsi(stderr))),
         timedOut: killed,
       });
     });

package/src/lib/result.ts

@@ -1,5 +1,10 @@
+import { spawn } from "node:child_process";
 import type { GtRunResult } from "./exec";
 
+/**
+ * Structured failure hints. Only populated when the underlying `gt` command
+ * exited non-zero. Never inferred from successful output.
+ */
 export interface GtHints {
   notInGitRepo?: boolean;
   notInitialized?: boolean;
@@ -11,58 +16,104 @@ export interface GtHints {
   branchNotTracked?: boolean;
   noChangesStaged?: boolean;
   prMissing?: boolean;
+  operatingOnTrunk?: boolean;
+  invalidArgument?: string;
 }
 
-const PATTERNS: Array<[keyof GtHints | "checkedOutElsewhere", RegExp]> = [
-  ["notInGitRepo", /not (a|in a) git repository/i],
-  ["notInitialized", /run\s+`?gt\s+init`?|graphite (is )?not (yet )?initialized/i],
-  ["notAuthenticated", /run\s+`?gt\s+auth`?|auth token|not authenticated|unauthorized/i],
-  ["conflictHalted", /merge\s+conflict|rebase\s+conflict|halted|run\s+`?gt\s+continue`?/i],
-  ["restackNeeded", /needs?\s+to\s+be\s+restacked|run\s+`?gt\s+restack`?/i],
-  ["trunkOutOfSync", /trunk\s+is\s+out\s+of\s+sync|out\s+of\s+sync\s+trunk/i],
-  ["branchNotTracked", /not\s+tracked\s+by\s+graphite|untracked\s+branch/i],
-  ["noChangesStaged", /no\s+(staged\s+)?changes\s+to\s+(commit|amend)/i],
-  ["prMissing", /no\s+pull\s+request|pr\s+not\s+found/i],
-  ["checkedOutElsewhere", /checked\s+out\s+in\s+(another|the)\s+worktree/i],
+// Patterns run only on failure text.
+const PATTERNS: Array<[Exclude<keyof GtHints, "checkedOutElsewhere" | "invalidArgument">, RegExp]> = [
+  [
+    "notInGitRepo",
+    /(?:fatal|ERROR)[^\n]*not\s+(?:a|in a)\s+git\s+repository|No \.git repository found/i,
+  ],
+  [
+    "notInitialized",
+    // Output is sanitized before hint parsing, so Charcoal is replaced with
+    // Graphite. We still allow the original spelling defensively in case the
+    // sanitizer is bypassed.
+    /Graphite has not been initialized|Charcoal has not been initialized|graphite is not (?:yet )?initialized|run\s+`?gt\s+init`?/i,
+  ],
+  [
+    "notAuthenticated",
+    /Run\s+`?gt\s+auth`?|invalid auth token|unauthorized|please log in|missing auth token/i,
+  ],
+  [
+    "conflictHalted",
+    /merge\s+conflict|rebase\s+conflict|halted\s+by|run\s+`?gt\s+continue`?|gt\s+abort/i,
+  ],
+  [
+    "restackNeeded",
+    /needs?\s+to\s+be\s+restacked|run\s+`?gt\s+restack`?|stack\s+is\s+out\s+of\s+date/i,
+  ],
+  [
+    "trunkOutOfSync",
+    /trunk\s+is\s+out\s+of\s+sync|--ignore-out-of-sync-trunk/i,
+  ],
+  [
+    "branchNotTracked",
+    /not\s+tracked\s+by\s+graphite|on\s+(?:an\s+)?untracked\s+branch|Cannot perform this operation on (?:an\s+)?untracked/i,
+  ],
+  [
+    "noChangesStaged",
+    /no\s+(?:staged\s+)?changes\s+to\s+(?:commit|amend)/i,
+  ],
+  [
+    "prMissing",
+    /no\s+pull\s+request|PR\s+not\s+found|branch\s+has\s+no\s+associated\s+pull\s+request/i,
+  ],
+  [
+    "operatingOnTrunk",
+    /Cannot perform this operation on the trunk branch/i,
+  ],
 ];
 
-export function parseHints(r: GtRunResult): GtHints {
+function parseHints(r: GtRunResult): GtHints {
   const text = `${r.stdout}\n${r.stderr}`;
   const hints: GtHints = {};
   for (const [key, re] of PATTERNS) {
-    if (re.test(text)) {
-      if (key === "checkedOutElsewhere") {
-        const m = text.match(/branch\s+`?([^\s`'"]+)`?[^\n]*checked\s+out\s+in[^\n]*?(\S+\/[^\s)]+)?/i);
-        hints.checkedOutElsewhere = { branch: m?.[1], worktree: m?.[2] };
-      } else {
-        (hints as Record<string, unknown>)[key] = true;
-      }
-    }
+    if (re.test(text)) (hints as Record<string, unknown>)[key] = true;
+  }
+  if (/checked\s+out\s+in\s+(?:another|the)\s+worktree/i.test(text)) {
+    const m = text.match(
+      /branch\s+`?([^\s`'"]+)`?[^\n]*?checked\s+out\s+in[^\n]*?(\/[^\s)]+)?/i,
+    );
+    hints.checkedOutElsewhere = { branch: m?.[1], worktree: m?.[2] };
   }
+  const invalid = text.match(/Unknown argument:\s*([^\n]+)/i);
+  if (invalid) hints.invalidArgument = invalid[1].trim();
   return hints;
 }
 
 export interface FormattedResult {
   ok: boolean;
+  isFailure: boolean;
   result: GtRunResult;
+  /** Empty object on success. Populated only on failure. */
   hints: GtHints;
+  /** Recovery suggestion derived from hints + auxiliary probes. */
+  suggestion?: string;
 }
 
 export function formatResult(r: GtRunResult): FormattedResult {
+  const isFailure = r.exitCode !== 0 || r.timedOut || !!r.spawnError;
   return {
-    ok: r.exitCode === 0 && !r.spawnError && !r.timedOut,
+    ok: !isFailure,
+    isFailure,
     result: r,
-    hints: parseHints(r),
+    hints: isFailure ? parseHints(r) : {},
   };
 }
 
-/** Render a formatted result into a single text block for the LLM. */
+/** Render a formatted result into a single text block. */
 export function renderText(label: string, f: FormattedResult): string {
   const r = f.result;
   const lines: string[] = [];
   lines.push(`$ gt ${r.args.join(" ")}`);
-  lines.push(`# cwd=${r.cwd}  exit=${r.exitCode}${r.timedOut ? "  (aborted)" : ""}`);
-  if (r.spawnError) lines.push(`# spawn-error: ${r.spawnError}`);
+  lines.push(
+    `# cwd=${r.cwd}  exit=${r.exitCode}${r.timedOut ? "  (aborted)" : ""}${
+      r.spawnError ? `  (spawn-error: ${r.spawnError})` : ""
+    }`,
+  );
   if (r.stdout.trim()) {
     lines.push("--- stdout ---");
     lines.push(r.stdout.replace(/\s+$/, ""));
@@ -71,10 +122,155 @@ export function renderText(label: string, f: FormattedResult): string {
     lines.push("--- stderr ---");
     lines.push(r.stderr.replace(/\s+$/, ""));
   }
-  const hintKeys = Object.keys(f.hints);
-  if (hintKeys.length) {
+  if (f.isFailure && Object.keys(f.hints).length) {
     lines.push("--- hints ---");
     lines.push(JSON.stringify(f.hints));
   }
+  if (f.isFailure && f.suggestion) {
+    lines.push("--- suggestion ---");
+    lines.push(f.suggestion);
+  }
   return `[${label}] ${f.ok ? "ok" : "fail"}\n${lines.join("\n")}`;
 }
+
+/* ----------------------- auxiliary probes (best-effort) ----------------------- */
+
+function execText(cmd: string, args: string[], cwd: string): Promise<string> {
+  return new Promise((resolve) => {
+    let out = "";
+    let child;
+    try {
+      child = spawn(cmd, args, { cwd, stdio: ["ignore", "pipe", "ignore"] });
+    } catch {
+      resolve("");
+      return;
+    }
+    child.stdout.on("data", (d) => {
+      out += d.toString();
+      if (out.length > 4096) out = out.slice(-4096);
+    });
+    child.on("error", () => resolve(""));
+    child.on("close", () => resolve(out));
+  });
+}
+
+async function detectCurrentBranch(cwd: string): Promise<string | undefined> {
+  const t = (await execText("git", ["-C", cwd, "branch", "--show-current"], cwd)).trim();
+  return t || undefined;
+}
+
+async function detectTrunk(cwd: string): Promise<string | undefined> {
+  const out = await execText("gt", ["--cwd", cwd, "--no-interactive", "trunk"], cwd);
+  // gt trunk prints the trunk name on its own line. Take last non-empty line.
+  const cleaned = out
+    .replace(/\x1b\[[0-9;]*[a-zA-Z]/g, "")
+    .replace(/charcoal/gi, (m) => (m[0] === m[0].toUpperCase() ? "Graphite" : "graphite"));
+  const line = cleaned
+    .split("\n")
+    .map((s) => s.trim())
+    .filter(Boolean)
+    // Skip Graphite banner / init lines so we keep the actual trunk name.
+    .filter((s) => !/Graphite|Welcome/i.test(s) && !/initialized/i.test(s))
+    .pop();
+  return line || undefined;
+}
+
+/** Enrich a failed FormattedResult with an actionable suggestion. */
+export async function enrichFailure(cwd: string, f: FormattedResult): Promise<void> {
+  if (!f.isFailure) return;
+  const parts: string[] = [];
+
+  if (f.hints.branchNotTracked) {
+    const [branch, trunk] = await Promise.all([
+      detectCurrentBranch(cwd),
+      detectTrunk(cwd),
+    ]);
+    const b = branch ?? "<current-branch>";
+    const p = trunk ?? "<trunk>";
+    parts.push(
+      `Current branch (${b}) is not tracked by Graphite. To track it, call: ` +
+        `graphite_branch_tracking({ action: "track", branch: "${b}", parent: "${p}" }). ` +
+        `Verify parent is correct before applying.`,
+    );
+  }
+  if (f.hints.notInitialized) {
+    parts.push(
+      `Graphite not initialized in this repo. Call: graphite_repo({ action: "init", trunk: "<trunk-branch>" }).`,
+    );
+  }
+  if (f.hints.conflictHalted) {
+    parts.push(
+      `A Graphite command is halted by a conflict. After resolving in git, call: ` +
+        `graphite_recovery({ action: "continue" }) (or "abort").`,
+    );
+  }
+  if (f.hints.restackNeeded) {
+    parts.push(`Stack is out of date. Call: graphite_stack_restack().`);
+  }
+  if (f.hints.trunkOutOfSync) {
+    parts.push(
+      `Trunk is out of sync with remote. Call: graphite_remote_sync({ action: "sync" }) first.`,
+    );
+  }
+  if (f.hints.notAuthenticated) {
+    parts.push(
+      `Graphite is not authenticated. Run \`gt auth\` interactively or set GRAPHITE_AUTH_TOKEN.`,
+    );
+  }
+  if (f.hints.checkedOutElsewhere) {
+    const b = f.hints.checkedOutElsewhere.branch ?? "<branch>";
+    parts.push(
+      `Branch ${b} is checked out in another worktree. Switch to that worktree, or use ` +
+        `\`graphite_branch_create({ onto: "${b}", ... })\` to stack a new branch on top.`,
+    );
+  }
+  if (f.hints.invalidArgument) {
+    parts.push(
+      `gt rejected an unknown argument (${f.hints.invalidArgument}). The local gt version may not support this flag; remove it and retry.`,
+    );
+  }
+  if (f.hints.operatingOnTrunk) {
+    parts.push(
+      `Operation refused on the trunk branch. Check out a non-trunk branch first (graphite_branch_navigate).`,
+    );
+  }
+
+  if (parts.length) f.suggestion = parts.join(" ");
+}
+
+/**
+ * Format a GtRunResult; if it failed, enrich and throw an Error whose message
+ * contains the rendered output plus the recovery suggestion. The thrown Error
+ * makes the tool result `isError: true` so the agent sees a real failure.
+ */
+export async function ensureSuccess(
+  label: string,
+  r: GtRunResult,
+  cwd: string,
+): Promise<FormattedResult> {
+  const f = formatResult(r);
+  if (f.isFailure) {
+    await enrichFailure(cwd, f);
+    throw new Error(renderText(label, f));
+  }
+  return f;
+}
+
+/**
+ * Run multiple gt calls and ensure all succeed. If any failed, enriches each
+ * failed result and throws an Error containing every rendered block so the
+ * agent sees the full picture, not just the first error.
+ */
+export async function ensureAllSuccess(
+  items: Array<{ label: string; result: GtRunResult }>,
+  cwd: string,
+): Promise<FormattedResult[]> {
+  const formatted = items.map((i) => ({ label: i.label, f: formatResult(i.result) }));
+  const failed = formatted.filter((x) => x.f.isFailure);
+  if (failed.length) {
+    await Promise.all(failed.map((x) => enrichFailure(cwd, x.f)));
+    const blocks = formatted.map((x) => renderText(x.label, x.f));
+    throw new Error(blocks.join("\n\n"));
+  }
+  return formatted.map((x) => x.f);
+}

package/src/tools/branch.ts

@@ -1,6 +1,11 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { runGt } from "../lib/exec";
-import { formatResult, renderText } from "../lib/result";
+import { runGt, type GtRunResult } from "../lib/exec";
+import {
+  ensureAllSuccess,
+  ensureSuccess,
+  renderText,
+  type FormattedResult,
+} from "../lib/result";
 import {
   CwdParam,
   StageMode,
@@ -13,61 +18,128 @@ import {
 
 /* --------------------------- branch_inspect --------------------------- */
 
+interface InspectSection {
+  label: string;
+  args: string[];
+  /** Display heading; null hides the section in the rendered output. */
+  heading: string | null;
+}
+
 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.",
+      "Inspect a branch with separately-labeled sections: summary (parent/PR), parent, children, diffstat, body, and (optionally) diff or patch. Read-only.",
     promptSnippet:
-      "graphite_branch_inspect: read-only branch metadata + diff/patch/stat",
+      "graphite_branch_inspect: structured `gt info` + parent/children sections, optional diffstat/body/diff",
     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.",
-        }),
+      branch: Type.Optional(
+        Type.String({ description: "Branch to inspect (default current)." }),
+      ),
+      body: Type.Optional(
+        Type.Boolean({ description: "Include the PR body section." }),
+      ),
+      stat: Type.Optional(
+        Type.Boolean({ description: "Include the diffstat section." }),
+      ),
+      diff: Type.Optional(
+        Type.Boolean({ description: "Include the full diff. Takes precedence over `patch`." }),
+      ),
+      patch: Type.Optional(
+        Type.Boolean({ description: "Include per-commit patch. Ignored if `diff` is set." }),
       ),
       withParentChildren: Type.Optional(
-        Type.Boolean({ description: "Also run `gt parent` and `gt children`." }),
+        Type.Boolean({
+          description:
+            "Also run `gt parent` and `gt children` (only meaningful when inspecting the currently checked-out branch).",
+        }),
       ),
     }),
     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 branchArg = p.branch ? [p.branch] : [];
+
+      const sections: InspectSection[] = [
+        {
+          label: "gt info",
+          heading: "## summary",
+          args: ["info", ...branchArg],
+        },
+      ];
 
-      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 }));
+        sections.push({ label: "gt parent", heading: "## parent", args: ["parent"] });
+        sections.push({ label: "gt children", heading: "## children", args: ["children"] });
       }
-      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)));
+      if (p.stat && !p.diff && !p.patch) {
+        sections.push({
+          label: "gt info --stat",
+          heading: "## diffstat",
+          args: ["info", ...branchArg, "--stat"],
+        });
+      }
+
+      if (p.body) {
+        sections.push({
+          label: "gt info --body",
+          heading: "## body",
+          args: ["info", ...branchArg, "--body"],
+        });
+      }
+
+      if (p.diff) {
+        const args = ["info", ...branchArg, "--diff"];
+        if (p.stat) args.push("--stat");
+        sections.push({ label: "gt info --diff", heading: "## diff", args });
+      } else if (p.patch) {
+        const args = ["info", ...branchArg, "--patch"];
+        if (p.stat) args.push("--stat");
+        sections.push({ label: "gt info --patch", heading: "## patch", args });
+      }
+
+      const results = await Promise.all(
+        sections.map((s) => runGt(s.args, { cwd: p.cwd, signal })),
+      );
+
+      const formatted = await ensureAllSuccess(
+        sections.map((s, i) => ({ label: s.label, result: results[i] })),
+        p.cwd,
+      );
+
+      // Compose section-by-section structured output.
+      const blocks: string[] = [];
+      formatted.forEach((f, i) => {
+        const s = sections[i];
+        if (s.heading) blocks.push(s.heading);
+        blocks.push(stripChrome(f.result.stdout));
+        blocks.push("");
+      });
+      blocks.push("--- raw ---");
+      formatted.forEach((f, i) => {
+        blocks.push(renderText(sections[i].label, f));
+        blocks.push("");
+      });
+
+      const details: Record<string, FormattedResult> = {};
+      sections.forEach((s, i) => {
+        const key = s.label.replace(/^gt\s+/, "").replace(/[^a-z0-9]/gi, "_");
+        details[key] = formatted[i];
+      });
 
       return {
-        content: [{ type: "text", text: blocks.join("\n\n") }],
-        details: {
-          info: formatResult(info),
-          parent: parent ? formatResult(parent) : undefined,
-          children: children ? formatResult(children) : undefined,
-        },
+        content: [{ type: "text", text: blocks.join("\n").trim() }],
+        details,
       };
     },
   });
 }
 
+function stripChrome(s: string): string {
+  return s.replace(/\s+$/, "");
+}
+
 /* --------------------------- branch_create --------------------------- */
 
 export function registerBranchCreate(pi: ExtensionAPI) {
@@ -107,10 +179,11 @@ export function registerBranchCreate(pi: ExtensionAPI) {
       if (p.onto) args.push("--onto", p.onto);
       if (p.insert) args.push("--insert");
       args.push(p.ai ? "--ai" : "--no-ai");
+      const label = `gt ${args.join(" ")}`;
       const r = await runGt(args, { cwd: p.cwd, signal });
-      const f = formatResult(r);
+      const f = await ensureSuccess(label, r, p.cwd);
       return {
-        content: [{ type: "text", text: renderText(`gt ${args.join(" ")}`, f) }],
+        content: [{ type: "text", text: renderText(label, f) }],
         details: { result: f },
       };
     },
@@ -224,10 +297,11 @@ export function registerBranchUpdate(pi: ExtensionAPI) {
         }
       }
 
-      const r = await runGt(args, { cwd: p.cwd, signal });
-      const f = formatResult(r);
+      const label = `gt ${args.join(" ")}`;
+      const r: GtRunResult = await runGt(args, { cwd: p.cwd, signal });
+      const f = await ensureSuccess(label, r, p.cwd);
       return {
-        content: [{ type: "text", text: renderText(`gt ${args.join(" ")}`, f) }],
+        content: [{ type: "text", text: renderText(label, f) }],
         details: { action: p.action, result: f },
       };
     },
@@ -276,10 +350,11 @@ export function registerBranchTracking(pi: ExtensionAPI) {
           if (p.branch) args.push(p.branch);
           break;
       }
+      const label = `gt ${args.join(" ")}`;
       const r = await runGt(args, { cwd: p.cwd, signal });
-      const f = formatResult(r);
+      const f = await ensureSuccess(label, r, p.cwd);
       return {
-        content: [{ type: "text", text: renderText(`gt ${args.join(" ")}`, f) }],
+        content: [{ type: "text", text: renderText(label, f) }],
         details: { action: p.action, result: f },
       };
     },
@@ -341,10 +416,11 @@ export function registerBranchNavigate(pi: ExtensionAPI) {
           args = ["bottom"];
           break;
       }
+      const label = `gt ${args.join(" ")}`;
       const r = await runGt(args, { cwd: p.cwd, signal });
-      const f = formatResult(r);
+      const f = await ensureSuccess(label, r, p.cwd);
       return {
-        content: [{ type: "text", text: renderText(`gt ${args.join(" ")}`, f) }],
+        content: [{ type: "text", text: renderText(label, f) }],
         details: { action: p.action, result: f },
       };
     },

package/src/tools/pr.ts

@@ -1,6 +1,6 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { runGt } from "../lib/exec";
-import { formatResult, renderText } from "../lib/result";
+import { ensureSuccess, renderText } from "../lib/result";
 import {
   CwdParam,
   StringEnum,
@@ -11,6 +11,12 @@ import {
 
 /* ------------------------------ pr_submit ------------------------------ */
 
+function shellQuote(s: string): string {
+  if (s === "") return "''";
+  if (/^[A-Za-z0-9_./:@%+=-]+$/.test(s)) return s;
+  return `'${s.replace(/'/g, `'"'"'`)}'`;
+}
+
 export function registerPrSubmit(pi: ExtensionAPI) {
   pi.registerTool({
     name: "graphite_pr_submit",
@@ -21,6 +27,7 @@ export function registerPrSubmit(pi: ExtensionAPI) {
       "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.",
+      "`gt submit` cannot set PR title/body inline. If you pass `title`/`body` to graphite_pr_submit, the tool will return a `gh pr edit` command for you to run via bash to apply the metadata.",
     ],
     parameters: Type.Object({
       cwd: CwdParam,
@@ -62,12 +69,27 @@ export function registerPrSubmit(pi: ExtensionAPI) {
       ignoreOutOfSyncTrunk: Type.Optional(Type.Boolean()),
       view: Type.Optional(Type.Boolean({ description: "--view (open PR in browser after submit)." })),
       confirmRemote: Type.Optional(Type.Boolean()),
+
+      title: Type.Optional(
+        Type.String({
+          description:
+            "Desired PR title. `gt submit` has no inline flag for this; the tool emits a `gh pr edit` command to run after submit.",
+        }),
+      ),
+      body: Type.Optional(
+        Type.String({
+          description:
+            "Desired PR body. `gt submit` has no inline flag for this; the tool emits a `gh pr edit` command to run after submit.",
+        }),
+      ),
     }),
     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 wantsCustomMetadata = p.title != null || p.body != null;
+
       const args: string[] = ["submit"];
       if (!apply) args.push("--dry-run");
 
@@ -88,7 +110,10 @@ export function registerPrSubmit(pi: ExtensionAPI) {
       if (p.comment) args.push("--comment", p.comment);
       if (p.targetTrunk) args.push("--target-trunk", p.targetTrunk);
 
-      const editMode = p.editMode ?? "none";
+      // If the caller supplied title/body, force --no-edit so gt doesn't try
+      // to prompt or open a web editor with conflicting metadata. The actual
+      // metadata is applied via the suggested `gh pr edit` command instead.
+      const editMode = wantsCustomMetadata ? "none" : (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");
@@ -99,11 +124,45 @@ export function registerPrSubmit(pi: ExtensionAPI) {
       if (p.ignoreOutOfSyncTrunk) args.push("--ignore-out-of-sync-trunk");
       if (p.view) args.push("--view");
 
+      const label = `gt ${args.join(" ")}`;
       const r = await runGt(args, { cwd: p.cwd, signal });
-      const f = formatResult(r);
+      const f = await ensureSuccess(label, r, p.cwd);
+
+      const blocks: string[] = [renderText(label, f)];
+
+      let metadataNote: string | undefined;
+      if (wantsCustomMetadata) {
+        const ghParts: string[] = ["gh", "pr", "edit"];
+        if (p.branch) ghParts.push(p.branch);
+        if (p.title != null) ghParts.push("--title", shellQuote(p.title));
+        if (p.body != null) ghParts.push("--body", shellQuote(p.body));
+        const ghCmd = ghParts.join(" ");
+
+        metadataNote = [
+          "## metadata note",
+          "`gt submit` has no flag to set PR title/body inline.",
+          "To apply the title/body you supplied, run the following via the bash tool" +
+            " (gt does not run gh for you; this keeps the tool composable):",
+          ghCmd,
+          p.stack === true || (!p.branch && p.stack !== false)
+            ? "If this submit covered multiple PRs, repeat `gh pr edit <branch>` for each PR that needs metadata."
+            : undefined,
+        ]
+          .filter((x): x is string => Boolean(x))
+          .join("\n");
+
+        blocks.push(metadataNote);
+      }
+
       return {
-        content: [{ type: "text", text: renderText(`gt ${args.join(" ")}`, f) }],
-        details: { apply, result: f },
+        content: [{ type: "text", text: blocks.join("\n\n") }],
+        details: {
+          apply,
+          editMode,
+          wantsCustomMetadata,
+          metadataNote,
+          result: f,
+        },
       };
     },
   });
@@ -139,40 +198,27 @@ export function registerPrLifecycle(pi: ExtensionAPI) {
       confirmRemote: Type.Optional(Type.Boolean()),
     }),
     async execute(_id, p, signal): Promise<ToolReturn> {
+      let args: string[];
       if (p.action === "open_url") {
-        const args = ["pr"];
+        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") {
+      } else if (p.action === "merge") {
         const apply = p.apply === true;
         if (apply) requireConfirm(p.confirmRemote, "gt merge (merges PRs on GitHub)");
-        const args = ["merge"];
+        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 },
-        };
+      } else {
+        args = ["unlink"];
+        if (p.branch) args.push(p.branch);
       }
-
-      // unlink
-      const args = ["unlink"];
-      if (p.branch) args.push(p.branch);
+      const label = `gt ${args.join(" ")}`;
       const r = await runGt(args, { cwd: p.cwd, signal });
-      const f = formatResult(r);
+      const f = await ensureSuccess(label, r, p.cwd);
       return {
-        content: [{ type: "text", text: renderText(`gt ${args.join(" ")}`, f) }],
-        details: { result: f },
+        content: [{ type: "text", text: renderText(label, f) }],
+        details: { action: p.action, result: f },
       };
     },
   });

package/src/tools/recovery.ts

@@ -1,6 +1,6 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { runGt } from "../lib/exec";
-import { formatResult, renderText } from "../lib/result";
+import { ensureSuccess, renderText } from "../lib/result";
 import { CwdParam, StringEnum, Type, type ToolReturn } from "../lib/schema";
 
 export function registerRecovery(pi: ExtensionAPI) {
@@ -41,10 +41,11 @@ export function registerRecovery(pi: ExtensionAPI) {
           if (p.force) args.push("--force");
           break;
       }
+      const label = `gt ${args.join(" ")}`;
       const r = await runGt(args, { cwd: p.cwd, signal });
-      const f = formatResult(r);
+      const f = await ensureSuccess(label, r, p.cwd);
       return {
-        content: [{ type: "text", text: renderText(`gt ${args.join(" ")}`, f) }],
+        content: [{ type: "text", text: renderText(label, f) }],
         details: { action: p.action, result: f },
       };
     },

package/src/tools/remote.ts

@@ -1,6 +1,6 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { runGt } from "../lib/exec";
-import { formatResult, renderText } from "../lib/result";
+import { ensureSuccess, renderText } from "../lib/result";
 import {
   CwdParam,
   StringEnum,
@@ -96,10 +96,11 @@ export function registerRemoteSync(pi: ExtensionAPI) {
         if (p.unfrozen) args.push("--unfrozen");
       }
 
+      const label = `gt ${args.join(" ")}`;
       const r = await runGt(args, { cwd: p.cwd, signal });
-      const f = formatResult(r);
+      const f = await ensureSuccess(label, r, p.cwd);
       return {
-        content: [{ type: "text", text: renderText(`gt ${args.join(" ")}`, f) }],
+        content: [{ type: "text", text: renderText(label, f) }],
         details: { action: p.action, result: f },
       };
     },

package/src/tools/repo.ts

@@ -1,6 +1,6 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { runGt } from "../lib/exec";
-import { formatResult, renderText } from "../lib/result";
+import { ensureAllSuccess, ensureSuccess, renderText } from "../lib/result";
 import { CwdParam, StringEnum, Type, type ToolReturn } from "../lib/schema";
 
 const params = Type.Object({
@@ -42,8 +42,13 @@ export function registerRepo(pi: ExtensionAPI) {
           runGt(["trunk"], { cwd, signal }),
           runGt(["log", "short"], { cwd, signal }),
         ]);
-        const ft = formatResult(trunk);
-        const fl = formatResult(log);
+        const [ft, fl] = await ensureAllSuccess(
+          [
+            { label: "gt trunk", result: trunk },
+            { label: "gt log short", result: log },
+          ],
+          cwd,
+        );
         return {
           content: [
             {
@@ -60,40 +65,34 @@ export function registerRepo(pi: ExtensionAPI) {
         if (p.trunk) args.push("--trunk", p.trunk);
         if (p.reset) args.push("--reset");
         const r = await runGt(args, { cwd, signal });
-        const f = formatResult(r);
+        const f = await ensureSuccess(`gt ${args.join(" ")}`, r, cwd);
         return {
-          content: [{ type: "text", text: renderText("gt init", f) }],
+          content: [{ type: "text", text: renderText(`gt ${args.join(" ")}`, f) }],
           details: { result: f },
         };
       }
 
       if (p.action === "set_trunk") {
         if (!p.trunk) throw new Error("action=set_trunk requires `trunk`.");
-        const args = ["trunk"];
-        if (p.addAdditionalTrunk) args.push("--add");
-        // gt trunk --add prompts for trunk name; not all gt versions accept positional.
-        // Fall back to gt init --trunk for non-additional sets.
         if (!p.addAdditionalTrunk) {
-          const r = await runGt(["init", "--trunk", p.trunk], { cwd, signal });
-          const f = formatResult(r);
+          const args = ["init", "--trunk", p.trunk];
+          const r = await runGt(args, { cwd, signal });
+          const f = await ensureSuccess(`gt ${args.join(" ")}`, r, cwd);
           return {
             content: [
-              { type: "text", text: renderText(`gt init --trunk ${p.trunk}`, f) },
+              { type: "text", text: renderText(`gt ${args.join(" ")}`, f) },
             ],
             details: { result: f },
           };
         }
-        // Additional trunk: `gt trunk --add` typically prompts; with
-        // --no-interactive it will fail fast. Surface that failure to the
-        // caller instead of pretending it worked.
-        const r = await runGt(args, { cwd, signal });
-        const f = formatResult(r);
+        // `gt trunk --add` is interactive (prompts for the new trunk name).
+        // With --no-interactive this will fail; surface that failure rather
+        // than silently misleading the caller.
+        const r = await runGt(["trunk", "--add"], { cwd, signal });
+        const f = await ensureSuccess("gt trunk --add", r, cwd);
         return {
           content: [{ type: "text", text: renderText("gt trunk --add", f) }],
-          details: {
-            result: f,
-            note: "`gt trunk --add` is interactive; this call runs with --no-interactive and may fail. Add the trunk via `gt config` or `gt init --trunk` instead.",
-          },
+          details: { result: f },
         };
       }
 
@@ -102,20 +101,21 @@ export function registerRepo(pi: ExtensionAPI) {
         runGt(["trunk"], { cwd, signal }),
         runGt(["trunk", "--all"], { cwd, signal }),
       ]);
+      const [ft, fta] = await ensureAllSuccess(
+        [
+          { label: "gt trunk", result: trunk },
+          { label: "gt trunk --all", result: trunkAll },
+        ],
+        cwd,
+      );
       return {
         content: [
           {
             type: "text",
-            text: [
-              renderText("gt trunk", formatResult(trunk)),
-              renderText("gt trunk --all", formatResult(trunkAll)),
-            ].join("\n\n"),
+            text: [renderText("gt trunk", ft), renderText("gt trunk --all", fta)].join("\n\n"),
           },
         ],
-        details: {
-          trunk: formatResult(trunk),
-          trunkAll: formatResult(trunkAll),
-        },
+        details: { trunk: ft, trunkAll: fta },
       };
     },
   });

package/src/tools/stack.ts

@@ -1,6 +1,6 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { runGt } from "../lib/exec";
-import { formatResult, renderText } from "../lib/result";
+import { ensureSuccess, renderText } from "../lib/result";
 import {
   CwdParam,
   StringEnum,
@@ -29,7 +29,7 @@ export function registerStackView(pi: ExtensionAPI) {
       scope: Type.Optional(
         StringEnum(["all_trunks", "current_stack", "default"] as const, {
           description:
-            "all_trunks adds --all, current_stack adds --stack, default does neither.",
+            "all_trunks adds --all (only supported on mode=full/default). current_stack adds --stack. default does neither.",
         }),
       ),
       showUntracked: Type.Optional(Type.Boolean()),
@@ -37,17 +37,34 @@ export function registerStackView(pi: ExtensionAPI) {
       steps: Type.Optional(Type.Integer({ minimum: 1 })),
     }),
     async execute(_id, p, signal): Promise<ToolReturn> {
-      const sub = p.mode === "short" ? ["log", "short"] : p.mode === "long" ? ["log", "long"] : ["log"];
+      // Empirically, current gt rejects `--all` on `gt log short` / `gt log long`
+      // ("Unknown argument: all"). Block that combination at the tool layer
+      // instead of exposing it to the model.
+      if (p.scope === "all_trunks" && (p.mode === "short" || p.mode === "long")) {
+        throw new Error(
+          "graphite_stack_view: scope='all_trunks' is not supported with mode='short'/'long' " +
+            "(current `gt` rejects `--all` on those forms). Omit `mode` (or use mode='full') to use --all.",
+        );
+      }
+
+      const sub =
+        p.mode === "short"
+          ? ["log", "short"]
+          : p.mode === "long"
+            ? ["log", "long"]
+            : ["log"];
       const args = [...sub];
       if (p.scope === "all_trunks") args.push("--all");
       if (p.scope === "current_stack") args.push("--stack");
       if (p.showUntracked) args.push("--show-untracked");
       if (p.reverse) args.push("--reverse");
       if (p.steps != null) args.push("--steps", String(p.steps));
+
+      const label = `gt ${args.join(" ")}`;
       const r = await runGt(args, { cwd: p.cwd, signal });
-      const f = formatResult(r);
+      const f = await ensureSuccess(label, r, p.cwd);
       return {
-        content: [{ type: "text", text: renderText(`gt ${args.join(" ")}`, f) }],
+        content: [{ type: "text", text: renderText(label, f) }],
         details: { result: f },
       };
     },
@@ -85,10 +102,12 @@ export function registerStackRestack(pi: ExtensionAPI) {
       if (p.scope === "downstack") args.push("--downstack");
       else if (p.scope === "upstack") args.push("--upstack");
       else if (p.scope === "only") args.push("--only");
+
+      const label = `gt ${args.join(" ")}`;
       const r = await runGt(args, { cwd: p.cwd, signal });
-      const f = formatResult(r);
+      const f = await ensureSuccess(label, r, p.cwd);
       return {
-        content: [{ type: "text", text: renderText(`gt ${args.join(" ")}`, f) }],
+        content: [{ type: "text", text: renderText(label, f) }],
         details: { result: f },
       };
     },
@@ -132,44 +151,34 @@ export function registerStackReorganize(pi: ExtensionAPI) {
       confirmRemote: Type.Optional(Type.Boolean()),
     }),
     async execute(_id, p, signal): Promise<ToolReturn> {
+      let args: string[];
       if (p.action === "move_branch") {
         if (!p.onto) throw new Error("action=move_branch requires `onto`.");
-        const args = ["move", "--onto", p.onto];
+        args = ["move", "--onto", p.onto];
         if (p.source) args.push("--source", p.source);
         if (p.onlyMove) args.push("--only");
-        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 === "fold") {
+      } else if (p.action === "fold") {
         if (p.foldClose) requireConfirm(p.confirmRemote, "fold --close");
-        const args = ["fold"];
+        args = ["fold"];
         if (p.foldKeep) args.push("--keep");
         if (p.foldStack) args.push("--stack");
         if (p.foldClose) args.push("--close");
-        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 },
-        };
+      } else {
+        if (!p.filePatterns || p.filePatterns.length === 0) {
+          throw new Error(
+            "action=split_by_file requires `filePatterns` (one or more pathspecs).",
+          );
+        }
+        args = ["split", "--by-file"];
+        for (const pat of p.filePatterns) args.push("-f", pat);
       }
 
-      // split_by_file
-      if (!p.filePatterns || p.filePatterns.length === 0) {
-        throw new Error("action=split_by_file requires `filePatterns` (one or more pathspecs).");
-      }
-      const args = ["split", "--by-file"];
-      for (const pat of p.filePatterns) args.push("-f", pat);
+      const label = `gt ${args.join(" ")}`;
       const r = await runGt(args, { cwd: p.cwd, signal });
-      const f = formatResult(r);
+      const f = await ensureSuccess(label, r, p.cwd);
       return {
-        content: [{ type: "text", text: renderText(`gt ${args.join(" ")}`, f) }],
-        details: { result: f },
+        content: [{ type: "text", text: renderText(label, f) }],
+        details: { action: p.action, result: f },
       };
     },
   });