@macintacos/caret 1.4.1 → 1.5.0

package/hooks/hooks.json

@@ -1,4 +1,5 @@
 {
+  "modules": ["../mod/hooks/band.tsx"],
   "hooks": {
     "PermissionRequest": [
       {

package/mod/band.d.ts

@@ -0,0 +1,5 @@
+declare module "claude-code" {
+  interface PluginState {
+    caret: { band: { session: string; url: string; owner: string } | null };
+  }
+}

package/mod/hooks/band.tsx

@@ -0,0 +1,84 @@
+// Claude Code's plan-waiting band. caret's CLI owns the link — host, port, login token —
+// and the band's on/off setting, so nothing here repeats caret's rules.
+import type { Hook, Register } from "claude-code";
+import { atom, read, update } from "claude-code";
+
+type Shown = { session: string; url: string; owner: string };
+type HookDollar = Parameters<Hook<"tool.call">>[0];
+
+const band = atom({ plugin: "caret", key: "band" } as const, null as Shown | null);
+
+// $.process.run takes no shell, and Windows cannot exec bin/caret's shebang. The timeout
+// must outlast band-link's review poll (src/commands/band-link.ts) plus its boot.
+const caret = ($: HookDollar, ...args: string[]) =>
+  $.process.run(["bash", `${$.plugin.root}/bin/caret`, ...args], { timeoutMs: 15_000 });
+
+// A band that breaks must never hold up the review: pass the event on.
+const passThrough = <E, R>(_: unknown, e: E, next: (e: E) => R) => next(e);
+
+const bandWhile = async <T,>(
+  $: HookDollar,
+  session: string,
+  signal: AbortSignal,
+  review: () => Promise<T>,
+): Promise<T> => {
+  // Waits overlap (a backgrounded review_plan, then another call): each clears only its own band.
+  const owner = crypto.randomUUID();
+  let settled = false;
+  const clear = async () => {
+    settled = true;
+    await update($, band, (cur) => (cur?.owner === owner ? null : cur));
+  };
+  // An interrupt aborts the signal; nothing promises it settles `review`.
+  const onAbort = () => void clear();
+  signal.addEventListener("abort", onAbort, { once: true });
+  // Not awaited: the review never waits on the band.
+  void caret($, "band-link", "--session", session).then(
+    async ({ stdout }) => {
+      const url = stdout.trim();
+      if (url && !settled) await update($, band, () => ({ session, url, owner }));
+    },
+    () => {},
+  );
+  try {
+    return await review();
+  } finally {
+    signal.removeEventListener("abort", onAbort);
+    await clear();
+  }
+};
+
+export const register: Register = (on) => {
+  on("tool.call", { tool: "mcp__plugin_caret_caret__review_plan" }, async ($, e, next) =>
+    // The `mcp-` prefix is src/commands/mcp.ts's session id; keep the two in sync.
+    bandWhile($, `mcp-${await $.session.id()}`, next.signal, () => next(e)),
+  ).catch(passThrough);
+  // caret's own PermissionRequest hook sits beneath this one and holds the plan until a decision.
+  on("classic.PermissionRequest", { tool_name: "ExitPlanMode" }, ($, e, next) =>
+    bandWhile($, e.session_id, next.signal, () => next(e)),
+  ).catch(passThrough);
+  on("ui.render", { component: "AbovePrompt" }, async ($, e, next) => {
+    const shown = await read($, band);
+    if (e.props.hasSurvey || shown === null) return next(e);
+    const { Box, Button, Link, Text } = $.ui.resolve(e);
+    return (
+      <Box gap={1}>
+        <Link href={shown.url}>
+          <Text bold color="inverseText" backgroundColor="warning">
+            {" 🥕 CARET PLAN WAITING FOR YOUR REVIEW "}
+          </Text>
+        </Link>
+        {/* A bare digit in an empty prompt presses a band Button. */}
+        <Button
+          hotkey="1"
+          plain
+          onPress={() =>
+            void caret($, "band-link", "--session", shown.session, "--open").catch(() => {})
+          }
+        >
+          open in browser
+        </Button>
+      </Box>
+    );
+  });
+};

package/opencode/caret.plugin.v2.ts

@@ -23,7 +23,7 @@ import {
   runPlanReview,
   type WarmRunner,
 } from "./caret.core.ts";
-import { editPermitted, type Rule } from "./permission.ts";
+import { editChecks, editPermitted, 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
@@ -91,6 +91,15 @@ export type SetupContext = {
   tool: {
     transform: (callback: (tools: { add: (tool: ReviewTool) => void }) => void) => Promise<unknown>;
   };
+  /** Hosts ≥ 2.0.29 only. */
+  permission?: {
+    assert: (input: {
+      sessionID: string;
+      agent?: string;
+      action: string;
+      resources: string[];
+    }) => Promise<void>;
+  };
 };
 
 /** The v2 tool-call context fields caret's `execute` reads. */
@@ -118,6 +127,7 @@ export function createCaretSetup(opts: {
       input: unknown,
       context: ToolContext,
     ): Promise<{ content: string; metadata?: Record<string, string> }> {
+      let declined: unknown;
       try {
         const session = await readSession(context.sessionID).catch(() => undefined);
         const directory = session?.location.directory ?? ctx.location.directory;
@@ -130,15 +140,34 @@ export function createCaretSetup(opts: {
             // Fail-open: an unreadable session is treated as primary, as on v1.
             isSubagent: async () => Boolean(session?.parentID),
             canEdit: async (planFilePath) => {
+              const location = { directory, projectDirectory: ctx.location.project.directory };
+              const permission = ctx.permission;
+              if (typeof permission?.assert === "function") {
+                try {
+                  for (const check of editChecks(planFilePath, location)) {
+                    await permission.assert({
+                      sessionID: context.sessionID,
+                      agent: context.agent,
+                      action: check.action,
+                      resources: [check.resource],
+                    });
+                  }
+                  return true;
+                } catch (error) {
+                  if ((error as { _tag?: unknown } | null)?._tag === "Tool.Error") return false;
+                  // A plain rejection must end the step, so it escapes the fail-safe catch below.
+                  declined = error;
+                  throw error;
+                }
+              }
               // Session rules can deny, so an unreadable session cannot prove allow.
               if (!session) return false;
               try {
                 const agent = await ctx.agent.get({ agentID: context.agent });
-                return editPermitted(
-                  planFilePath,
-                  { directory, projectDirectory: ctx.location.project.directory },
-                  { agent: agent.data.permissions, session: session.permissions ?? [] },
-                );
+                return editPermitted(planFilePath, location, {
+                  agent: agent.data.permissions,
+                  session: session.permissions ?? [],
+                });
               } catch {
                 return false;
               }
@@ -155,6 +184,7 @@ export function createCaretSetup(opts: {
         if (!decision || context.signal.aborted) return { content: text };
         return { content: text, 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(

package/opencode/commands/doctor.md

@@ -3,13 +3,13 @@ description: Diagnose this caret install — run caret doctor, relay each failin
 ---
 
 caret's `doctor` subcommand renders a verdict over a one-shot, read-only snapshot of the
-local install: a `checks:` block naming what is wrong and how to fix it, then the state it
-read that from — running caret processes, daemon identity, lock/port state, effective
-settings, review counts, the OpenCode adapter's install-state probe (plugin version,
-enabled state), log sizes and error counts, recent failures grouped by review with their
-codes, and system basics. The report is **always redacted** (home paths become `~`,
-foreign usernames censored) and never contains plan, prompt, or feedback bodies — it
-exists to be shared.
+local install: the failing checks first, each with the command that fixes it, then the
+passing ones, then the state it read them from — running caret processes, daemon identity,
+lock/port state, effective settings, review counts, the OpenCode adapter's install-state
+probe (plugin version, enabled state), log sizes and error counts, recent failures grouped
+by review with their codes, and system basics. The report is **always redacted** (home
+paths become `~`, foreign usernames censored) and never contains plan, prompt, or feedback
+bodies — it exists to be shared.
 
 ## 1. Run it
 
@@ -47,9 +47,9 @@ one. What each id means:
 | `opencode-caret-version` | OpenCode 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 `<name> error: …`
-and leaves the check with no detail. Present it as-is. A daemon that is simply not running
-is not one of these — it reports `reachable false` and *passes*.
+config, or a report section that never collected, which also shows as an `error` line and
+leaves the check with no detail. Present it as-is. A daemon that is simply not running is
+not one of these — it reports `reachable false` and *passes*.
 
 ## 3. Present the report
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@macintacos/caret",
-  "version": "1.4.1",
+  "version": "1.5.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.",
@@ -28,6 +28,8 @@
     "commands/",
     "opencode/",
     "templates/",
+    "mod/hooks/band.tsx",
+    "mod/band.d.ts",
     ".claude-plugin/plugin.json"
   ],
   "scripts": {
@@ -46,13 +48,13 @@
     "@codemirror/state": "^6.6.0",
     "@codemirror/view": "^6.43.0",
     "@commander-js/extra-typings": "^15.0.0",
-    "@happy-dom/global-registrator": "^20.11.2",
+    "@happy-dom/global-registrator": "^21.0.4",
     "@internationalized/date": "^3.12.2",
     "@laststance/tailwind-suggest-canonical-classes": "^0.1.1",
     "@lezer/highlight": "^1.2.3",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "@opencode/plugin": "^2.0.18",
-    "@pierre/diffs": "1.3.6",
+    "@pierre/diffs": "1.5.2",
     "@pierre/trees": "1.0.0-beta.6",
     "@playwright/test": "^1.62.1",
     "@sveltejs/vite-plugin-svelte": "^7.3.0",
@@ -64,7 +66,7 @@
     "clsx": "^2.1.1",
     "commander": "^15.0.0",
     "cuelume": "^0.2.2",
-    "happy-dom": "^20.11.2",
+    "happy-dom": "^21.0.4",
     "jsonc-parser": "^3.3.1",
     "listr2": "^11.0.0",
     "marked": "^18.0.4",