@dieulc/workflow 0.10.0 → 0.11.1

package/index.ts

@@ -14,7 +14,7 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import { spawn } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
 import type { AssistantMessage, TextContent } from "@earendil-works/pi-ai";
 import type {
@@ -41,7 +41,6 @@ import {
   type EditorTheme,
   type SelectItem,
   wrapTextWithAnsi,
-  truncateToWidth,
 } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import { StringEnum } from "@earendil-works/pi-ai";
@@ -121,6 +120,60 @@ import {
   type PendingCommitFlow,
   type StepCommitCandidate,
 } from "./commit-policy.ts";
+import {
+  baseFolderRoots,
+  buildFolderPolicyDeny,
+  decideFolderGate,
+  describeFolderEvaluation,
+  detectRepoRoot,
+  dialogGrantRootForTarget,
+  broadGrantRootReason,
+  isBroadGrantRoot,
+  evaluateFolderTargets,
+  evaluateBaseCoverage,
+  matchSensitivePath,
+  readFolderPolicyConfig,
+  writeFolderPolicyConfig,
+  revokeFolderPolicyListEntry,
+  folderPolicyArgumentCompletions,
+  folderPolicyConfigPaths,
+  EXCLUDE_USAGE,
+  grantRootForTarget,
+  isBroadExcludePattern,
+  isWorkflowSettingsPath,
+  normalizeExcludePattern,
+  parseExcludeArgs,
+  splitPolicyArgs,
+  DEFAULT_SENSITIVE_PATTERNS,
+  type FolderPolicyConfig,
+  type FolderTarget,
+} from "./folder-policy.ts";
+import { analyzeShellPaths } from "./shell-paths.ts";
+import {
+  buildReadDenyReason,
+  buildReadGuidanceMessage,
+  decideReadGate,
+  parseReadGateChoice,
+  readGateItemFromTarget,
+  readGateItemsKind,
+  readGateOptions,
+  readGateTargetKey,
+  readGateTargetsLabel,
+  readGateTitle,
+  readReadPolicyConfig,
+  sanitizeReadInstruction,
+  writeReadPolicyConfig,
+  readPolicyArgumentCompletions,
+  readPolicyConfigPaths,
+  revokeReadPolicyPath,
+  describeReadPolicy,
+  READ_INSTRUCTION_PROMPT_PLACEHOLDER,
+  READ_INSTRUCTION_PROMPT_TITLE,
+  type ReadGateItem,
+  type ReadPolicyConfig,
+} from "./read-policy.ts";
+import { classifyReadCall } from "./read-policy-tools.ts";
+import { redactToolResult } from "./read-policy-redact.ts";
 import {
   buildWriteDenyReason,
   buildWriteGuidanceMessage,
@@ -128,6 +181,7 @@ import {
   decideWriteGate,
   describeWritePolicyMode,
   isWriteCallAllowed,
+  normalizeWritePath,
   parseWriteGateChoice,
   readWritePolicyConfig,
   sanitizeWriteInstruction,
@@ -143,6 +197,7 @@ import {
   WRITE_INSTRUCTION_PROMPT_TITLE,
   type WriteGateChoice,
   type WriteGateItem,
+  type WriteGateSource,
   type WriteCallClassification,
   type WritePolicyConfig,
   type WritePolicyMode,
@@ -187,6 +242,17 @@ import {
   setWorkflowStatus,
   WORKFLOW_STATUS_KEYS,
 } from "./workflow-status.ts";
+import {
+  buildTodoRows,
+  deriveTodoPanel,
+  isTodoListSettled,
+  readPersistedTodoPanel,
+  renderTodoSummary,
+  todoCompletionSignature,
+  todoListKey,
+  type TodoPanelOverride,
+  type TodoPanelState,
+} from "./todo-panel.ts";
 import {
   defaultProfileConfig,
   loadProfilesDetailed,
@@ -256,6 +322,9 @@ import {
   reviewModeLockKind,
   reviewModeLockNotice,
   reviewModeLockStatusLine,
+  reviewInputDecision,
+  reviewRoundOwnsTurn,
+  reviewTurnOwns,
   reviewNoticeText,
   reviewPauseIsCurrent,
   reviewResumeGateOutcome,
@@ -278,6 +347,7 @@ import {
   type ReviewHandoffPhase,
   type ReviewHandoffResult,
   type ReviewModeLockKind,
+  type ReviewTurnPhase,
   type ReviewState,
   type ReviewTranscriptOp,
   type ReviewTrigger,
@@ -411,6 +481,7 @@ async function runSingleAgent(
   agent: AgentConfig,
   task: string,
   signal?: AbortSignal,
+  folderEnv?: Record<string, string>,
 ): Promise<{ messages: any[]; stderr: string; exitCode: number; usage: any }> {
   const tmpDir = await fs.promises.mkdtemp(
     path.join(os.tmpdir(), "pi-subagent-"),
@@ -449,8 +520,19 @@ async function runSingleAgent(
         shell: false,
         stdio: ["ignore", "pipe", "pipe"],
         // Carry the role into the child so its workflow extension gates bash
-        // with the same policy the parent applies (see permissions.ts).
-        env: subagentEnv(process.env, agent.role),
+        // with the same policy the parent applies (see permissions.ts), and
+        // lock the folder roots so the child cannot expand via a sibling
+        // project's settings.
+        env: {
+          ...subagentEnv(process.env, agent.role),
+          ...(folderEnv ?? {
+            PI_FOLDER_POLICY_LOCKED: "1",
+            PI_FOLDER_POLICY_ROOTS: JSON.stringify([
+              detectRepoRoot(cwd) ?? cwd,
+            ]),
+            PI_FOLDER_POLICY_SOURCE: "parent",
+          }),
+        },
       },
     );
     // Track for cleanup on session_shutdown — prevents orphaned subagents
@@ -607,12 +689,33 @@ export default function workflowExtension(
     null;
   let writeGateTurnSteered = false;
   const writeGateRunDenials = new Map<string, { instruction: string }>();
+  // ── Read-policy gate state (turn-scoped grants, run-scoped denials) ──
+  let readGateBatchCalls: { name: string; args: unknown }[] = [];
+  let readGateBatchCallIds = new Set<string>();
+  const readGateTurnGrantedRoots = new Set<string>();
+  const readGateTurnUncertainAllowed = new Set<string>();
+  let readGateTurnAnswer: {
+    choice: "allow-once" | "always" | "deny";
+    instruction: string;
+  } | null = null;
+  let readGateTurnSteered = false;
+  const readGateRunDenials = new Map<string, { instruction: string }>();
   // ── Reminder throttle + staleness tracking (passive enforcement layer) ──
   let turnsSinceLastTodoWrite = 0;
   let turnsSinceLastReminder = 0;
   let mutatedSinceLastTodoWrite = false;
   let lastRefMisses: { refs: string[] } | undefined;
   let todoStale = false;
+  // ── Todo panel presentation (pinned widget above the editor) ──
+  // The widget can never scroll with the transcript, so it collapses to one
+  // line when the plan settles and hides at the next user prompt. Overrides
+  // are scoped to `todoPanelOverrideKey` (ref/text/group identity), so status
+  // churn keeps the user's choice while a new/renamed list expires it.
+  let todoPanelOverride: TodoPanelOverride = null;
+  let todoPanelOverrideKey: string | null = null;
+  let todoPanelPromptAfterSettle = false;
+  let lastCompletedSignature: string | null = null;
+  let todoPanelAppliedState: TodoPanelState | "unregistered" = "unregistered";
   let footerInjectedThisTurn = false;
   let lastStaleNoticeAt: number | undefined;
   // Path+content hash of the last plan-file reconciliation (skip no-op merges).
@@ -1189,83 +1292,81 @@ export default function workflowExtension(
     todoStale = false;
   }
 
-  /** Display ref for a todo row (stable canonical GLOBAL step). */
-  function todoLabel(it: TodoItem, index: number): string {
-    return todoRef(it) || String(it.step || index + 1);
-  }
-
   /**
-   * Rows for the todo widget: group headers + labelled items, anchored on the
-   * first incomplete item (including its group header), capped for the terminal.
+   * Reconcile the pinned todo widget with the derived presentation state.
+   * Called from `updateStatus` after the footer writes; only re-registers the
+   * component when the state changes (marking a step done repaints through
+   * the host, so the widget is not disposed/rebuilt on every refresh).
    */
-  function buildTodoRows(
-    theme: any,
-    width: number,
-    mode: WorkflowMode | null,
-  ): string[] {
-    if (todoItems.length === 0) return [];
-    const MAX_WIDGET_LINES = 15;
-    const contentWidth = Math.max(1, width - 2);
-    type Row = { group?: string; item?: TodoItem; index: number };
-    const rows: Row[] = [];
-    let lastGroup: string | undefined;
-    todoItems.forEach((item, index) => {
-      if (item.group && item.group !== lastGroup) {
-        rows.push({ group: item.group, index });
-        lastGroup = item.group;
-      }
-      rows.push({ item, index });
+  function refreshTodoPanel(ctx: ExtensionContext) {
+    const view = deriveTodoPanel({
+      items: todoItems,
+      override: todoPanelOverride,
+      overrideKey: todoPanelOverrideKey,
+      promptAfterSettle: todoPanelPromptAfterSettle,
+      stale: todoStale,
     });
-    const firstUndone = todoItems.findIndex(
-      (t) => !isDone(t) && itemStatus(t) !== "cancelled",
-    );
-    const anchorIndex = firstUndone < 0 ? 0 : firstUndone;
-    let startRow = rows.findIndex((r) => r.item && r.index === anchorIndex);
-    if (startRow < 0) startRow = 0;
-    if (startRow > 0 && rows[startRow - 1]?.group) startRow -= 1;
-    const visible = rows.slice(startRow, startRow + MAX_WIDGET_LINES);
-    const rendered = visible.map((row) => {
-      if (row.group) {
-        return truncateToWidth(
-          theme.fg("muted", `── ${row.group}`),
-          contentWidth,
-          "…",
-        );
-      }
-      const item = row.item as TodoItem;
-      const ref = todoLabel(item, row.index);
-      const status = itemStatus(item);
-      const isCurrent = row.index === anchorIndex && !isDone(item);
-      const prefix =
-        isCurrent || status === "in_progress"
-          ? theme.fg("accent", "▶ ")
-          : status === "completed"
-            ? theme.fg("success", "☑ ")
-            : status === "cancelled"
-              ? theme.fg("dim", "✖ ")
-              : theme.fg("dim", "☐ ");
-      const labelPart =
-        item.label !== undefined && String(item.label) !== ref
-          ? theme.fg("muted", ` (${item.label})`)
-          : "";
-      const body = `${ref}. ${item.text}${labelPart}`;
-      let styled: string;
-      if (isDone(item)) {
-        styled = theme.fg("muted", theme.strikethrough(body));
-      } else if (isCurrent && mode === "build") {
-        styled = theme.fg("accent", body);
-      } else if (mode === "plan" || mode === null) {
-        styled = theme.fg("muted", body);
-      } else {
-        styled = body;
+    // A choice made for a different list must not hide a new task.
+    if (todoPanelOverrideKey !== view.listKey) {
+      todoPanelOverride = null;
+      todoPanelOverrideKey = null;
+    }
+    if (!view.settled && todoPanelPromptAfterSettle) {
+      todoPanelPromptAfterSettle = false;
+    }
+    // Reopened list: a later completion may emit its own card again.
+    if (!view.settled && lastCompletedSignature !== null) {
+      lastCompletedSignature = null;
+    }
+    if (view.settled && todoStale) todoStale = false;
+    if (view.state === todoPanelAppliedState) return;
+    todoPanelAppliedState = view.state;
+    try {
+      if (view.state === "hidden") {
+        ctx.ui.setWidget("workflow-todos", undefined);
+        return;
       }
-      return truncateToWidth(`${prefix}${styled}`, contentWidth, "…");
-    });
-    const remaining = rows.length - (startRow + visible.length);
-    if (remaining > 0) {
-      rendered.push(theme.fg("muted", `… +${remaining} more`));
+      ctx.ui.setWidget("workflow-todos", (_tui, theme) => {
+        const render = (w: number) => {
+          // Re-derive so the component always shows live items and the live
+          // mode, even though it was registered for an earlier state.
+          const live = deriveTodoPanel({
+            items: todoItems,
+            override: todoPanelOverride,
+            overrideKey: todoPanelOverrideKey,
+            promptAfterSettle: todoPanelPromptAfterSettle,
+            stale: todoStale,
+          });
+          if (live.state === "hidden") return [];
+          return live.state === "collapsed"
+            ? [renderTodoSummary(theme, w, live)]
+            : buildTodoRows(theme, w, todoItems, workflowMode);
+        };
+        return { render, invalidate: () => {}, dispose: () => {} };
+      });
+    } catch (_e) {
+      void _e;
+    }
+  }
+
+  function setTodoPanelOverride(
+    ctx: ExtensionContext,
+    override: TodoPanelOverride,
+    note?: string,
+  ) {
+    if (!todoItems.length && override === "expanded") {
+      ctx.ui.notify("No todos.", "info");
+      return;
+    }
+    todoPanelOverride = override;
+    todoPanelOverrideKey = override === null ? null : todoListKey(todoItems);
+    updateStatus(ctx);
+    try {
+      persistState();
+    } catch (_e) {
+      void _e;
     }
-    return rendered;
+    if (note) ctx.ui.notify(note, "info");
   }
 
   function updateStatus(ctx: ExtensionContext) {
@@ -1280,6 +1381,7 @@ export default function workflowExtension(
       commitMode = readCommitPolicyConfig(
         (ctx as any).cwd ?? process.cwd(),
         getAgentDir(),
+        { trusted: (ctx as any).isProjectTrusted?.() === true },
       ).config.mode;
     } catch {
       commitMode = "never";
@@ -1293,27 +1395,41 @@ export default function workflowExtension(
       writeMode = readWritePolicyConfig(
         (ctx as any).cwd ?? process.cwd(),
         getAgentDir(),
+        { trusted: (ctx as any).isProjectTrusted?.() === true },
       ).config.mode;
     } catch {
       writeMode = "allow";
     }
+    let folderMode: string | null = null;
+    try {
+      folderMode = readFolderPolicyConfig(
+        (ctx as any).cwd ?? process.cwd(),
+        getAgentDir(),
+        { trusted: (ctx as any).isProjectTrusted?.() === true },
+      ).config.mode;
+    } catch {
+      folderMode = null;
+    }
     const segments = buildWorkflowStatusSegments({
       mode: workflowMode,
-      plannotatorActive,
+      reviewPhase: reviewTurn,
       done: todoItems.filter((t) => isDone(t)).length,
       total: todoItems.length,
-      stale: todoStale,
+      stale: todoStale && !isTodoListSettled(todoItems),
       profileLabel,
       roleLabel,
       commitMode,
       writeMode: workflowMode === null ? writeMode : null,
+      folderMode,
     });
     const modeTone =
-      workflowMode === "build"
+      reviewTurn !== "idle"
         ? "accent"
-        : workflowMode === "plan"
-          ? "warning"
-          : "muted";
+        : workflowMode === "build"
+          ? "accent"
+          : workflowMode === "plan"
+            ? "warning"
+            : "muted";
     setWorkflowStatus(
       ctx.ui,
       WORKFLOW_STATUS_KEYS.mode,
@@ -1330,15 +1446,10 @@ export default function workflowExtension(
       ctx.ui.theme.fg("dim", segments.policy),
     );
     if (todoItems.length > 0) {
-      ctx.ui.setWidget("workflow-todos", (_tui, theme) => {
-        return {
-          render: (w: number) => buildTodoRows(theme, w, workflowMode),
-          invalidate: () => {},
-          dispose: () => {},
-        };
-      });
+      refreshTodoPanel(ctx);
     } else {
       ctx.ui.setWidget("workflow-todos", undefined);
+      todoPanelAppliedState = "hidden";
     }
     // One status owner: every footer refresh (mode switch, model change, round
     // phase, pause) also re-evaluates the review widget. This is what clears a
@@ -1415,6 +1526,15 @@ export default function workflowExtension(
   let activeReview:
     | { planText: string; round: number; controller: AbortController }
     | undefined;
+  /**
+   * The exclusive Review turn (plan 2026-11-14). Unlike the old derived lock,
+   * this also covers the browser/inline handoff, where no child session runs.
+   * In-memory: a reload restores `handoff` from `awaitingDecision`, otherwise
+   * idle (a running round cannot survive the process).
+   */
+  let reviewTurn: ReviewTurnPhase = "idle";
+  /** The next plan turn is the feedback/refine continuation of a Deny. */
+  let reviewFeedbackTurn = false;
   /** Long-lived ESC listener covering a round and the paused window. */
   let detachReviewEscListener: (() => void) | undefined;
   /**
@@ -1466,9 +1586,47 @@ export default function workflowExtension(
       roundActive,
       paused,
       gatePhase,
+      handoff: reviewTurn === "handoff" || awaitingDecision,
+      transition: reviewTurn === "transition",
+    });
+  }
+
+  /** True while a reviewer round or a real pause owns the turn (not handoff). */
+  function reviewRoundInFlight(): boolean {
+    let roundActive = false;
+    try {
+      roundActive = reviewRuntime?.isRoundActive() === true;
+    } catch (_e) {
+      void _e;
+    }
+    return reviewRoundOwnsTurn({
+      roundInFlight: activeReview !== undefined,
+      roundActive,
+      paused: currentPausedReview() !== undefined,
+      gatePhase:
+        reviewGateCycleId === reviewCycleId ? reviewGatePhase : "idle",
     });
   }
 
+  /** One status refresh for every review-turn transition. */
+  function setReviewTurn(phase: ReviewTurnPhase): void {
+    if (reviewTurn === phase) return;
+    reviewTurn = phase;
+    try {
+      if (currentSessionCtx) updateStatus(currentSessionCtx);
+    } catch (_e) {
+      void _e;
+    }
+  }
+
+  function beginReviewTurn(): void {
+    setReviewTurn("running");
+  }
+
+  function endReviewTurn(): void {
+    setReviewTurn("idle");
+  }
+
   /** Refuse a mode transition while a review round or pause owns the turn. */
   function blockModeSwitchDuringReview(
     ctx?: ExtensionContext,
@@ -1715,6 +1873,32 @@ export default function workflowExtension(
     return currentSessionCtx?.cwd ?? process.cwd();
   }
 
+  /**
+   * Environment for a spawned subagent: the role, the parent-approved roots
+   * (repo root of the task folder plus the task folder itself) and the
+   * parent's deny layer (sensitive extras + `excludePaths`). The child cannot
+   * widen its own scope: it ignores project settings entirely.
+   */
+  function subagentFolderEnv(cwd: string): Record<string, string> {
+    const parentCwd = (currentSessionCtx as any)?.cwd ?? cwd;
+    const trusted = (currentSessionCtx as any)?.isProjectTrusted?.() === true;
+    let deny = "";
+    try {
+      deny = buildFolderPolicyDeny(
+        readFolderPolicyConfig(parentCwd, getAgentDir(), { trusted }).config,
+      );
+    } catch (_e) {
+      void _e;
+    }
+    const roots = [...new Set([detectRepoRoot(cwd) ?? cwd, cwd])];
+    return {
+      PI_FOLDER_POLICY_LOCKED: "1",
+      PI_FOLDER_POLICY_ROOTS: JSON.stringify(roots),
+      PI_FOLDER_POLICY_SOURCE: "parent",
+      PI_FOLDER_POLICY_DENY: deny,
+    };
+  }
+
   /**
    * Current plan-file text (absolute or cwd-relative), or `undefined` when there
    * is no plan path, the file is gone, or it is unreadable. Never throws.
@@ -1979,7 +2163,13 @@ export default function workflowExtension(
       if (m) agent.model = `${m.provider}/${m.id}`;
       if (m?.thinking) agent.thinking = m.thinking;
 
-      const res = await runSingleAgent(cwd, agent, task, signal);
+      const res = await runSingleAgent(
+        cwd,
+        agent,
+        task,
+        signal,
+        subagentFolderEnv(cwd),
+      );
       const out = getFinalOutput(res.messages);
       if (!out && res.exitCode !== 0) {
         throw new Error(
@@ -1999,6 +2189,20 @@ export default function workflowExtension(
     reviewRuntime = createReviewRuntime({
       cwd,
       agentDir,
+      // The reviewer is an isolated session: hand it the parent's deny layer
+      // (sensitive extras + excludePaths) and read grants so its guarded
+      // read/grep/find/ls and review_bash cannot see an excluded tree.
+      folderPolicy: () => {
+        const cwdNow = reviewCwd();
+        const trusted =
+          (currentSessionCtx as any)?.isProjectTrusted?.() === true;
+        return {
+          config: readFolderPolicyConfig(cwdNow, getAgentDir(), { trusted })
+            .config,
+          grants: readReadPolicyConfig(cwdNow, getAgentDir(), { trusted }).config
+            .allowedPaths,
+        };
+      },
       config: () => reviewConfigNow()?.config,
       reviewerModel: () => {
         // The round snapshot wins while set (see executeReviewRound): a
@@ -2124,6 +2328,7 @@ export default function workflowExtension(
     // A gated audit becomes a paused gate (the handoff keeps waiting). A
     // manual review (idle gate) leaves the phase alone.
     if (reviewGatePhase === "auditing") reviewGatePhase = "paused";
+    setReviewTurn("paused");
     refreshReviewPauseUi();
     return true;
   }
@@ -2335,6 +2540,7 @@ export default function workflowExtension(
     // follow `reviewState`; the spinner row needs an explicit message while
     // the child session streams off the main turn.
     setReviewWorkingMessage("🔍 Reviewing plan…");
+    setReviewTurn("running");
     // Paint the live review line now, not after the child session's first
     // state event: a manual `/review` must look alive from the first tick.
     updateStatus(ctx as any);
@@ -2890,6 +3096,7 @@ export default function workflowExtension(
     flushReviewEntries(true);
     resetReviewStream();
     detachReviewEscListenerNow();
+    endReviewTurn();
     try {
       currentSessionCtx?.ui.setStatus(WORKFLOW_STATUS_KEYS.review, undefined);
     } catch (_e) {
@@ -3015,6 +3222,15 @@ export default function workflowExtension(
 
       const scope = scopeFor("global");
       const enable = sub === "on";
+      // Disabling would tear down the review (and its pending handoff) behind
+      // the lock. Abort is the explicit exit while Review owns the turn.
+      if (!enable && reviewTurnOwns(reviewTurn)) {
+        ctx.ui.notify(
+          "Review is active — /review-abort first (or resume/approve in the review tab).",
+          "info",
+        );
+        return;
+      }
 
       const res = writeReviewModeConfig(scope, cwd, agentDir, {
         enabled: enable,
@@ -3066,7 +3282,9 @@ export default function workflowExtension(
           : "global";
 
       if (!sub || sub === "status") {
-        const resolved = readCommitPolicyConfig(cwd, agentDir);
+        const resolved = readCommitPolicyConfig(cwd, agentDir, {
+          trusted: (ctx as any).isProjectTrusted?.() === true,
+        });
         const paths = commitConfigPaths(cwd, agentDir);
         const where =
           resolved.sources.mode === "default"
@@ -3125,8 +3343,9 @@ export default function workflowExtension(
   });
 
   // ── /write-policy: view/set the write permission (workflow.writePolicy) ──
-  // Available in every mode: it only writes settings JSON; the gate itself
-  // lives in tool_call and applies in Default mode only.
+  // Available in every mode: it only writes settings JSON. The write *mode*
+  // applies in Default mode only; the shared folder floor applies in every
+  // mode, Build included.
   pi.registerCommand("write-policy", {
     description:
       "View or set the write permission (what the agent may modify in Default mode): /write-policy allow|ask|never [global|project]",
@@ -3144,7 +3363,9 @@ export default function workflowExtension(
           : "global";
 
       if (!sub || sub === "status") {
-        const resolved = readWritePolicyConfig(cwd, agentDir);
+        const resolved = readWritePolicyConfig(cwd, agentDir, {
+          trusted: (ctx as any).isProjectTrusted?.() === true,
+        });
         const paths = writePolicyConfigPaths(cwd, agentDir);
         const where =
           resolved.sources.mode === "default"
@@ -3153,7 +3374,8 @@ export default function workflowExtension(
         const lines = [
           `Write policy: ${resolved.config.mode} (${where})`,
           `  ${describeWritePolicyMode(resolved.config.mode)}`,
-          "  Applies to Default mode only — Plan mode is read-only already, /build is the execution escape hatch.",
+          "  The write mode applies to Default mode only; the shared folder floor applies in every mode.",
+          "  Plan mode is read-only already; /build is the execution escape hatch.",
         ];
         if (resolved.config.allowedPaths.length > 0) {
           lines.push(
@@ -3227,6 +3449,345 @@ export default function workflowExtension(
   // gate: it reads the same analyzeCommand/explainCommandRefusal the gates
   // use, so the explanation cannot describe a policy the gate no longer
   // enforces. Read-only, so it is safe in every mode.
+  pi.registerCommand("folder-policy", {
+    description: "Shared folder scope for read/write/commit: repo|cwd|parent|any, outside ask|block, sensitive list",
+    handler: async (args, ctx) => {
+      const cwd = (ctx as any)?.cwd ?? process.cwd();
+      const agentDir = getAgentDir();
+      const trusted = (ctx as any).isProjectTrusted?.() === true;
+      const split = splitPolicyArgs(args);
+      if (split.error) {
+        ctx.ui.notify(`${split.error}\n${EXCLUDE_USAGE}`, "warning");
+        return;
+      }
+      const tokens = split.tokens;
+      const sub = (tokens[0] || "status").toLowerCase();
+      const second = (tokens[1] || "").toLowerCase();
+      // Legacy bare-token scope for the mode verbs. `exclude` parses its own
+      // scope (flags only) because a standalone `project`/`global` word there
+      // is a path, not a scope.
+      const modeScope: "global" | "project" = tokens.includes("--project")
+        ? "project"
+        : tokens.includes("--global")
+          ? "global"
+          : tokens.includes("project")
+            ? "project"
+            : "global";
+      const resolved = readFolderPolicyConfig(cwd, agentDir, { trusted });
+      const baseRoot = baseFolderRoots(resolved.config, cwd)[0] ?? cwd;
+      // Per capability, with that capability's real grants: a read grant can
+      // rescue reads while writes and commits stay refused at the base.
+      const baseCoverage = (config: typeof resolved.config) =>
+        evaluateBaseCoverage({
+          config,
+          cwd,
+          lockedRoots: resolved.locked?.roots,
+          grantsByCapability: {
+            read: readReadPolicyConfig(cwd, agentDir, { trusted }).config
+              .allowedPaths,
+            write: readWritePolicyConfig(cwd, agentDir, { trusted }).config
+              .allowedPaths,
+            commit: readCommitPolicyConfig(cwd, agentDir, { trusted }).config
+              .allowedPaths,
+          },
+        });
+      if (sub === "status") {
+        const paths = folderPolicyConfigPaths(cwd, agentDir);
+        const lines = [
+          `Folder policy: ${resolved.config.mode} (${resolved.sources.mode === "default" ? "default" : resolved.sources.mode + " settings"})`,
+          `  outside: ${resolved.config.outside}; grantScope: ${resolved.config.grantScope}; templates: ${resolved.config.sensitiveTemplates}`,
+          `  base: ${baseRoot}`,
+          "  unverifiable writes: not prompted (use /write-policy ask for strictness)",
+          `  sensitive: ${DEFAULT_SENSITIVE_PATTERNS.length} default, ${resolved.config.sensitivePatterns.length} extra, ${resolved.config.sensitiveExemptions.length} exemption(s)`,
+          `  excluded: ${resolved.config.excludePaths.length} rule(s)`,
+          ...(resolved.config.excludePaths.length > 0
+            ? [
+                ...resolved.config.excludePaths.map((p) => `    ${p}`),
+                "    (an excluded folder itself is refused; a sub-folder needs an explicit grant)",
+              ]
+            : []),
+          `Global: ${paths.global}`,
+          `Project: ${paths.project}${resolved.sources.projectIgnored ? " (ignored: project not trusted)" : ""}`,
+          "Usage: /folder-policy repo|cwd|parent|any [global|project] · outside ask|block · grant project|global · templates allow|block · sensitive · exclude <path>|add <path>|revoke <path>|list [--global|--project] (quote paths with spaces)",
+        ];
+        const coverage = baseCoverage(resolved.config);
+        const blocked = coverage.filter(
+          (entry) => entry.excluded.length > 0 || entry.outside.length > 0,
+        );
+        const rescued = coverage.filter((entry) => entry.rescuedBy);
+        if (blocked.length > 0) {
+          const hit = blocked[0]?.excluded[0] ?? blocked[0]?.outside[0];
+          ctx.ui.notify(
+            [
+              ...lines,
+              "",
+              `WARNING: the session folder itself is excluded (${hit?.path ?? baseRoot}).`,
+              `Refused at the session folder: ${blocked.map((entry) => entry.capability).join(", ")}.`,
+              ...(rescued.length > 0
+                ? [
+                    `Still covered by a grant: ${rescued
+                      .map((entry) => `${entry.capability} (${entry.rescuedBy})`)
+                      .join(", ")}.`,
+                  ]
+                : []),
+              "Grant a sub-folder explicitly, or revoke with:",
+              "  /folder-policy exclude revoke <path>",
+            ].join("\n"),
+            "error",
+          );
+          return;
+        }
+        ctx.ui.notify(
+          [
+            ...lines,
+            ...(rescued.length > 0
+              ? [
+                  `  (the session folder is inside an exclusion, but ${rescued
+                    .map((entry) => entry.capability)
+                    .join(", ")} is covered by a grant)`,
+                ]
+              : []),
+          ].join("\n"),
+          "info",
+        );
+        return;
+      }
+      if (sub === "exclude") {
+        const parsed = parseExcludeArgs(tokens.slice(1));
+        if (!parsed.ok) {
+          ctx.ui.notify(`${parsed.message}\n${EXCLUDE_USAGE}`, "warning");
+          return;
+        }
+        const settingsPaths = folderPolicyConfigPaths(cwd, agentDir);
+        const activeLines = (config: typeof resolved.config): string[] => [
+          `Active exclusions (${config.excludePaths.length}):`,
+          ...(config.excludePaths.length > 0
+            ? config.excludePaths.map((rule) => `  ${rule}`)
+            : ["  (none)"]),
+        ];
+        if (parsed.action === "list") {
+          ctx.ui.notify(
+            [
+              `Excluded paths (${resolved.config.excludePaths.length}):`,
+              ...(resolved.config.excludePaths.length > 0
+                ? resolved.config.excludePaths.map((rule) => `  ${rule}`)
+                : ["  (none)"]),
+              ...(resolved.sources.projectIgnored
+                ? ["Project settings are ignored: this project is not trusted."]
+                : []),
+              "The excluded path itself is refused (no dialog, no grant). A path below it",
+              "is outside: it can be approved once, or always via a grant inside it.",
+              "Sensitive files stay blocked even inside an approved sub-folder.",
+              `Global: ${settingsPaths.global}`,
+              `Project: ${settingsPaths.project}`,
+            ].join("\n"),
+            "info",
+          );
+          return;
+        }
+        const rawPattern = parsed.pattern ?? "";
+        const trimmedInput = rawPattern.trim();
+        if (parsed.action === "revoke") {
+          const result = revokeFolderPolicyListEntry(
+            parsed.scope,
+            cwd,
+            agentDir,
+            "excludePaths",
+            rawPattern,
+          );
+          if (!result.ok) {
+            ctx.ui.notify(
+              `Could not update the exclude list: ${result.error ?? "unknown error"}`,
+              "error",
+            );
+            return;
+          }
+          const after = readFolderPolicyConfig(cwd, agentDir, { trusted });
+          ctx.ui.notify(
+            [
+              result.removed
+                ? `Removed (${parsed.scope}): ${trimmedInput}`
+                : `Not in the exclude list (${parsed.scope}): ${trimmedInput}`,
+              `Settings: ${result.path}`,
+              ...activeLines(after.config),
+            ].join("\n"),
+            result.removed ? "info" : "warning",
+          );
+          updateStatus(ctx as any);
+          return;
+        }
+        const pattern = normalizeExcludePattern(rawPattern);
+        if (!pattern || pattern === "*" || pattern === "**" || pattern === "**/*") {
+          ctx.ui.notify(
+            "Refusing that exclude pattern: it would block every path. Give a path such as C:/ or ~ (quoting paths that contain spaces).",
+            "warning",
+          );
+          return;
+        }
+        const written = writeFolderPolicyConfig(parsed.scope, cwd, agentDir, {
+          excludePaths: [pattern],
+        });
+        if (!written.ok) {
+          ctx.ui.notify(
+            `Could not write the exclude list: ${written.error ?? "unknown error"}`,
+            "error",
+          );
+          return;
+        }
+        const after = readFolderPolicyConfig(cwd, agentDir, { trusted });
+        const coverage = baseCoverage(after.config);
+        const blocked = coverage.filter(
+          (entry) => entry.excluded.length > 0 || entry.outside.length > 0,
+        );
+        const rescued = coverage.filter((entry) => entry.rescuedBy);
+        const notes: string[] = [];
+        // A successful write is never an error. Only a rule that cripples the
+        // session folder (and that no grant rescues) escalates.
+        let level: "info" | "warning" | "error" = "info";
+        if (blocked.length > 0) {
+          notes.push(
+            `WARNING: this also covers the session folder (${baseRoot}).`,
+            `Refused at the session folder: ${blocked.map((entry) => entry.capability).join(", ")}.`,
+            ...(rescued.length > 0
+              ? [
+                  `Still covered by a grant: ${rescued
+                    .map((entry) => `${entry.capability} (${entry.rescuedBy})`)
+                    .join(", ")}.`,
+                ]
+              : []),
+            "Grant a sub-folder explicitly, or revoke with:",
+            `  /folder-policy exclude revoke ${pattern}`,
+          );
+          level = "error";
+        } else if (rescued.length > 0) {
+          notes.push(
+            `Note: this also covers the session folder, but ${rescued
+              .map((entry) => entry.capability)
+              .join(", ")} is covered by an explicit grant.`,
+          );
+          level = "warning";
+        } else if (isBroadExcludePattern(pattern)) {
+          notes.push(
+            `Note: ${pattern} is an OS/drive root or your home directory.`,
+            "Nothing inside it is reachable until a sub-folder is approved once or",
+            "granted explicitly; dialogs cannot grant a root or home in one click.",
+          );
+          level = "warning";
+        }
+        ctx.ui.notify(
+          [
+            `Excluded (${parsed.scope}): ${pattern}` +
+              (trimmedInput && trimmedInput !== pattern
+                ? ` (normalised from ${trimmedInput})`
+                : ""),
+            `Settings: ${written.path}`,
+            ...activeLines(after.config),
+            ...notes,
+          ].join("\n"),
+          level,
+        );
+        updateStatus(ctx as any);
+        return;
+      }
+      if (sub === "sensitive") {
+        ctx.ui.notify(
+          [
+            "Sensitive deny list (always blocked for read/write/commit):",
+            ...DEFAULT_SENSITIVE_PATTERNS.map((p) => `  ${p}`),
+            ...(resolved.config.sensitivePatterns.length
+              ? ["Extra:", ...resolved.config.sensitivePatterns.map((p) => `  ${p}`)]
+              : []),
+            ...(resolved.config.sensitiveExemptions.length
+              ? ["Exemptions (manual):", ...resolved.config.sensitiveExemptions.map((p) => `  ${p}`)]
+              : []),
+          ].join("\n"),
+          "info",
+        );
+        return;
+      }
+      let patch: Record<string, unknown> | undefined;
+      if (["repo", "cwd", "parent", "any"].includes(sub)) patch = { mode: sub };
+      else if (sub === "outside" && ["ask", "block"].includes(second)) patch = { outside: second };
+      else if (sub === "grant" && ["project", "global"].includes(second)) patch = { grantScope: second };
+      else if (sub === "templates" && ["allow", "block"].includes(second)) patch = { sensitiveTemplates: second };
+      if (!patch) {
+        ctx.ui.notify("Usage: /folder-policy repo|cwd|parent|any · outside ask|block · grant project|global · templates allow|block · sensitive", "info");
+        return;
+      }
+      const written = writeFolderPolicyConfig(modeScope, cwd, agentDir, patch as any);
+      ctx.ui.notify(
+        written.ok
+          ? `Folder policy updated (${modeScope}): ${written.path}`
+          : `Could not write folder policy: ${written.error ?? "unknown error"}`,
+        written.ok ? "info" : "error",
+      );
+      updateStatus(ctx as any);
+    },
+    getArgumentCompletions: (prefix: string) => folderPolicyArgumentCompletions(prefix),
+  });
+
+  pi.registerCommand("read-policy", {
+    description: "Read permission: grants, shell paths|strict, guarded tools and the shared folder scope",
+    handler: async (args, ctx) => {
+      const cwd = (ctx as any)?.cwd ?? process.cwd();
+      const agentDir = getAgentDir();
+      const trusted = (ctx as any).isProjectTrusted?.() === true;
+      const tokens = String(args || "").trim().split(/\s+/).filter(Boolean);
+      const sub = (tokens[0] || "status").toLowerCase();
+      const readResolved = readReadPolicyConfig(cwd, agentDir, { trusted });
+      const folderResolved = readFolderPolicyConfig(cwd, agentDir, { trusted });
+      const paths = readPolicyConfigPaths(cwd, agentDir);
+      if (sub === "status" || !sub) {
+        ctx.ui.notify(
+          [
+            describeReadPolicy(readResolved.config, folderResolved.config),
+            `  grants: ${readResolved.config.allowedPaths.join(", ") || "none"}`,
+            `  guarded tools: ${readResolved.config.guardedTools.join(", ") || "none"}`,
+            `Global: ${paths.global}`,
+            `Project: ${paths.project}${readResolved.sources.projectIgnored ? " (ignored: project not trusted)" : ""}`,
+            "Usage: /read-policy allow <path> [global|project] · revoke <path> · shell paths|strict · status",
+          ].join("\n"),
+          "info",
+        );
+        return;
+      }
+      const scope: "global" | "project" = tokens.includes("project")
+        ? "project"
+        : "global";
+      if (sub === "shell") {
+        const value = (tokens[1] || "").toLowerCase();
+        if (value !== "paths" && value !== "strict") {
+          ctx.ui.notify("Usage: /read-policy shell paths|strict [global|project]", "info");
+          return;
+        }
+        const written = writeReadPolicyConfig(scope, cwd, agentDir, { shell: value });
+        ctx.ui.notify(written.ok ? `Read shell → ${value} (${scope})` : `Could not save: ${written.error}`, written.ok ? "info" : "error");
+        updateStatus(ctx as any);
+        return;
+      }
+      if (sub === "allow" || sub === "revoke") {
+        const target = tokens.slice(1).find((t) => t !== "global" && t !== "project");
+        if (!target) {
+          ctx.ui.notify(`Usage: /read-policy ${sub} <path> [global|project]`, "info");
+          return;
+        }
+        const result =
+          sub === "allow"
+            ? writeReadPolicyConfig(scope, cwd, agentDir, { allowedPaths: [target] })
+            : revokeReadPolicyPath(scope, cwd, agentDir, target);
+        ctx.ui.notify(
+          result.ok
+            ? `Read grant ${sub === "allow" ? "added" : "removed"} (${scope}): ${target}`
+            : `Could not save read grant: ${result.error}`,
+          result.ok ? "info" : "error",
+        );
+        return;
+      }
+      ctx.ui.notify("Usage: /read-policy status|allow <path>|revoke <path>|shell paths|strict", "info");
+    },
+    getArgumentCompletions: (prefix: string) => readPolicyArgumentCompletions(prefix),
+  });
+
   pi.registerCommand("permissions", {
     description:
       "Explain why a shell command would be allowed or refused: /permissions explain <command>",
@@ -3235,7 +3796,55 @@ export default function workflowExtension(
       const first = raw.split(/\s+/)[0]?.toLowerCase() ?? "";
       // `/permissions explain <cmd>` and `/permissions <cmd>` both work.
       const command = first === "explain" ? raw.slice("explain".length).trim() : raw;
-      ctx.ui.notify(describeCommandPolicy(command).join("\n"), "info");
+      const lines = describeCommandPolicy(command);
+      if (command.trim()) {
+        const cwd = (ctx as any)?.cwd ?? process.cwd();
+        const trusted = (ctx as any).isProjectTrusted?.() === true;
+        const folderConfig = readFolderPolicyConfig(cwd, getAgentDir(), {
+          trusted,
+        }).config;
+        const writeConfig = readWritePolicyConfig(cwd, getAgentDir(), {
+          trusted,
+        }).config;
+        const readConfig = readReadPolicyConfig(cwd, getAgentDir(), {
+          trusted,
+        }).config;
+        const analysis = analyzeShellPaths(command, cwd);
+        const classification = classifyWriteCall(
+          "bash",
+          { command },
+          writeConfig,
+        );
+        const writeTargets = writeFolderTargetsFor(
+          "bash",
+          { command },
+          classification,
+          cwd,
+        );
+        const evaluation = evaluateFolderTargets(
+          [...analysis.reads, ...writeTargets],
+          {
+            config: folderConfig,
+            grants: [...writeConfig.allowedPaths, ...readConfig.allowedPaths],
+            cwd,
+            action: "write",
+          },
+        );
+        lines.push(
+          "",
+          ...describeFolderEvaluation(
+            evaluation,
+            detectRepoRoot(cwd) ?? cwd,
+          ),
+        );
+        if (analysis.uncertain.length > 0) {
+          lines.push(`  shell analysis: ${analysis.uncertain.join("; ")}`);
+        }
+        lines.push(
+          "  unverifiable writes are not prompted under writePolicy allow/Build; use /write-policy ask for strictness",
+        );
+      }
+      ctx.ui.notify(lines.join("\n"), "info");
     },
     getArgumentCompletions: (prefix: string) =>
       permissionsArgumentCompletions(prefix),
@@ -3506,6 +4115,9 @@ export default function workflowExtension(
       abortedReviewHash = undefined;
       pausedReview = undefined;
       reviewRound = 0;
+      // Manual /review is a Review turn from the first tick: the mode status,
+      // input gate and mode lock must be active before the child boots.
+      beginReviewTurn();
       const result = await runReviewStep(
         target.text,
         ctx as any,
@@ -3580,6 +4192,7 @@ export default function workflowExtension(
       // A manual pause (idle gate) is unchanged; the runtime/activeReview
       // flags carry that lock.
       reviewGatePhase = reviewGatePhaseOnResume(reviewGatePhase);
+      setReviewTurn("running");
       // A stale quiet-abort marker must not silence this explicit resume.
       quietAbortHash = undefined;
       // If the plan file moved on while paused, review the new revision fresh
@@ -3669,6 +4282,46 @@ export default function workflowExtension(
       const active =
         activeReview !== undefined || rt?.isRoundActive() === true;
       const paused = currentPausedReview();
+      // A browser/inline decision can own the turn with no round and no pause.
+      if (!active && !paused && awaitingDecision) {
+        const planPath = pendingHandoffPlanPath ?? currentPlanFile ?? "";
+        const planText =
+          (planPath &&
+            (() => {
+              try {
+                return fs.existsSync(planPath)
+                  ? fs.readFileSync(planPath, "utf8")
+                  : undefined;
+              } catch {
+                return undefined;
+              }
+            })()) ??
+          "";
+        if (pendingHandoffReviewUrl) {
+          setReviewTurn("handoff");
+          ctx.ui.notify(
+            "Review skipped — approve or annotate in the review tab.",
+            "info",
+          );
+          return;
+        }
+        if (planText && planPath) {
+          const handed = await openManualHandoff(
+            { planText, outcome: "aborted", paused: false },
+            planPath,
+            ctx as any,
+          );
+          if (!handed) setReviewTurn("handoff");
+          return;
+        }
+        clearPendingHandoffDecision();
+        setReviewTurn("idle");
+        ctx.ui.notify(
+          `Review skipped — the plan file is ${planPath || "unavailable"}.`,
+          "info",
+        );
+        return;
+      }
       if (!active && !paused) {
         ctx.ui.notify("No review running or paused.", "info");
         return;
@@ -3680,6 +4333,10 @@ export default function workflowExtension(
       // abort lands; falls back to the author's draft when unknown).
       const abortedText =
         paused?.planText ?? activeReview?.planText;
+      const pausedPlanPath = currentPlanFile ?? "";
+      // A parked automatic handoff owns its own presentation: settle the gate
+      // and let `runHandoff` render, never present twice.
+      const gated = reviewGatePhase !== "idle" && !reviewHandoffGate.settled();
       pausedReview = undefined;
       // An aborted revision is not auto-reviewed again until the plan changes.
       if (targetHash) abortedReviewHash = targetHash;
@@ -3702,9 +4359,15 @@ export default function workflowExtension(
           "Review stopped — the author's plan stands unreviewed.",
           "info",
         );
-        // A gated handoff was waiting on this round: hand off the author's
-        // plan through the normal renderer so the plan is always delivered.
-        settleReviewGate({ outcome: "unreviewed", planText: abortedText });
+        if (gated) {
+          setReviewTurn("handoff");
+          settleReviewGate({ outcome: "unreviewed", planText: abortedText });
+          return;
+        }
+        // A manual /review command is awaiting this round; it will present the
+        // aborted plan through `openManualHandoff` (shouldHandoffManualResult
+        // now includes aborted). Keep Review visible until then.
+        setReviewTurn("handoff");
         return;
       }
       flushReviewEntries(true);
@@ -3713,8 +4376,20 @@ export default function workflowExtension(
         "Paused review discarded — the author's plan stands.",
         "info",
       );
-      settleReviewGate({ outcome: "unreviewed", planText: abortedText });
-      // No round will run its finally, so clear the live review line here.
+      if (gated) {
+        setReviewTurn("handoff");
+        settleReviewGate({ outcome: "unreviewed", planText: abortedText });
+        return;
+      }
+      if (abortedText && pausedPlanPath) {
+        await openManualHandoff(
+          { planText: abortedText, outcome: "aborted", paused: false },
+          pausedPlanPath,
+          ctx as any,
+        );
+        return;
+      }
+      setReviewTurn("idle");
       updateStatus(ctx as any);
     },
   });
@@ -3742,6 +4417,12 @@ export default function workflowExtension(
    */
   interface ModeSwitchOptions {
     quiet?: boolean;
+    /**
+     * Internal review-decision exit: the caller already validated the pending
+     * decision and owns the `transition` state, so the full review lock must
+     * not refuse it. Never set this from a user-facing mode switch.
+     */
+    fromReview?: boolean;
   }
 
   /** Pure helper for tests: resolve which RoleModel plan/build will switch to. */
@@ -4177,6 +4858,12 @@ export default function workflowExtension(
       },
       defaultModel,
       lastModeSwitch,
+      todoPanel: {
+        override: todoPanelOverride,
+        overrideKey: todoPanelOverrideKey,
+        promptAfterSettle: todoPanelPromptAfterSettle,
+        completedSignature: lastCompletedSignature,
+      },
     } as any);
     lastPersistedPlanFile = currentPlanFile;
   }
@@ -4193,9 +4880,10 @@ export default function workflowExtension(
       return;
     }
     // A live review owns the turn: no mode transition until it lands, fails,
-    // pauses or is aborted. The post-review approve path enters Build through
-    // `enterBuildModeFromPlan`, which is no longer locked once the gate settles.
-    if (blockModeSwitchDuringReview(ctx)) return;
+    // pauses or is aborted. A validated browser/inline decision passes
+    // `fromReview` because it is the exit, not a competing mode switch.
+    if (opts?.fromReview !== true && blockModeSwitchDuringReview(ctx)) return;
+    if (opts?.fromReview === true && reviewRoundInFlight()) return;
     // Leaving Default mode: remember its model so it can be restored on return.
     if (workflowMode === null) captureDefaultModel(ctx);
     workflowMode = "plan";
@@ -4414,11 +5102,19 @@ export default function workflowExtension(
   async function enterBuildModeFromPlan(
     ctx: ExtensionContext,
     planPath: string,
-  ) {
-    // Defense in depth: the inline/browser approve paths only run after the
-    // gated review resolves, but a stale approve must never switch tools while
-    // a round or pause still owns the turn.
-    if (blockModeSwitchDuringReview(ctx)) return;
+    opts?: { fromReview?: boolean },
+  ): Promise<boolean> {
+    // Defense in depth: a stale approve must never switch tools while a real
+    // reviewer round/pause owns the turn. The handoff itself is consumed by
+    // the caller (fromReview), so only `reviewRoundInFlight()` can refuse it.
+    if (opts?.fromReview === true) {
+      if (reviewRoundInFlight()) {
+        ctx.ui.notify(reviewModeLockNotice("running"), "info");
+        return false;
+      }
+    } else if (blockModeSwitchDuringReview(ctx)) {
+      return false;
+    }
     workflowMode = "build";
     syncLegacyFlags();
     // The plan is being handed to Build; this Plan cycle cannot hand off again.
@@ -4457,6 +5153,7 @@ export default function workflowExtension(
         : `Build mode: ${loaded.count} todos synced from plan (progress kept).`,
       "info",
     );
+    return true;
   }
 
   // ── Plannotator bridge helpers ─────────────────────────────────
@@ -4560,6 +5257,9 @@ export default function workflowExtension(
     pendingHandoffReviewUrl = null;
     lastReviewId = null;
     recordedHandoffReviewId = null;
+    // Keep the Review mode visible while the browser/inline decision owns the
+    // turn. The reviewer has finished, but prompts and modes stay locked.
+    setReviewTurn("handoff");
     persistState();
     const timeoutMs = Math.max(50, deps.plannotatorRequestTimeoutMs ?? 15_000);
     const response = await new Promise<PlanReviewRequestOutcome>((resolve) => {
@@ -4723,6 +5423,7 @@ export default function workflowExtension(
       if (reason === "startup" || reason === "new" || !lastReviewId) {
         const changed = clearPendingHandoffDecision();
         if (changed) persistState();
+        endReviewTurn();
         record("clear", { why: "no restorable review" });
         return;
       }
@@ -4739,6 +5440,7 @@ export default function workflowExtension(
       });
       if (decision.action === "keep") {
         if (pendingHandoffSource === "manual") manualReviewCycle = true;
+        setReviewTurn("handoff");
         record("keep", {
           reviewId: lastReviewId,
           ...(pendingHandoffReviewUrl
@@ -4758,7 +5460,7 @@ export default function workflowExtension(
           approved: decision.approved,
         });
         if (decision.approved) {
-          handlePlannotatorApprove(
+          await handlePlannotatorApprove(
             pendingHandoffPlanPath ?? currentPlanFile ?? "",
             currentFile ?? "",
             decision.feedback,
@@ -4773,6 +5475,7 @@ export default function workflowExtension(
       }
       const changed = clearPendingHandoffDecision();
       if (changed) persistState();
+      endReviewTurn();
       record("clear", { why: decision.reason, reviewId: lastReviewId ?? "" });
       notifyReview(
         `Previous browser review could not be recovered — ${decision.reason}.`,
@@ -4823,20 +5526,62 @@ export default function workflowExtension(
     return true;
   }
 
-  function handlePlannotatorApprove(
+  /** One execute handoff: todo list + the Build-starting message. */
+  function sendExecuteMessages(
+    ctx: ExtensionContext,
+    planPath: string,
+    feedback?: string,
+  ): void {
+    try {
+      const remainingList = formatTodoNumberedList(todoItems);
+      const todoListText = formatTodoNumberedList(todoItems, { glyph: true });
+      const planTodoListMessage = {
+        customType: "workflow-todo-list",
+        content: `**Plan Steps (${todoItems.length}):**\n\n${todoListText}`,
+        display: true,
+      };
+      const firstTodo = todoItems[0];
+      const feedbackBlock = feedback ? `\n\nFeedback: ${feedback}` : "";
+      const execMessage = `Execute the plan.\n\nRemaining steps:\n${remainingList}\n\nStart with: ${firstTodo ? firstTodo.text : (todoItems[0]?.text ?? "first step")}${feedbackBlock}${commitDirectiveLine(ctx)}\nAfter completing a step, include a [DONE:<ref>] tag in your response (use the numbers shown above).`;
+      (pi as any).sendMessage?.(planTodoListMessage, { deliverAs: "followUp" });
+      (pi as any).sendMessage?.(
+        {
+          customType: "workflow-plan-execute",
+          content: execMessage,
+          display: true,
+        },
+        { triggerTurn: true, deliverAs: "followUp" },
+      );
+    } catch (_e) {
+      void _e;
+    }
+    try {
+      pi.appendEntry("workflow-handoff-result", {
+        at: Date.now(),
+        choice: "execute",
+        source: "plannotator",
+        planPath,
+      });
+    } catch (_e) {
+      void _e;
+    }
+  }
+
+  async function handlePlannotatorApprove(
     planFilePath: string,
     planContent: string,
     feedback: string | undefined,
     cwd: string | undefined,
-  ) {
+  ): Promise<void> {
     const ctx = getActiveCtx();
     if (!ctx) return;
     // A manual `/review` handoff may be approved from Default/Build; an
     // automatic handoff only exists in Plan mode.
     if (workflowMode !== "plan" && pendingHandoffSource !== "manual") return;
-    // A stale browser approve while a review runs must not clear the pending
-    // decision or send the execute messages: the plan is still being audited.
-    if (blockModeSwitchDuringReview(ctx as any)) {
+    // A stale browser approve while a reviewer round/pause runs must not clear
+    // the pending decision or send execute. The handoff itself is deliberately
+    // NOT part of this predicate: it is the decision being consumed here.
+    if (reviewRoundInFlight()) {
       supersedePendingHandoff(
         "a browser decision arrived while a new review round was running",
         { force: true },
@@ -4898,59 +5643,42 @@ export default function workflowExtension(
     } catch (_e) {
       void _e;
     }
+    // Atomic decision exit: stop the reviewer and apply Build BEFORE any
+    // follow-up message. `transition` keeps input/mode gates closed while the
+    // async mode switch runs, so a queued prompt cannot race it.
+    setReviewTurn("transition");
     if (pendingHandoffSource === "manual") manualReviewCycle = false;
     clearPendingHandoffDecision();
-    void enterBuildModeFromPlan(ctx as any, resolvedPlan)
-      .then(() => updateStatus(ctx as any))
-      .catch(() => {
-        try {
-          updateStatus(ctx as any);
-        } catch (_e) {
-          void _e;
-        }
-      });
+    let enteredBuild = false;
     try {
-      const remainingList = formatTodoNumberedList(todoItems);
-      const todoListText = formatTodoNumberedList(todoItems, { glyph: true });
-      const planTodoListMessage = {
-        customType: "workflow-todo-list",
-        content: `**Plan Steps (${todoItems.length}):**\n\n${todoListText}`,
-        display: true,
-      };
-      const firstTodo = todoItems[0];
-      const feedbackBlock = feedback ? `\n\nFeedback: ${feedback}` : "";
-      const execMessage = `Execute the plan.\n\nRemaining steps:\n${remainingList}\n\nStart with: ${firstTodo ? firstTodo.text : (todoItems[0]?.text ?? "first step")}${feedbackBlock}${commitDirectiveLine(ctx)}\nAfter completing a step, include a [DONE:<ref>] tag in your response (use the numbers shown above).`;
-      (pi as any).sendMessage?.(planTodoListMessage, { deliverAs: "followUp" });
-      (pi as any).sendMessage?.(
-        {
-          customType: "workflow-plan-execute",
-          content: execMessage,
-          display: true,
-        },
-        { triggerTurn: true, deliverAs: "followUp" },
+      enteredBuild = await enterBuildModeFromPlan(
+        ctx as any,
+        resolvedPlan,
+        { fromReview: true },
+      );
+    } catch (e: any) {
+      ctx.ui.notify(
+        `Could not enter Build mode (${String(e?.message ?? e)}); the plan was not executed.`,
+        "warning",
       );
-    } catch (_e) {
-      void _e;
     }
-    try {
-      pi.appendEntry("workflow-handoff-result", {
-        at: Date.now(),
-        choice: "execute",
-        source: "plannotator",
-        planPath: resolvedPlan,
-      });
-    } catch (_e) {
-      void _e;
+    if (!enteredBuild) {
+      setReviewTurn("handoff");
+      updateStatus(ctx as any);
+      return;
     }
+    setReviewTurn("idle");
+    updateStatus(ctx as any);
+    sendExecuteMessages(ctx as any, resolvedPlan, feedback);
   }
 
   async function handlePlannotatorDeny(feedback: string) {
     const ctx = getActiveCtx();
     if (!ctx) return;
-    // Not a mode transition, but while a review owns the turn every browser
-    // decision is stale: injecting feedback here would mutate the plan under
-    // the reviewer. A legitimate deny only arrives after the gate resolves.
-    if (blockModeSwitchDuringReview(ctx as any)) {
+    // A stale deny while a new reviewer round/pause runs must not inject
+    // feedback under the reviewer. The pending handoff (if any) is the decision
+    // being consumed, so only the round predicate can refuse it.
+    if (reviewRoundInFlight()) {
       supersedePendingHandoff(
         "a browser decision arrived while a new review round was running",
         { force: true },
@@ -4959,11 +5687,12 @@ export default function workflowExtension(
     }
     if (!awaitingDecision) return;
     const manualSource = pendingHandoffSource === "manual";
+    setReviewTurn("transition");
     if (manualSource && workflowMode !== "plan") {
       // A manual review can be launched from Default/Build. Its feedback is a
       // plan revision, so switch to Plan before the follow-up turn starts.
       try {
-        await setPlanMode(ctx as any, { quiet: true });
+        await setPlanMode(ctx as any, { quiet: true, fromReview: true });
       } catch (_e) {
         void _e;
       }
@@ -4977,6 +5706,11 @@ export default function workflowExtension(
     // outstanding findings are carried forward so the reviewer can confirm they
     // were actually addressed rather than re-raising them.
     await beginReviewCycle({ reason: "deny", keepFindings: true });
+    setReviewTurn("idle");
+    // The feedback turn is not a fresh user prompt: keeping the refine reason
+    // preserves manualReviewCycle, so a manual review with automatic Review
+    // Mode off still re-reviews the revision.
+    reviewFeedbackTurn = true;
     persistState();
     try {
       const todoListText = formatTodoNumberedList(todoItems, { glyph: true });
@@ -5010,6 +5744,91 @@ export default function workflowExtension(
     }
   }
 
+  /**
+   * The browser review closed without a decision. The user must still get a
+   * handoff: present a compact inline Approve/Revise choice with the author's
+   * plan. Reopening the browser here could loop on every close, so this path is
+   * deliberately inline-only. Never leaves Review stuck: cancel/idle clears it.
+   */
+  async function presentClosedHandoff(
+    ctx: ExtensionContext,
+    planPath: string,
+    planText: string,
+  ): Promise<void> {
+    clearPendingHandoffDecision();
+    setReviewTurn("handoff");
+    if (!planText || !planPath) {
+      endReviewTurn();
+      ctx.ui.notify(
+        `Plan review closed — the plan file is ${planPath || "unavailable"}.`,
+        "info",
+      );
+      return;
+    }
+    if ((ctx as any).hasUI !== true) {
+      try {
+        (pi as any).sendMessage?.(
+          {
+            customType: "workflow-handoff-fallback",
+            content: `**Plan ready**\n\nPlan review closed without a decision. The plan is at ${planPath}.\n\nType "Execute the plan" to build, or tell me what to refine.`,
+            display: true,
+          },
+          { triggerTurn: false },
+        );
+      } catch (_e) {
+        void _e;
+      }
+      endReviewTurn();
+      return;
+    }
+    const execute = "Execute the plan in Build Mode";
+    const refine = "Refine the plan in Plan Mode";
+    let choice: string | undefined;
+    try {
+      choice = await (ctx as any).ui.select(
+        "Plan review closed — choose next step",
+        [execute, refine],
+      );
+    } catch {
+      choice = undefined;
+    }
+    if (choice === execute) {
+      setReviewTurn("transition");
+      const ok = await enterBuildModeFromPlan(ctx as any, planPath, {
+        fromReview: true,
+      });
+      if (!ok) {
+        setReviewTurn("handoff");
+        return;
+      }
+      setReviewTurn("idle");
+      sendExecuteMessages(ctx, planPath);
+      return;
+    }
+    if (choice === refine) {
+      setReviewTurn("transition");
+      if (workflowMode !== "plan") {
+        try {
+          await setPlanMode(ctx as any, { quiet: true, fromReview: true });
+        } catch (_e) {
+          void _e;
+        }
+      }
+      await beginReviewCycle({ reason: "refine", keepFindings: true });
+      setReviewTurn("idle");
+      ctx.ui.notify(
+        "Plan review closed — staying in Plan mode. Tell me what to change.",
+        "info",
+      );
+      return;
+    }
+    endReviewTurn();
+    ctx.ui.notify(
+      `Plan review closed — the plan is at ${planPath}.`,
+      "info",
+    );
+  }
+
   function ensurePlannotatorListeners() {
     if (plannotatorListenersRegistered) return;
     try {
@@ -5017,16 +5836,17 @@ export default function workflowExtension(
       if (!bus || typeof bus.on !== "function") return;
       // plan-approved (external executionMode) — direct handoff
       bus.on(PLANNOTATOR_PLAN_APPROVED, (event: any) => {
-        try {
-          handlePlannotatorApprove(
-            event.planFilePath,
-            event.planContent,
-            event.feedback,
-            event.cwd,
+        void handlePlannotatorApprove(
+          event?.planFilePath,
+          event?.planContent,
+          event?.feedback,
+          event?.cwd,
+        ).catch((e: unknown) => {
+          notifyReview(
+            `Plan approval failed: ${e instanceof Error ? e.message : String(e)}`,
+            "error",
           );
-        } catch (_e) {
-          void _e;
-        }
+        });
       });
       // review-result (plan-review shared API) — approve/deny from browser
       bus.on(PLANNOTATOR_REVIEW_RESULT, (event: any) => {
@@ -5046,12 +5866,17 @@ export default function workflowExtension(
             } catch (_e) {
               void _e;
             }
-            handlePlannotatorApprove(
+            void handlePlannotatorApprove(
               planPath,
               content,
               event.feedback,
               (getActiveCtx() as any)?.cwd,
-            );
+            ).catch((e: unknown) => {
+              notifyReview(
+                `Plan approval failed: ${e instanceof Error ? e.message : String(e)}`,
+                "error",
+              );
+            });
           } else {
             void handlePlannotatorDeny(
               event.feedback || "Plan needs revision.",
@@ -5099,9 +5924,31 @@ export default function workflowExtension(
           if (event.outcome !== "closed") return;
           if (!lastReviewId || event.reviewId !== lastReviewId) return;
           if (!awaitingDecision) return;
-          supersedePendingHandoff(
-            "the browser review closed without a decision",
-            { force: true },
+          const planPath = pendingHandoffPlanPath ?? currentPlanFile ?? "";
+          let planText = "";
+          try {
+            if (planPath && fs.existsSync(planPath)) {
+              planText = fs.readFileSync(planPath, "utf8");
+            }
+          } catch (_e) {
+            void _e;
+          }
+          const ctx = getActiveCtx();
+          if (!ctx) {
+            supersedePendingHandoff(
+              "the browser review closed without a decision",
+              { force: true },
+            );
+            return;
+          }
+          void presentClosedHandoff(ctx as any, planPath, planText).catch(
+            (e: unknown) => {
+              notifyReview(
+                `Plan handoff after review close failed: ${e instanceof Error ? e.message : String(e)}`,
+                "warning",
+              );
+              endReviewTurn();
+            },
           );
         } catch (_e) {
           void _e;
@@ -5296,6 +6143,34 @@ export default function workflowExtension(
     void _e;
   }
 
+  // Todo panel toggle: expanded ↔ collapsed, and hidden → expanded.
+  // Ctrl+Alt+T is the Linux default for opening a terminal, so this uses O.
+  try {
+    pi.registerShortcut(Key.ctrlAlt("o"), {
+      description: "Toggle the workflow todo panel",
+      handler: async (ctx: any) => {
+        if (overlayDepth > 0) return;
+        if (todoItems.length === 0) {
+          ctx.ui.notify("No todos.", "info");
+          return;
+        }
+        const view = deriveTodoPanel({
+          items: todoItems,
+          override: todoPanelOverride,
+          overrideKey: todoPanelOverrideKey,
+          promptAfterSettle: todoPanelPromptAfterSettle,
+          stale: todoStale,
+        });
+        setTodoPanelOverride(
+          ctx as any,
+          view.state === "expanded" ? "collapsed" : "expanded",
+        );
+      },
+    });
+  } catch (_e) {
+    void _e;
+  }
+
   // Tab cycles workflow modes (context-aware: not when an overlay is active).
   // WorkflowTabEditor gives Tab back to autocomplete while a suggestion list is
   // visible; this registration remains the no-list path. Single registration to
@@ -5559,7 +6434,10 @@ export default function workflowExtension(
           };
           todoItems.push(item);
           try {
-            if (currentSessionCtx) updateStatus(currentSessionCtx);
+            if (currentSessionCtx) {
+              updateStatus(currentSessionCtx);
+              persistState();
+            }
           } catch (_e) {
             void _e;
           }
@@ -5680,6 +6558,10 @@ export default function workflowExtension(
           const c = todoItems.length;
           todoItems = [];
           todoPlanPath = undefined;
+          todoPanelOverride = null;
+          todoPanelOverrideKey = null;
+          todoPanelPromptAfterSettle = false;
+          lastCompletedSignature = null;
           try {
             if (currentSessionCtx) {
               updateStatus(currentSessionCtx);
@@ -5711,19 +6593,119 @@ export default function workflowExtension(
   });
 
   pi.registerCommand("todos", {
-    description: "Show workflow todos",
-    handler: async (_args, ctx) => {
-      const list = todoItems.length
-        ? `Steps are numbered GLOBALLY 1..${todoItems.length}:
+    description:
+      "Show or control the todo panel: /todos [show|expand|collapse|hide|auto|clear]",
+    handler: async (args, ctx) => {
+      const tokens = String(args || "")
+        .trim()
+        .split(/\s+/)
+        .filter(Boolean);
+      const sub = (tokens[0] || "").toLowerCase();
+      const usage = [
+        "Usage: /todos [show|expand|collapse|hide|auto|clear]",
+        "  (no arg)  list every step with global refs",
+        "  expand    show the full pinned panel",
+        "  collapse  keep one summary line",
+        "  hide      remove the pinned panel (footer keeps progress)",
+        "  auto      follow the automatic collapse/hide sequence",
+        "  clear     delete the todo list (asks first when UI is available)",
+      ].join("\n");
+
+      if (!sub) {
+        const list = todoItems.length
+          ? `Steps are numbered GLOBALLY 1..${todoItems.length}:
 ` +
-          todoItems
-            .map((t) => {
-              const g = t.group ? `[${t.group}] ` : "";
-              return `${g}${formatTodoLine(t)}`;
-            })
-            .join("\n")
-        : "No todos.";
-      ctx.ui.notify(`Todos (${todoItems.length}):\n${list}`, "info");
+            todoItems
+              .map((t) => {
+                const g = t.group ? `[${t.group}] ` : "";
+                return `${g}${formatTodoLine(t)}`;
+              })
+              .join("\n")
+          : "No todos.";
+        ctx.ui.notify(`Todos (${todoItems.length}):\n${list}`, "info");
+        return;
+      }
+
+      if (sub === "show" || sub === "expand") {
+        setTodoPanelOverride(ctx, "expanded");
+        return;
+      }
+      if (sub === "collapse") {
+        setTodoPanelOverride(ctx, "collapsed");
+        return;
+      }
+      if (sub === "hide") {
+        setTodoPanelOverride(ctx, "hidden");
+        return;
+      }
+      if (sub === "auto") {
+        setTodoPanelOverride(ctx, null);
+        return;
+      }
+      if (sub === "clear") {
+        const count = todoItems.length;
+        if (count === 0) {
+          ctx.ui.notify("No todos.", "info");
+          return;
+        }
+        // Headless confirm() resolves false and would silently turn this into
+        // a no-op; the command is explicit, so only ask when there is UI.
+        const confirmed =
+          (ctx as any).hasUI === true
+            ? await ctx.ui.confirm(
+                "Clear todos?",
+                "This resets the list. In Build mode, edits are blocked until a list exists again.",
+              )
+            : true;
+        if (!confirmed) {
+          ctx.ui.notify("Clear cancelled.", "info");
+          return;
+        }
+        todoItems = [];
+        todoPlanPath = undefined;
+        todoPanelOverride = null;
+        todoPanelOverrideKey = null;
+        todoPanelPromptAfterSettle = false;
+        lastCompletedSignature = null;
+        updateStatus(ctx);
+        try {
+          persistState();
+        } catch (_e) {
+          void _e;
+        }
+        onTodoWrite();
+        ctx.ui.notify(
+          `Cleared ${count} todos. In Build mode, edits are blocked until a list exists again (approve a plan or add a step).`,
+          "info",
+        );
+        return;
+      }
+      if (sub === "help") {
+        ctx.ui.notify(usage, "info");
+        return;
+      }
+      ctx.ui.notify(`Unknown /todos action: ${sub}\n${usage}`, "info");
+    },
+    getArgumentCompletions: (prefix: string) => {
+      const raw = String(prefix ?? "");
+      if (/\s/.test(raw.trim())) return null;
+      const lower = raw.trim().toLowerCase();
+      const verbs = [
+        { name: "show", description: "Show the full pinned panel" },
+        { name: "expand", description: "Show the full pinned panel" },
+        { name: "collapse", description: "Keep one summary line" },
+        { name: "hide", description: "Remove the pinned panel" },
+        { name: "auto", description: "Automatic collapse/hide sequence" },
+        { name: "clear", description: "Delete the todo list" },
+        { name: "help", description: "Show usage" },
+      ];
+      const matching = verbs.filter((v) => v.name.startsWith(lower));
+      if (matching.length === 0) return null;
+      return matching.map((v) => ({
+        value: `${v.name} `,
+        label: v.name,
+        description: v.description,
+      }));
     },
   });
 
@@ -8275,6 +9257,7 @@ export default function workflowExtension(
               ag.role ? ag : { ...ag, role: "explorer" },
               job.task,
               signal,
+              subagentFolderEnv(job.cwd ?? cwd),
             );
             if (signal?.aborted) {
               results[idx] = {
@@ -8805,6 +9788,20 @@ export default function workflowExtension(
   // command reaches the reviewer now; the write-gate steer guard below stays
   // (a write instruction must never be steered into the reviewer).
   pi.on("input", async (event, _ctx) => {
+    // Review owns the turn: only the explicit controls and model/profile
+    // changes may become a prompt. This is the terminal-Pi half of the lock;
+    // the Desktop store refuses prose before it reaches this hook.
+    if (reviewTurnOwns(reviewTurn)) {
+      const decision = reviewInputDecision(
+        typeof event.text === "string" ? event.text : "",
+        reviewTurn,
+      );
+      if (decision.action === "block") {
+        notifyReview(decision.notice, "info");
+        return { action: "handled" } as any;
+      }
+      return { action: "continue" } as any;
+    }
     if (typeof event.text === "string" && event.text.startsWith("/btw ")) {
       const note = event.text.slice(5).trim();
       if (note) {
@@ -8900,12 +9897,27 @@ export default function workflowExtension(
     // A session boundary owns the session-scoped plan fallback; the restore
     // loop below re-seeds it from the persisted `planFile`.
     resetSessionPlanProvenance();
+    // The branch is the source of truth for the panel's presentation. The
+    // host has cleared every extension widget on a session switch/reload, so
+    // the reconciler must register it again from the restored state.
+    todoPanelOverride = null;
+    todoPanelOverrideKey = null;
+    todoPanelPromptAfterSettle = false;
+    lastCompletedSignature = null;
+    todoPanelAppliedState = "unregistered";
     // A reloaded/forked session must never inherit a stale write denial.
     writeGateRunDenials.clear();
     writeGateTurnAnswer = null;
     writeGateTurnSteered = false;
     writeGateBatchCalls = [];
     writeGateBatchCallIds = new Set();
+    readGateRunDenials.clear();
+    readGateTurnAnswer = null;
+    readGateTurnSteered = false;
+    readGateBatchCalls = [];
+    readGateBatchCallIds = new Set();
+    readGateTurnGrantedRoots.clear();
+    readGateTurnUncertainAllowed.clear();
     // Roles are file-backed; load them up-front so every read path (status,
     // band label, reviewer runtime) sees the real config even in a fresh
     // session that has no persisted workflow entry yet. Profiles likewise.
@@ -8945,6 +9957,15 @@ export default function workflowExtension(
             }
             syncLegacyFlags();
             if (Array.isArray(d.todos)) todoItems = ensureTodoLabels(d.todos);
+            // Entries written before this feature have no `todoPanel`; they
+            // must not erase a value restored from an earlier entry.
+            if (d.todoPanel && typeof d.todoPanel === "object") {
+              const panel = readPersistedTodoPanel(d);
+              todoPanelOverride = panel.override;
+              todoPanelOverrideKey = panel.overrideKey;
+              todoPanelPromptAfterSettle = panel.promptAfterSettle;
+              lastCompletedSignature = panel.completedSignature;
+            }
             todoPlanPath = d.planFile;
             toolsBeforePlanMode = d.toolsBeforePlanMode;
             // An entry without a planFile must not erase a value restored
@@ -9275,6 +10296,9 @@ export default function workflowExtension(
     // whether it survives; do not null it here, or a restored gate can only
     // suppress the next handoff.
     if (!awaitingDecision) clearPendingHandoffDecision();
+    // A reload cannot preserve a running/paused reviewer child. Only a
+    // persisted pending decision survives, and it owns the turn as `handoff`.
+    reviewTurn = awaitingDecision ? "handoff" : "idle";
     currentSessionCtx = ctx as any;
     // Give Tab back to autocomplete while a suggestion list is visible; the raw
     // `tab` shortcut keeps cycling modes otherwise.
@@ -9321,6 +10345,13 @@ export default function workflowExtension(
     writeGateTurnSteered = false;
     writeGateBatchCalls = [];
     writeGateBatchCallIds = new Set();
+    readGateRunDenials.clear();
+    readGateTurnAnswer = null;
+    readGateTurnSteered = false;
+    readGateBatchCalls = [];
+    readGateBatchCallIds = new Set();
+    readGateTurnGrantedRoots.clear();
+    readGateTurnUncertainAllowed.clear();
     // Kill any active explore subagents to prevent orphan leaks.
     // Without this, `pi --mode json` children spawned by runSingleAgent
     // (up to 4 concurrent) could survive if VS Code closes the terminal
@@ -9355,6 +10386,8 @@ export default function workflowExtension(
     ctx.ui.setStatus(WORKFLOW_STATUS_KEYS.policy, undefined);
     ctx.ui.setStatus(WORKFLOW_STATUS_KEYS.review, undefined);
     ctx.ui.setWidget("workflow-todos", undefined);
+    // The host dropped the widget; a later session_start re-registers it.
+    todoPanelAppliedState = "unregistered";
     // Drop any /commit authorization or flow: a reload/quit must never leave
     // an exemption armed for whatever runs next.
     commitAuthorization = null;
@@ -9370,6 +10403,12 @@ export default function workflowExtension(
     todoItems = [];
     todoPlanPath = undefined;
     btwNotes = [];
+    // A rewind is a branch boundary: the panel choice belongs to the branch.
+    todoPanelOverride = null;
+    todoPanelOverrideKey = null;
+    todoPanelPromptAfterSettle = false;
+    lastCompletedSignature = null;
+    todoPanelAppliedState = "unregistered";
     // A rewind is a branch boundary: no per-run write from the old branch
     // may authorize a handoff or a manual review on the new one.
     resetPlanRunProvenance();
@@ -9380,13 +10419,18 @@ export default function workflowExtension(
     try {
       const branch = ctx.sessionManager.getBranch();
       for (const e of branch as any[]) {
-        if (
-          e.type === "custom" &&
-          e.customType === "workflow" &&
-          Array.isArray(e.data?.todos)
-        ) {
-          todoItems = ensureTodoLabels(e.data.todos);
-          if (e.data.planFile) todoPlanPath = e.data.planFile;
+        if (e.type === "custom" && e.customType === "workflow") {
+          if (Array.isArray(e.data?.todos)) {
+            todoItems = ensureTodoLabels(e.data.todos);
+            if (e.data.planFile) todoPlanPath = e.data.planFile;
+          }
+          if (e.data?.todoPanel && typeof e.data.todoPanel === "object") {
+            const panel = readPersistedTodoPanel(e.data);
+            todoPanelOverride = panel.override;
+            todoPanelOverrideKey = panel.overrideKey;
+            todoPanelPromptAfterSettle = panel.promptAfterSettle;
+            lastCompletedSignature = panel.completedSignature;
+          }
         }
         if (
           e.type === "message" &&
@@ -9426,15 +10470,226 @@ export default function workflowExtension(
    * The decision itself is the pure `decideCommitGate`; this wrapper supplies
    * the runtime inputs and renders the block reasons / ask overlay.
    */
-  async function commitPolicyGate(
-    event: any,
-    ctx: any,
+  function runGitZ(
+    repoRoot: string,
+    args: string[],
+  ): { ok: boolean; paths: string[]; error?: string } {
+    // The Pi host's PATH is not the shell's PATH (Windows especially). Honour
+    // an explicit override so a desktop install without git on PATH can still
+    // run the commit gate's synchronous checks.
+    const gitBinary = process.env.PI_GIT_BIN?.trim() || "git";
+    try {
+      const res = spawnSync(gitBinary, ["-C", repoRoot, ...args], {
+        encoding: "utf8",
+        timeout: 5000,
+        windowsHide: true,
+        maxBuffer: 8 * 1024 * 1024,
+      });
+      if (res.error) {
+        const code = (res.error as NodeJS.ErrnoException).code;
+        const missing =
+          code === "ENOENT" || /\bENOENT\b/.test(res.error.message);
+        return {
+          ok: false,
+          paths: [],
+          error: missing
+            ? `git executable not found (${gitBinary}); set PI_GIT_BIN to the git binary`
+            : res.error.message,
+        };
+      }
+      if (res.status !== 0)
+        return {
+          ok: false,
+          paths: [],
+          error: String(res.stderr ?? "").trim() || `git exited ${res.status}`,
+        };
+      const paths = String(res.stdout ?? "")
+        .split("\0")
+        .map((entry) => entry.replace(/\r?\n$/, ""))
+        .map((entry) => entry.replace(/^..\s+/, ""))
+        .map((entry) => entry.split(" -> ").pop() ?? entry)
+        .filter(Boolean);
+      return { ok: true, paths };
+    } catch (error: unknown) {
+      return {
+        ok: false,
+        paths: [],
+        error: error instanceof Error ? error.message : String(error),
+      };
+    }
+  }
+
+  function resolveCommitRoot(
+    candidate: string,
+    cwd: string,
+  ): { root: string; uncertain: boolean } {
+    const res = runGitZ(candidate, ["rev-parse", "--show-toplevel"]);
+    if (res.ok && res.paths[0]) {
+      return {
+        root: normalizeWritePath(res.paths[0], candidate),
+        uncertain: false,
+      };
+    }
+    const detected = detectRepoRoot(candidate) ?? detectRepoRoot(cwd);
+    return detected
+      ? { root: detected, uncertain: false }
+      : { root: candidate, uncertain: true };
+  }
+
+  interface CommitPathScan {
+    /** Explicit operands first, then index/working-tree paths. */
+    paths: string[];
+    failed?: string;
+  }
+
+  /**
+   * One git scan per `git add|commit`, shared by the sensitive and the
+   * exclusion checks (they must not disagree about which paths are involved,
+   * and running git twice doubled the timeout exposure).
+   */
+  function scanCommitPaths(
+    scope: NonNullable<ReturnType<typeof analyzeShellPaths>["git"]>,
+  ): CommitPathScan {
+    const paths: string[] = [];
+    const push = (values: readonly string[]) => {
+      for (const value of values) if (!paths.includes(value)) paths.push(value);
+    };
+    push(scope.explicitPaths);
+    if (scope.hit === "add" && scope.allPaths) {
+      const status = runGitZ(scope.repoRoot, [
+        "status",
+        "--porcelain=v1",
+        "-z",
+        "--untracked-files=all",
+      ]);
+      if (!status.ok)
+        return { paths, failed: status.error ?? "git status failed" };
+      push(status.paths);
+    }
+    if (scope.hit === "commit") {
+      const staged = runGitZ(scope.repoRoot, [
+        "diff",
+        "--cached",
+        "--name-only",
+        "-z",
+      ]);
+      if (!staged.ok)
+        return { paths, failed: staged.error ?? "git diff --cached failed" };
+      push(staged.paths);
+      if (scope.allPaths) {
+        const status = runGitZ(scope.repoRoot, [
+          "status",
+          "--porcelain=v1",
+          "-z",
+          "--untracked-files=all",
+        ]);
+        if (!status.ok)
+          return { paths, failed: status.error ?? "git status failed" };
+        push(status.paths);
+      }
+    }
+    return { paths };
+  }
+
+  /** First sensitive path in a scan, in scan order. */
+  function commitSensitiveHit(
+    scan: CommitPathScan,
+    scope: NonNullable<ReturnType<typeof analyzeShellPaths>["git"]>,
+    folderConfig: FolderPolicyConfig,
+  ): { path: string; pattern: string } | undefined {
+    for (const p of scan.paths) {
+      const hit = matchSensitivePath(p, folderConfig, scope.repoRoot);
+      if (hit.sensitive)
+        return { path: p, pattern: hit.pattern ?? "sensitive" };
+    }
+    return undefined;
+  }
+
+  async function commitPolicyGate(
+    event: any,
+    ctx: any,
     cwd: string,
   ): Promise<{ block: true; reason: string } | undefined> {
     const cmd = String(event?.input?.command ?? "");
     const hit = gitCommitPolicyHit(cmd);
     if (!hit) return undefined;
-    const policy = readCommitPolicyConfig(cwd, getAgentDir()).config.mode;
+    const trusted = ctx?.isProjectTrusted?.() === true;
+    const policyConfig = readCommitPolicyConfig(cwd, getAgentDir(), {
+      trusted,
+    }).config;
+    const policy = policyConfig.mode;
+    const folderConfig = readFolderPolicyConfig(cwd, getAgentDir(), {
+      trusted,
+    }).config;
+    const git = analyzeShellPaths(cmd, cwd).git;
+    const gitDir = /\bGIT_DIR=([^\s;&|]+)/.exec(cmd)?.[1];
+    const candidateRoot = gitDir
+      ? normalizeWritePath(gitDir.replace(/^['"]|['"]$/g, ""), cwd)
+      : (git?.repoRoot ?? normalizeWritePath(cwd, cwd));
+    const resolvedRoot = resolveCommitRoot(candidateRoot, cwd);
+    const repoRoot = resolvedRoot.root;
+    const gitScope = git ? { ...git, repoRoot } : undefined;
+    const folderEvaluation = evaluateFolderTargets(
+      [{ path: repoRoot, kind: "dir" }],
+      {
+        config: folderConfig,
+        grants: policyConfig.allowedPaths,
+        cwd,
+        action: "commit",
+      },
+    );
+    if (resolvedRoot.uncertain)
+      folderEvaluation.uncertain.push(repoRoot);
+    const baseRoot = baseFolderRoots(folderConfig, cwd)[0] ?? cwd;
+    // decideFolderGate already turns uncertainty into ask (outside: ask) or
+    // block (outside: block); there is no "allow" case left to escalate.
+    const scan = gitScope ? scanCommitPaths(gitScope) : undefined;
+    if (scan?.failed) {
+      return {
+        block: true,
+        reason:
+          `Commit policy: the sensitive-file/exclusion check could not run (${scan.failed}). ` +
+          "Refusing to commit unverified. Do not retry; ask the user to commit manually or fix git access.",
+      };
+    }
+    const sensitiveHit =
+      scan && gitScope ? commitSensitiveHit(scan, gitScope, folderConfig) : undefined;
+    // The exclusion rule is applied to the same scanned paths with the same
+    // rescue semantics as the folder floor. Git paths are repository-relative.
+    const pathEvaluation =
+      scan && scan.paths.length > 0
+        ? evaluateFolderTargets(
+            scan.paths.map((p) => ({
+              path: path.isAbsolute(p) ? p : path.join(repoRoot, p),
+              kind: "file" as const,
+            })),
+            {
+              config: folderConfig,
+              grants: policyConfig.allowedPaths,
+              cwd,
+              action: "commit",
+            },
+          )
+        : undefined;
+    const excludedHit =
+      folderEvaluation.excluded[0] ?? pathEvaluation?.excluded[0];
+    // A staged path below an excluded folder is "outside" (the commit does not
+    // name it, so the floor decides ask/block for the whole commit). Only
+    // exclusion-caused outside targets carry `excludeRoot`; an ordinary
+    // outside repository keeps its existing attribution below.
+    const outsidePathTarget = pathEvaluation?.outside.find(
+      (target) => target.excludeRoot !== undefined,
+    );
+    const pathOutside = outsidePathTarget !== undefined;
+    const folderOutside =
+      folderEvaluation.outside.length > 0 || pathOutside;
+    const folderDecision = decideFolderGate({
+      sensitive: false,
+      excluded: folderEvaluation.excluded.length > 0,
+      outside: folderOutside,
+      outsideAction: folderConfig.outside,
+      uncertain: folderEvaluation.uncertain.length > 0,
+    });
     const now = Date.now();
     const decision = decideCommitGate({
       policy,
@@ -9442,6 +10697,9 @@ export default function workflowExtension(
       hasTodos: todoItems.length > 0,
       auth: commitAuthorization,
       now,
+      folder: folderDecision,
+      sensitive: Boolean(sensitiveHit),
+      excluded: Boolean(excludedHit),
     });
     if (decision === "allow") {
       // Count a granted `git commit` against the authorization, but only when
@@ -9464,6 +10722,36 @@ export default function workflowExtension(
     }
 
     if (decision === "block") {
+      if (excludedHit) {
+        return {
+          block: true,
+          reason:
+            `Folder policy: \`${excludedHit.path}\` is excluded by \`workflow.folderPolicy.excludePaths\` (${excludedHit.pattern}). ` +
+            "Committing an excluded path is refused even when the commit mode is 'allow'. " +
+            "Do not retry. Remove it from the index, or ask the user to revoke the rule with `/folder-policy exclude revoke`.",
+        };
+      }
+      if (sensitiveHit) {
+        return {
+          block: true,
+          reason:
+            `Commit policy: \`${sensitiveHit.path}\` is a sensitive file (${sensitiveHit.pattern}). ` +
+            "Committing it is blocked even when the commit mode is 'allow'. Do not retry; remove it from the index, or ask the user to add a manual sensitiveExemptions entry.",
+        };
+      }
+      if (folderDecision === "block" && policy !== "never") {
+        return {
+          block: true,
+          reason: pathOutside
+            ? `Folder policy is 'block' (workflow.folderPolicy): the staged path \`${outsidePathTarget?.path}\` is inside an excluded folder. ` +
+              "Committing it is refused even when the commit mode is 'allow'. Do not retry; unstage it, or ask the user to revoke the rule with `/folder-policy exclude revoke`."
+            : `Folder policy is 'block' (workflow.folderPolicy): \`git ${hit}\` targets ${repoRoot}, ` +
+              (folderOutside
+                ? `which is outside the permitted folders (${baseRoot}). `
+                : "which could not be verified against the permitted folders. ") +
+              "Do not retry. Ask the user to grant that repository folder or change /folder-policy.",
+        };
+      }
       return {
         block: true,
         reason:
@@ -9484,20 +10772,106 @@ export default function workflowExtension(
       return {
         block: true,
         reason:
-          `Commit policy is 'ask' (workflow.commitPolicy): \`git ${hit}\` needs user approval, ` +
+          `${folderOutside ? "Folder policy is 'ask' (workflow.folderPolicy)" : "Commit policy is 'ask' (workflow.commitPolicy)"}: \`git ${hit}\` needs user approval, ` +
           "but no interactive UI is available. Leave the change uncommitted and let the user decide.",
       };
     }
+    const repoGrant = dialogGrantRootForTarget(
+      { path: repoRoot, kind: "dir" },
+      baseRoot,
+      cwd,
+    );
+    // When the ask is caused by a staged path inside an excluded folder, the
+    // grant must sit inside the exclusion too (a repo-root grant is above it).
+    const rescueGrant =
+      pathOutside && outsidePathTarget
+        ? grantRootForTarget(outsidePathTarget)
+        : undefined;
+    const persistGrant = rescueGrant ?? repoGrant.root;
+    const persistBroad = broadGrantRootReason(persistGrant, cwd);
+    const commitScopeOk = folderConfig.grantScope === "global" || trusted;
+    const persistable = !persistBroad && commitScopeOk;
+    const commitRemedyScope = commitScopeOk ? folderConfig.grantScope : "global";
+    const commitGrantBlockedReason =
+      folderOutside && !persistable
+        ? persistBroad
+          ? `${persistBroad}; add it to workflow.commitPolicy.allowedPaths in the ${commitRemedyScope} settings (/commit-policy status shows the path)`
+          : "this project is not trusted; add it to workflow.commitPolicy.allowedPaths in the global settings (/commit-policy status shows the path)"
+        : undefined;
     let sel: unknown;
     try {
       sel = await ui.select(
-        `Commit policy 'ask': allow \`git ${hit}\`?`,
-        ["Allow once", "Deny"],
+        `${folderOutside ? "Folder" : "Commit"} policy 'ask': allow \`git ${hit}\`?` +
+          `\nRepository: ${repoRoot}` +
+          (rescueGrant ? `\nExcluded staged path: ${outsidePathTarget?.path}` : "") +
+          (folderOutside ? `\nOutside: ${baseRoot}` : "") +
+          (commitGrantBlockedReason
+            ? `\nGrant not available: ${commitGrantBlockedReason}`
+            : ""),
+        folderOutside && persistable
+          ? ["Allow once", "Always allow this repository folder", "Deny"]
+          : ["Allow once", "Deny"],
       );
     } catch {
       sel = undefined;
     }
-    if (String(sel ?? "").startsWith("Allow")) return undefined;
+    const answer = String(sel ?? "");
+    if (answer.startsWith("Always allow")) {
+      // The dialog omits "Always" when persistence is impossible; a stale or
+      // forced answer still must not turn an approval into a denial.
+      const allowOnceWithWarning = (message: string) => {
+        try {
+          (ctx as any).ui?.notify?.(message, "warning");
+        } catch (_e) {
+          void _e;
+        }
+        return undefined;
+      };
+      if (persistBroad) {
+        return allowOnceWithWarning(
+          `Folder policy: ${persistBroad} cannot be granted from a dialog. ` +
+            "This commit was allowed once, but no grant was saved. " +
+            `Add it to workflow.commitPolicy.allowedPaths in the ${commitRemedyScope} settings (/commit-policy status shows the path).`,
+        );
+      }
+      if (folderConfig.grantScope === "project" && !trusted) {
+        return allowOnceWithWarning(
+          "Folder policy: this project is not trusted, so a project-scoped grant would be ignored. " +
+            "This commit was allowed once, but no grant was saved. " +
+            "Add it to workflow.commitPolicy.allowedPaths in the global settings, or trust the project.",
+        );
+      }
+      const written = writeCommitPolicyConfig(
+        folderConfig.grantScope,
+        cwd,
+        getAgentDir(),
+        { allowedPaths: [persistGrant] },
+      );
+      if (!written.ok) {
+        return allowOnceWithWarning(
+          `Folder policy: could not save the commit folder grant (${written.error ?? "unknown error"}). ` +
+            "This commit was allowed once, but no grant was saved.",
+        );
+      }
+      try {
+        (ctx as any).ui?.notify?.(
+          `Commit policy: always allowed ${persistGrant}`,
+          "info",
+        );
+      } catch (_e) {
+        void _e;
+      }
+      return undefined;
+    }
+    if (answer.startsWith("Allow")) return undefined;
+    if (folderOutside) {
+      return {
+        block: true,
+        reason:
+          `Folder policy 'ask': the user declined \`git ${hit}\` for ${repoRoot}, which is outside ${baseRoot}. ` +
+          "Do not retry — leave the changes uncommitted for the user.",
+      };
+    }
     return {
       block: true,
       reason:
@@ -9514,7 +10888,9 @@ export default function workflowExtension(
   function commitDirectiveLine(ctx: any): string {
     try {
       const cwd = ctx?.cwd ?? process.cwd();
-      const mode = readCommitPolicyConfig(cwd, getAgentDir()).config.mode;
+      const mode = readCommitPolicyConfig(cwd, getAgentDir(), {
+        trusted: ctx?.isProjectTrusted?.() === true,
+      }).config.mode;
       switch (mode) {
         case "never":
           return (
@@ -9550,16 +10926,94 @@ export default function workflowExtension(
    * part of the list (its arguments may have been rewritten by another
    * extension's tool_call handler after the assistant message was sealed).
    */
+  function writeFolderTargetsFor(
+    toolName: string,
+    input: any,
+    classification: WriteCallClassification,
+    cwd: string,
+  ): FolderTarget[] {
+    if (classification.paths.length > 0) {
+      return classification.paths.map((p) => ({ path: p, kind: "file" as const }));
+    }
+    if (toolName === "bash" || toolName === "powershell") {
+      const command = String(input?.command ?? "");
+      return analyzeShellPaths(command, cwd, {
+        family: toolName === "powershell" ? "powershell" : "posix",
+      }).writes;
+    }
+    return [];
+  }
+
+  function withFolderGrant(
+    item: WriteGateItem,
+    targets: readonly FolderTarget[],
+    cwd: string,
+    baseRoot: string,
+  ): WriteGateItem {
+    const grantEntries = targets
+      .map((target) => {
+        const exact = normalizeWritePath(target.path, cwd);
+        // The outside-project grouping, the exclusion rescue and the
+        // broad-root fallback live in one shared helper so read, write and
+        // commit cannot disagree about what "Always allow" persists.
+        const { root } = dialogGrantRootForTarget(target, baseRoot, cwd);
+        // A dir/repo target (or a glob's static prefix) is granted as a
+        // folder; so is a containing folder computed for an outside file. A
+        // file directly in the common parent is granted as that file alone.
+        const folder = target.kind !== "file" || root !== exact;
+        return { path: root, folder };
+      })
+      .filter((entry) => entry.path.length > 0);
+    if (grantEntries.length === 0) return item;
+    const unique = [...new Set(grantEntries.map((entry) => entry.path))].sort();
+    const exclusionReason = targets.find((target) => target.reason)?.reason;
+    return {
+      ...item,
+      target: unique.join(", "),
+      why: exclusionReason ?? item.why,
+      grantPaths: [...new Set([...(item.grantPaths ?? []), ...unique])],
+      grantKind: grantEntries.every((entry) => entry.folder)
+        ? "folder"
+        : "file",
+      grantCommand: undefined,
+      key: `path:${unique.join("|")}`,
+    };
+  }
+
   function collectWriteGateItems(
     currentEvent: any,
     currentClassification: WriteCallClassification,
     config: WritePolicyConfig,
+    folderConfig: FolderPolicyConfig,
     cwd: string,
+    baseRoot: string,
   ): WriteGateItem[] {
     const items: WriteGateItem[] = [];
     const seen = new Set<string>();
-    const add = (name: string, classification: WriteCallClassification) => {
-      const item = writeGateItemFromClassification(name, classification, cwd);
+    const add = (
+      name: string,
+      classification: WriteCallClassification,
+      input: any,
+    ) => {
+      const targets = writeFolderTargetsFor(
+        name,
+        input,
+        classification,
+        cwd,
+      );
+      const evaluation = evaluateFolderTargets(targets, {
+        config: folderConfig,
+        grants: config.allowedPaths,
+        cwd,
+        action: "write",
+      });
+      const needsFolder = evaluation.outside.length > 0;
+      if (!needsFolder && isWriteCallAllowed(classification, config, cwd))
+        return;
+      const base = writeGateItemFromClassification(name, classification, cwd);
+      const item = needsFolder
+        ? withFolderGrant(base, targets, cwd, baseRoot)
+        : base;
       if (!item.key || seen.has(item.key)) return;
       seen.add(item.key);
       items.push(item);
@@ -9569,8 +11023,6 @@ export default function workflowExtension(
       if (!name) continue;
       const classification = classifyWriteCall(name, call.args, config);
       if (!classification.mutating) continue;
-      // A granted target is not gated — it never reaches a dialog.
-      if (isWriteCallAllowed(classification, config, cwd)) continue;
       // The plan directory stays writable in every mode.
       if (
         classification.paths.length > 0 &&
@@ -9578,9 +11030,9 @@ export default function workflowExtension(
       ) {
         continue;
       }
-      add(name, classification);
+      add(name, classification, call.args);
     }
-    add(String(currentEvent?.toolName ?? ""), currentClassification);
+    add(String(currentEvent?.toolName ?? ""), currentClassification, currentEvent?.input);
     return items;
   }
 
@@ -9625,13 +11077,16 @@ export default function workflowExtension(
   }
 
   /**
-   * Write permission gate (workflow.writePolicy) — Default mode only.
+   * Write permission gate (workflow.writePolicy + the shared folder floor).
    *
    * The Workflow extension's three modes are Plan → Build → Default. Plan
-   * mode is read-only and Build mode is unrestricted by design, but DEFAULT
-   * mode was ALSO unrestricted: `resolveSessionRole()` returns undefined
-   * there, so the tool_call gate has no branch to take and the agent edits
-   * files without asking. This gate is the missing permission knob.
+   * mode is read-only and Build mode is unrestricted *inside the permitted
+   * folders*, but DEFAULT mode was ALSO unrestricted: `resolveSessionRole()`
+   * returns undefined there, so the tool_call gate has no branch to take and
+   * the agent edits files without asking. This gate is the missing permission
+   * knob. The write MODE is Default-only; the folder floor applies in every
+   * mode (Build included) and asks only for proven outside targets, sensitive
+   * files, or an explicit target path that cannot be resolved.
    *
    * It is deliberately INDEPENDENT of the role gate and of the commit
    * policy: those govern *what* a role may do, this governs *whether the
@@ -9651,24 +11106,24 @@ export default function workflowExtension(
     cwd: string,
   ): Promise<{ block: true; reason: string } | undefined> {
     try {
-      // Scope: the top-level Default-mode session only.
-      //  - Plan mode has its own stricter rules (writes only to .pi/plans/).
-      //  - Build mode is the deliberate "go ahead" execution escape hatch.
-      //  - A spawned child carries PI_WORKFLOW_ROLE and is already read-only
-      //    through the role gate (and has no UI to answer a prompt).
-      if (workflowMode !== null) return undefined;
-      if (
-        resolveSessionRole({
-          envRole: process.env[WORKFLOW_ROLE_ENV],
-          workflowMode,
-        }) !== undefined
-      ) {
-        return undefined;
-      }
+      // Scope: the write MODE is a Default-mode knob; the shared FOLDER floor
+      // applies to every mode. Plan mode already restricts writes to
+      // .pi/plans/ (inside the folder root); Build mode is the deliberate
+      // execution path but must still respect the user's folder floor.
+      const gateRole = resolveSessionRole({
+        envRole: process.env[WORKFLOW_ROLE_ENV],
+        workflowMode,
+      });
+      if (gateRole && gateRole !== "builder") return undefined;
+      const defaultMode = workflowMode === null && gateRole === undefined;
 
-      const resolved = readWritePolicyConfig(cwd, getAgentDir());
+      const trusted = ctx?.isProjectTrusted?.() === true;
+      const resolved = readWritePolicyConfig(cwd, getAgentDir(), { trusted });
       const config = resolved.config;
-      if (config.mode === "allow") return undefined;
+      const effectiveWriteMode = defaultMode ? config.mode : "allow";
+      const folderConfig = readFolderPolicyConfig(cwd, getAgentDir(), {
+        trusted,
+      }).config;
 
       const classification = classifyWriteCall(
         event.toolName,
@@ -9686,23 +11141,123 @@ export default function workflowExtension(
         return undefined;
       }
 
+      const folderTargets = writeFolderTargetsFor(
+        String(event.toolName ?? ""),
+        event.input,
+        classification,
+        cwd,
+      );
+      // Workflow settings are user-owned: an agent that could rewrite them
+      // could delete its own exclusions. Applies in every mode, including
+      // Build, and is never softened by a grant. Slash commands write through
+      // fs and are unaffected.
+      const settingsTarget = folderTargets.find((folderTarget) =>
+        isWorkflowSettingsPath(folderTarget.path, cwd, getAgentDir()),
+      );
+      if (settingsTarget) {
+        return {
+          block: true,
+          reason:
+            `Write policy: \`${settingsTarget.path}\` is the workflow settings file, which is user-owned. ` +
+            "The agent may not rewrite permissions or the exclude list, even with a write grant or in Build mode. " +
+            "Do not retry. Ask the user to run the matching slash command (/folder-policy, /read-policy, /write-policy, /commit-policy) or edit the file themselves.",
+        };
+      }
+      for (const folderTarget of folderTargets) {
+        const hit = matchSensitivePath(folderTarget.path, folderConfig, cwd);
+        if (hit.sensitive) {
+          return {
+            block: true,
+            reason:
+              `Write policy: \`${folderTarget.path}\` is a sensitive file` +
+              (hit.pattern ? ` (${hit.pattern})` : "") +
+              ". This cannot be overridden by a write grant or folder. " +
+              "Do not retry; ask the user to edit the sensitive list in settings.json if this is intentional.",
+          };
+        }
+      }
+
+      const folderEvaluation = evaluateFolderTargets(folderTargets, {
+        config: folderConfig,
+        grants: config.allowedPaths,
+        cwd,
+        action: "write",
+      });
+      const folderDecision = decideFolderGate({
+        sensitive: false,
+        excluded: folderEvaluation.excluded.length > 0,
+        outside: folderEvaluation.outside.length > 0,
+        outsideAction: folderConfig.outside,
+        // Only a concrete target path that cannot be canonicalised is folder
+        // uncertainty. "Mutating but no discovered write target" is NOT: the
+        // shell analyzer cannot see inside `npm run build`, `node script`,
+        // `npx`, `sed`/`awk` programs or `powershell`, and treating that as
+        // "possibly outside" made Build and writePolicy:allow prompt for
+        // ordinary in-repo toolchain commands. The capability policy owns
+        // that case — writePolicy:ask still asks for every mutating call —
+        // and undiscoverable shell writes are the documented residual
+        // (README "Not a sandbox").
+        uncertain: folderEvaluation.uncertain.length > 0,
+      });
       const allowed = isWriteCallAllowed(classification, config, cwd);
       const decision = decideWriteGate({
-        mode: config.mode,
+        mode: effectiveWriteMode,
         mutating: true,
         allowed,
+        folder: folderDecision,
       });
       if (decision === "allow") return undefined;
 
+      // Which policy actually produced this ask. A folder-sourced prompt must
+      // not be labelled "Write policy" — that misattribution is what made the
+      // in-repo toolchain regression look like a write-policy bug.
+      const baseRoot = baseFolderRoots(folderConfig, cwd)[0] ?? cwd;
+      const folderAsk = folderDecision === "ask";
+      const gateSource: WriteGateSource = folderAsk
+        ? effectiveWriteMode === "ask"
+          ? "mixed"
+          : "folder"
+        : "write";
+      const gatePolicyLabel =
+        gateSource === "folder"
+          ? "Folder policy"
+          : gateSource === "mixed"
+            ? "Permission policy"
+            : "Write policy";
+      const gateOutside = gateSource === "folder" ? baseRoot : undefined;
+
       const target =
-        classification.paths.length > 0
-          ? classification.paths.join(", ")
-          : (classification.key ?? String(event.toolName));
+        folderTargets.length > 0
+          ? folderTargets.map((item) => item.path).join(", ")
+          : classification.paths.length > 0
+            ? classification.paths.join(", ")
+            : (classification.key ?? String(event.toolName));
       const why = classification.reason
         ? ` (${classification.reason})`
         : "";
 
       if (decision === "block") {
+        // An excluded folder (or the excluded root itself) is the most
+        // specific reason: name the rule and the revoke command.
+        if (folderEvaluation.excluded.length > 0) {
+          const hit = folderEvaluation.excluded[0];
+          return {
+            block: true,
+            reason:
+              `Folder policy: \`${hit.path}\` is excluded by \`workflow.folderPolicy.excludePaths\` (${hit.pattern}). ` +
+              "Writing to an excluded folder is refused in every mode, including Build, and cannot be overridden by a write grant. " +
+              `Do not retry. A specific sub-folder can still be requested; ask the user to revoke the rule with \`/folder-policy exclude revoke\`. Target: ${target}`,
+          };
+        }
+        if (folderDecision === "block" && effectiveWriteMode !== "never") {
+          return {
+            block: true,
+            reason:
+              `Folder policy is 'block' (workflow.folderPolicy): the target is outside the permitted folders. ` +
+              "Do not retry. Ask the user to open the project at that folder, grant it, or change /folder-policy. " +
+              `Target: ${target}`,
+          };
+        }
         return {
           block: true,
           reason:
@@ -9728,11 +11283,18 @@ export default function workflowExtension(
       // the answer applies to all of them.
       const ui = ctx?.ui;
       if (!ui || !ctx.hasUI) {
+        const policyName =
+          gateSource === "folder"
+            ? "Folder policy is 'ask' (workflow.folderPolicy)"
+            : gateSource === "mixed"
+              ? "Folder and write policies are 'ask' (workflow.folderPolicy + workflow.writePolicy)"
+              : "Write policy is 'ask' (workflow.writePolicy)";
         return {
           block: true,
           reason:
-            `Write policy is 'ask' (workflow.writePolicy): writing needs user approval${why}, but no interactive UI is available. ` +
+            `${policyName}: writing needs user approval${why}, but no interactive UI is available. ` +
             "Do not retry. Report what you would change and let the user apply it, or tell them to switch to Build mode (/build). " +
+            (gateSource === "folder" ? `Outside: ${baseRoot}. ` : "") +
             `Target: ${target}`,
         };
       }
@@ -9749,12 +11311,23 @@ export default function workflowExtension(
         writeGateBatchCalls = [];
         writeGateBatchCallIds = new Set();
       }
-      const items = collectWriteGateItems(event, classification, config, cwd);
-      const currentItem = writeGateItemFromClassification(
+      const items = collectWriteGateItems(
+        event,
+        classification,
+        config,
+        folderConfig,
+        cwd,
+        baseRoot,
+      );
+      const currentBase = writeGateItemFromClassification(
         String(event.toolName ?? ""),
         classification,
         cwd,
       );
+      const currentItem =
+        folderEvaluation.outside.length > 0
+          ? withFolderGrant(currentBase, folderTargets, cwd, baseRoot)
+          : currentBase;
 
       // (a) The user denied this target earlier in THIS RUN → deny again,
       // silently. The model gets the same sentence; the user is not asked a
@@ -9768,6 +11341,8 @@ export default function workflowExtension(
             target,
             why: classification.reason,
             instruction: remembered.instruction,
+            source: gateSource,
+            outside: gateOutside,
           }),
         };
       }
@@ -9785,15 +11360,37 @@ export default function workflowExtension(
             target,
             why: classification.reason,
             instruction: answer.instruction,
+            source: gateSource,
+            outside: gateOutside,
           }),
         };
       }
 
       // (c) The first gated call of the turn → ask ONCE.
-      const options = writeGateOptions(writeGateItemsKind(items));
+      const grantPaths = [
+        ...new Set(items.flatMap((item) => item.grantPaths ?? [])),
+      ];
+      const broad = grantPaths.find((root) => isBroadGrantRoot(root, cwd));
+      const broadReason = broad ? broadGrantRootReason(broad, cwd) : undefined;
+      const scopeOk = folderConfig.grantScope === "global" || trusted;
+      const persistable = !broad && scopeOk;
+      const remedyScope = scopeOk ? folderConfig.grantScope : "global";
+      const writeGrantBlockedReason = !persistable
+        ? broad
+          ? `${broadReason ?? "a protected root"}; add it to workflow.writePolicy.allowedPaths in the ${remedyScope} settings (/write-policy status shows the path)`
+          : "this project is not trusted; add it to workflow.writePolicy.allowedPaths in the global settings (/write-policy status shows the path)"
+        : undefined;
+      const options = writeGateOptions(writeGateItemsKind(items), {
+        allowAlways: persistable,
+      });
       let sel: unknown;
       try {
-        sel = await ui.select(writeGateTitle(items), options);
+        sel = await ui.select(
+          writeGateTitle(items, gateSource, baseRoot, {
+            grantBlockedReason: writeGrantBlockedReason,
+          }),
+          options,
+        );
       } catch (_e) {
         void _e;
         sel = undefined;
@@ -9815,14 +11412,40 @@ export default function workflowExtension(
           for (const p of item.grantPaths ?? []) allowedPaths.push(p);
           if (item.grantCommand) allowedCommands.push(item.grantCommand);
         }
-        const written = writeWritePolicyConfig("global", cwd, getAgentDir(), {
+        // The dialog omits "Always" when persistence is impossible, but a
+        // stale/forced answer must never turn an approval into a denial.
+        const allowOnceWithWarning = (message: string) => {
+          try {
+            (ctx as any).ui?.notify?.(message, "warning");
+          } catch (_e) {
+            void _e;
+          }
+          writeGateTurnAnswer = { choice: "allow-once", instruction: "" };
+          return undefined;
+        };
+        if (broad) {
+          return allowOnceWithWarning(
+            `${gatePolicyLabel}: ${broadReason ?? "a protected root"} cannot be granted from a dialog. ` +
+              "This write was allowed once, but no grant was saved. " +
+              `Add it to workflow.writePolicy.allowedPaths in the ${remedyScope} settings (/write-policy status shows the path).`,
+          );
+        }
+        const grantScope = folderConfig.grantScope;
+        if (grantScope === "project" && !trusted) {
+          return allowOnceWithWarning(
+            `${gatePolicyLabel}: this project is not trusted, so a project-scoped grant would be ignored. ` +
+              "This write was allowed once, but no grant was saved. " +
+              "Add it to workflow.writePolicy.allowedPaths in the global settings, or trust the project.",
+          );
+        }
+        const written = writeWritePolicyConfig(grantScope, cwd, getAgentDir(), {
           allowedPaths,
           allowedCommands,
         });
         if (written.ok) {
           try {
             (ctx as any).ui?.notify?.(
-              `Write policy: always allowed ${writeGateTargetsLabel(items)}`,
+              `${gatePolicyLabel}: always allowed ${writeGateTargetsLabel(items)}`,
               "info",
             );
           } catch (_e) {
@@ -9831,14 +11454,11 @@ export default function workflowExtension(
           writeGateTurnAnswer = { choice, instruction: "" };
           return undefined;
         }
-        // The grant could not be persisted — do not silently allow a write
-        // the user asked to remember. Fall through to the denial below.
-        return {
-          block: true,
-          reason:
-            `Write policy 'ask': could not save the permission grant (${written.error ?? "unknown error"}), so the write was not allowed. ` +
-            `Target: ${target}`,
-        };
+        return allowOnceWithWarning(
+          `${gatePolicyLabel}: could not save the permission grant (${written.error ?? "unknown error"}). ` +
+            "This write was allowed once, but no grant was saved. " +
+            `Add it to workflow.writePolicy.allowedPaths in the ${remedyScope} settings (/write-policy status shows the path).`,
+        );
       }
 
       // ── Denial ──
@@ -9886,6 +11506,8 @@ export default function workflowExtension(
         target: items.length > 1 ? writeGateTargetsLabel(items) : target,
         why: classification.reason,
         instruction,
+        source: gateSource,
+        outside: gateOutside,
       });
 
       if (instruction) {
@@ -9933,6 +11555,403 @@ export default function workflowExtension(
     }
   }
 
+  function collectReadGateItems(
+    currentEvent: any,
+    currentClassification: ReturnType<typeof classifyReadCall>,
+    config: ReadPolicyConfig,
+    folderConfig: FolderPolicyConfig,
+    cwd: string,
+    lockedRoots?: readonly string[],
+    baseRoot?: string,
+  ): ReadGateItem[] {
+    const items: ReadGateItem[] = [];
+    const seen = new Set<string>();
+    const add = (
+      name: string,
+      classification: ReturnType<typeof classifyReadCall>,
+    ) => {
+      if (classification.exempt) return;
+      const targets = classification.targets;
+      const evaluation = evaluateFolderTargets(targets, {
+        config: folderConfig,
+        grants: [...config.allowedPaths, ...readGateTurnGrantedRoots],
+        cwd,
+        lockedRoots,
+        action: "read",
+      });
+      for (const target of evaluation.outside) {
+        const item = readGateItemFromTarget(
+          name,
+          target,
+          target.reason ?? "outside the folder",
+          cwd,
+          baseRoot,
+        );
+        if (seen.has(item.key)) continue;
+        seen.add(item.key);
+        items.push(item);
+      }
+      if (evaluation.outside.length === 0) {
+        for (const reason of classification.uncertain) {
+          const key = `cmd:${reason}`;
+          if (seen.has(key)) continue;
+          seen.add(key);
+          items.push({
+            tool: name,
+            target: { path: reason, kind: "file" },
+            grantRoot: "",
+            why: reason,
+            key,
+          });
+        }
+      }
+    };
+    for (const call of readGateBatchCalls) {
+      const name = String(call.name ?? "");
+      if (!name) continue;
+      add(name, classifyReadCall(name, call.args, cwd, config));
+    }
+    add(
+      String(currentEvent?.toolName ?? ""),
+      currentClassification,
+    );
+    return items;
+  }
+
+  function deliverReadInstruction(instruction: string, target: string): void {
+    if (!instruction || readGateTurnSteered) return;
+    const rt = reviewRuntime;
+    const wouldRouteToReviewer = shouldRouteInputToReviewer({
+      reviewEnabled: reviewEnabled(),
+      reviewActive: rt?.isRoundActive() === true,
+      hasReviewerSession: rt?.isAlive() === true,
+      manualSessionActive: reviewSessionLive(),
+    });
+    if (!wouldRouteToReviewer) {
+      try {
+        (pi as any).sendUserMessage?.(
+          buildReadGuidanceMessage({ target, instruction }),
+          { deliverAs: "steer" },
+        );
+      } catch (_e) {
+        void _e;
+      }
+    }
+    readGateTurnSteered = true;
+  }
+
+  /**
+   * Read permission gate. Applies in every workflow mode and to every role,
+   * including Build/explorer/reviewer-adjacent calls. The shared folder floor
+   * decides scope; the sensitive list always wins; the dialog is batched once
+   * per assistant turn.
+   */
+  async function readPolicyGate(
+    event: any,
+    ctx: any,
+    cwd: string,
+  ): Promise<{ block: true; reason: string } | undefined> {
+    try {
+      const trusted = ctx?.isProjectTrusted?.() === true;
+      const readResolved = readReadPolicyConfig(cwd, getAgentDir(), {
+        trusted,
+      });
+      const folderResolved = readFolderPolicyConfig(cwd, getAgentDir(), {
+        trusted,
+      });
+      const config = readResolved.config;
+      const folderConfig = folderResolved.config;
+      const classification = classifyReadCall(
+        String(event.toolName ?? ""),
+        event.input,
+        cwd,
+        config,
+      );
+      if (classification.exempt) return undefined;
+      if (
+        classification.targets.length === 0 &&
+        classification.uncertain.length === 0
+      )
+        return undefined;
+
+      const grants = [...config.allowedPaths, ...readGateTurnGrantedRoots];
+      const evaluation = evaluateFolderTargets(classification.targets, {
+        config: folderConfig,
+        grants,
+        cwd,
+        lockedRoots: folderResolved.locked?.roots,
+        action: "read",
+      });
+      if (evaluation.sensitive.length > 0) {
+        const hit = evaluation.sensitive[0];
+        return {
+          block: true,
+          reason: buildReadDenyReason({
+            kind: "sensitive",
+            target: hit.path,
+            pattern: hit.pattern,
+          }),
+        };
+      }
+
+      // An excluded folder is refused outright: no dialog, no grant.
+      if (evaluation.excluded.length > 0) {
+        const hit = evaluation.excluded[0];
+        return {
+          block: true,
+          reason: buildReadDenyReason({
+            kind: "excluded",
+            target: hit.path,
+            pattern: hit.pattern,
+          }),
+        };
+      }
+
+      const outside = evaluation.outside;
+      const uncertain = classification.uncertain;
+      let decision = decideReadGate({
+        sensitive: false,
+        excluded: evaluation.excluded.length > 0,
+        outside: outside.length > 0,
+        outsideAction: folderConfig.outside,
+        granted: false,
+        uncertain:
+          uncertain.length > 0 || evaluation.uncertain.length > 0,
+        shell: config.shell,
+      });
+
+      if (uncertain.length > 0 && config.shell === "strict") {
+        const allowed = uncertain.every((reason) =>
+          readGateTurnUncertainAllowed.has(reason),
+        );
+        if (allowed) decision = "allow";
+      }
+      if (decision === "allow") return undefined;
+      if (decision === "block") {
+        return {
+          block: true,
+          reason: buildReadDenyReason({
+            kind: "blocked",
+            target:
+              outside.length > 0
+                ? outside.map((target) => target.path).join(", ")
+                : uncertain[0] ?? String(event.toolName),
+            outsideAction: folderConfig.outside,
+          }),
+        };
+      }
+
+      const ui = ctx?.ui;
+      if (!ui || !ctx.hasUI) {
+        return {
+          block: true,
+          reason:
+            "Read policy is 'ask' (workflow.folderPolicy): this read needs approval, but no interactive UI is available. " +
+            "Do not retry; report what you need and let the user approve it.",
+        };
+      }
+
+      const callId = String(event.toolCallId ?? "");
+      if (!readGateBatchCallIds.has(callId)) {
+        readGateTurnAnswer = null;
+        readGateTurnSteered = false;
+        readGateBatchCalls = [];
+        readGateBatchCallIds = new Set();
+        readGateTurnGrantedRoots.clear();
+        readGateTurnUncertainAllowed.clear();
+      }
+      const baseRoot = baseFolderRoots(folderConfig, cwd)[0] ?? cwd;
+      const items = collectReadGateItems(
+        event,
+        classification,
+        config,
+        folderConfig,
+        cwd,
+        folderResolved.locked?.roots,
+        baseRoot,
+      );
+      const currentItems = items.filter((item) => {
+        if (outside.length > 0)
+          return outside.some((target) => item.key === readGateTargetKey(target));
+        return uncertain.some((reason) => item.key === `cmd:${reason}`);
+      });
+      const currentItem = currentItems[0];
+      const remembered = currentItem
+        ? readGateRunDenials.get(currentItem.key)
+        : undefined;
+      if (remembered) {
+        return {
+          block: true,
+          reason: buildReadDenyReason({
+            kind: "outside",
+            target: readGateTargetsLabel(currentItems) || "the requested read",
+            instruction: remembered.instruction,
+          }),
+        };
+      }
+      if (readGateTurnAnswer) {
+        if (readGateTurnAnswer.choice === "deny") {
+          return {
+            block: true,
+            reason: buildReadDenyReason({
+              kind: "outside",
+              target: readGateTargetsLabel(currentItems) || "the requested read",
+              instruction: readGateTurnAnswer.instruction,
+            }),
+          };
+        }
+        return undefined;
+      }
+
+      const roots = [
+        ...new Set(items.map((item) => item.grantRoot).filter(Boolean)),
+      ];
+      const broad = roots.find((root) => isBroadGrantRoot(root, cwd));
+      const broadReason = broad ? broadGrantRootReason(broad, cwd) : undefined;
+      const scopeOk = folderConfig.grantScope === "global" || trusted;
+      const persistable = roots.length > 0 && !broad && scopeOk;
+      const exactTarget = items[0]?.target.path ?? roots[0] ?? "";
+      const remedyScope = scopeOk ? folderConfig.grantScope : "global";
+      const grantBlockedReason =
+        !persistable && roots.length > 0
+          ? broad
+            ? `${broadReason ?? "a protected root"}; persist the exact target with /read-policy allow ${exactTarget} ${remedyScope}`
+            : `this project is not trusted; persist with /read-policy allow ${exactTarget} global`
+          : undefined;
+      const options = readGateOptions(readGateItemsKind(items), {
+        allowAlways: persistable || roots.length === 0,
+      });
+      let sel: unknown;
+      try {
+        sel = await ui.select(
+          readGateTitle(items, baseRoot, { grantBlockedReason }),
+          options,
+        );
+      } catch {
+        sel = undefined;
+      }
+      const choice = parseReadGateChoice(sel);
+      if (choice === "allow-once") {
+        for (const item of items) if (item.grantRoot) readGateTurnGrantedRoots.add(item.grantRoot);
+        for (const reason of uncertain) readGateTurnUncertainAllowed.add(reason);
+        readGateTurnAnswer = { choice: "allow-once", instruction: "" };
+        return undefined;
+      }
+      if (choice === "always") {
+        if (roots.length === 0) {
+          for (const reason of uncertain)
+            readGateTurnUncertainAllowed.add(reason);
+          readGateTurnAnswer = { choice: "always", instruction: "" };
+          return undefined;
+        }
+        // The dialog omits "Always" when persistence is impossible, but a
+        // stale/forced answer must never turn an approval into a denial.
+        const allowOnceWithWarning = (message: string) => {
+          try {
+            (ctx as any).ui?.notify?.(message, "warning");
+          } catch (_e) {
+            void _e;
+          }
+          for (const item of items)
+            if (item.grantRoot) readGateTurnGrantedRoots.add(item.grantRoot);
+          for (const reason of uncertain)
+            readGateTurnUncertainAllowed.add(reason);
+          readGateTurnAnswer = { choice: "allow-once", instruction: "" };
+          return undefined;
+        };
+        if (broad) {
+          return allowOnceWithWarning(
+            `Read policy: ${broadReason ?? "a protected root"} cannot be granted from a dialog. ` +
+              "This read was allowed once, but no grant was saved. " +
+              `Persist it deliberately with /read-policy allow ${exactTarget} ${remedyScope}.`,
+          );
+        }
+        if (folderConfig.grantScope === "project" && !trusted) {
+          return allowOnceWithWarning(
+            "Read policy: this project is not trusted, so a project-scoped grant would be ignored. " +
+              "This read was allowed once, but no grant was saved. " +
+              `Persist it with /read-policy allow ${exactTarget} global, or trust the project.`,
+          );
+        }
+        const written = writeReadPolicyConfig(
+          folderConfig.grantScope,
+          cwd,
+          getAgentDir(),
+          { allowedPaths: roots },
+        );
+        if (!written.ok) {
+          return allowOnceWithWarning(
+            `Read policy: could not save the permission grant (${written.error ?? "unknown error"}). ` +
+              "This read was allowed once, but no grant was saved. " +
+              `Persist it with /read-policy allow ${exactTarget} ${remedyScope}.`,
+          );
+        }
+        try {
+          (ctx as any).ui?.notify?.(
+            `Read policy: always allowed ${roots.join(", ")}`,
+            "info",
+          );
+        } catch (_e) {
+          void _e;
+        }
+        for (const root of roots) readGateTurnGrantedRoots.add(root);
+        for (const reason of uncertain) readGateTurnUncertainAllowed.add(reason);
+        readGateTurnAnswer = { choice: "always", instruction: "" };
+        return undefined;
+      }
+
+      let instruction = "";
+      if (choice === "deny-with-instructions") {
+        const inputFn = (ui as any).input;
+        if (typeof inputFn === "function") {
+          try {
+            instruction = sanitizeReadInstruction(
+              await inputFn.call(
+                ui,
+                READ_INSTRUCTION_PROMPT_TITLE,
+                READ_INSTRUCTION_PROMPT_PLACEHOLDER,
+              ),
+            );
+          } catch {
+            instruction = "";
+          }
+        }
+      }
+      readGateTurnAnswer = { choice: "deny", instruction };
+      for (const item of items) readGateRunDenials.set(item.key, { instruction });
+      if (instruction)
+        deliverReadInstruction(
+          instruction,
+          readGateTargetsLabel(items) || "the requested read",
+        );
+      try {
+        pi.appendEntry("workflow-read-denial", {
+          tool: String(event.toolName ?? ""),
+          target: readGateTargetsLabel(items),
+          instruction,
+          at: Date.now(),
+        });
+      } catch (_e) {
+        void _e;
+      }
+      return {
+        block: true,
+        reason: buildReadDenyReason({
+          kind: "outside",
+          target: readGateTargetsLabel(items) || "the requested read",
+          instruction,
+        }),
+      };
+    } catch (error: unknown) {
+      return {
+        block: true,
+        reason:
+          `Read policy could not be evaluated (${error instanceof Error ? error.message : String(error)}), so the read was blocked. ` +
+          "Do not retry; ask the user to fix /read-policy or /folder-policy.",
+      };
+    }
+  }
+
   // Block edits/writes + bash gating
   pi.on("tool_call", async (event, ctx) => {
     const cwd = (ctx as ExtensionContext).cwd;
@@ -10066,15 +12085,19 @@ export default function workflowExtension(
         reason: `${gateRole} role: ${event.toolName} blocked — this role is read-only.`,
       } as any;
     }
-    // ── Write permission gate (workflow.writePolicy) ── Independent of the
-    // role gate and of the commit policy: it governs whether the USER
-    // permits a write at all. It only applies in Default mode — Plan has its
-    // own stricter rules and Build is the approved-execution escape hatch —
-    // and it runs last so it only sees calls nothing else claimed.
-    if (workflowMode === null) {
+    // ── Write permission gate (workflow.writePolicy + shared folder floor) ──
+    // The write MODE is a Default-mode knob; the folder floor applies in every
+    // mode. It runs after the role/commit rules and before the build-todo
+    // guard so a folder/sensitive refusal wins.
+    {
       const writeBlock = await writePolicyGate(event, ctx, cwd);
       if (writeBlock) return writeBlock as any;
     }
+    // ── Read permission gate (workflow.readPolicy + shared folder floor) ──
+    {
+      const readBlock = await readPolicyGate(event, ctx, cwd);
+      if (readBlock) return readBlock as any;
+    }
     // In build mode, ensure todos exist before first real edit
     if (
       (event.toolName === "edit" || event.toolName === "write") &&
@@ -10136,7 +12159,91 @@ export default function workflowExtension(
       seedCommittedStepRefs();
       const completed = uncommittedDoneSteps();
       const dirty = await isDirty(pi as any, cwd);
-      const mode = readCommitPolicyConfig(cwd, getAgentDir()).config.mode;
+      const trusted = ctx?.isProjectTrusted?.() === true;
+      const commitConfig = readCommitPolicyConfig(cwd, getAgentDir(), {
+        trusted,
+      }).config;
+      const folderConfig = readFolderPolicyConfig(cwd, getAgentDir(), {
+        trusted,
+      }).config;
+      const repoRoot = detectRepoRoot(cwd) ?? cwd;
+      const folder = evaluateFolderTargets(
+        [{ path: repoRoot, kind: "dir" }],
+        {
+          config: folderConfig,
+          grants: commitConfig.allowedPaths,
+          cwd,
+          action: "commit",
+        },
+      );
+      if (folder.excluded.length > 0) {
+        const hit = folder.excluded[0];
+        ctx?.ui?.notify?.(
+          `Per-step commit skipped: ${repoRoot} is excluded by workflow.folderPolicy.excludePaths (${hit.pattern}). Revoke it with /folder-policy exclude revoke or commit manually.`,
+          "warning",
+        );
+        return;
+      }
+      if (folder.outside.length > 0) {
+        ctx?.ui?.notify?.(
+          `Per-step commit skipped: ${repoRoot} is outside the permitted folders (use /folder-policy or grant it first).`,
+          "warning",
+        );
+        return;
+      }
+      const status = runGitZ(repoRoot, [
+        "status",
+        "--porcelain=v1",
+        "-z",
+        "--untracked-files=all",
+      ]);
+      if (!status.ok) {
+        ctx?.ui?.notify?.(
+          `Per-step commit skipped: sensitive-file check could not run (${status.error ?? "git status failed"}).`,
+          "warning",
+        );
+        return;
+      }
+      const sensitive = status.paths
+        .map((p) => matchSensitivePath(p, folderConfig, repoRoot))
+        .find((hit) => hit.sensitive);
+      if (sensitive) {
+        ctx?.ui?.notify?.(
+          `Per-step commit skipped: ${sensitive.path} is sensitive. Remove it from the working tree/index or add a manual sensitiveExemptions entry.`,
+          "warning",
+        );
+        return;
+      }
+      const statusFolder = evaluateFolderTargets(
+        status.paths.map((p) => ({
+          path: path.join(repoRoot, p),
+          kind: "file" as const,
+        })),
+        {
+          config: folderConfig,
+          grants: commitConfig.allowedPaths,
+          cwd,
+          action: "commit",
+        },
+      );
+      if (
+        statusFolder.excluded.length > 0
+      ) {
+        const hit = statusFolder.excluded[0];
+        ctx?.ui?.notify?.(
+          `Per-step commit skipped: ${hit.path} is excluded by workflow.folderPolicy.excludePaths (${hit.pattern}). Revoke it with /folder-policy exclude revoke or commit manually.`,
+          "warning",
+        );
+        return;
+      }
+      if (statusFolder.outside.length > 0 || statusFolder.uncertain.length > 0) {
+        ctx?.ui?.notify?.(
+          `Per-step commit skipped: staged paths leave the permitted folders or could not be verified. Review the working tree and commit manually.`,
+          "warning",
+        );
+        return;
+      }
+      const mode = commitConfig.mode;
       const decision = stepCommitDecision({
         mode,
         hasTodos: todoItems.length > 0,
@@ -10193,6 +12300,53 @@ export default function workflowExtension(
     }
   }
 
+  // Output redaction is defence in depth for channels the tool gate cannot
+  // fully see (grep --hidden, git diff/show, truncated bash output).
+  pi.on("tool_result", async (event, ctx) => {
+    try {
+      const cwd = (ctx as any)?.cwd ?? process.cwd();
+      const trusted = (ctx as any)?.isProjectTrusted?.() === true;
+      const folderConfig = readFolderPolicyConfig(cwd, getAgentDir(), {
+        trusted,
+      }).config;
+      // Roots that can re-open an excluded path: the session floor plus the
+      // read grants (an approved sub-folder must stay readable).
+      const readGrants = readReadPolicyConfig(cwd, getAgentDir(), {
+        trusted,
+      }).config.allowedPaths;
+      return redactToolResult(event as any, folderConfig, cwd, {
+        base: baseFolderRoots(folderConfig, cwd),
+        grants: [...readGrants, ...readGateTurnGrantedRoots],
+      }) as any;
+    } catch (error: unknown) {
+      const tool = String((event as any)?.toolName ?? "");
+      if (
+        [
+          "read",
+          "read_symbol",
+          "read_enclosing",
+          "module_report",
+          "grep",
+          "find",
+          "ls",
+          "bash",
+          "powershell",
+        ].includes(tool)
+      ) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `[read policy redaction failed — output withheld: ${error instanceof Error ? error.message : String(error)}]`,
+            },
+          ],
+          structuredContent: undefined,
+        } as any;
+      }
+      return undefined;
+    }
+  });
+
   pi.on("tool_result", async (_event, ctx) => {
     try {
       const leaf =
@@ -10245,6 +12399,10 @@ export default function workflowExtension(
       writeGateBatchCallIds = callIds;
       writeGateTurnAnswer = null;
       writeGateTurnSteered = false;
+      readGateBatchCalls = calls;
+      readGateBatchCallIds = callIds;
+      readGateTurnAnswer = null;
+      readGateTurnSteered = false;
     } catch (_e) {
       void _e;
     }
@@ -10258,6 +12416,12 @@ export default function workflowExtension(
     writeGateTurnSteered = false;
     writeGateBatchCalls = [];
     writeGateBatchCallIds = new Set();
+    readGateTurnAnswer = null;
+    readGateTurnSteered = false;
+    readGateBatchCalls = [];
+    readGateBatchCallIds = new Set();
+    readGateTurnGrantedRoots.clear();
+    readGateTurnUncertainAllowed.clear();
     // Seed the per-step commit ledger once per session: steps already done
     // (restored sessions, re-executed plans) never trigger a spurious commit.
     try {
@@ -10308,6 +12472,13 @@ export default function workflowExtension(
     writeGateTurnSteered = false;
     writeGateBatchCalls = [];
     writeGateBatchCallIds = new Set();
+    readGateRunDenials.clear();
+    readGateTurnAnswer = null;
+    readGateTurnSteered = false;
+    readGateBatchCalls = [];
+    readGateBatchCallIds = new Set();
+    readGateTurnGrantedRoots.clear();
+    readGateTurnUncertainAllowed.clear();
     // keep persisted CustomEntry for reload, clear in-memory tombstone only on explicit prune; for now no clear to survive fork
   });
 
@@ -10356,12 +12527,47 @@ export default function workflowExtension(
   pi.on("before_agent_start", async (event, ctx) => {
     currentSessionCtx = ctx as any;
     ensurePlannotatorListeners();
+    // Safety valve for a prompt that bypassed `input` (host queue, another
+    // extension): never let a Review turn run concurrently with a plan/build
+    // turn. Stop the reviewer first, then let the queued prompt proceed.
+    if (reviewTurnOwns(reviewTurn) && reviewTurn !== "transition") {
+      // Invalidate the parked handoff BEFORE settling its gate: otherwise the
+      // runHandoff continuation can observe the old cycle token and render the
+      // abandoned plan alongside the new prompt.
+      reviewCycleId += 1;
+      try {
+        await suspendReview();
+      } catch (_e) {
+        void _e;
+      }
+      endReviewTurn();
+      notifyReview(
+        "Review stopped — a prompt was already queued; the plan was not reviewed.",
+        "info",
+      );
+    }
     // Fresh user prompt → reset the passive reminder cadence. Continuation runs
     // (triggerTurn/steer/followUp) do not fire this event, so state survives them.
     turnsSinceLastTodoWrite = 0;
     turnsSinceLastReminder = 0;
     mutatedSinceLastTodoWrite = false;
     footerInjectedThisTurn = false;
+    // A real user prompt means the user has moved on from a finished plan:
+    // hide the one-line todo panel. `custom` runs (triggerTurn) must not do
+    // this — they can be self-initiated while the user is still reading.
+    if (
+      event.messageType === "user" &&
+      isTodoListSettled(todoItems) &&
+      !todoPanelPromptAfterSettle
+    ) {
+      todoPanelPromptAfterSettle = true;
+      updateStatus(ctx);
+      try {
+        persistState();
+      } catch (_e) {
+        void _e;
+      }
+    }
     // A fresh user prompt starts a new handoff/provenance run. It also
     // supersedes any pending browser/inline decision immediately: the user
     // moved on, so a stale tab must not approve the previous plan. Follow-up
@@ -10386,10 +12592,14 @@ export default function workflowExtension(
     }
     // Every fresh prompt is a new review cycle: reset the round budget, cancel
     // an abandoned pause/gate, and tag the cycle so an old handoff cannot
-    // render after this prompt.
+    // render after this prompt. A feedback/refine continuation keeps the
+    // manual cycle alive; a genuine user prompt ends it.
+    const feedbackTurn = reviewFeedbackTurn;
+    reviewFeedbackTurn = false;
     try {
+      if (!feedbackTurn) endReviewTurn();
       await beginReviewCycle({
-        reason: "prompt",
+        reason: feedbackTurn ? "refine" : "prompt",
         keepFindings: true,
         planPath: currentPlanFile,
       });
@@ -11002,26 +13212,36 @@ export default function workflowExtension(
       }
       // Build completion
       if (workflowMode === "build" && todoItems.length > 0) {
-        const allDone = todoItems.every(
-          (t) => isDone(t) || itemStatus(t) === "cancelled",
-        );
+        const allDone = isTodoListSettled(todoItems);
         if (allDone) {
-          try {
-            (pi as any).sendMessage?.(
-              {
-                customType: "workflow-complete",
-                content: `**Build Complete! ✓**\n\n${todoItems.map((t) => `~~${todoRef(t)}. ${t.text}~~`).join("\n")}`,
-                display: true,
-              },
-              { triggerTurn: false },
-            );
-          } catch (_e) {
-            void _e;
+          // One card per list revision: a settled list stays settled across
+          // turns, and re-sending the same card on every agent_end buried the
+          // transcript in duplicates. A new/renamed list or changed statuses
+          // produce a new signature and therefore a new card.
+          const signature = todoCompletionSignature(todoItems);
+          if (signature !== lastCompletedSignature) {
+            lastCompletedSignature = signature;
+            try {
+              (pi as any).sendMessage?.(
+                {
+                  customType: "workflow-complete",
+                  content: `**Build Complete! ✓**\n\n${todoItems.map((t) => `~~${todoRef(t)}. ${t.text}~~`).join("\n")}`,
+                  display: true,
+                },
+                { triggerTurn: false },
+              );
+            } catch (_e) {
+              void _e;
+            }
           }
           // keep todos for history but stay in build
           todoStale = false;
           updateStatus(ctx as any);
           persistState();
+        } else if (lastCompletedSignature !== null) {
+          // The list reopened (new step or a reverted status): allow the next
+          // completion to emit its own card. Persisted on the next mutation.
+          lastCompletedSignature = null;
         }
         return;
       }
@@ -11238,6 +13458,9 @@ export default function workflowExtension(
         reviewHandoffGate.reset();
         reviewGatePhase = "auditing";
         reviewGateCycleId = handoffCycle;
+        // Review owns the turn before the reviewer boots. A plan handoff with
+        // Review Mode off never reaches this block (no Review turn).
+        beginReviewTurn();
         try {
           const reviewed = await runReviewStep(
             authorPlan,