@macintacos/caret 1.1.0 → 1.2.0

package/opencode/caret.plugin.ts

@@ -6,7 +6,8 @@
 // tool's execute() by spawning `caret review` (CARET_AGENT=opencode). The whole
 // caret daemon/review pipeline is reused unchanged — this plugin is the
 // OpenCode-side counterpart to Claude Code's hooks.json, which likewise spawns
-// `caret review`.
+// `caret review`. Its host-neutral parts live in caret.core.ts, shared with
+// caret.plugin.v2.ts and caret.tui.ts.
 //
 // Subagent-bypass mitigation: OpenCode's tool.execute.before does not fire for
 // subagent tool calls, so caret does NOT rely on a hook to gate subagents. The
@@ -15,108 +16,49 @@
 // tool body re-checks the calling session's shape — defense in depth. Any PRIMARY
 // agent may ask for a review; only the plan agent is steered toward it.
 //
-// It ships in the @macintacos/caret npm package; OpenCode loads it when the package
-// is in the user's `plugin` array, and it resolves its own binary and version at
-// runtime from that package. (The legacy file-deploy path substitutes the two
-// __CARET_*__ markers instead.) It stays self-contained: its only imports are node
-// builtins, its sibling review-bridge.ts, and @opencode-ai/plugin (resolved by OpenCode
-// at runtime). Which ctx/tool/config shapes are live-verified and which are not:
+// It ships in the @macintacos/caret npm package. `caret install` lists the package
+// under v1's `plugin` config key or v2's `plugins` key (v2 reads both, legacy `plugin`
+// first). OpenCode imports the package entry, index.ts, which re-exports this file's
+// default; it withholds v2's caret.plugin.v2.ts and caret.tui.ts for now.
+// 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.
 
-import { spawn } from "node:child_process";
-import { mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, relative, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
+import { relative } from "node:path";
 
 import { type Hooks, type Plugin, tool } from "@opencode-ai/plugin";
 
 import {
-  buildEnvelope,
-  decisionText,
-  nodeSpawnRunner,
-  PLAN_TITLE_INSTRUCTION,
-  runReviewViaCaret,
-  type SpawnRunner,
-} from "./review-bridge.ts";
-
-/** Install-time markers. The legacy file-deploy path substituted these with the
- * resolved caret version and binary path; the array install leaves them as
- * placeholders, so the resolvers below fall back to the package that ships this
- * file. */
-export const CARET_PLUGIN_VERSION = "__CARET_VERSION__";
-const CARET_BIN = "__CARET_BIN__";
-
-/** The caret binary the review tool spawns. Env override wins; then a substituted
- * marker (an absolute path, from the legacy file-deploy path); else the binary that
- * ships beside this module in the npm package (the array install). */
-export function resolveCaretBin(opts: {
-  env: Record<string, string | undefined>;
-  marker: string;
-  importMetaUrl: string;
-}): string {
-  const override = opts.env.CARET_OPENCODE_BIN?.trim();
-  if (override) return override;
-  if (opts.marker !== "__CARET_BIN__") return opts.marker;
-  return fileURLToPath(new URL("../bin/caret", opts.importMetaUrl));
-}
-
-/** The plugin's own caret version, for the update check. A substituted marker wins
- * (file-deploy); else read it from the package.json shipped beside this module (the
- * array install). "unknown" when neither is available — deliberately UNPARSEABLE so
- * `isNewer` compares false and a broken read stays silent ("0.0.0" would parse and
- * nag "update available (you have 0.0.0)" on every start). */
-export function resolveCaretVersion(opts: {
-  marker: string;
-  importMetaUrl: string;
-  readFile: (path: string) => string;
-}): string {
-  if (opts.marker !== "__CARET_VERSION__") return opts.marker;
-  try {
-    const raw = opts.readFile(fileURLToPath(new URL("../package.json", opts.importMetaUrl)));
-    const v = (JSON.parse(raw) as { version?: unknown }).version;
-    return typeof v === "string" ? v : "unknown";
-  } catch {
-    return "unknown";
-  }
-}
-
-/** 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;
-
-// ---------------------------------------------------------------------------
-// Pure helpers (exported for unit tests)
-// ---------------------------------------------------------------------------
-
-/** True for the planning agent(s) caret treats specially — the planning steer and
- * the daemon warm-up both fire only for them. Not a permission check: the review
- * tool itself is open to every primary agent. */
-export function isPlanningAgent(agent: string | undefined): boolean {
-  return agent !== undefined && (PLANNING_AGENTS as readonly string[]).includes(agent);
-}
-
-/** The label caret puts in the review toast's TITLE. The review URL goes in the
- * toast MESSAGE alone, not concatenated after this — OpenCode's toast word-wraps,
- * and a URL sharing a line with this prefix breaks across the wrap and stops being
- * terminal-clickable (EXC-691). caret owns this toast surface because OpenCode
- * renders `caret_review_plan` as a generic tool whose running state never shows the
- * tool's `metadata` title. */
-const REVIEW_TOAST_TITLE = "caret: review this plan";
+  decisionToast,
+  isPlanningAgent,
+  nodeWarmRunner,
+  PLAN_ARG_DESCRIPTION,
+  PLANNING_AGENTS,
+  pathArgDescription,
+  planningSteer,
+  productionUpdateCheck,
+  REVIEW_TOOL,
+  REVIEW_TOOL_DESCRIPTION,
+  resolveCaretBin,
+  resolvePlansDir,
+  reviewLinkToast,
+  runPlanReview,
+  type ToastBody,
+  type ToastSink,
+  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
  * against version skew between the pinned plugin SDK and the running OpenCode. */
-type ToastBody = {
-  title?: string;
-  message: string;
-  variant: "info" | "success" | "warning" | "error";
-  duration?: number;
-};
-type ToastClient = { tui?: { showToast?: (opts: { body: ToastBody }) => unknown } } | undefined;
+export type ToastClient =
+  | { tui?: { showToast?: (opts: { body: ToastBody }) => unknown } }
+  | undefined;
 
 /** The same client, narrowed to the session read the review tool's subagent check
  * makes — narrowed separately, and for the same skew-safety reason, so each helper
@@ -128,26 +70,12 @@ type SessionClient =
 /** What OpenCode actually hands the plugin: both narrowings at once. */
 type CaretClient = NonNullable<ToastClient> & NonNullable<SessionClient>;
 
-/** How long the pending review-link toast stays up. Long enough to outlast a
- * review; on a decision we supersede it with the short toast below, so this
- * ceiling only bites if the review process dies without ever deciding. */
-const REVIEW_TOAST_MS = 10 * 60_000;
-/** The brief decision toast that supersedes (and thereby clears) the review-link
- * toast, since OpenCode's single-slot toast surface has no hide API. */
-const DECISION_TOAST_MS = 4_000;
-
-/** Best-effort toast: surfacing or clearing the review link must never crash or
- * delay the review. Swallows a missing method (SDK skew) and any sync throw or
- * async rejection. Called as `tui.showToast(...)` so the SDK client keeps its
- * `this` binding. */
-function showToast(client: ToastClient, body: ToastBody): void {
+/** v1's toast sink, through `toastBestEffort`. A missing method (SDK skew) is a no-op.
+ * Called as `tui.showToast(...)` so the SDK client keeps its `this` binding. */
+export function showToast(client: ToastClient, body: ToastBody): void {
   const tui = client?.tui;
   if (!tui || typeof tui.showToast !== "function") return;
-  try {
-    Promise.resolve(tui.showToast({ body })).catch(() => {});
-  } catch {
-    // best-effort — the review decision is what matters.
-  }
+  toastBestEffort((b) => tui.showToast?.({ body: b }), body);
 }
 
 /** True when this tool call arrived from a subagent — a `parentID` on the calling
@@ -170,239 +98,6 @@ async function isSubagentSession(client: SessionClient, sessionID: string): Prom
   }
 }
 
-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 plugin 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
- * most once a day (see UPDATE_CHECK_INTERVAL_MS), so it never approaches the
- * 60 req/hr/IP limit. */
-const LATEST_RELEASE_URL = "https://api.github.com/repos/macintacos/caret/releases/latest";
-/** How long the update nudge stays up — long enough to read the link. */
-const UPDATE_TOAST_MS = 5_000;
-/** Minimum gap between update checks. The nudge is a convenience, not a security
- * fix, so checking once a day is plenty — and it keeps the network hit off every
- * 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 {
-  if (typeof json !== "object" || json === null) return null;
-  const o = json as { tag_name?: unknown; html_url?: unknown };
-  if (typeof o.tag_name !== "string") return null;
-  const url =
-    typeof o.html_url === "string"
-      ? o.html_url
-      : "https://github.com/macintacos/caret/releases/latest";
-  return { version: o.tag_name.replace(/^v/, ""), url };
-}
-
-/** The update-available toast body, or null when the user is already current. */
-export function updateToastBody(
-  current: string,
-  latest: { version: string; url: string },
-): ToastBody | null {
-  if (!isNewer(latest.version, current)) return null;
-  return {
-    title: "caret update available",
-    message: `caret ${latest.version} is available (you have ${current}). ${latest.url}`,
-    variant: "info",
-    duration: UPDATE_TOAST_MS,
-  };
-}
-
-/** The slice of `fetch` the update check needs — narrow so a test can pass a plain
- * stub without reconstructing `fetch`'s `preconnect` sibling. The global `fetch`
- * (and Bun's) is assignable to it. */
-type FetchLike = (
-  url: string,
-  init?: { headers?: Record<string, string> },
-) => Promise<{ ok: boolean; json: () => Promise<unknown> }>;
-
-/** True when the last check is old enough (or absent) to check again. Pure so the
- * 24h throttle is unit-testable without a clock or the filesystem. */
-export function shouldCheckForUpdate(lastCheckMs: number | null, nowMs: number): boolean {
-  return lastCheckMs === null || nowMs - lastCheckMs >= UPDATE_CHECK_INTERVAL_MS;
-}
-
-/** Absolute path of the throttle file holding the last-check epoch-ms. Lives under
- * caret's state dir, beside caret's other small machine-global markers (update-check.json).
- * The plugin stays self-contained and cannot import src/config/paths.ts, so that
- * convention is mirrored here by hand. */
-export function updateCheckCachePath(
-  env: Record<string, string | undefined>,
-  home: string,
-): string {
-  const base = env.XDG_STATE_HOME?.trim() || `${home}/.local/state`;
-  return `${base}/caret/opencode-update-check`;
-}
-
-/** The throttle seam: read the last-check epoch-ms (null when never / unreadable),
- * and persist a new one. Injected so realUpdateChecker's throttle is testable
- * without touching disk. */
-type UpdateCache = { read: () => number | null; write: (epochMs: number) => void };
-
-/** File-backed UpdateCache. Read tolerates a missing or garbage file (→ null, so
- * the check runs); write is best-effort — a failure just means we check again next
- * start rather than crashing plugin load. */
-function fileUpdateCache(path: string): UpdateCache {
-  return {
-    read: () => {
-      try {
-        const n = Number.parseInt(readFileSync(path, "utf-8").trim(), 10);
-        return Number.isFinite(n) ? n : null;
-      } catch {
-        return null;
-      }
-    },
-    write: (epochMs) => {
-      try {
-        mkdirSync(dirname(path), { recursive: true });
-        writeFileSync(path, String(epochMs));
-      } catch {
-        // best-effort — a throttle-file write must never disrupt load.
-      }
-    },
-  };
-}
-
-/** Best-effort startup update check: fetch caret's latest GitHub release and, if it
- * is newer than this plugin's version, toast a nudge with a link. Throttled to at
- * most once a day via the injected cache. Never throws and never blocks plugin load
- * — the `CARET_OPENCODE_NO_UPDATE_CHECK` opt-out and every failure resolve
- * silently. */
-export async function realUpdateChecker(
-  client: ToastClient,
-  opts: {
-    currentVersion: string;
-    env: Record<string, string | undefined>;
-    fetchImpl: FetchLike;
-    now: () => number;
-    cache: UpdateCache;
-    url?: string;
-  },
-): Promise<void> {
-  if (opts.env.CARET_OPENCODE_NO_UPDATE_CHECK) return;
-  const nowMs = opts.now();
-  if (!shouldCheckForUpdate(opts.cache.read(), nowMs)) return;
-  // Stamp the check up front so a failed/offline check still backs off a day.
-  opts.cache.write(nowMs);
-  try {
-    const res = await opts.fetchImpl(opts.url ?? LATEST_RELEASE_URL, {
-      headers: { "user-agent": "caret-opencode-plugin", accept: "application/vnd.github+json" },
-    });
-    if (!res.ok) return;
-    const latest = parseLatestRelease(await res.json());
-    if (!latest) return;
-    const body = updateToastBody(opts.currentVersion, latest);
-    if (body) showToast(client, body);
-  } catch {
-    // best-effort — an update nudge must never disrupt the session.
-  }
-}
-
-/** Where the planning steer sends the plan agent's plan file: `[opencode] plans_dir`
- * from caret's config.toml (a leading `~` expanded), else OpenCode's data-dir
- * `plans/`, which OpenCode's plan agent may edit. The config path mirrors
- * src/config/paths.ts configFile() by hand, since the plugin cannot import src/. */
-export function resolvePlansDir(opts: {
-  env: Record<string, string | undefined>;
-  home: string;
-  readFile: (path: string) => string;
-}): string {
-  const configFile =
-    opts.env.CARET_CONFIG_FILE ||
-    `${opts.env.XDG_CONFIG_HOME || `${opts.home}/.config`}/caret/config.toml`;
-  try {
-    const config = Bun.TOML.parse(opts.readFile(configFile)) as {
-      opencode?: { plans_dir?: unknown };
-    };
-    const dir = config.opencode?.plans_dir;
-    if (typeof dir === "string" && dir) return dir.replace(/^~(?=\/|$)/, opts.home);
-  } catch {
-    // An absent or malformed config.toml leaves the default.
-  }
-  return `${opts.env.XDG_DATA_HOME || `${opts.home}/.local/share`}/opencode/plans`;
-}
-
-/** The planning-prompt steer appended to the system array so the Plan agent
- * submits its plan to caret instead of calling the native plan_exit. */
-export function planningSteer(plansDir: string): string {
-  return [
-    "## Plan review (caret)",
-    "",
-    `When you have a plan ready for the user, do NOT call plan_exit. Instead write the plan as markdown to a file in \`${plansDir}/\` (a directory you may write to), for example \`${plansDir}/<short-name>.md\`, and call the \`${REVIEW_TOOL}\` tool with that file as the \`path\` argument.`,
-    "It opens caret's visual review UI in the browser; the user approves or requests changes. A change request comes back as the tool result: re-read the file, revise it with targeted edits rather than rewriting it, and call the tool again with the same `path` until it is approved. An approved plan is already saved in that file.",
-    PLAN_TITLE_INSTRUCTION,
-  ].join("\n");
-}
-
 // --- config-hook mutation (subagent-bypass mitigation) -------------------------
 
 type LooseAgent = { mode?: string; permission?: unknown } & Record<string, unknown>;
@@ -452,26 +147,6 @@ function ensurePermission(agent: LooseAgent): Record<string, unknown> {
   return agent.permission as Record<string, unknown>;
 }
 
-/** Warms the caret daemon ahead of a review. Injected so the chat.message hook is
- * 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. */
-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 plugin
 // ---------------------------------------------------------------------------
@@ -485,13 +160,11 @@ export function createCaretPlugin(
     bin?: string;
     run?: SpawnRunner;
     warm?: WarmRunner;
-    checkUpdate?: (client: ToastClient) => void;
+    checkUpdate?: (show: ToastSink) => void;
     plansDir?: string;
   } = {},
 ): Plugin {
-  const bin =
-    opts.bin ??
-    resolveCaretBin({ env: process.env, marker: CARET_BIN, importMetaUrl: import.meta.url });
+  const bin = opts.bin ?? resolveCaretBin({ env: process.env, importMetaUrl: import.meta.url });
   const run = opts.run ?? nodeSpawnRunner;
   const warm = opts.warm ?? nodeWarmRunner;
   const plansDir =
@@ -508,7 +181,7 @@ export function createCaretPlugin(
     const client = (input as { client?: CaretClient }).client;
     // Startup update nudge (EXC-794), fire-and-forget. Only the production default
     // export wires this.
-    if (opts.checkUpdate) opts.checkUpdate(client);
+    if (opts.checkUpdate) opts.checkUpdate((body) => showToast(client, body));
     // The agent driving each session, recorded by chat.message and read by
     // system.transform, which carries no agent of its own. Why a map is the only
     // route: `doc/agents/opencode-integration.md` § Why gating the steer needs a
@@ -528,10 +201,12 @@ export function createCaretPlugin(
       // may call the tool: the plan agent is the one whose turn reliably ends in a review,
       // and warming on every build message would spawn a process on the session's busiest
       // traffic to save ~0.4s in the rare case.
-      "chat.message": async (input) => {
+      "chat.message": async (input, output) => {
+        // A client may omit `input.agent`; OpenCode resolves the default onto the message.
+        const agent = input.agent ?? output.message.agent;
         // A message whose agent is unknown must not clobber the recorded one.
-        if (input.sessionID && input.agent) sessionAgents.set(input.sessionID, input.agent);
-        if (!isPlanningAgent(input.agent)) return;
+        if (input.sessionID && agent) sessionAgents.set(input.sessionID, agent);
+        if (!isPlanningAgent(agent)) return;
         try {
           warm(bin);
         } catch {
@@ -557,82 +232,48 @@ export function createCaretPlugin(
       },
       tool: {
         [REVIEW_TOOL]: 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.",
+          description: REVIEW_TOOL_DESCRIPTION,
           args: {
-            plan: tool.schema
-              .string()
-              .optional()
-              .describe(
-                "The complete plan, as markdown, to present for human review. The inline alternative to `path`.",
-              ),
-            path: tool.schema
-              .string()
-              .optional()
-              .describe(
-                `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}/.)`,
-              ),
+            plan: tool.schema.string().optional().describe(PLAN_ARG_DESCRIPTION),
+            path: tool.schema.string().optional().describe(pathArgDescription(plansDir)),
           },
           async execute(args, context) {
-            if (await isSubagentSession(client, context.sessionID)) {
-              return `${REVIEW_TOOL} is available to primary agents only; this call came from a subagent session. Continue without caret review, or hand the plan back to the primary agent to submit.`;
-            }
-            const source = resolvePlanSource(args, context.directory, readRegularFile);
-            if ("error" in source) return source.error;
-            if (source.planFilePath) {
-              // caret rewrites this file, and the model chose the path, so OpenCode's own
-              // edit permission must allow it.
-              try {
-                await context.ask({
-                  permission: "edit",
-                  patterns: [relative(context.worktree, source.planFilePath)],
-                  always: ["*"],
-                  metadata: { filepath: source.planFilePath },
-                });
-              } catch {
-                return `caret: ${REVIEW_TOOL} was not permitted to edit ${source.planFilePath}, which a path review rewrites. Write the plan in \`${plansDir}/\` and pass that file as \`path\`, or pass the plan inline as \`plan\`.`;
-              }
-            }
-            const envelope = buildEnvelope(source.plan, {
-              sessionID: context.sessionID,
-              directory: context.directory,
-              planFilePath: source.planFilePath,
-            });
             let linkShown = false;
-            const decision = await runReviewViaCaret(envelope, {
-              command: [bin, "review"],
-              agent: "opencode",
-              run,
-              // Show the review URL as a toast while the plan is pending.
-              onUrl: (url) => {
-                linkShown = true;
-                showToast(client, {
-                  title: REVIEW_TOAST_TITLE,
-                  message: url,
-                  variant: "info",
-                  duration: REVIEW_TOAST_MS,
-                });
+            const { text, decision } = await runPlanReview(
+              args,
+              {
+                sessionID: context.sessionID,
+                directory: context.directory,
+                isSubagent: () => isSubagentSession(client, context.sessionID),
+                canEdit: async (planFilePath) => {
+                  try {
+                    await context.ask({
+                      permission: "edit",
+                      patterns: [relative(context.worktree, planFilePath)],
+                      always: ["*"],
+                      metadata: { filepath: planFilePath },
+                    });
+                    return true;
+                  } catch {
+                    return false;
+                  }
+                },
+                signal: context.abort,
+                onUrl: (url) => {
+                  linkShown = true;
+                  showToast(client, reviewLinkToast(url));
+                },
               },
-            });
+              { bin, run, plansDir },
+            );
             // Supersede the pending review-link toast with a brief decision toast —
             // the surface is single-slot with no hide API (EXC-691).
-            if (linkShown) {
-              showToast(
-                client,
-                decision.behavior === "allow"
-                  ? {
-                      message: "caret: plan approved",
-                      variant: "success",
-                      duration: DECISION_TOAST_MS,
-                    }
-                  : {
-                      message: "caret: changes requested",
-                      variant: "info",
-                      duration: DECISION_TOAST_MS,
-                    },
-              );
+            if (linkShown && context.abort.aborted) {
+              showToast(client, decisionToast("cancelled"));
+            } else if (linkShown && decision) {
+              showToast(client, decisionToast(decision.behavior));
             }
-            return decisionText(decision, REVIEW_TOOL, source.planFilePath);
+            return text;
           },
         }),
       },
@@ -641,21 +282,7 @@ export function createCaretPlugin(
   };
 }
 
-/** The plugin OpenCode loads (bare default-export function), wiring the production
- * update checker. */
-const CaretPlugin: Plugin = createCaretPlugin({
-  checkUpdate: (client) => {
-    void realUpdateChecker(client, {
-      currentVersion: resolveCaretVersion({
-        marker: CARET_PLUGIN_VERSION,
-        importMetaUrl: import.meta.url,
-        readFile: (p) => readFileSync(p, "utf-8"),
-      }),
-      env: process.env,
-      fetchImpl: fetch,
-      now: () => Date.now(),
-      cache: fileUpdateCache(updateCheckCachePath(process.env, homedir())),
-    });
-  },
-});
+/** caret's OpenCode v1 plugin, which index.ts's lazy `server` delegates to, wired to the
+ * production update checker. */
+const CaretPlugin: Plugin = createCaretPlugin({ checkUpdate: productionUpdateCheck });
 export default CaretPlugin;