@macintacos/caret 0.13.0 → 1.0.0

package/hooks/hooks.json

@@ -20,6 +20,11 @@
             "type": "command",
             "command": "${CLAUDE_PLUGIN_ROOT}/bin/caret prewarm",
             "timeout": 30
+          },
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/bin/caret steer",
+            "timeout": 10
           }
         ]
       },
@@ -33,6 +38,17 @@
           }
         ]
       }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/bin/caret steer",
+            "timeout": 10
+          }
+        ]
+      }
     ]
   }
 }

package/opencode/caret.plugin.ts

@@ -2,13 +2,11 @@
 // shaped: it loads this in-process module and lets it register tools and mutate
 // config. caret has no native plan-approval gate to intercept here (OpenCode has
 // no ExitPlanMode equivalent), so this plugin REGISTERS its own plan-review tool,
-// steers the Plan agent to call it, and
-// runs the review synchronously inside the tool's execute(): it spawns
-// `caret review` (CARET_AGENT=opencode) with a caret-defined envelope on stdin,
-// blocks until the human decides in caret's browser UI, and returns the approval
-// or change-request string as the tool result. 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`.
+// steers the Plan agent to call it, and runs the review synchronously inside the
+// 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`.
 //
 // 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
@@ -17,24 +15,31 @@
 // 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.
 //
-// This file runs in-process inside OpenCode. 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 (child_process, fs, url) and
-// @opencode-ai/plugin (resolved by OpenCode at runtime). Live in-OpenCode
-// verification of the exact ctx/tool/config shapes is recorded in
-// doc/agents/opencode-integration.md § Verified vs. follow-up, which also names what
-// remains unverified; the pure logic below is covered by test/opencode/.
+// 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:
+// doc/agents/opencode-integration.md § Verified vs. follow-up.
 
 import { spawn } from "node:child_process";
-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname } from "node:path";
+import { dirname, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 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
@@ -83,73 +88,10 @@ export const REVIEW_TOOL = "caret_review_plan";
  * the review tool and warms the daemon for. */
 export const PLANNING_AGENTS = ["plan"] as const;
 
-export interface CaretDecision {
-  behavior: "allow" | "deny";
-  feedback?: string;
-}
-
 // ---------------------------------------------------------------------------
 // Pure helpers (exported for unit tests)
 // ---------------------------------------------------------------------------
 
-/** The first markdown heading in the plan, used as the review title — or
- * undefined when the plan has no `# ` heading. */
-export function planTitle(plan: string): string | undefined {
-  for (const line of plan.split("\n")) {
-    const m = line.match(/^#\s+(.+?)\s*$/);
-    if (m?.[1]) return m[1];
-  }
-  return undefined;
-}
-
-/** Build the caret review envelope `caret review` (CARET_AGENT=opencode) parses.
- * Mirrors the snake_case session/cwd shape the opencode adapter's parseHookInput
- * reads — both ends are caret-owned. */
-export function buildEnvelope(
-  plan: string,
-  ctx: { sessionID?: string; directory?: string },
-): string {
-  return JSON.stringify({
-    session_id: ctx.sessionID,
-    cwd: ctx.directory,
-    tool_input: { plan, title: planTitle(plan) },
-  });
-}
-
-/** Parse the single decision JSON line `caret review` prints on stdout. Fail-safe:
- * anything unrecognized or unparseable becomes a deny — shipping an unreviewed
- * plan is the one outcome caret never allows. */
-export function parseDecision(stdout: string): CaretDecision {
-  const line =
-    stdout
-      .trim()
-      .split("\n")
-      .map((s) => s.trim())
-      .filter(Boolean)
-      .at(-1) ?? "";
-  try {
-    const d = JSON.parse(line) as { behavior?: unknown; feedback?: unknown };
-    if (d.behavior === "allow") {
-      // Reviewer notes (EXC-791) ride the allow; surface them to the agent below.
-      const notes = typeof d.feedback === "string" ? d.feedback.trim() : "";
-      return notes ? { behavior: "allow", feedback: notes } : { behavior: "allow" };
-    }
-    if (d.behavior === "deny") {
-      return {
-        behavior: "deny",
-        feedback: typeof d.feedback === "string" ? d.feedback : "Plan changes requested.",
-      };
-    }
-    return failsafeDeny("caret: unrecognized review decision — denying to fail safe.");
-  } catch {
-    return failsafeDeny("caret: could not parse the review decision — denying to fail safe.");
-  }
-}
-
-function failsafeDeny(feedback: string): CaretDecision {
-  return { behavior: "deny", feedback };
-}
-
 /** 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. */
@@ -157,65 +99,12 @@ export function isPlanningAgent(agent: string | undefined): boolean {
   return agent !== undefined && (PLANNING_AGENTS as readonly string[]).includes(agent);
 }
 
-/** Tool result returned to the agent on approval. Optional reviewer notes
- * (EXC-791) are folded in as a clearly-labeled section the agent incorporates as
- * it implements — the plan is already approved, so no re-planning round. The
- * OpenCode agent holds the plan in its own tool args (there is no plan file to
- * append to), so this tool result is the delivery channel. */
-export function approvedMessage(notes?: string): string {
-  const base = "caret: the user APPROVED this plan. Proceed with the implementation as planned.";
-  const trimmed = notes?.trim();
-  if (!trimmed) return base;
-  return [
-    "caret: the user APPROVED this plan.",
-    "",
-    "They added notes to fold into your work — incorporate them as you implement; no need to re-plan:",
-    "",
-    "## Notes from the user",
-    "",
-    trimmed,
-    "",
-    "Proceed with the implementation.",
-  ].join("\n");
-}
-
-/** Tool result returned to the agent on a change request: the reviewer feedback
- * and a resubmit instruction. The plan itself is NOT echoed — the agent already
- * has it in its own `caret_review_plan` tool-call args, so re-pasting the full
- * plan every round is redundant. A feedback line reference indexes the plan
- * version caret stored, and the abbreviated quote paired with it is what the agent
- * matches against its own text. `abbreviate` in ui/src/lib/feedback.ts builds that
- * quote. The stored version is rumdl-reflowed to 90 columns at ingest
- * (src/plan/markdown.ts); on this path there is no plan file to mirror it back to,
- * so the numbers need not line up with the agent's copy at all. (Pinned across its
- * three surfaces by test/structure/line-anchor-claim.test.ts.) */
-export function deniedMessage(feedback: string): string {
-  return [
-    "caret: the user requested CHANGES to this plan.",
-    "",
-    "Feedback:",
-    feedback,
-    "",
-    `Revise the plan accordingly, then call \`${REVIEW_TOOL}\` again with the updated plan.`,
-  ].join("\n");
-}
-
-/** Extract caret's review URL from the child's stderr text. Core writes
- * `caret: review this plan at <url>\n` (src/review/orchestrate.ts); both ends are caret-owned,
- * so this regex is coupled to that one line by design. The trailing `\s` match
- * means a stderr chunk cut off mid-URL (before the newline) yields nothing rather
- * than a truncated URL — the match only fires once the whole line has arrived. */
-export function parseReviewUrl(stderr: string): string | undefined {
-  return stderr.match(/caret: review this plan at (\S+)\s/)?.[1];
-}
-
 /** The label caret puts in the review toast's TITLE. The review URL goes in the
- * toast MESSAGE (on its own line), 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. Title + message-alone keeps the (short) URL whole
- * on its own full-width line (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. */
+ * 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";
 
 /** OpenCode's plugin client, structurally narrowed to the calls caret makes.
@@ -281,6 +170,48 @@ 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 — the same check the core's plan-file write-back makes,
+ * repeated here because this plugin cannot import src/. `readPlanFile` returns the
+ * text, or undefined when absPath is not a readable regular file. */
+export function resolvePlanSource(
+  args: { plan?: string; path?: string },
+  directory: string,
+  readPlanFile: (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 = readPlanFile(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
@@ -291,7 +222,7 @@ const LATEST_RELEASE_URL = "https://api.github.com/repos/macintacos/caret/releas
 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. The last-check time is persisted in a small throttle file. */
+ * 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
@@ -360,10 +291,9 @@ export function shouldCheckForUpdate(lastCheckMs: number | null, nowMs: number):
 }
 
 /** Absolute path of the throttle file holding the last-check epoch-ms. Lives under
- * caret's state dir ($XDG_STATE_HOME/caret or ~/.local/state/caret), matching where
- * caret keeps its other small machine-global markers (prefs.json). Pure so the
- * location is testable; the plugin stays self-contained and cannot import
- * src/config/paths.ts, so the convention is mirrored here by hand. */
+ * caret's state dir, beside caret's other small machine-global markers (prefs.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,
@@ -403,12 +333,9 @@ function fileUpdateCache(path: string): UpdateCache {
 
 /** 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 — the check time is stamped up front, so
- * even an offline/failed start backs off a full day rather than hitting the network
- * on every restart. Never throws and never blocks plugin load — a network error, a
- * non-200, an unusable body, the throttle, or the `CARET_OPENCODE_NO_UPDATE_CHECK`
- * opt-out all resolve silently. `fetchImpl`/`url`/`now`/`cache` are injected so it is
- * unit-testable without the network or the filesystem. */
+ * 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: {
@@ -439,14 +366,39 @@ export async function realUpdateChecker(
   }
 }
 
+/** 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(): string {
+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 call the \`${REVIEW_TOOL}\` tool with your full plan (markdown) as the \`plan\` argument.`,
-    "It opens caret's visual review UI in the browser; the user approves or requests changes. Any change request comes back as the tool result — revise the plan and call the tool again until it is approved.",
+    `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");
 }
 
@@ -499,97 +451,16 @@ function ensurePermission(agent: LooseAgent): Record<string, unknown> {
   return agent.permission as Record<string, unknown>;
 }
 
-// --- the spawn bridge ----------------------------------------------------------
-
-/** Runs `caret review`, returning its captured stdout. Injected so execute() is
- * unit-testable without spawning a real process. `onStderr` streams the child's
- * stderr chunks as they arrive, so the caller can surface the review URL the core
- * prints there while the review is still pending. */
-export type SpawnRunner = (
-  bin: string,
-  env: Record<string, string | undefined>,
-  stdin: string,
-  onStderr?: (chunk: string) => void,
-) => Promise<{ stdout: string; exitCode: number }>;
-
-/** Spawn `caret review` with the review envelope on stdin and CARET_AGENT=opencode,
- * then parse its decision line. Any spawn failure fails safe to a deny. `onUrl`, if
- * given, fires once with the review URL the moment core prints it on stderr — the
- * caller surfaces it inside the tool block so it clears on decision (EXC-691). */
-export async function runReviewViaCaret(
-  envelope: string,
-  opts: { bin: string; run: SpawnRunner; onUrl?: (url: string) => void },
-): Promise<CaretDecision> {
-  try {
-    // Accumulate stderr and report the URL once — the line may arrive split
-    // across chunks, and only the first occurrence matters.
-    const { onUrl } = opts;
-    let stderrBuf = "";
-    let urlSent = false;
-    const onStderr = onUrl
-      ? (chunk: string) => {
-          if (urlSent) return;
-          stderrBuf += chunk;
-          const url = parseReviewUrl(stderrBuf);
-          if (url) {
-            urlSent = true;
-            // Best-effort: surfacing the URL must never crash or fail-safe-deny
-            // the review. This fires on the stderr `data` event while we're
-            // suspended at `await opts.run(...)`, so a throw here would escape the
-            // try/catch below as an uncaughtException rather than a deny.
-            try {
-              onUrl(url);
-            } catch {
-              // swallow — the review decision is what matters.
-            }
-          }
-        }
-      : undefined;
-    const { stdout } = await opts.run(
-      opts.bin,
-      { ...process.env, CARET_AGENT: "opencode" },
-      envelope,
-      onStderr,
-    );
-    return parseDecision(stdout);
-  } catch (e) {
-    const message = e instanceof Error ? e.message : String(e);
-    return failsafeDeny(`caret: review failed to run (${message}) — denying to fail safe.`);
-  }
-}
-
-/** Production runner: spawn the caret binary's `review` subcommand. stderr is
- * PIPED (not inherited) and streamed to `onStderr`: inheriting it leaked core's
- * "review this plan at <url>" line straight into OpenCode's TUI scrollback, where
- * the renderer never owns it and it lingered after the decision (EXC-691). We now
- * parse that URL and surface it as a caret-owned toast instead; the child logs
- * diagnostics to caret.log, so dropping the rest of stderr loses nothing. */
-const nodeSpawnRunner: SpawnRunner = (bin, env, stdin, onStderr) =>
-  new Promise((resolve, reject) => {
-    const child = spawn(bin, ["review"], { env, stdio: ["pipe", "pipe", "pipe"] });
-    let stdout = "";
-    child.stdout.on("data", (chunk) => {
-      stdout += chunk.toString();
-    });
-    child.stderr.on("data", (chunk) => onStderr?.(chunk.toString()));
-    child.on("error", reject);
-    child.on("close", (code) => resolve({ stdout, exitCode: code ?? 0 }));
-    child.stdin.write(stdin);
-    child.stdin.end();
-  });
-
 /** 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. Two non-obvious
- * requirements, both spelled out in `doc/agents/opencode-integration.md` § Daemon
- * warm-up: CARET_AGENT rides along because this spawn is what stands the daemon
- * up and the daemon picks its adapter from that env; and 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. */
+ * 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",
@@ -604,16 +475,17 @@ const nodeWarmRunner: WarmRunner = (bin) => {
 // The plugin
 // ---------------------------------------------------------------------------
 
-/** Build the caret OpenCode plugin. The DI seam (bin/run/warm/checkUpdate) keeps
- * the tool's execute(), the daemon warm, and the startup update check
- * unit-testable; the default export wires the production runners and update
- * checker. */
+/** Build the caret OpenCode plugin. The DI seam (bin/run/warm/checkUpdate/plansDir)
+ * keeps the tool's execute(), the daemon warm, the planning steer, and the startup
+ * update check unit-testable; the default export wires the production runners and
+ * update checker. */
 export function createCaretPlugin(
   opts: {
     bin?: string;
     run?: SpawnRunner;
     warm?: WarmRunner;
     checkUpdate?: (client: ToastClient) => void;
+    plansDir?: string;
   } = {},
 ): Plugin {
   const bin =
@@ -621,14 +493,20 @@ export function createCaretPlugin(
     resolveCaretBin({ env: process.env, marker: CARET_BIN, importMetaUrl: import.meta.url });
   const run = opts.run ?? nodeSpawnRunner;
   const warm = opts.warm ?? nodeWarmRunner;
+  const plansDir =
+    opts.plansDir ??
+    resolvePlansDir({
+      env: process.env,
+      home: homedir(),
+      readFile: (p) => readFileSync(p, "utf-8"),
+    });
 
   return async (input) => {
-    // OpenCode gives every plugin its SDK client; caret uses it to surface the
-    // review link as a toast (EXC-691) and to read the calling session's shape.
-    // Narrowed structurally for skew-safety.
+    // The SDK client OpenCode hands every plugin — caret uses it for the review-link
+    // toast (EXC-691) and to read the calling session's shape.
     const client = (input as { client?: CaretClient }).client;
-    // Best-effort startup update nudge (EXC-794); fire-and-forget so it never
-    // delays plugin load. Only the production default export wires this.
+    // Startup update nudge (EXC-794), fire-and-forget. Only the production default
+    // export wires this.
     if (opts.checkUpdate) opts.checkUpdate(client);
     // 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
@@ -637,21 +515,18 @@ export function createCaretPlugin(
     // module-global, so a test constructs a fresh one.
     const sessionAgents = new Map<string, string>();
     const hooks: Hooks = {
-      // Restrict the review tool to primary agents (see applyCaretConfig).
       config: async (config) => {
         applyCaretConfig(config as unknown as LooseConfig);
       },
-      // Two jobs. (1) Record the session's agent, ALWAYS — it is what the steer
-      // below gates on. (2) Warm the daemon, for the PLAN AGENT ONLY, so the first
-      // caret_review_plan call doesn't pay the cold-spawn cost. This is
-      // OpenCode's counterpart to Claude Code's PostToolUse/EnterPlanMode
-      // prewarm hook — the closest-to-submission signal the plugin API offers.
-      // Deliberately per-message and unthrottled: the daemon idle-exits after
-      // [daemon].idle_ms (60s default), so a once-per-session warm would be
-      // dead long before the plan lands. The warm stays plan-only even though any
-      // primary agent 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.
+      // Two jobs. (1) Record the session's agent, ALWAYS — it is what the steer below
+      // gates on. (2) Warm the daemon, for the PLAN AGENT ONLY, so the first
+      // caret_review_plan call doesn't pay the cold-spawn cost. Deliberately per-message
+      // and unthrottled: the daemon idle-exits after [daemon].idle_ms (60s default; a
+      // resident daemon never does), so a once-per-session warm would be dead
+      // long before the plan lands. The warm stays plan-only even though any primary agent
+      // 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) => {
         // A message whose agent is unknown must not clobber the recorded one.
         if (input.sessionID && input.agent) sessionAgents.set(input.sessionID, input.agent);
@@ -672,9 +547,8 @@ export function createCaretPlugin(
       // it points plan_exit — permitted only on the plan agent — at caret.
       "experimental.chat.system.transform": async (input, output) => {
         const agent = input.sessionID ? sessionAgents.get(input.sessionID) : undefined;
-        if (isPlanningAgent(agent)) output.system.push(planningSteer());
+        if (isPlanningAgent(agent)) output.system.push(planningSteer(plansDir));
       },
-      // Redirect the native plan_exit tool's description toward caret's tool.
       "tool.definition": async (input, output) => {
         if (input.toolID === "plan_exit") {
           output.description = `Do not call this tool. Call ${REVIEW_TOOL} instead — it opens caret's visual plan-review UI for human approval.`;
@@ -683,27 +557,52 @@ export function createCaretPlugin(
       tool: {
         [REVIEW_TOOL]: tool({
           description:
-            "Submit the current plan to caret for human review in a local browser UI. Blocks until the user approves or requests changes. On a change request, revise the plan and call this tool again with the updated plan.",
+            "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.",
           args: {
             plan: tool.schema
               .string()
-              .describe("The complete plan, as markdown, to present for human review."),
+              .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}/.)`,
+              ),
           },
           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 envelope = buildEnvelope(args.plan, {
+            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, {
-              bin,
+              command: [bin, "review"],
+              agent: "opencode",
               run,
-              // Show the review URL as a toast while the plan is pending. The URL
-              // is the message ALONE (label in the title) so it renders on its own
-              // full-width line and word-wraps whole, staying clickable (EXC-691).
+              // Show the review URL as a toast while the plan is pending.
               onUrl: (url) => {
                 linkShown = true;
                 showToast(client, {
@@ -714,9 +613,8 @@ export function createCaretPlugin(
                 });
               },
             });
-            // Clear the pending review-link toast on decision by superseding it
-            // with a brief decision toast — OpenCode's toast surface is single-slot
-            // with no hide API, so a fresh toast replaces the link (EXC-691).
+            // 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,
@@ -733,9 +631,7 @@ export function createCaretPlugin(
                     },
               );
             }
-            return decision.behavior === "allow"
-              ? approvedMessage(decision.feedback)
-              : deniedMessage(decision.feedback ?? "Plan changes requested.");
+            return decisionText(decision, REVIEW_TOOL, source.planFilePath);
           },
         }),
       },
@@ -744,8 +640,8 @@ export function createCaretPlugin(
   };
 }
 
-/** The plugin OpenCode loads (bare default-export function). Wires the production
- * update checker: on load, check caret's latest release and toast if behind. */
+/** The plugin OpenCode loads (bare default-export function), wiring the production
+ * update checker. */
 const CaretPlugin: Plugin = createCaretPlugin({
   checkUpdate: (client) => {
     void realUpdateChecker(client, {