@dieulc/workflow 0.10.0 → 0.11.1

package/review-runtime.ts

@@ -27,9 +27,11 @@ import * as path from "node:path";
 import {
   DEFAULT_REVIEW_MODE_CONFIG,
   buildReviewerAttempts,
+  classifyAssistantStop,
   createReviewRoundGate,
   createReviewSession,
   createReviewState,
+  isAbortStopText,
   planHash,
   readProviderErrorEvent,
   reviewNeedsVerification,
@@ -73,6 +75,15 @@ const SETTLE_IN_FLIGHT_FALLBACK_MS = 60_000;
 export interface ReviewRuntimeDeps {
   cwd: string;
   agentDir: string;
+  /**
+   * The parent's effective folder policy (sensitive extras, `excludePaths`)
+   * and read grants, handed to the reviewer's guarded tools. Optional so
+   * existing tests and embedders keep working.
+   */
+  folderPolicy?: () => {
+    config: import("./folder-policy.ts").FolderPolicyConfig;
+    grants: readonly string[];
+  };
   config: () => ReviewModeConfig | undefined;
   /** Resolve the reviewer role's model (falls back to the planner when unset). */
   reviewerModel: () =>
@@ -392,6 +403,31 @@ export function createReviewRuntime(deps: ReviewRuntimeDeps): ReviewRuntime {
     | { message: string; retries: number; at: number }
     | undefined;
 
+  /**
+   * Agent runs stopped by Review Mode's own abort (pass complete, pause,
+   * teardown). The SDK's setup path can report such a stop as
+   * `stopReason: "error"` with an abort-shaped message, so the subscriber
+   * pairs this expectation with `classifyAssistantStop` before suppressing it.
+   * Bounded by two anchors: reset before every pass and on every settle.
+   */
+  let expectedAbortEnds = 0;
+
+  /** Record that the next child run end was requested by this runtime. */
+  const noteExpectedAbort = (): void => {
+    expectedAbortEnds += 1;
+  };
+
+  /** Consume one pending self-abort expectation; false when none is pending. */
+  const consumeExpectedAbort = (): boolean => {
+    if (expectedAbortEnds <= 0) return false;
+    expectedAbortEnds -= 1;
+    return true;
+  };
+
+  const resetExpectedAborts = (): void => {
+    expectedAbortEnds = 0;
+  };
+
   /** Ordered plan chunks for the current pass; reset on submit/abort/switch. */
   let planAssembler:
     | { chunks: string[]; nextIndex: number; totalChunks?: number }
@@ -470,6 +506,8 @@ export function createReviewRuntime(deps: ReviewRuntimeDeps): ReviewRuntime {
   /** Drop the captured error when a new pass starts. */
   const clearProviderError = (): void => {
     lastProviderError = undefined;
+    // A pending self-abort expectation belongs to the run that already ended.
+    resetExpectedAborts();
   };
 
   const config = (): ReviewModeConfig => {
@@ -604,6 +642,7 @@ export function createReviewRuntime(deps: ReviewRuntimeDeps): ReviewRuntime {
   /** Abort the reviewer's in-flight run. Best-effort; never throws. */
   async function abortChild(): Promise<void> {
     try {
+      noteExpectedAbort();
       await session?.abort();
     } catch {
       /* cancellation is best-effort */
@@ -712,6 +751,7 @@ export function createReviewRuntime(deps: ReviewRuntimeDeps): ReviewRuntime {
   async function disposeSession(options: { keepRoundController?: boolean } = {}): Promise<void> {
     try {
       if (options.keepRoundController !== true) abortController?.abort();
+      noteExpectedAbort();
       await session?.abort();
     } catch {
       /* ignore */
@@ -791,6 +831,7 @@ export function createReviewRuntime(deps: ReviewRuntimeDeps): ReviewRuntime {
         const built = createReviewTools(sdk, {
           cwd: deps.cwd,
           log: deps.log,
+          folderPolicy: deps.folderPolicy,
           explore: {
             // Step 8: Planner recon rides along in the prompt — when it is
             // present the reviewer verifies instead of re-exploring.
@@ -920,44 +961,68 @@ export function createReviewRuntime(deps: ReviewRuntimeDeps): ReviewRuntime {
         ensureTranscript();
         const child = created.session;
         session.subscribe((event) => {
-          let ops: ReviewTranscriptOp[] = [];
-          try {
-            ops = ensureTranscript().ingest(event);
-          } catch {
-            /* a malformed event must not break the review */
-          }
-          if (ops.length > 0) {
+          // D4: a round ends at `review_pass_done`/settle, but the child may
+          // still stream a closing tail. Once the round is inactive its events
+          // must never reach the main transcript (that tail used to appear
+          // while Build/Plan had already started).
+          if (!roundActive) return;
+          const type = readEventType(event);
+          // Classify BEFORE ingest/capture: a stop the runtime requested itself
+          // must never reach the transcript or the provider-error slot. The
+          // SDK can label that stop `error` with an abort-shaped message, so
+          // the expectation and the classification are both required.
+          const stop =
+            type === "agent_end"
+              ? classifyAssistantStop(
+                  (event as { messages?: unknown } | undefined)?.messages,
+                )
+              : undefined;
+          // Consume on EVERY agent_end so a real error after a silent abort
+          // cannot leave a stale expectation behind.
+          const expectedAbort = type === "agent_end" && consumeExpectedAbort();
+          const selfAbort = expectedAbort && stop?.kind === "aborted";
+          if (!selfAbort) {
+            let ops: ReviewTranscriptOp[] = [];
             try {
-              deps.onTranscriptOps?.(ops);
+              ops = ensureTranscript().ingest(event);
             } catch {
-              /* streaming to the main transcript is display-only: never fatal */
+              /* a malformed event must not break the review */
             }
-          }
-          const type = readEventType(event);
-          // Capture provider failures as they happen, so a pass that ends
-          // without a submission can be diagnosed with the reviewer's real
-          // API error instead of a generic "no plan" message (see runRound).
-          try {
-            const failure = readProviderErrorEvent(event);
-            if (failure.kind === "retry") {
-              noteProviderError(failure.message, failure.retries);
-            } else if (failure.kind === "exhaust") {
-              noteProviderError(
-                failure.message ||
-                  lastProviderError?.message ||
-                  "provider error (no detail)",
-                failure.retries || lastProviderError?.retries || 0,
-              );
-            } else if (failure.kind === "stop") {
-              noteProviderError(
-                failure.message,
-                lastProviderError?.retries ?? 0,
-              );
+            if (ops.length > 0) {
+              try {
+                deps.onTranscriptOps?.(ops);
+              } catch {
+                /* streaming to the main transcript is display-only: never fatal */
+              }
+            }
+            // Capture provider failures as they happen, so a pass that ends
+            // without a submission can be diagnosed with the reviewer's real
+            // API error instead of a generic "no plan" message (see runRound).
+            // `aborted` is deliberately not captured: it is our own cancel.
+            try {
+              const failure = readProviderErrorEvent(event);
+              if (failure.kind === "retry") {
+                noteProviderError(failure.message, failure.retries);
+              } else if (failure.kind === "exhaust") {
+                noteProviderError(
+                  failure.message ||
+                    lastProviderError?.message ||
+                    "provider error (no detail)",
+                  failure.retries || lastProviderError?.retries || 0,
+                );
+              } else if (failure.kind === "stop") {
+                noteProviderError(
+                  failure.message,
+                  lastProviderError?.retries ?? 0,
+                );
+              }
+            } catch {
+              /* error capture is diagnostics only: never break the review */
             }
-          } catch {
-            /* error capture is diagnostics only: never break the review */
           }
           if (type === "agent_settled") {
+            // The abort (if any) has landed; no expectation may outlive it.
+            resetExpectedAborts();
             noteSettled();
           } else if (type === "agent_end") {
             // Fallback for a runtime without `agent_settled`: a retry or a
@@ -1248,6 +1313,21 @@ export function createReviewRuntime(deps: ReviewRuntimeDeps): ReviewRuntime {
         return child.prompt(pass1Prompt);
       });
 
+      // A round aborted by ESC / the host signal must take the abort path even
+      // when the in-flight send rejected first: the rejection is a symptom of
+      // the abort, not a provider/send failure to recover from.
+      if (p1.stop === "aborted" || rc.signal.aborted) {
+        await abortChild();
+        if (state) state.phase = "aborted";
+        return {
+          ok: false,
+          fallback: true,
+          planText: p1.submitted?.planText ?? originalPlan,
+          planHash: hash,
+          state: state as ReviewState,
+          reason: "aborted",
+        };
+      }
       if (p1.stop === "error") {
         await abortChild();
         const sendMessage = errorText(p1.error);
@@ -1279,18 +1359,6 @@ export function createReviewRuntime(deps: ReviewRuntimeDeps): ReviewRuntime {
         }
         return fail(lastFailure);
       }
-      if (p1.stop === "aborted" || rc.signal.aborted) {
-        await abortChild();
-        if (state) state.phase = "aborted";
-        return {
-          ok: false,
-          fallback: true,
-          planText: p1.submitted?.planText ?? originalPlan,
-          planHash: hash,
-          state: state as ReviewState,
-          reason: "aborted",
-        };
-      }
       if (!p1.submitted) {
         // The run is over (or out of time) and nothing reached the plan file.
         await abortChild();
@@ -1352,6 +1420,13 @@ export function createReviewRuntime(deps: ReviewRuntimeDeps): ReviewRuntime {
         cfg.passes > 1 &&
         reviewNeedsVerification(state?.findings ?? []);
 
+      // Pass 1's protocol submission is final; stop a tail that is still
+      // streaming before deciding whether pass 2 runs. This is what keeps the
+      // reviewer quiescent when the handoff opens.
+      if (!wantVerify && session?.isStreaming()) {
+        await abortChild();
+      }
+
       if (wantVerify) {
         setPhase("verifying");
         await settleInFlight(deadline, rc);
@@ -1369,16 +1444,29 @@ export function createReviewRuntime(deps: ReviewRuntimeDeps): ReviewRuntime {
         });
         // Name the provider when the verification pass died on one; pass 2
         // stays best-effort either way — pass 1's plan is never lost to it.
-        const p2Provider = lastProviderError
-          ? `provider error after ${lastProviderError.retries} retry attempt(s): ${truncateErrorText(lastProviderError.message)}`
-          : undefined;
+        // A round abort (or an abort-shaped stop) is not provider health.
+        const p2Send = p2.error === undefined ? "" : errorText(p2.error);
+        const p2Aborted =
+          rc.signal.aborted ||
+          isAbortStopText(p2Send) ||
+          isAbortStopText(lastProviderError?.message);
+        const p2Provider =
+          !p2Aborted && lastProviderError
+            ? `provider error after ${lastProviderError.retries} retry attempt(s): ${truncateErrorText(lastProviderError.message)}`
+            : undefined;
         if (p2.error !== undefined) {
           // Verification is an enhancement: never lose pass 1's plan over it.
+          let failureText: string;
+          if (p2Aborted) {
+            failureText = "verification pass aborted";
+          } else if (p2Provider) {
+            failureText = `verification pass failed (${p2Provider}; send error: ${p2Send})`;
+          } else {
+            failureText = `verification pass failed (${p2Send})`;
+          }
           deps.log(
-            p2Provider
-              ? `verification pass failed (${p2Provider}; send error: ${errorText(p2.error)}) — keeping pass 1's plan.`
-              : `verification pass failed (${errorText(p2.error)}) — keeping pass 1's plan.`,
-            "warning",
+            `${failureText} — keeping pass 1's plan.`,
+            p2Aborted ? "info" : "warning",
           );
         } else if (p2.submitted) {
           finalPlan = p2.submitted.planText;
@@ -1427,8 +1515,19 @@ export function createReviewRuntime(deps: ReviewRuntimeDeps): ReviewRuntime {
       } catch {
         /* listener cleanup is best-effort */
       }
-      abortController = undefined;
+      // D4: no terminal path may return while the reviewer child is still
+      // streaming. `review_pass_done` ends the protocol, not the SDK run; the
+      // remaining tail could still call review tools or write the plan while
+      // the parent has moved to Build/Plan. The submission is already captured.
+      // Mark the round inactive FIRST: the abort's own `agent_end` is teardown
+      // noise, not a run result, and must never reach the transcript.
       roundActive = false;
+      try {
+        if (session?.isStreaming()) await session.abort();
+      } catch {
+        /* cancellation is best-effort */
+      }
+      abortController = undefined;
     }
   }
 
@@ -1448,6 +1547,7 @@ export function createReviewRuntime(deps: ReviewRuntimeDeps): ReviewRuntime {
     async abortRound() {
       try {
         abortController?.abort();
+        noteExpectedAbort();
         await session?.abort();
       } catch {
         /* cancellation is best-effort */

package/review-tools.ts

@@ -29,6 +29,16 @@ import {
     type ReviewFinding,
 } from "./utils.ts";
 import { explainCommandRefusal } from "./permissions.ts";
+import { analyzeShellPaths } from "./shell-paths.ts";
+import {
+    DEFAULT_FOLDER_POLICY_CONFIG,
+    detectRepoRoot,
+    evaluateFolderTargets,
+    matchSensitivePath,
+    type FolderPolicyConfig,
+    type FolderTarget,
+} from "./folder-policy.ts";
+import { redactSensitiveText } from "./read-policy-redact.ts";
 import type {
     PiCodingAgentSdk,
     ReviewPassResult,
@@ -48,6 +58,11 @@ export interface ReviewBashDeps {
     cwd: string;
     /** Surface refusals and anomalies to the parent session. */
     log: (message: string, level?: "info" | "warning" | "error") => void;
+    /** The parent's folder policy + read grants (see ReviewToolDeps). */
+    folderPolicy?: () => {
+        config: FolderPolicyConfig;
+        grants: readonly string[];
+    };
 }
 
 /** Injectable shell-tool builder so this module is testable without the SDK. */
@@ -145,6 +160,41 @@ export function createReviewBashTool(
                 };
             }
 
+            const guard = reviewerReadGuard(deps.cwd, deps.folderPolicy?.());
+            const readPaths = analyzeShellPaths(command, deps.cwd).reads;
+            const readEval = evaluateFolderTargets(readPaths, {
+                config: guard.config,
+                grants: guard.grants,
+                cwd: deps.cwd,
+                lockedRoots: [guard.root],
+                explicitGrants: guard.grants,
+                action: "read",
+            });
+            if (
+                readEval.sensitive.length > 0 ||
+                readEval.excluded.length > 0 ||
+                readEval.outside.length > 0
+            ) {
+                const target =
+                    readEval.sensitive[0]?.path ??
+                    readEval.excluded[0]?.path ??
+                    readEval.outside[0]?.path ??
+                    "the requested path";
+                deps.log(
+                    `Review Mode refused a read outside the repository/sensitive guard: ${target}`,
+                    "warning",
+                );
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `review_bash: REFUSED — \`${target}\` is outside the reviewer's permitted repository or is a sensitive file. Work only inside the repository; do not work around this.`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+
             try {
                 const result = (await inner.execute(
                     toolCallId,
@@ -153,7 +203,14 @@ export function createReviewBashTool(
                     onUpdate,
                     ctx,
                 )) as ReviewToolTextResult;
-                return result;
+                return redactReviewResult(
+                    result,
+                    "bash",
+                    rawParams,
+                    deps.cwd,
+                    guard.config,
+                    { base: [guard.root] },
+                );
             } catch (e: unknown) {
                 return {
                     content: [
@@ -341,6 +398,15 @@ export interface ReviewToolDeps {
     explore: ReviewExploreDeps;
     submit: ReviewSubmitDeps;
     passDone: ReviewPassDoneDeps;
+    /**
+     * The parent's effective folder policy (sensitive extras, `excludePaths`)
+     * and read grants. The reviewer is a separate session with no ambient
+     * extensions, so without this it would ignore the user's deny layer.
+     */
+    folderPolicy?: () => {
+        config: FolderPolicyConfig;
+        grants: readonly string[];
+    };
 }
 
 // ── Steps 9-11: review_submit_plan ───────────────────────────────────
@@ -460,6 +526,10 @@ export function createReviewPlanBeginTool(deps: ReviewSubmitDeps): {
             ),
         }),
         async execute(...args: unknown[]): Promise<ReviewToolTextResult> {
+            // SAFETY: Pi calls every tool `execute(toolCallId, params, …)`,
+            // so index 1 is the model-supplied params object. This tool's
+            // schema declares `totalChunks`, which is narrowed below before
+            // use — nothing else is read off the value.
             const [, rawParams] = args as unknown as [
                 string,
                 { totalChunks?: unknown },
@@ -535,6 +605,9 @@ export function createReviewPlanChunkTool(deps: ReviewSubmitDeps): {
             }),
         }),
         async execute(...args: unknown[]): Promise<ReviewToolTextResult> {
+            // SAFETY: Pi calls every tool `execute(toolCallId, params, …)`,
+            // so index 1 is the model-supplied params object. `index` and
+            // `content` are narrowed below before use.
             const [, rawParams] = args as unknown as [
                 string,
                 { index?: unknown; content?: unknown },
@@ -1015,6 +1088,149 @@ export function createReviewPassDoneTool(deps: ReviewPassDoneDeps): {
     };
 }
 
+interface ReviewerReadGuard {
+    root: string;
+    config: FolderPolicyConfig;
+    /** Explicit grants that can re-open an excluded subtree. */
+    grants: readonly string[];
+}
+
+function reviewerReadGuard(
+    cwd: string,
+    parent?: { config: FolderPolicyConfig; grants: readonly string[] },
+): ReviewerReadGuard {
+    return {
+        root: detectRepoRoot(cwd) ?? cwd,
+        config: {
+            ...(parent?.config ?? DEFAULT_FOLDER_POLICY_CONFIG),
+            mode: "cwd",
+            outside: "block",
+        },
+        grants: parent?.grants ?? [],
+    };
+}
+
+function reviewerRefusal(target: FolderTarget): ReviewToolTextResult {
+    return {
+        content: [
+            {
+                type: "text",
+                text: `review read: REFUSED — \`${target.path}\` is outside the reviewer's repository or is a sensitive file. Work inside the repository; sensitive files stay blocked.`,
+            },
+        ],
+        isError: true,
+    };
+}
+
+function guardReviewerTarget(
+    tool: string,
+    input: Record<string, unknown>,
+    guard: ReviewerReadGuard,
+    cwd: string,
+): ReviewToolTextResult | undefined {
+    const raw = input.path;
+    const value =
+        typeof raw === "string" && raw.trim()
+            ? raw
+            : tool === "read"
+              ? ""
+              : cwd;
+    if (!value) {
+        return {
+            content: [{ type: "text", text: `review ${tool}: missing path` }],
+            isError: true,
+        };
+    }
+    const target: FolderTarget = {
+        path: value,
+        kind: tool === "read" ? "file" : "dir",
+    };
+    const hit = matchSensitivePath(value, guard.config, cwd);
+    const evaluation = evaluateFolderTargets([target], {
+        config: guard.config,
+        grants: guard.grants,
+        cwd,
+        lockedRoots: [guard.root],
+        explicitGrants: guard.grants,
+        action: "read",
+    });
+    if (hit.sensitive || evaluation.sensitive.length > 0)
+        return reviewerRefusal(target);
+    // The excluded folder itself, or a path inside it that no approved grant
+    // re-opens, is refused to the reviewer too.
+    if (evaluation.excluded.length > 0) return reviewerRefusal(target);
+    if (evaluation.outside.length > 0) return reviewerRefusal(target);
+    return undefined;
+}
+
+function redactReviewResult(
+    result: ReviewToolTextResult,
+    tool: string,
+    input: Record<string, unknown>,
+    cwd: string,
+    config: FolderPolicyConfig,
+    roots?: { base?: readonly string[]; grants?: readonly string[] },
+): ReviewToolTextResult {
+    let redacted = false;
+    const content = (result.content ?? []).map((block) => {
+        if (block?.type !== "text") return block;
+        const next = redactSensitiveText(
+            block.text,
+            tool,
+            input,
+            cwd,
+            config,
+            roots,
+        );
+        if (next.redacted) redacted = true;
+        return next.redacted ? { ...block, text: next.text } : block;
+    });
+    if (!redacted) return result;
+    return { ...result, content };
+}
+
+function createGuardedBuiltinTools(
+    sdk: PiCodingAgentSdk | undefined,
+    cwd: string,
+    parent?: { config: FolderPolicyConfig; grants: readonly string[] },
+): { tools: unknown[]; unavailable: string[] } {
+    const tools: unknown[] = [];
+    const unavailable: string[] = [];
+    const guard = reviewerReadGuard(cwd, parent);
+    const builders: Array<[string, string, unknown]> = [
+        ["read", "read", (sdk as any)?.createReadToolDefinition],
+        ["grep", "grep", (sdk as any)?.createGrepToolDefinition],
+        ["find", "find", (sdk as any)?.createFindToolDefinition],
+        ["ls", "ls", (sdk as any)?.createLsToolDefinition],
+    ];
+    for (const [name, tool, builder] of builders) {
+        if (typeof builder !== "function") {
+            unavailable.push(`${name} (guarded builder unavailable)`);
+            continue;
+        }
+        const definition = builder(cwd) as {
+            name: string;
+            execute: (...args: unknown[]) => Promise<unknown>;
+        };
+        tools.push({
+            ...definition,
+            name,
+            async execute(...args: unknown[]) {
+                const input = (args[1] ?? {}) as Record<string, unknown>;
+                const refusal = guardReviewerTarget(tool, input, guard, cwd);
+                if (refusal) return refusal;
+                const result = (await definition.execute(
+                    ...args,
+                )) as ReviewToolTextResult;
+                return redactReviewResult(result, tool, input, cwd, guard.config, {
+                    base: [guard.root],
+                });
+            },
+        });
+    }
+    return { tools, unavailable };
+}
+
 /**
  * Build every tool the reviewer may use.
  */
@@ -1032,6 +1248,17 @@ export function createReviewTools(
         unavailable.push("review_bash (createBashToolDefinition unavailable)");
     }
 
+    // The reviewer session has NO ambient extensions, so its built-in
+    // read/grep/find/ls are otherwise a complete bypass of the read gate.
+    // Custom tools with those names override the built-ins.
+    const guarded = createGuardedBuiltinTools(
+        sdk,
+        deps.cwd,
+        deps.folderPolicy?.(),
+    );
+    tools.push(...guarded.tools);
+    unavailable.push(...guarded.unavailable);
+
     tools.push(createReviewExploreTool(deps.explore));
     tools.push(createReviewPlanBeginTool(deps.submit));
     tools.push(createReviewPlanChunkTool(deps.submit));