@mrclrchtr/supi-review 2.4.1 → 2.6.0

package/README.md

@@ -8,7 +8,7 @@
 
 # @mrclrchtr/supi-review
 
-Adds an interactive `/supi-review` command to the [pi coding agent](https://github.com/earendil-works/pi) for session-aware code review.
+Adds human-driven and agent-driven Session-Aware Review workflows to the [pi coding agent](https://github.com/earendil-works/pi).
 
 ## Install
 
@@ -26,9 +26,13 @@ pi install ./packages/supi-review
 
 ## What you get
 
-After install, pi gets one command:
+After install, pi gets one human-driven command and two agent-facing tools:
 
 - `/supi-review` — launch a guided review flow over a concrete git snapshot
+- `supi_review_prepare` — synthesize a versioned brief and return a session-scoped `planId`
+- `supi_review_run` — accept the main agent's structured brief critique, freshness-check the plan, and run focused reviewers concurrently
+
+The run tool is initially inactive and is dynamically enabled after `supi_review_prepare` returns a plan. This keeps the initial agent-facing prompt surface small.
 
 The reviewer runs in managed child agent sessions:
 
@@ -57,13 +61,34 @@ The reviewer runs in managed child agent sessions:
 8. normalize the submitted review items into a host-derived verdict + structured result
 9. if review items exist, hand off to the main agent so it can ask what to do next with fixed options (`Fix all`, `Fix selected`, `Verify findings`, `Skip`)
 
+## Agent-driven review flow
+
+The agent-facing path deliberately separates preparation from execution:
+
+1. `supi_review_prepare` resolves the target, serializes the active session context, and synthesizes a generated brief.
+2. The main agent compares that brief with the user request, session evidence, and snapshot.
+3. The main agent calls `supi_review_run` with:
+   - the prepared `planId`
+   - an `accept` or `revise` critique
+   - evidence-backed critique findings
+   - at least one evidence-backed finding and a full `revisedBrief` when revision is required
+   - one to four independent reviewer assignments
+4. The host atomically consumes the plan, checks snapshot freshness, and runs reviewer child sessions concurrently.
+5. The tool returns each normalized review result plus a retained brief evaluation artifact.
+
+The evaluation artifact keeps the generated brief, main-agent critique, effective brief, synthesis prompt version, model id, and snapshot fingerprint separate. This makes brief-synthesis prompt regressions inspectable instead of hiding main-agent repairs. The full artifact is stored in tool-result `details`; a summary is also recorded as a `supi-review/brief-critique` SuPi Debug event when debug capture is enabled.
+
+Prepared plans are session-scoped. File or git changes before or during review invalidate the run, so `supi_review_run` should not share a tool batch with mutating tools.
+
 ## Review targets
 
 Current targets:
 
 - working tree
-- branch diff vs a selected local base branch
-- one recent commit
+- branch diff vs a selected local base branch (`merge-base..HEAD`, excluding dirty worktree changes)
+- one commit (recent-commit picker in the command; hexadecimal object id in the agent tool)
+
+Agent-provided branch targets must name an existing local branch. Commit targets must be unique 7–64 character hexadecimal commit-object ids: object-only disambiguation rejects ambiguous prefixes, non-commit objects, and hexadecimal branch/tag fallback. Git revision arguments are option-hardened before execution.
 
 ## Session-aware brief synthesis
 
@@ -104,13 +129,15 @@ The Overview mode uses the same structured packet data that feeds the reviewer p
 
 ## Model selection
 
-Every `/supi-review` run asks you to choose the reviewer model.
+Every `/supi-review` command run asks you to choose the reviewer model.
 
 - the picker only shows **scoped models** from Pi's `enabledModels` configuration
 - the current session model is preselected only when it is inside that scoped set
 - the selected model is used for both brief synthesis and the final review
 - no review model is persisted in settings
 
+Agent-driven tool runs use the current session model for preparation and all focused reviewers. The selected model is retained in the prepared plan so a model change between tool calls cannot silently alter the run.
+
 ## Result shape
 
 A successful review includes:
@@ -155,6 +182,9 @@ When a successful review contains review items, `supi-review` also injects an ag
 - `src/review-result.ts` — review-item normalization, verdict derivation, and summary counts
 - `src/target/review-instruction-blocks.ts` — fixed catalog of host-owned review instruction blocks
 - `src/target/packet.ts` — final reviewer packet builder + shared preview-data derivation for the inspector
+- `src/session/review-plan-store.ts` — session-scoped, one-shot prepared review plans
+- `src/tool/agent-review-tools.ts` — prepare/run tool registration, dynamic activation, progress, and debug artifact recording
+- `src/tool/agent-review-workflow.ts` — preparation, critique validation, freshness checks, and concurrent reviewer fan-out
 - `src/tool/brief-runner.ts` — brief synthesis child session
 - `src/tool/review-runner.ts` — read-only reviewer child session with snapshot-aware tools
 - `src/tool/snapshot-tools.ts` — per-file diff and before/after content tools scoped to the selected snapshot

package/node_modules/@mrclrchtr/supi-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-core",
-  "version": "2.4.1",
+  "version": "2.6.0",
   "description": "SuPi core — shared infrastructure for SuPi extensions (XML context tags, config system)",
   "license": "MIT",
   "repository": {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mrclrchtr/supi-review",
-  "version": "2.4.1",
-  "description": "SuPi Review extension — structured code review via /supi-review command",
+  "version": "2.6.0",
+  "description": "SuPi Review extension — session-aware review command and agent tools",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -31,7 +31,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@mrclrchtr/supi-core": "2.4.1"
+    "@mrclrchtr/supi-core": "2.6.0"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-core"

package/src/git.ts

@@ -1,12 +1,20 @@
 // biome-ignore lint/style/noExcessiveLinesPerFile: many tightly-coupled git helpers; splitting would create cross-ref overhead
 import { execFile } from "node:child_process";
-import { readFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { lstat, readFile, readlink } from "node:fs/promises";
 import { basename, join } from "node:path";
 import { promisify } from "node:util";
-import type { DiffStats, ReviewSnapshot, ReviewTargetSpec } from "./types.ts";
+import type {
+  DiffStats,
+  ReviewSnapshot,
+  ReviewSnapshotSummary,
+  ReviewTargetSpec,
+} from "./types.ts";
 
 const execFileAsync = promisify(execFile);
 const GIT_TIMEOUT_MS = 30_000;
+const COMMIT_OBJECT_ID_RE = /^[0-9a-f]{7,64}$/i;
 
 function scrubGitEnv(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
   const next = { ...env };
@@ -52,11 +60,22 @@ export function parseDiffStats(text: string): DiffStats {
   return { files, additions, deletions };
 }
 
+/** Return whether a value is a hexadecimal abbreviated or full Git object id. */
+export function isCommitObjectId(value: string): boolean {
+  return COMMIT_OBJECT_ID_RE.test(value);
+}
+
 export async function getMergeBase(repoPath: string, branch: string): Promise<string | undefined> {
+  const branchRef = `refs/heads/${branch}`;
   try {
+    await execFileAsync(
+      "git",
+      ["show-ref", "--verify", "--quiet", branchRef],
+      gitExecOptions(repoPath),
+    );
     const { stdout } = await execFileAsync(
       "git",
-      ["merge-base", "HEAD", branch],
+      ["merge-base", "HEAD", branchRef],
       gitExecOptions(repoPath),
     );
     return stdout.trim() || undefined;
@@ -66,7 +85,11 @@ export async function getMergeBase(repoPath: string, branch: string): Promise<st
 }
 
 export async function getDiff(repoPath: string, baseSha: string): Promise<string> {
-  const { stdout } = await execFileAsync("git", ["diff", baseSha], gitExecOptions(repoPath));
+  const { stdout } = await execFileAsync(
+    "git",
+    ["diff", "--end-of-options", baseSha, "HEAD"],
+    gitExecOptions(repoPath),
+  );
   return stdout;
 }
 
@@ -132,14 +155,18 @@ export async function getRecentCommits(repoPath: string, limit = 20): Promise<Co
 }
 
 export async function getCommitShow(repoPath: string, sha: string): Promise<string> {
-  const { stdout } = await execFileAsync("git", ["show", sha], gitExecOptions(repoPath));
+  const { stdout } = await execFileAsync(
+    "git",
+    ["show", "--end-of-options", sha],
+    gitExecOptions(repoPath),
+  );
   return stdout;
 }
 
 export async function getDiffFileNames(repoPath: string, baseSha: string): Promise<string[]> {
   const { stdout } = await execFileAsync(
     "git",
-    ["diff", "--name-only", baseSha],
+    ["diff", "--name-only", "--end-of-options", baseSha, "HEAD"],
     gitExecOptions(repoPath),
   );
   return stdout
@@ -192,7 +219,7 @@ export async function getUncommittedFileNames(repoPath: string): Promise<string[
 export async function getCommitFileNames(repoPath: string, sha: string): Promise<string[]> {
   const { stdout } = await execFileAsync(
     "git",
-    ["diff-tree", "--no-commit-id", "--name-only", "-r", sha],
+    ["diff-tree", "--no-commit-id", "--name-only", "-r", "--end-of-options", sha],
     gitExecOptions(repoPath),
   );
   return stdout
@@ -230,6 +257,117 @@ export async function getLocalBranches(repoPath: string): Promise<string[]> {
   return sorted;
 }
 
+/** Resolve any supported review target into a concrete snapshot. */
+export function resolveReviewSnapshot(
+  repoPath: string,
+  target: ReviewTargetSpec,
+): Promise<ReviewSnapshot | undefined> {
+  switch (target.kind) {
+    case "working-tree":
+      return resolveWorkingTreeSnapshot(repoPath);
+    case "branch":
+      return resolveBranchSnapshot(repoPath, target.base);
+    case "commit":
+      return resolveCommitSnapshot(repoPath, target.sha);
+  }
+}
+
+/** Remove bulk diff text before retaining snapshot metadata in tool results. */
+export function summarizeReviewSnapshot(snapshot: ReviewSnapshot): ReviewSnapshotSummary {
+  return {
+    target: snapshot.target,
+    title: snapshot.title,
+    changedFiles: [...snapshot.changedFiles],
+    stats: { ...snapshot.stats },
+  };
+}
+
+/**
+ * Compute an abort-aware deterministic snapshot fingerprint.
+ * Untracked regular files are streamed, symlinks are hashed by link identity,
+ * and special file types are encoded without opening potentially blocking paths.
+ */
+export async function fingerprintReviewSnapshot(
+  repoPath: string,
+  snapshot: ReviewSnapshot,
+  signal?: AbortSignal,
+): Promise<string> {
+  const changedFiles = [...snapshot.changedFiles].sort((left, right) => left.localeCompare(right));
+  const hash = createHash("sha256").update(
+    JSON.stringify({
+      target: snapshot.target,
+      changedFiles,
+      diffText: snapshot.diffText,
+    }),
+  );
+
+  for (const file of extractUntrackedFiles(snapshot)) {
+    signal?.throwIfAborted();
+    const filePath = join(repoPath, file);
+    hash.update(`\nuntracked:${file}\n`);
+    try {
+      const stat = await lstat(filePath);
+      signal?.throwIfAborted();
+      hash.update(`mode:${stat.mode.toString(8)}\n`);
+      if (stat.isSymbolicLink()) {
+        hash.update(`symlink:${await readlink(filePath)}\n`);
+      } else if (stat.isFile()) {
+        for await (const chunk of createReadStream(filePath, { signal })) {
+          hash.update(chunk);
+        }
+      } else {
+        hash.update("[unsupported-file-type]");
+      }
+    } catch {
+      signal?.throwIfAborted();
+      hash.update("[unavailable]");
+    }
+    signal?.throwIfAborted();
+  }
+
+  return hash.digest("hex");
+}
+
+function extractUntrackedFiles(snapshot: ReviewSnapshot): string[] {
+  if (snapshot.target.kind !== "working-tree") return [];
+  const marker = "=== Untracked files ===\n";
+  const markerIndex = snapshot.diffText.indexOf(marker);
+  if (markerIndex < 0) return [];
+  const changedFiles = new Set(snapshot.changedFiles);
+  return snapshot.diffText
+    .slice(markerIndex + marker.length)
+    .split("\n")
+    .map((file) => file.trim())
+    .filter((file) => file.length > 0 && changedFiles.has(file))
+    .sort((left, right) => left.localeCompare(right));
+}
+
+/** Re-resolve a snapshot target and report whether its review evidence has drifted. */
+export async function checkReviewSnapshotFreshness(
+  repoPath: string,
+  snapshot: ReviewSnapshot,
+  expectedFingerprint: string,
+  signal?: AbortSignal,
+): Promise<{ fresh: true } | { fresh: false; reason: string }> {
+  const current = await resolveReviewSnapshot(repoPath, snapshot.target);
+  if (!current) {
+    return {
+      fresh: false,
+      reason: "The prepared review target no longer has reviewable changes.",
+    };
+  }
+
+  if ((await fingerprintReviewSnapshot(repoPath, current, signal)) !== expectedFingerprint) {
+    return {
+      fresh: false,
+      reason:
+        "The review target changed after the brief was prepared. Run supi_review_prepare again.",
+    };
+  }
+
+  return { fresh: true };
+}
+
 /** Resolve the current working tree into a concrete review snapshot. */
 export async function resolveWorkingTreeSnapshot(
   repoPath: string,
@@ -269,19 +407,54 @@ export async function resolveBranchSnapshot(
   };
 }
 
+async function resolveCommitObjectId(
+  repoPath: string,
+  revision: string,
+): Promise<string | undefined> {
+  if (!isCommitObjectId(revision)) return undefined;
+  try {
+    const { stdout } = await execFileAsync(
+      "git",
+      ["rev-parse", `--disambiguate=${revision}`],
+      gitExecOptions(repoPath),
+    );
+    const candidates = Array.from(
+      new Set(
+        stdout
+          .split("\n")
+          .map((candidate) => candidate.trim())
+          .filter((candidate) => isCommitObjectId(candidate)),
+      ),
+    );
+    if (candidates.length !== 1) return undefined;
+
+    const candidate = candidates[0];
+    const { stdout: objectType } = await execFileAsync(
+      "git",
+      ["cat-file", "-t", candidate],
+      gitExecOptions(repoPath),
+    );
+    return objectType.trim() === "commit" ? candidate : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 /** Resolve one commit into a concrete review snapshot. */
 export async function resolveCommitSnapshot(
   repoPath: string,
   sha: string,
 ): Promise<ReviewSnapshot | undefined> {
+  const resolvedSha = await resolveCommitObjectId(repoPath, sha);
+  if (!resolvedSha) return undefined;
   const [diffText, changedFiles] = await Promise.all([
-    getCommitShow(repoPath, sha),
-    getCommitFileNames(repoPath, sha),
+    getCommitShow(repoPath, resolvedSha),
+    getCommitFileNames(repoPath, resolvedSha),
   ]);
   if (!diffText.trim() && changedFiles.length === 0) return undefined;
   return {
-    target: { kind: "commit", sha },
-    title: `Commit ${sha.slice(0, 7)}`,
+    target: { kind: "commit", sha: resolvedSha },
+    title: `Commit ${resolvedSha.slice(0, 7)}`,
     changedFiles,
     diffText,
     stats: parseDiffStats(diffText),
@@ -309,7 +482,7 @@ export async function getSnapshotFileDiff(
       if (!baseSha) return "";
       const { stdout } = await execFileAsync(
         "git",
-        ["diff", baseSha, "HEAD", "--", file],
+        ["diff", "--end-of-options", baseSha, "HEAD", "--", file],
         gitExecOptions(repoPath),
       );
       return stdout;
@@ -317,7 +490,7 @@ export async function getSnapshotFileDiff(
     case "commit": {
       const { stdout } = await execFileAsync(
         "git",
-        ["show", target.sha, "--", file],
+        ["show", "--end-of-options", target.sha, "--", file],
         gitExecOptions(repoPath),
       );
       return stdout;
@@ -329,7 +502,7 @@ export async function getSnapshotFileDiff(
 async function showGitBlob(repoPath: string, ref: string, file: string): Promise<string> {
   const { stdout } = await execFileAsync(
     "git",
-    ["show", `${ref}:${file}`],
+    ["show", "--end-of-options", `${ref}:${file}`],
     gitExecOptions(repoPath),
   );
   return stdout;
@@ -348,7 +521,11 @@ async function resolveWorkingTreeContent(
     }
   }
   try {
-    return await readFile(join(repoPath, file), "utf-8");
+    const filePath = join(repoPath, file);
+    const stat = await lstat(filePath);
+    if (stat.isSymbolicLink()) return await readlink(filePath);
+    if (!stat.isFile()) return undefined;
+    return await readFile(filePath, "utf-8");
   } catch {
     return undefined;
   }

package/src/history/synthesize.ts

@@ -10,6 +10,9 @@ import type {
 
 const DIFF_EXCERPT_CHAR_BUDGET = 12_000;
 
+/** Version of the brief-synthesis prompt contract retained in evaluation artifacts. */
+export const BRIEF_SYNTHESIS_PROMPT_VERSION = "1";
+
 export interface SynthesizeReviewBriefOptions {
   model: ReviewModelSelection;
   modelRegistry: ModelRegistry;

package/src/model.ts

@@ -16,3 +16,22 @@ export function getSelectableReviewModels(
 ): ReviewModelSelection[] {
   return getSelectableModels(ctx, enabledModelPatterns) as ReviewModelSelection[];
 }
+
+/** Resolve the current session model for a non-interactive agent-driven review. */
+export function getCurrentReviewModel(
+  ctx: Pick<ExtensionContext, "model">,
+): ReviewModelSelection | undefined {
+  const model = ctx.model;
+  if (!model) return undefined;
+
+  const canonicalId = `${model.provider}/${model.id}`;
+  return {
+    canonicalId,
+    provider: model.provider,
+    id: model.id,
+    model,
+    label: model.name ?? canonicalId,
+    description: canonicalId,
+    isCurrent: true,
+  };
+}

package/src/review.ts

@@ -6,6 +6,7 @@ import { serializeSessionContext } from "./history/collect.ts";
 import { synthesizeReviewBrief } from "./history/synthesize.ts";
 import { normalizeReviewResult } from "./review-result.ts";
 import { buildReviewPacket } from "./target/packet.ts";
+import { registerAgentReviewTools } from "./tool/agent-review-tools.ts";
 import { runReviewer } from "./tool/review-runner.ts";
 import type {
   BriefSynthesisRunResult,
@@ -23,6 +24,7 @@ type CommandContext = Parameters<Parameters<ExtensionAPI["registerCommand"]>[1][
 
 export default function reviewExtension(pi: ExtensionAPI) {
   registerReviewRenderer(pi);
+  registerAgentReviewTools(pi);
 
   pi.registerCommand("supi-review", {
     description: "Run a structured code review informed by the current session history",

package/src/session/review-plan-store.ts

@@ -0,0 +1,69 @@
+import { createHash } from "node:crypto";
+import type { ReviewModelSelection, ReviewSnapshot, SynthesizedReviewBrief } from "../types.ts";
+
+/** Session-scoped state retained between review preparation and execution. */
+export interface StoredAgentReviewPlan {
+  id: string;
+  snapshot: ReviewSnapshot;
+  snapshotFingerprint: string;
+  generatedBrief: SynthesizedReviewBrief;
+  model: ReviewModelSelection;
+  briefPromptVersion: string;
+  createdAt: number;
+}
+
+/** Inputs retained when creating a session-scoped review plan. */
+export interface CreateAgentReviewPlanInput {
+  snapshot: ReviewSnapshot;
+  snapshotFingerprint: string;
+  generatedBrief: SynthesizedReviewBrief;
+  model: ReviewModelSelection;
+  briefPromptVersion: string;
+}
+
+/**
+ * Owns prepared review plans for one PI extension session.
+ *
+ * Plans are claimed atomically before reviewer child sessions start, preventing
+ * duplicate runs from concurrent sibling tool calls.
+ */
+export class ReviewPlanStore {
+  readonly #plans = new Map<string, StoredAgentReviewPlan>();
+  #sequence = 0;
+
+  /** Create and retain one prepared review plan. */
+  create(input: CreateAgentReviewPlanInput): StoredAgentReviewPlan {
+    const createdAt = Date.now();
+    const id = this.createPlanId(input.snapshotFingerprint, createdAt);
+    const plan: StoredAgentReviewPlan = { id, createdAt, ...input };
+    this.#plans.set(id, plan);
+    return plan;
+  }
+
+  /** Read a plan without consuming it. */
+  get(id: string): StoredAgentReviewPlan | undefined {
+    return this.#plans.get(id);
+  }
+
+  /** Atomically consume a plan so it can run at most once. */
+  take(id: string): StoredAgentReviewPlan | undefined {
+    const plan = this.#plans.get(id);
+    if (!plan) return undefined;
+    this.#plans.delete(id);
+    return plan;
+  }
+
+  /** Remove all plans when PI replaces or reloads the session. */
+  clear(): void {
+    this.#plans.clear();
+  }
+
+  private createPlanId(snapshotFingerprint: string, createdAt: number): string {
+    this.#sequence++;
+    const hash = createHash("sha256")
+      .update(`${snapshotFingerprint}:${createdAt}:${this.#sequence}`)
+      .digest("hex")
+      .slice(0, 12);
+    return `review-plan-${hash}`;
+  }
+}

package/src/target/packet.ts

@@ -1,4 +1,5 @@
 import type {
+  ReviewerAssignment,
   ReviewInstructionBlockId,
   ReviewModelSelection,
   ReviewPacket,
@@ -90,6 +91,7 @@ export function buildReviewPacket(
   snapshot: ReviewSnapshot,
   brief: SynthesizedReviewBrief,
   model: ReviewModelSelection,
+  assignment?: ReviewerAssignment,
 ): ReviewPacket {
   const previewData = buildReviewPacketPreviewData(snapshot, brief.reviewInstructionBlockIds);
 
@@ -111,6 +113,18 @@ export function buildReviewPacket(
     "",
     "## Open questions",
     ...toBullets(brief.unresolvedQuestions, "- No unresolved questions identified."),
+  ];
+
+  if (assignment) {
+    parts.push(
+      "",
+      "## Delegated reviewer focus",
+      `Reviewer assignment: ${assignment.id}`,
+      assignment.focus,
+    );
+  }
+
+  parts.push(
     "",
     "## Snapshot under review",
     `Target: ${snapshot.title}`,
@@ -120,7 +134,7 @@ export function buildReviewPacket(
     "",
     "## Changed files manifest",
     ...snapshot.changedFiles.map((file) => `- ${file}`),
-  ];
+  );
 
   if (previewData.reviewInstructionBlocks.length > 0) {
     parts.push(