@dieulc/workflow 0.11.0 → 0.11.1

package/index.ts

@@ -122,17 +122,28 @@ import {
 } from "./commit-policy.ts";
 import {
   baseFolderRoots,
+  buildFolderPolicyDeny,
   decideFolderGate,
   describeFolderEvaluation,
   detectRepoRoot,
+  dialogGrantRootForTarget,
+  broadGrantRootReason,
   isBroadGrantRoot,
-  outsideProjectRootForTarget,
   evaluateFolderTargets,
+  evaluateBaseCoverage,
   matchSensitivePath,
   readFolderPolicyConfig,
   writeFolderPolicyConfig,
+  revokeFolderPolicyListEntry,
   folderPolicyArgumentCompletions,
   folderPolicyConfigPaths,
+  EXCLUDE_USAGE,
+  grantRootForTarget,
+  isBroadExcludePattern,
+  isWorkflowSettingsPath,
+  normalizeExcludePattern,
+  parseExcludeArgs,
+  splitPolicyArgs,
   DEFAULT_SENSITIVE_PATTERNS,
   type FolderPolicyConfig,
   type FolderTarget,
@@ -470,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-"),
@@ -513,11 +525,13 @@ async function runSingleAgent(
         // project's settings.
         env: {
           ...subagentEnv(process.env, agent.role),
-          PI_FOLDER_POLICY_LOCKED: "1",
-          PI_FOLDER_POLICY_ROOTS: JSON.stringify([
-            detectRepoRoot(cwd) ?? cwd,
-          ]),
-          PI_FOLDER_POLICY_SOURCE: "parent",
+          ...(folderEnv ?? {
+            PI_FOLDER_POLICY_LOCKED: "1",
+            PI_FOLDER_POLICY_ROOTS: JSON.stringify([
+              detectRepoRoot(cwd) ?? cwd,
+            ]),
+            PI_FOLDER_POLICY_SOURCE: "parent",
+          }),
         },
       },
     );
@@ -1859,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.
@@ -2123,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(
@@ -2143,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
@@ -3395,26 +3455,238 @@ export default function workflowExtension(
       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 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();
-      const scope: "global" | "project" = tokens.includes("project")
+      // 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"
-        : "global";
+        : 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: ${detectRepoRoot(cwd) ?? cwd}`,
+          `  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",
+          "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)",
         ];
-        ctx.ui.notify(lines.join("\n"), "info");
+        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") {
@@ -3442,10 +3714,10 @@ export default function workflowExtension(
         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(scope, cwd, agentDir, patch as any);
+      const written = writeFolderPolicyConfig(modeScope, cwd, agentDir, patch as any);
       ctx.ui.notify(
         written.ok
-          ? `Folder policy updated (${scope}): ${written.path}`
+          ? `Folder policy updated (${modeScope}): ${written.path}`
           : `Could not write folder policy: ${written.error ?? "unknown error"}`,
         written.ok ? "info" : "error",
       );
@@ -8985,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] = {
@@ -10263,21 +10536,25 @@ export default function workflowExtension(
       : { root: candidate, uncertain: true };
   }
 
-  function commitSensitiveHit(
+  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"]>,
-    folderConfig: FolderPolicyConfig,
-  ): { path: string; pattern: string } | { failed: string } | undefined {
-    const check = (paths: readonly string[]) => {
-      for (const p of paths) {
-        const hit = matchSensitivePath(p, folderConfig, scope.repoRoot);
-        if (hit.sensitive)
-          return { path: p, pattern: hit.pattern ?? "sensitive" };
-      }
-      return undefined;
+  ): CommitPathScan {
+    const paths: string[] = [];
+    const push = (values: readonly string[]) => {
+      for (const value of values) if (!paths.includes(value)) paths.push(value);
     };
-    const explicit = check(scope.explicitPaths);
-    if (explicit) return explicit;
-
+    push(scope.explicitPaths);
     if (scope.hit === "add" && scope.allPaths) {
       const status = runGitZ(scope.repoRoot, [
         "status",
@@ -10286,9 +10563,8 @@ export default function workflowExtension(
         "--untracked-files=all",
       ]);
       if (!status.ok)
-        return { failed: status.error ?? "git status failed" };
-      const hit = check(status.paths);
-      if (hit) return hit;
+        return { paths, failed: status.error ?? "git status failed" };
+      push(status.paths);
     }
     if (scope.hit === "commit") {
       const staged = runGitZ(scope.repoRoot, [
@@ -10298,9 +10574,8 @@ export default function workflowExtension(
         "-z",
       ]);
       if (!staged.ok)
-        return { failed: staged.error ?? "git diff --cached failed" };
-      const hit = check(staged.paths);
-      if (hit) return hit;
+        return { paths, failed: staged.error ?? "git diff --cached failed" };
+      push(staged.paths);
       if (scope.allPaths) {
         const status = runGitZ(scope.repoRoot, [
           "status",
@@ -10309,11 +10584,24 @@ export default function workflowExtension(
           "--untracked-files=all",
         ]);
         if (!status.ok)
-          return { failed: status.error ?? "git status failed" };
-        const modified = check(status.paths);
-        if (modified) return modified;
+          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;
   }
 
@@ -10352,27 +10640,56 @@ export default function workflowExtension(
     );
     if (resolvedRoot.uncertain)
       folderEvaluation.uncertain.push(repoRoot);
-    const folderOutside = folderEvaluation.outside.length > 0;
     const baseRoot = baseFolderRoots(folderConfig, cwd)[0] ?? cwd;
-    const folderDecision = decideFolderGate({
-      sensitive: false,
-      outside: folderEvaluation.outside.length > 0,
-      outsideAction: folderConfig.outside,
-      uncertain: folderEvaluation.uncertain.length > 0,
-    });
     // decideFolderGate already turns uncertainty into ask (outside: ask) or
     // block (outside: block); there is no "allow" case left to escalate.
-    const sensitiveHit = gitScope
-      ? commitSensitiveHit(gitScope, folderConfig)
-      : undefined;
-    if (sensitiveHit && "failed" in sensitiveHit) {
+    const scan = gitScope ? scanCommitPaths(gitScope) : undefined;
+    if (scan?.failed) {
       return {
         block: true,
         reason:
-          `Commit policy: the sensitive-file check could not run (${sensitiveHit.failed}). ` +
+          `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,
@@ -10381,7 +10698,8 @@ export default function workflowExtension(
       auth: commitAuthorization,
       now,
       folder: folderDecision,
-      sensitive: Boolean(sensitiveHit && !("failed" in sensitiveHit)),
+      sensitive: Boolean(sensitiveHit),
+      excluded: Boolean(excludedHit),
     });
     if (decision === "allow") {
       // Count a granted `git commit` against the authorization, but only when
@@ -10404,7 +10722,16 @@ export default function workflowExtension(
     }
 
     if (decision === "block") {
-      if (sensitiveHit && !("failed" in sensitiveHit)) {
+      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:
@@ -10415,12 +10742,14 @@ export default function workflowExtension(
       if (folderDecision === "block" && policy !== "never") {
         return {
           block: true,
-          reason:
-            `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.",
+          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 {
@@ -10447,17 +10776,39 @@ export default function workflowExtension(
           "but no interactive UI is available. Leave the change uncommitted and let the user decide.",
       };
     }
-    const commitGrant = folderOutside
-      ? (outsideProjectRootForTarget({ path: repoRoot, kind: "dir" }, baseRoot) ??
-        repoRoot)
-      : repoRoot;
+    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(
         `${folderOutside ? "Folder" : "Commit"} policy 'ask': allow \`git ${hit}\`?` +
           `\nRepository: ${repoRoot}` +
-          (folderOutside ? `\nOutside: ${baseRoot}` : ""),
-        folderOutside
+          (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"],
       );
@@ -10466,25 +10817,49 @@ export default function workflowExtension(
     }
     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 {
-          block: true,
-          reason:
-            "Folder policy 'ask': this project is not trusted, so a project-scoped grant would be ignored. " +
-            "Choose Allow once, trust the project first, or set folderPolicy.grantScope to 'global'.",
-        };
+        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: [commitGrant] },
+        { allowedPaths: [persistGrant] },
       );
       if (!written.ok) {
-        return {
-          block: true,
-          reason: `Could not save the commit folder grant (${written.error ?? "unknown error"}); the commit was not allowed.`,
-        };
+        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;
     }
@@ -10562,7 +10937,9 @@ export default function workflowExtension(
     }
     if (toolName === "bash" || toolName === "powershell") {
       const command = String(input?.command ?? "");
-      return analyzeShellPaths(command, cwd).writes;
+      return analyzeShellPaths(command, cwd, {
+        family: toolName === "powershell" ? "powershell" : "posix",
+      }).writes;
     }
     return [];
   }
@@ -10576,22 +10953,24 @@ export default function workflowExtension(
     const grantEntries = targets
       .map((target) => {
         const exact = normalizeWritePath(target.path, cwd);
-        const outsideRoot = outsideProjectRootForTarget(target, baseRoot);
-        const path = outsideRoot ?? exact;
+        // 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" ||
-          (outsideRoot !== undefined && outsideRoot !== exact);
-        return { path, folder };
+        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"
@@ -10768,6 +11147,22 @@ export default function workflowExtension(
         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) {
@@ -10790,6 +11185,7 @@ export default function workflowExtension(
       });
       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
@@ -10841,6 +11237,18 @@ export default function workflowExtension(
         : "";
 
       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,
@@ -10959,10 +11367,30 @@ export default function workflowExtension(
       }
 
       // (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, gateSource, baseRoot), options);
+        sel = await ui.select(
+          writeGateTitle(items, gateSource, baseRoot, {
+            grantBlockedReason: writeGrantBlockedReason,
+          }),
+          options,
+        );
       } catch (_e) {
         void _e;
         sel = undefined;
@@ -10984,14 +11412,31 @@ export default function workflowExtension(
           for (const p of item.grantPaths ?? []) allowedPaths.push(p);
           if (item.grantCommand) allowedCommands.push(item.grantCommand);
         }
+        // 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 {
-            block: true,
-            reason:
-              `${gatePolicyLabel} 'ask': this project is not trusted, so a project-scoped grant would be ignored. ` +
-              "Choose Allow once, trust the project first, or set folderPolicy.grantScope to 'global'.",
-          };
+          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,
@@ -11009,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:
-            `${gatePolicyLabel} '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 ──
@@ -11141,7 +11583,8 @@ export default function workflowExtension(
         const item = readGateItemFromTarget(
           name,
           target,
-          "outside the folder",
+          target.reason ?? "outside the folder",
+          cwd,
           baseRoot,
         );
         if (seen.has(item.key)) continue;
@@ -11251,10 +11694,24 @@ export default function workflowExtension(
         };
       }
 
+      // 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,
@@ -11346,10 +11803,30 @@ export default function workflowExtension(
         return undefined;
       }
 
-      const options = readGateOptions(readGateItemsKind(items));
+      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), options);
+        sel = await ui.select(
+          readGateTitle(items, baseRoot, { grantBlockedReason }),
+          options,
+        );
       } catch {
         sel = undefined;
       }
@@ -11361,30 +11838,40 @@ export default function workflowExtension(
         return undefined;
       }
       if (choice === "always") {
-        const roots = [
-          ...new Set(items.map((item) => item.grantRoot).filter(Boolean)),
-        ];
         if (roots.length === 0) {
           for (const reason of uncertain)
             readGateTurnUncertainAllowed.add(reason);
           readGateTurnAnswer = { choice: "always", instruction: "" };
           return undefined;
         }
-        const broad = roots.find((root) => isBroadGrantRoot(root));
+        // 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 {
-            block: true,
-            reason:
-              `Read policy: \`${broad}\` is too broad to persist from a dialog. Choose Allow once, or use /folder-policy any deliberately.`,
-          };
+          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 {
-            block: true,
-            reason:
-              "Read policy 'ask': this project is not trusted, so a project-scoped grant would be ignored. " +
-              "Choose Allow once, trust the project first, or set folderPolicy.grantScope to 'global'.",
-          };
+          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,
@@ -11393,10 +11880,19 @@ export default function workflowExtension(
           { allowedPaths: roots },
         );
         if (!written.ok) {
-          return {
-            block: true,
-            reason: `Read policy 'ask': could not save the permission grant (${written.error ?? "unknown error"}).`,
-          };
+          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);
@@ -11680,6 +12176,14 @@ export default function workflowExtension(
           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).`,
@@ -11722,6 +12226,16 @@ export default function workflowExtension(
           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.`,
@@ -11791,10 +12305,19 @@ export default function workflowExtension(
   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: (ctx as any)?.isProjectTrusted?.() === true,
+        trusted,
       }).config;
-      return redactToolResult(event as any, folderConfig, cwd) as any;
+      // 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 (