claude-plan-review 0.2.0 → 0.3.1

package/README.md

@@ -8,7 +8,10 @@ When Claude finishes a plan in **plan mode**, a `PreToolUse` hook on the
 `ExitPlanMode` tool intercepts it, opens the plan in your browser, and **blocks**
 until you decide:
 
-- **Approve** → Claude exits plan mode and starts implementing.
+- **Approve** → Claude exits plan mode and starts implementing **immediately** —
+  no need to switch back to the terminal and confirm. (If you leave any comments
+  before approving, they ride along as guidance for Claude to incorporate while
+  implementing — "approve with comments".)
 - **Request changes** → your line + general comments are sent back as the denial
   reason; Claude stays in plan mode and revises, producing a new version.
 
@@ -57,15 +60,6 @@ npx  claude-plan-review init --published     # if you have Node
 `--published` makes the hook run via the package runner (`bunx`/`npx`), so it works on
 any machine — nothing to keep in your repo but the one settings entry.
 
-### Option B — from a local clone (for hacking on it)
-
-```bash
-git clone https://github.com/pavlo-petrychenko/claude-plan-review
-cd claude-plan-review
-bun install                                  # or: npm install
-bun  src/cli.js init /path/to/your/project   # …or…
-node src/cli.js init /path/to/your/project   # writes an absolute-path hook command
-```
 
 ### All projects at once (global)
 
@@ -140,8 +134,10 @@ Claude finishes plan ──> PreToolUse hook (ExitPlanMode)
                           │  ensures the server is up, opens the browser
                           │  BLOCKS, polling for your decision
    browser (you) ─────────┘
-     approve  ──> hook emits {permissionDecision:"allow"}            ──> Claude implements
-     request  ──> hook emits {permissionDecision:"deny", reason:...} ──> Claude revises (new version)
+     approve  ──> hook emits {permissionDecision:"allow", updatedInput, additionalContext?} ──> Claude implements
+                  (updatedInput is what skips the native "Exit plan mode?" prompt;
+                   additionalContext carries any comments as "approve with comments")
+     request  ──> hook emits {permissionDecision:"deny", reason:...}                        ──> Claude revises (new version)
 ```
 
 ## Storage layout

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-plan-review",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Review, comment on, and approve/reject Claude Code plans in a local GitHub-style web UI — with persistent comments, version history, and diffs.",
   "type": "module",
   "bin": {

package/src/channels/gh.js

@@ -73,11 +73,13 @@ export function api(method, path, body) {
     }
   }
   const errText = `${r.stderr}${r.stdout}`.trim();
-  // gh surfaces a "(HTTP 404)"/"(HTTP 403)" + scope hint when the token can't touch gists
-  const needsGistScope =
-    /gist/i.test(errText) && /(scope|HTTP 40[34]|Not Found|requires)/i.test(errText);
+  const httpStatus = Number(errText.match(/HTTP (\d{3})/)?.[1]) || null;
+  // A genuine missing-scope error names the scope explicitly ("requires the
+  // 'gist' scope"). A bare 404 just means the gist is gone — don't conflate them.
+  const needsGistScope = /gist/i.test(errText) && /scope|requires/i.test(errText);
   return {
     ok: false,
+    httpStatus,
     error: errText || (r.spawnError ? String(r.spawnError.message || r.spawnError) : "gh failed"),
     needsGistScope,
   };

package/src/channels/gist.js

@@ -47,12 +47,15 @@ export function available() {
 }
 
 function ghError(res) {
+  // Only blame the scope when the token actually lacks it — otherwise surface
+  // gh's real error so a deleted gist / network failure isn't misdiagnosed.
+  const missingScope = res.needsGistScope && !gh.status().scopes.includes("gist");
   const e = new Error(
-    res.needsGistScope
-      ? `GitHub rejected the gist write — your gh token likely lacks the 'gist' scope. Run: ${REFRESH_CMD}`
+    missingScope
+      ? `GitHub rejected the gist write — your gh token lacks the 'gist' scope. Run: ${REFRESH_CMD}`
       : res.error || "gh request failed",
   );
-  e.fixCommand = res.needsGistScope ? REFRESH_CMD : null;
+  e.fixCommand = missingScope ? REFRESH_CMD : null;
   return e;
 }
 
@@ -87,6 +90,10 @@ export function update({ id: gistId, markdown, description, filename, oldFilenam
     description: description ?? "",
     files: { [fileKey]: filePatch },
   });
+  // The bound gist was deleted on GitHub — recreate one and re-bind instead of failing.
+  if (!res.ok && res.httpStatus === 404) {
+    return create({ markdown, description, filename: newName });
+  }
   if (!res.ok) throw ghError(res);
   return {
     id: res.data.id,

package/src/hook.js

@@ -23,17 +23,48 @@ const POLL_MS = 700;
 
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 
-function out(decision, reason, sys) {
-  process.stdout.write(
-    JSON.stringify({
-      hookSpecificOutput: {
-        hookEventName: "PreToolUse",
-        permissionDecision: decision,
-        permissionDecisionReason: reason,
-      },
-      systemMessage: sys,
-    }),
-  );
+function emit(payload) {
+  process.stdout.write(JSON.stringify(payload));
+}
+
+/**
+ * Approve and auto-proceed WITHOUT the terminal "Exit plan mode?" keypress.
+ *
+ * ExitPlanMode reports requiresUserInteraction()=true, so a bare allow falls
+ * through to the native prompt. The permission combiner only bypasses the
+ * prompt when the hook ALSO returns `updatedInput` (it treats that as "the hook
+ * already satisfied the user interaction"). So we echo the original tool input
+ * back. `additionalContext`, when present, carries the reviewer's notes into
+ * Claude's context — i.e. "approve with comments".
+ * (Verified against the Claude Code 2.1.185 binary.)
+ */
+function allow(toolInput, notes) {
+  const hookSpecificOutput = {
+    hookEventName: "PreToolUse",
+    permissionDecision: "allow",
+    permissionDecisionReason: notes
+      ? "Approved with comments in the plan-review UI."
+      : "Approved in the plan-review UI.",
+    updatedInput: toolInput, // REQUIRED to skip the native approval prompt
+  };
+  if (notes) hookSpecificOutput.additionalContext = notes;
+  emit({
+    hookSpecificOutput,
+    systemMessage: notes
+      ? "✅ Plan approved with comments via plan-review"
+      : "✅ Plan approved via plan-review",
+  });
+}
+
+function deny(reason) {
+  emit({
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: "deny",
+      permissionDecisionReason: reason,
+    },
+    systemMessage: "📝 Changes requested via plan-review",
+  });
 }
 
 function serverPort() {
@@ -92,7 +123,8 @@ async function main() {
 
   if (input.tool_name !== "ExitPlanMode") process.exit(0);
 
-  const plan = input.tool_input?.plan ?? "";
+  const toolInput = input.tool_input ?? {};
+  const plan = toolInput.plan ?? "";
   if (!plan.trim()) process.exit(0);
 
   const { key, version, reviewId } = recordPlan({
@@ -114,15 +146,11 @@ async function main() {
   while (Date.now() < deadline) {
     const review = getReview(reviewId);
     if (review && review.status === "approved") {
-      out("allow", "Approved in the plan-review UI.", "✅ Plan approved via plan-review");
+      allow(toolInput, review.notes);
       process.exit(0);
     }
     if (review && review.status === "rejected") {
-      out(
-        "deny",
-        review.reason || "Changes requested in the plan-review UI.",
-        "📝 Changes requested via plan-review",
-      );
+      deny(review.reason || "Changes requested in the plan-review UI.");
       process.exit(0);
     }
     await sleep(POLL_MS);

package/src/store.js

@@ -198,27 +198,50 @@ export function getReview(id) {
   return existsSync(reviewPath(id)) ? readJSON(reviewPath(id), null) : null;
 }
 
-/** Resolve a review; for reject, compile its version's comments into the reason. */
+/**
+ * Resolve a review.
+ *   - reject  → compile the version's comments into `reason` (fed back via deny).
+ *   - approve → if the version has comments, compile them into `notes`
+ *               (delivered to Claude as additionalContext on the allow — "approve with comments").
+ * Returns the review including `commentCount` so callers can reflect it in the UI.
+ */
 export function resolveReview(id, decision) {
   const review = getReview(id);
   if (!review) return null;
   review.status = decision === "approve" ? "approved" : "rejected";
   review.resolvedAt = now();
-  if (decision === "reject") review.reason = compileReason(review.projectKey, review.version);
+  review.commentCount = listComments(review.projectKey, review.version).length;
+  if (decision === "reject") {
+    review.reason = compileComments(review.projectKey, review.version, "reject");
+  } else {
+    const notes = compileComments(review.projectKey, review.version, "approve");
+    if (notes) review.notes = notes;
+  }
   writeFileSync(reviewPath(id), enc(review));
   return review;
 }
 
-function compileReason(key, n) {
+/**
+ * Format a version's comments for the model.
+ *   mode "reject"  → "address these, then re-present" (always returns text, even with no comments).
+ *   mode "approve" → "plan is approved, incorporate these notes" (returns "" when there are none).
+ */
+function compileComments(key, n, mode) {
   const comments = listComments(key, n);
   const lineComments = comments.filter((c) => c.line != null).sort((a, b) => a.line - b.line);
   const general = comments.filter((c) => c.line == null);
+
+  if (mode === "approve" && !lineComments.length && !general.length) return "";
+
   const md = getVersion(key, n)?.markdown ?? "";
   const lines = md.split("\n");
 
   const parts = [
-    "The reviewer requested changes to this plan in the plan-review UI. " +
-      "Address each comment below, then re-present the revised plan with ExitPlanMode.",
+    mode === "approve"
+      ? "The reviewer APPROVED this plan in the plan-review UI and left the notes below. " +
+        "Proceed with implementation, incorporating each note as you go."
+      : "The reviewer requested changes to this plan in the plan-review UI. " +
+        "Address each comment below, then re-present the revised plan with ExitPlanMode.",
   ];
   if (lineComments.length) {
     parts.push("\nLine comments:");
@@ -239,7 +262,7 @@ function compileReason(key, n) {
     parts.push("\nGeneral comments:");
     for (const c of general) parts.push(`- ${c.body}`);
   }
-  if (!lineComments.length && !general.length) {
+  if (mode === "reject" && !lineComments.length && !general.length) {
     parts.push("\n(No specific comments were left — please reconsider and improve the plan.)");
   }
   return parts.join("\n");

package/src/ui/app.js

@@ -359,13 +359,22 @@ async function refreshReview() {
 }
 
 async function resolve(decision) {
-  await api(`/api/reviews/${state.reviewId}/decision`, {
+  const review = await api(`/api/reviews/${state.reviewId}/decision`, {
     method: "POST",
     headers: { "content-type": "application/json" },
     body: JSON.stringify({ decision }),
   });
   await refreshReview();
-  toast(decision === "approve" ? "Plan approved — Claude will proceed." : "Sent back to Claude with your comments.");
+  if (decision === "approve") {
+    const n = review?.commentCount || 0;
+    toast(
+      n
+        ? `Approved with ${n} comment${n === 1 ? "" : "s"} — Claude will proceed and incorporate them.`
+        : "Plan approved — Claude will proceed.",
+    );
+  } else {
+    toast("Sent back to Claude with your comments.");
+  }
 }
 
 // ---------- storage / save ----------