@macintacos/caret 1.8.1 → 1.9.0

package/opencode/caret.core.ts

@@ -1,35 +1,39 @@
-// caret's host-neutral OpenCode core: the review tool's name, model-facing text and
-// runPlanReview, the planning steer, the caret binary/version/plans-dir resolution, the
-// warm runner, the toast bodies and tool-call metadata keys, and the update check.
+// caret's host-neutral OpenCode core: runPlanReview, the planning steer, the caret
+// version and plans-dir resolution, the warm runner, the toast bodies and tool-call
+// metadata keys, and the update check. It re-uses the bridge's tool name, text, binary
+// resolution and version comparison.
 // caret.plugin.ts (v1), caret.plugin.v2.ts and caret.tui.ts are thin host adapters over
-// it. Its imports are node builtins and review-bridge.ts only, so loading it never
-// evaluates either host's SDK; test/structure/dependency-placement.test.ts holds it there.
+// it. Its imports are node builtins and ../bridge/review-bridge.ts only, so loading it
+// never evaluates either host's SDK; test/structure/dependency-placement.test.ts holds it
+// there.
 
-import { spawn } from "node:child_process";
-import { mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, resolve } from "node:path";
+import { dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 
 import {
   buildEnvelope,
   type CaretDecision,
   decisionText,
+  isNewer,
   PLAN_TITLE_INSTRUCTION,
+  REVIEW_TOOL,
+  readRegularFile,
+  resolvePlanSource,
   runReviewViaCaret,
   type SpawnRunner,
-} from "./review-bridge.ts";
-
-/** The caret binary the OpenCode plugin spawns. Env override wins; else the binary that
- * ships beside this module in the npm package. */
-export function resolveCaretBin(opts: {
-  env: Record<string, string | undefined>;
-  importMetaUrl: string;
-}): string {
-  const override = opts.env.CARET_OPENCODE_BIN?.trim();
-  if (override) return override;
-  return fileURLToPath(new URL("../bin/caret", opts.importMetaUrl));
-}
+  warmCaret,
+} from "../bridge/review-bridge.ts";
+
+export {
+  isNewer,
+  PLAN_ARG_DESCRIPTION,
+  REVIEW_TOOL,
+  REVIEW_TOOL_DESCRIPTION,
+  resolveCaretBin,
+  resolvePlanSource,
+} from "../bridge/review-bridge.ts";
 
 /** The plugin's own caret version, for the update check, read from the package.json
  * shipped beside this module. "unknown" when it is unreadable — deliberately UNPARSEABLE
@@ -48,9 +52,6 @@ export function resolveCaretVersion(opts: {
   }
 }
 
-/** The plan-review tool the Plan agent calls. */
-export const REVIEW_TOOL = "caret_review_plan";
-
 /** OpenCode's built-in primary planning agent — the one agent caret steers toward
  * the review tool and warms the daemon for. */
 export const PLANNING_AGENTS = ["plan"] as const;
@@ -123,49 +124,6 @@ export function decisionToast(outcome: ReviewOutcome): ToastBody {
   }
 }
 
-type PlanSource = { plan: string; planFilePath?: string };
-
-/** The plan the review tool submits, from exactly one of its `plan` / `path` args (an
- * empty string counts as absent). A `path` resolves against the session directory and
- * must be a readable `.md` file — mirroring the core's `isPlanFile`
- * (src/plan/canonical-file.ts), repeated here because this module cannot import src/.
- * `readFile` returns the text, or undefined when absPath is not a readable regular
- * file. */
-export function resolvePlanSource(
-  args: { plan?: string; path?: string },
-  directory: string,
-  readFile: (absPath: string) => string | undefined,
-): PlanSource | { error: string } {
-  const plan = args.plan || undefined;
-  const path = args.path || undefined;
-  const notExactlyOne = {
-    error: `caret: ${REVIEW_TOOL} takes exactly one of \`plan\` or \`path\`. Pass the plan file as \`path\`, or the plan inline as \`plan\`.`,
-  };
-  if (path === undefined) return plan === undefined ? notExactlyOne : { plan };
-  if (plan !== undefined) return notExactlyOne;
-  const planFilePath = resolve(directory, path);
-  if (!planFilePath.endsWith(".md")) {
-    return {
-      error: `caret: ${REVIEW_TOOL} needs a markdown (.md) file as \`path\`, not ${planFilePath}. Write the plan to a .md file, or pass it inline as \`plan\`.`,
-    };
-  }
-  const text = readFile(planFilePath);
-  if (text === undefined) {
-    return {
-      error: `caret: ${REVIEW_TOOL} could not read ${planFilePath} as a regular file. Write the plan there first, or pass it inline as \`plan\`.`,
-    };
-  }
-  return { plan: text, planFilePath };
-}
-
-function readRegularFile(absPath: string): string | undefined {
-  try {
-    return statSync(absPath).isFile() ? readFileSync(absPath, "utf-8") : undefined;
-  } catch {
-    return undefined;
-  }
-}
-
 // --- version-check toast (EXC-794) -----------------------------------------
 
 /** caret's latest-release endpoint. Unauthenticated GitHub API — throttled to at
@@ -179,30 +137,6 @@ const UPDATE_TOAST_MS = 5_000;
  * OpenCode start. */
 const UPDATE_CHECK_INTERVAL_MS = 24 * 60 * 60_000;
 
-/** Semver triple `[major, minor, patch]`, or null when `v` is not `X.Y.Z` (an
- * optional leading `v` is stripped; trailing prerelease/build metadata ignored). */
-function parseVersionTriple(v: string): [number, number, number] | null {
-  const m = v
-    .trim()
-    .replace(/^v/, "")
-    .match(/^(\d+)\.(\d+)\.(\d+)/);
-  return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
-}
-
-/** True when `latest` is a strictly higher semver than `current`. Inline (no semver
- * dep) so the deployed plugin stays self-contained; an unparseable version on
- * either side compares false, so the check never nags on something it can't read. */
-export function isNewer(latest: string, current: string): boolean {
-  const a = parseVersionTriple(latest);
-  const b = parseVersionTriple(current);
-  if (!a || !b) return false;
-  const [a0, a1, a2] = a;
-  const [b0, b1, b2] = b;
-  if (a0 !== b0) return a0 > b0;
-  if (a1 !== b1) return a1 > b1;
-  return a2 > b2;
-}
-
 /** The version (v-stripped) and release-page URL from GitHub's /releases/latest
  * JSON, or null when the shape is unusable. */
 export function parseLatestRelease(json: unknown): { version: string; url: string } | null {
@@ -365,29 +299,8 @@ export function planningSteer(plansDir: string): string {
  * unit-testable without spawning a process. */
 export type WarmRunner = (bin: string) => void;
 
-/** Production warm: `caret prewarm`, detached and unref'd so it never holds up the
- * turn. Output is discarded — the child logs to caret.log. CARET_AGENT rides along
- * because this spawn is what stands the daemon up and the daemon picks its adapter
- * from that env; the 'error' handler is mandatory because spawn emits 'error'
- * ASYNCHRONOUSLY (ENOENT on a bad bin), where the hook's synchronous try/catch
- * cannot see it and an unhandled event would take OpenCode's whole process down. */
-export const nodeWarmRunner: WarmRunner = (bin) => {
-  const child = spawn(bin, ["prewarm"], {
-    stdio: "ignore",
-    detached: true,
-    env: { ...process.env, CARET_AGENT: "opencode" },
-  });
-  child.on("error", () => {});
-  child.unref();
-};
-
-// The review tool's model-facing text. Both hosts' registrations read these, so v1 and
-// v2 stay word-for-word identical (plugin-v2.test.ts pins the refusal texts).
-export const REVIEW_TOOL_DESCRIPTION =
-  "Submit the current plan to caret for human review in a local browser UI. For plans only: caret presents what it receives as a plan, so do not use it for other documents or questions. Pass exactly one of `path` (preferred: a markdown file you write once and revise with edits) or `plan` (the plan inline). Blocks until the user approves or requests changes. On a change request, follow the result's instructions and call this tool again. Do not implement the plan until a call returns an approval.";
-
-export const PLAN_ARG_DESCRIPTION =
-  "The complete plan, as markdown, to present for human review. The inline alternative to `path`.";
+/** Production warm, as the OpenCode adapter. */
+export const nodeWarmRunner: WarmRunner = (bin) => warmCaret(bin, "opencode");
 
 export function pathArgDescription(plansDir: string): string {
   return `Preferred. A markdown (.md) file holding the complete plan, absolute or relative to the session directory. (OpenCode's plan agent writes its plan files in ${plansDir}/.)`;

package/opencode/caret.plugin.ts

@@ -20,9 +20,9 @@
 // under v1's `plugin` config key or v2's `plugins` key (v2 reads both, legacy `plugin`
 // first). This module is the `server` half of index.ts's dual default: index.ts imports
 // it on v1's first `server` call, so a v2 load never evaluates it. Its imports are node
-// builtins, caret.core.ts, review-bridge.ts, and @opencode-ai/plugin (resolved by
-// OpenCode at runtime). Which ctx/tool/config shapes are live-verified and which are not:
-// doc/agents/opencode-integration.md § Verified vs. follow-up.
+// builtins, caret.core.ts, ../bridge/review-bridge.ts, and @opencode-ai/plugin (resolved
+// by OpenCode at runtime). Which ctx/tool/config shapes are live-verified and which are
+// not: doc/agents/opencode-integration.md § Verified vs. follow-up.
 
 import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
@@ -30,6 +30,7 @@ import { relative } from "node:path";
 
 import { type Hooks, type Plugin, tool } from "@opencode-ai/plugin";
 
+import { nodeSpawnRunner, type SpawnRunner } from "../bridge/review-bridge.ts";
 import {
   decisionToast,
   isPlanningAgent,
@@ -50,7 +51,6 @@ import {
   toastBestEffort,
   type WarmRunner,
 } from "./caret.core.ts";
-import { nodeSpawnRunner, type SpawnRunner } from "./review-bridge.ts";
 
 /** OpenCode's plugin client, structurally narrowed to the calls caret makes.
  * A structural type (rather than importing the SDK client) keeps this robust
@@ -163,7 +163,13 @@ export function createCaretPlugin(
     plansDir?: string;
   } = {},
 ): Plugin {
-  const bin = opts.bin ?? resolveCaretBin({ env: process.env, importMetaUrl: import.meta.url });
+  const bin =
+    opts.bin ??
+    resolveCaretBin({
+      env: process.env,
+      importMetaUrl: import.meta.url,
+      overrideVar: "CARET_OPENCODE_BIN",
+    });
   const run = opts.run ?? nodeSpawnRunner;
   const warm = opts.warm ?? nodeWarmRunner;
   const plansDir =

package/opencode/caret.plugin.v2.ts

@@ -8,6 +8,12 @@ import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 
+import {
+  decisionText,
+  errorMessage,
+  nodeSpawnRunner,
+  type SpawnRunner,
+} from "../bridge/review-bridge.ts";
 import {
   CARET_DECISION_KEY,
   CARET_URL_KEY,
@@ -24,7 +30,6 @@ import {
   type WarmRunner,
 } from "./caret.core.ts";
 import { editChecks, type Rule } from "./permission.ts";
-import { decisionText, nodeSpawnRunner, type SpawnRunner } from "./review-bridge.ts";
 
 /** Appended last, it outranks a config deny-all: v2 disables a tool only when the last
  * rule naming it is a `*` deny. */
@@ -210,12 +215,11 @@ export function createCaretSetup(opts: {
         return { content, metadata: { [CARET_DECISION_KEY]: decision.behavior } };
       } catch (error) {
         if (declined !== undefined && error === declined) throw error;
-        const message = error instanceof Error ? error.message : String(error);
         return {
           content: decisionText(
             {
               behavior: "deny",
-              feedback: `caret: review failed to run (${message}) — denying to fail safe.`,
+              feedback: `caret: review failed to run (${errorMessage(error)}) — denying to fail safe.`,
             },
             REVIEW_TOOL,
           ),
@@ -284,7 +288,11 @@ export function createCaretSetup(opts: {
 
 /** The v2 `setup` OpenCode loads, wired to the production runners. */
 const setup = createCaretSetup({
-  bin: resolveCaretBin({ env: process.env, importMetaUrl: import.meta.url }),
+  bin: resolveCaretBin({
+    env: process.env,
+    importMetaUrl: import.meta.url,
+    overrideVar: "CARET_OPENCODE_BIN",
+  }),
   run: nodeSpawnRunner,
   warm: nodeWarmRunner,
   plansDir: resolvePlansDir({

package/opencode/caret.tui.ts

@@ -10,8 +10,7 @@
 // toasts. `theme` and `renderer` are optional too: without them the pending row renders in
 // OpenTUI's default colours, or opens on every mouse-up, selection or not.
 
-import { spawn } from "node:child_process";
-
+import { type DetachedSpawn, nodeDetachedSpawn } from "../bridge/review-bridge.ts";
 import {
   CARET_DECISION_KEY,
   CARET_URL_KEY,
@@ -94,21 +93,6 @@ type CaretCommand = {
   run: () => void;
 };
 
-/** Spawns `bin args` detached and unwaited; `onError` hears a child that fails to start
- * or exits non-zero. */
-export type DetachedSpawn = (bin: string, args: string[], onError: (err: Error) => void) => void;
-
-export const nodeDetachedSpawn: DetachedSpawn = (bin, args, onError) => {
-  // spawn reports ENOENT asynchronously; unhandled, that 'error' takes OpenCode down.
-  const child = spawn(bin, args, { stdio: "ignore", detached: true });
-  child.on("error", onError);
-  // band-link exits 0 on its own failures, so non-zero means caret never ran.
-  child.on("exit", (code) => {
-    if (code) onError(new Error(`exited with status ${code}`));
-  });
-  child.unref();
-};
-
 /** The `@opentui/solid` reconciler calls the pending row takes. */
 type OpenTuiReconciler = {
   createElement: (tag: "box" | "text" | "span" | "b") => unknown;
@@ -336,7 +320,11 @@ function pendingRow(
 const loadOpenTui = (): Promise<OpenTuiReconciler> => import("@opentui/solid");
 const setup = createCaretTui({
   checkUpdate: productionUpdateCheck,
-  bin: resolveCaretBin({ env: process.env, importMetaUrl: import.meta.url }),
+  bin: resolveCaretBin({
+    env: process.env,
+    importMetaUrl: import.meta.url,
+    overrideVar: "CARET_OPENCODE_BIN",
+  }),
   spawn: nodeDetachedSpawn,
   loadOpenTui,
 });

package/opencode/commands/demo.md

@@ -3,7 +3,7 @@ description: Demo caret by submitting a short plan about this repo to caret's re
 agent: plan
 ---
 
-The demo template is at the end of this command. Follow its leading HTML comment exactly
+The demo template is at the end of this message. Follow its leading HTML comment exactly
 to fill the slots, then call the `caret_review_plan` tool with everything after that
 comment as the `plan` argument. Do **no** other research and edit **no** file — this is
 only to exercise caret's plan-review flow.

package/opencode/commands/doctor.md

@@ -44,7 +44,11 @@ one. What each id means:
 | `daemon-lock` | the lock names a dead pid, or a port caret is not configured to bind | the check's remedy verbatim |
 | `agent-install` | the agent the check names does not have caret enabled | `caret install` |
 | `log-errors` | a live log wrote an NDJSON error record in the last 24h; the detail names which log and when it last erred | step 4 |
+| `opencode-host` | an `opencode` on PATH is below its major's floor (1.3.4 for v1, 2.0.29 for v2), or caret sits in a key or config file that OpenCode doesn't load | the check's remedy verbatim |
 | `opencode-caret-version` | OpenCode would load a caret behind the published one | the check's remedy verbatim |
+| `pi-host` | `pi` can't run, is older than 1.5.0, or is the pre-rename `@mariozechner/pi-coding-agent` | the check's remedy verbatim |
+| `pi-caret-entry` | pi lists caret more than once, filters out its extension, or lists it without its package installed | the check's remedy verbatim |
+| `pi-caret-version` | pi would load a caret behind the published one | the check's remedy verbatim |
 
 An `unknown` check is not a failure: it names its own `reason` — no network, an unreadable
 config, or a report section that never collected, which also shows as an `error` line and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@macintacos/caret",
-  "version": "1.8.1",
+  "version": "1.9.0",
   "license": "MIT",
   "type": "module",
   "description": "A Claude Code plugin that replaces the terminal plan-approval prompt with a local web UI for inline review, annotation, and approval.",
@@ -9,6 +9,15 @@
     ".": "./opencode/index.ts",
     "./tui": "./opencode/caret.tui.ts"
   },
+  "pi": {
+    "extensions": [
+      "./pi/caret.ts"
+    ],
+    "changelogPath": ""
+  },
+  "keywords": [
+    "pi-package"
+  ],
   "bin": {
     "caret": "./bin/caret"
   },
@@ -28,6 +37,8 @@
     "hooks/",
     "commands/",
     "opencode/",
+    "pi/",
+    "bridge/",
     "templates/",
     "mod/hooks/band.tsx",
     "mod/band.d.ts",
@@ -49,6 +60,9 @@
     "@codemirror/state": "^6.6.0",
     "@codemirror/view": "^6.43.0",
     "@commander-js/extra-typings": "^15.0.0",
+    "@earendil-works/pi-ai": "^1.5.1",
+    "@earendil-works/pi-coding-agent": "^1.5.0",
+    "@earendil-works/pi-tui": "^1.5.1",
     "@happy-dom/global-registrator": "^21.0.4",
     "@internationalized/date": "^3.12.2",
     "@laststance/tailwind-suggest-canonical-classes": "^0.1.1",
@@ -70,10 +84,10 @@
     "happy-dom": "^21.0.4",
     "jsonc-parser": "^3.3.1",
     "listr2": "^11.0.0",
-    "marked": "^18.0.4",
+    "marked": "^18.1.3",
     "pino": "^10.3.1",
     "pino-pretty": "^13.1.3",
-    "semver": "^7.8.1",
+    "semver": "^7.8.6",
     "shiki": "^4.4.3",
     "smol-toml": "^1.8.0",
     "svelte": "^5.56.9",
@@ -82,6 +96,7 @@
     "tailwind-variants": "^3.2.2",
     "tailwindcss": "^4.3.3",
     "tw-animate-css": "^1.4.0",
+    "typebox": "^1.3.27",
     "typescript": "^6.0.3",
     "vite": "^8.2.1",
     "xss": "^1.0.15",

package/pi/caret.ts

@@ -0,0 +1,145 @@
+// caret's pi extension. pi loads this file through jiti on Node, from `package.json`
+// `pi.extensions`. It may import only node builtins, pi's host-provided packages, its own
+// pi/ modules, and ../bridge/review-bridge.ts — and nothing it reaches may use bun's
+// runtime API, since pi runs on Node.
+
+import { writeSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { getAgentDir, VERSION } from "@earendil-works/pi-coding-agent";
+
+import {
+  type DetachedSpawn,
+  detachedSpawnWith,
+  isNewer,
+  nodeSpawnRunner,
+  parseVersionTriple,
+  resolveCaretBin,
+  type SpawnRunner,
+  warmCaret,
+} from "../bridge/review-bridge.ts";
+import { DEMO_COMMAND, DEMO_TEMPLATE, type DemoApi, installDemo } from "./demo.ts";
+import { type DoctorApi, installDoctor } from "./doctor.ts";
+import { installNotice, type NoticeApi } from "./notice.ts";
+import { installPlanning, type PlanningApi } from "./plan.ts";
+import { reviewStore } from "./state.ts";
+import { type PiTool, reviewTool } from "./tool.ts";
+
+/** Keep equal to src/adapters/pi/host.ts's PI_FLOOR (test/pi/caret.test.ts pins it);
+ * pi/ can't import src/. */
+export const PI_FLOOR = "1.5.0";
+
+/** The slice of pi's session context caret calls; pinned by test/pi/sdk-conformance.ts. */
+export type PiNotifyContext = {
+  ui: { notify(message: string, type?: "info" | "warning" | "error"): void };
+};
+
+/** The slice of pi's extension API caret calls; pinned by test/pi/sdk-conformance.ts. */
+export type PiApi = PlanningApi &
+  NoticeApi &
+  DemoApi &
+  DoctorApi & {
+    registerTool(tool: PiTool): void;
+    on(event: "session_start", handler: (event: unknown, ctx: PiNotifyContext) => void): void;
+    on(event: "session_shutdown", handler: () => void): void;
+  };
+
+export interface CaretHost {
+  version: string;
+  /** This copy's module URL: its identity against other installed copies, and the base
+   * `../bin/caret` and the demo template resolve against. */
+  entryUrl: string;
+  /** globalThis in production: survives `/reload`, which loads a fresh module instance. */
+  holder: Record<symbol, unknown>;
+  env: Record<string, string | undefined>;
+  run: SpawnRunner;
+  /** pi's agent dir; the plans folder sits under it. */
+  agentDir: string;
+  /** Spawns `caret prewarm` for `bin`; best-effort. */
+  warm: (bin: string) => void;
+  /** Starts `caret band-link` detached. */
+  spawn: DetachedSpawn;
+  /** Writes to the real stdout, for print mode's report. */
+  stdout: (text: string) => void;
+}
+
+const OWNER = Symbol.for("caret.pi.owner");
+const NOTIFIED = Symbol.for("caret.pi.notified");
+
+/** Whether `version` parses and is at least PI_FLOOR. */
+export function meetsFloor(version: string): boolean {
+  return parseVersionTriple(version) !== null && !isNewer(PI_FLOOR, version);
+}
+
+/** One caret warning per process, whichever refusal comes first. */
+function notifyOnce(pi: PiApi, holder: Record<symbol, unknown>, message: string): void {
+  pi.on("session_start", (_event, ctx) => {
+    if (holder[NOTIFIED]) return;
+    holder[NOTIFIED] = true;
+    ctx.ui.notify(message, "warning");
+  });
+}
+
+/** Registers the review tool, the planning mode, the pending-plan notice, and the
+ * `/caret:*` commands unless pi is below PI_FLOOR or another installed copy already owns
+ * `Symbol.for("caret.pi.owner")`. The owner is keyed by `entryUrl`, which differs between
+ * installed copies and is stable across `/reload`. It is released on `session_shutdown`
+ * so a surviving copy takes over after the owner is removed. Either refusal warns once
+ * per process. */
+export function installCaret(pi: PiApi, host: CaretHost): void {
+  const { version, entryUrl, holder, env, run } = host;
+  if (!meetsFloor(version)) {
+    notifyOnce(
+      pi,
+      holder,
+      `caret needs pi ${PI_FLOOR} or later (this is pi ${version}), so its review tool is off. Update pi to use caret.`,
+    );
+    return;
+  }
+  holder[OWNER] ??= entryUrl;
+  const owner = holder[OWNER];
+  if (owner !== entryUrl) {
+    notifyOnce(
+      pi,
+      holder,
+      `caret is loaded twice: the copy at ${fileURLToPath(String(owner))} runs and the copy at ${fileURLToPath(entryUrl)} stays off. Remove one, then run /reload.`,
+    );
+    return;
+  }
+  pi.on("session_shutdown", () => {
+    if (holder[OWNER] === entryUrl) delete holder[OWNER];
+  });
+  const bin = resolveCaretBin({ env, importMetaUrl: entryUrl, overrideVar: "CARET_PI_BIN" });
+  const store = reviewStore(holder);
+  pi.registerTool(reviewTool({ bin, run, store }));
+  installPlanning(pi, {
+    store,
+    plansDir: join(host.agentDir, "plans"),
+    warm: () => host.warm(bin),
+  });
+  installNotice(pi, { store, bin, spawn: host.spawn });
+  installDemo(pi, {
+    commandPath: fileURLToPath(new URL(DEMO_COMMAND, entryUrl)),
+    templatePath: fileURLToPath(new URL(DEMO_TEMPLATE, entryUrl)),
+    isPlanning: (id) => store.get(id).planning,
+  });
+  installDoctor(pi, { bin, run, env, stdout: host.stdout });
+}
+
+export default function caret(pi: PiApi): void {
+  installCaret(pi, {
+    version: VERSION,
+    entryUrl: import.meta.url,
+    holder: globalThis as unknown as Record<symbol, unknown>,
+    env: process.env,
+    run: nodeSpawnRunner,
+    agentDir: getAgentDir(),
+    warm: (bin) => warmCaret(bin, "pi"),
+    spawn: detachedSpawnWith({ CARET_AGENT: "pi" }),
+    // ponytail: fd 1, not process.stdout, since print mode reroutes process.stdout.write
+    // to stderr. A non-blocking stdout can throw EAGAIN on a report past the pipe buffer;
+    // retry as pi's own raw writer does if reports grow.
+    stdout: (text) => writeSync(1, text),
+  });
+}

package/pi/demo.ts

@@ -0,0 +1,79 @@
+// `/caret:demo` for pi: sends the agent OpenCode's `/caret:demo` prompt with caret's demo
+// template in place of its marker, both read from beside the package on every run, so a
+// new user sees a review end to end.
+
+import { readFile } from "node:fs/promises";
+
+import { errorMessage } from "../bridge/review-bridge.ts";
+import { sendAndWait } from "./follow-up.ts";
+
+/** The demo template and OpenCode's `/caret:demo` command, relative to the extension
+ * entry `pi/caret.ts`. Both hosts submit through the same review tool, so the command's
+ * body is pi's prompt too. */
+export const DEMO_TEMPLATE = "../templates/demo.md";
+export const DEMO_COMMAND = "../opencode/commands/demo.md";
+
+const TEMPLATE_MARKER = "__CARET_DEMO_TEMPLATE__";
+const FRONTMATTER = /^---\n[\s\S]*?\n---\n+/;
+
+/** `command`'s body with `template` taken literally in place of its marker. */
+const demoPrompt = (command: string, template: string): string =>
+  command.replace(FRONTMATTER, "").replace(TEMPLATE_MARKER, () => template);
+
+export type DemoCommandContext = {
+  ui: { notify(message: string, type?: "info" | "warning" | "error"): void };
+  waitForIdle(): Promise<void>;
+  sessionManager: { getSessionId(): string };
+};
+
+/** The slice of pi's extension API `/caret:demo` calls; pinned by
+ * test/pi/sdk-conformance.ts. */
+export type DemoApi = {
+  registerCommand(
+    name: string,
+    options: {
+      description: string;
+      handler: (args: string, ctx: DemoCommandContext) => Promise<void>;
+    },
+  ): void;
+  sendUserMessage(content: string, options: { deliverAs: "followUp" }): void;
+};
+
+/** Registers `/caret:demo`, which reads the command at `commandPath` and the template at
+ * `templatePath` on every run and refuses while the session is planning, where approving
+ * the demo could end planning for the real task. */
+export function installDemo(
+  pi: DemoApi,
+  deps: {
+    commandPath: string;
+    templatePath: string;
+    isPlanning: (sessionId: string) => boolean;
+  },
+): void {
+  const { commandPath, templatePath, isPlanning } = deps;
+  pi.registerCommand("caret:demo", {
+    description: "Demo caret: review a short plan about this repo",
+    handler: async (_args, ctx) => {
+      if (isPlanning(ctx.sessionManager.getSessionId())) {
+        ctx.ui.notify(
+          "caret's demo is off while planning; run /caret:plan to leave planning first.",
+          "warning",
+        );
+        return;
+      }
+      let prompt: string;
+      try {
+        const [command, template] = await Promise.all([
+          readFile(commandPath, "utf-8"),
+          readFile(templatePath, "utf-8"),
+        ]);
+        prompt = demoPrompt(command, template);
+      } catch (err) {
+        // The error names the file that failed.
+        ctx.ui.notify(`caret couldn't read its demo prompt: ${errorMessage(err)}`, "error");
+        return;
+      }
+      await sendAndWait(pi, ctx, prompt);
+    },
+  });
+}