feat: 组合包配置以包内 config/ 为唯一来源，并新增受保护写入人工审批

配置统一：权限策略、硬防御、Tool Search、提示词封面以及新迁入的
RTK、pi-compaction、pi-worktree、pi-hermes-memory 配置全部由扩展
直接读取已安装组合包内的 config/，pi install / pi update 即完成部署；
删除 rebuild-bundle-config.mjs 与 bundle-manifest.json，my-pi/ 只保留
日志与缓存。update.sh 成功升级后将默认 git 来源的已安装副本
reset 回发布版本。AGENTS.md 新增「组合包配置原则」。

脚本整合：search_config.sh / ssh_config.sh 合并为 configure.sh
search|ssh；install.sh / update.sh 共享函数抽到 scripts/lib.sh，远程
安装器改为先下载到临时文件再执行，下载失败可被检测。

权限：hard-guards 新增 protectedWrites，写入 Pi 凭据/设置、已安装
组合包与扩展目录、pi-ssh 凭据库时一律人工确认（跳过 AutoReview、
yolo 与 Session grant，无 UI 时拒绝）；放行 ls、LSP 查询、ctx 只读、
web_search、Chrome 只读与 git 只读命令，skill_manage 改为 ask。

Generated with [Devin](https://devin.ai)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>

pi-permission-system/src/access-intent/bash/bash-path-resolver.ts

@@ -9,9 +9,11 @@ import {
   classifyTokenAsRuleCandidate,
 } from "#src/access-intent/bash/token-classification";
 import {
-  collectCommandTokens,
-  collectPathCandidateTokens,
-  collectRedirectTokens,
+  type BashPathTokenRole,
+  type CollectedPathToken,
+  collectCommandTokensDetailed,
+  collectPathCandidateTokensDetailed,
+  collectRedirectTokensDetailed,
   extractCommandName,
 } from "#src/access-intent/bash/token-collection";
 import { normalizePathPolicyLiteral } from "#src/access-intent/path-normalization";
@@ -40,6 +42,9 @@ type EffectiveBase =
 interface PathCandidate {
   readonly token: string;
   readonly base: EffectiveBase;
+  readonly role: BashPathTokenRole;
+  readonly program: string | null;
+  readonly wrapped: boolean;
 }
 
 // ── Public output types ──────────────────────────────────────────────────────
@@ -49,13 +54,41 @@ export interface BashPathRuleCandidate {
   readonly token: string;
   /** The path's lexical and canonical forms for permission policy matching. */
   readonly path: AccessPath;
+  /**
+   * How the command uses the token — `redirect-out`/`redirect-in` for
+   * redirect destinations, `argument` otherwise. Only the protected-write
+   * gate reads this; the ordinary path gate is role-agnostic.
+   */
+  readonly role: BashPathTokenRole;
+  /** The enclosing command's program name, or `null` outside a command. */
+  readonly program: string | null;
+  /**
+   * True inside a wrapper payload (`bash -c`, `eval`, `sudo`, `xargs`, …) or a
+   * command/process substitution — the enclosing program cannot vouch for the
+   * token's use.
+   */
+  readonly wrapped: boolean;
 }
 
 /** Cd-aware path-rule candidates extracted from a bash program. */
 export interface ResolvedBashPaths {
   readonly ruleCandidates: readonly BashPathRuleCandidate[];
+  /**
+   * The protected-write slice: every `ruleCandidates` entry plus every
+   * `redirect-out` destination, which is admitted unconditionally — a redirect
+   * target need not exist nor look like a path to still be written (`cd dir
+   * && echo 1 > new.json`). Role metadata is what the gate classifies on.
+   */
+  readonly writeCandidates: readonly BashPathRuleCandidate[];
 }
 
+/**
+ * Redirect targets that are really file-descriptor plumbing, not files:
+ * `>&1`, `2>&-` and friends write to a descriptor, so they never enter the
+ * write slice.
+ */
+const FD_DUPLICATE_TARGET = /^&?[\d-]+$/;
+
 // ── Walk-time constants ──────────────────────────────────────────────────────
 
 /** The working directory in force at the start of a program (`cwd`). */
@@ -101,9 +134,7 @@ export class BashPathResolver {
         ? CWD_BASE
         : this.deriveBaseFromCdTarget(CWD_BASE, this.workdir);
     const candidates = this.collectPathCandidates(rootNode, initialBase);
-    return {
-      ruleCandidates: this.projectRuleCandidates(candidates),
-    };
+    return this.projectCandidates(candidates);
   }
 
   // ── AST walk — collect PathCandidates ──────────────────────────────────
@@ -145,7 +176,7 @@ export class BashPathResolver {
       case "redirected_statement":
         return this.walkCurrentShellSequence(node, base, out);
       case "command":
-        tagTokens(collectCommandTokens(node), base, out);
+        tagTokens(collectCommandTokensDetailed(node), base, out);
         return this.foldCd(node, base);
       case "pipeline":
         // tree-sitter-bash mis-groups a redirect-bearing `&&`/`;` list as the
@@ -170,7 +201,7 @@ export class BashPathResolver {
         // substitution interiors: collect every candidate in the subtree tagged
         // with the enclosing base and do not fold their internal `cd`s. (Folding
         // inside substitutions is deferred — conservative, never under-flags.)
-        tagTokens(collectPathCandidateTokens(node), base, out);
+        tagTokens(collectPathCandidateTokensDetailed(node), base, out);
         return base;
     }
   }
@@ -230,7 +261,7 @@ export class BashPathResolver {
       }
       // Downstream stage (after a `|`): subshell — collect against the folded
       // base, do not fold.
-      tagTokens(collectPathCandidateTokens(child), current, out);
+      tagTokens(collectPathCandidateTokensDetailed(child), current, out);
     }
     return current;
   }
@@ -260,7 +291,7 @@ export class BashPathResolver {
         if (child.type === "file_redirect") {
           // Redirect destinations are part of the piped stage; collect them
           // against the folded base without folding.
-          tagTokens(collectRedirectTokens(child), current, out);
+          tagTokens(collectRedirectTokensDetailed(child), current, out);
           continue;
         }
         // The inner statement is the `list`/`command` being redirected; fold its
@@ -270,7 +301,7 @@ export class BashPathResolver {
       return current;
     }
     // Bare `command` or any other shape: a true subshell first stage.
-    tagTokens(collectPathCandidateTokens(node), base, out);
+    tagTokens(collectPathCandidateTokensDetailed(node), base, out);
     return base;
   }
 
@@ -298,7 +329,7 @@ export class BashPathResolver {
         current = this.walkForCandidates(child, current, out);
       } else {
         // Terminal child = the real pipe stage; collect without folding.
-        tagTokens(collectPathCandidateTokens(child), current, out);
+        tagTokens(collectPathCandidateTokensDetailed(child), current, out);
       }
     }
     return current;
@@ -363,34 +394,67 @@ export class BashPathResolver {
   /**
    * Project candidates into policy lookup values while preserving literal
    * values after a non-literal `cd`, where no reliable absolute base exists.
+   *
+   * `ruleCandidates` keeps the long-standing admission rule — path-shaped
+   * tokens plus bare tokens an existence probe confirms. `writeCandidates`
+   * additionally admits every `redirect-out` destination: a redirect writes
+   * its target whether or not the file exists yet, so existence and shape
+   * cannot gate it. The write slice is deduplicated per role so the same
+   * path appearing as both a read argument and a write destination keeps
+   * both classifications.
    */
-  private projectRuleCandidates(
+  private projectCandidates(
     candidates: readonly PathCandidate[],
-  ): BashPathRuleCandidate[] {
-    const seen = new Set<string>();
-    const result: BashPathRuleCandidate[] = [];
+  ): ResolvedBashPaths {
+    const seenRules = new Set<string>();
+    const seenWrites = new Set<string>();
+    const ruleCandidates: BashPathRuleCandidate[] = [];
+    const writeCandidates: BashPathRuleCandidate[] = [];
 
-    for (const { token, base } of candidates) {
+    const pushWrite = (
+      candidate: BashPathRuleCandidate,
+      matchValues: readonly string[],
+    ): void => {
+      const key = `${candidate.role}${matchValues.join("")}`;
+      if (seenWrites.has(key)) return;
+      seenWrites.add(key);
+      writeCandidates.push(candidate);
+    };
+
+    for (const candidate of candidates) {
+      const { token, base, role, program, wrapped } = candidate;
       const shaped = classifyTokenAsRuleCandidate(
         token,
         this.normalizer.flavor,
       );
-      const candidate =
+      const resolved =
         shaped === null
-          ? this.probeBareToken(token, base)
+          ? this.probeBareToken(token, base, { role, program, wrapped })
           : { token: shaped, path: this.buildRuleCandidatePath(shaped, base) };
-      if (!candidate) continue;
-
-      const matchValues = candidate.path.matchValues();
-      if (matchValues.length === 0) continue;
-
-      const key = matchValues.join("\0");
-      if (seen.has(key)) continue;
-      seen.add(key);
-      result.push(candidate);
+      if (resolved) {
+        const matchValues = resolved.path.matchValues();
+        if (matchValues.length === 0) continue;
+        const projected = { ...resolved, role, program, wrapped };
+        const key = matchValues.join("");
+        if (!seenRules.has(key)) {
+          seenRules.add(key);
+          ruleCandidates.push(projected);
+        }
+        pushWrite(projected, matchValues);
+        continue;
+      }
+      // A redirect-out destination that fails the shape/probe admission is
+      // still written — admit it to the write slice unconditionally (#393's
+      // literal-only fallback covers the unknown-base case).
+      if (role === "redirect-out" && !FD_DUPLICATE_TARGET.test(token)) {
+        const path = this.buildRuleCandidatePath(token, base);
+        const matchValues = path.matchValues();
+        if (matchValues.length === 0) continue;
+        pushWrite({ token, path, role, program, wrapped }, matchValues);
+      }
     }
 
-    return result;
+    return { ruleCandidates, writeCandidates };
   }
 
   /**
@@ -414,6 +478,11 @@ export class BashPathResolver {
   private probeBareToken(
     token: string,
     base: EffectiveBase,
+    meta: {
+      role: BashPathTokenRole;
+      program: string | null;
+      wrapped: boolean;
+    },
   ): BashPathRuleCandidate | null {
     const bare = classifyBareTokenCandidate(token);
     if (bare === null) return null;
@@ -424,7 +493,7 @@ export class BashPathResolver {
     });
     const lexical = path.value();
     if (!lexical || !this.normalizer.entryExists(lexical)) return null;
-    return { token: bare, path };
+    return { token: bare, path, ...meta };
   }
 
   private buildRuleCandidatePath(
@@ -474,11 +543,19 @@ function isBackgrounded(seqNode: TSNode, index: number): boolean {
 }
 
 function tagTokens(
-  tokens: readonly string[],
+  tokens: readonly CollectedPathToken[],
   base: EffectiveBase,
   out: PathCandidate[],
 ): void {
-  for (const token of tokens) out.push({ token, base });
+  for (const token of tokens) {
+    out.push({
+      token: token.text,
+      base,
+      role: token.role,
+      program: token.program,
+      wrapped: token.wrapped,
+    });
+  }
 }
 
 /**

pi-permission-system/src/access-intent/bash/command-enumeration.ts

@@ -176,8 +176,11 @@ function makeCommandUnit(
  * A leading `variable_assignment` prefix is skipped (matching
  * `commandUnitText`), so offsets are relative to the `command_name`. An empty
  * list means a pure assignment with no `command_name`.
+ *
+ * Exported for the token collector, which runs the same wrapper classification
+ * to mark wrapper payloads as wrapped path candidates.
  */
-function readCommandWords(node: TSNode): CommandWord[] {
+export function readCommandWords(node: TSNode): CommandWord[] {
   const words: CommandWord[] = [];
   let unitStart: number | undefined;
   for (let i = 0; i < node.childCount; i++) {

pi-permission-system/src/access-intent/bash/program.ts

@@ -26,6 +26,7 @@ export class BashProgram {
     private readonly sourceCommand: string,
     private readonly commandUnits: readonly BashCommand[],
     private readonly resolvedRuleCandidates: readonly BashPathRuleCandidate[],
+    private readonly resolvedWriteCandidates: readonly BashPathRuleCandidate[],
   ) {}
 
   /**
@@ -52,10 +53,10 @@ export class BashProgram {
   ): Promise<BashProgram> {
     const parser = await getParser();
     const tree = parser.parse(command);
-    if (!tree) return new BashProgram(command, [], []);
+    if (!tree) return new BashProgram(command, [], [], []);
 
     try {
-      const { ruleCandidates } = new BashPathResolver(
+      const { ruleCandidates, writeCandidates } = new BashPathResolver(
         normalizer,
         options?.workdir,
       ).resolve(tree.rootNode);
@@ -63,6 +64,7 @@ export class BashProgram {
         command,
         collectCommands(tree.rootNode),
         ruleCandidates,
+        writeCandidates,
       );
     } finally {
       tree.delete();
@@ -112,4 +114,14 @@ export class BashProgram {
   pathRuleCandidates(): BashPathRuleCandidate[] {
     return [...this.resolvedRuleCandidates];
   }
+
+  /**
+   * The protected-write slice: all path-rule candidates plus every
+   * `redirect-out` destination (admitted unconditionally), each carrying its
+   * `role`/`program`/`wrapped` metadata for the protected-write gate's
+   * read-vs-write classification.
+   */
+  writeCandidates(): BashPathRuleCandidate[] {
+    return [...this.resolvedWriteCandidates];
+  }
 }

pi-permission-system/src/access-intent/bash/token-collection.ts

@@ -1,4 +1,5 @@
 import { basename } from "node:path";
+import { readCommandWords } from "#src/access-intent/bash/command-enumeration";
 import {
   EXECUTION_HOST_TYPES,
   forEachNestedExecution,
@@ -10,6 +11,50 @@ import {
   SKIP_SUBTREE_TYPES,
 } from "#src/access-intent/bash/node-text";
 import type { TSNode } from "#src/access-intent/bash/parser";
+import { classifyWrapperWords } from "#src/access-intent/bash/wrapper-analysis";
+
+// ── Token roles and context ─────────────────────────────────────────────────
+
+/**
+ * How the enclosing command uses a collected token.
+ *
+ * `redirect-out` covers every operator that writes a file (`>`, `>>`, `&>`,
+ * `&>>`, `>|`, `<>`, `>&`); `redirect-in` is a `<` read; `argument` is any
+ * other candidate — the protected-write gate decides read vs write from the
+ * program name.
+ */
+export type BashPathTokenRole = "argument" | "redirect-out" | "redirect-in";
+
+/**
+ * A collected token together with the metadata the protected-write gate
+ * needs: the enclosing command's program name (after stripping env
+ * assignments), how the command uses it, and whether it sits inside a wrapper
+ * payload (`bash -c`, `eval`, `sudo`, `xargs`, …) or a nested execution
+ * context (command/process substitution).
+ */
+export interface CollectedPathToken {
+  readonly text: string;
+  readonly role: BashPathTokenRole;
+  readonly program: string | null;
+  readonly wrapped: boolean;
+}
+
+/**
+ * Enclosing-context facts carried down the token walk.
+ * `program` is the `command_name` of the enclosing command unit — `null` for
+ * tokens outside any command (e.g. a redirect on a subshell). `wrapped`
+ * becomes true inside a nested execution context and inside a wrapper
+ * command's payload.
+ */
+export interface TokenCollectionContext {
+  readonly program: string | null;
+  readonly wrapped: boolean;
+}
+
+const TOP_LEVEL_CONTEXT: TokenCollectionContext = {
+  program: null,
+  wrapped: false,
+};
 
 // ── Public surface ─────────────────────────────────────────────────────────
 
@@ -30,17 +75,33 @@ import type { TSNode } from "#src/access-intent/bash/parser";
  * arguments generically.
  */
 export function collectPathCandidateTokens(node: TSNode): string[] {
-  if (node.type === "command") return collectCommandTokens(node);
-  if (node.type === "file_redirect") return collectRedirectTokens(node);
+  return collectPathCandidateTokensDetailed(node).map((token) => token.text);
+}
+
+/**
+ * The metadata-carrying form of {@link collectPathCandidateTokens}; every
+ * token keeps its role, enclosing program, and wrapped flag for the
+ * protected-write write classification.
+ */
+export function collectPathCandidateTokensDetailed(
+  node: TSNode,
+  context: TokenCollectionContext = TOP_LEVEL_CONTEXT,
+): CollectedPathToken[] {
+  if (node.type === "command")
+    return collectCommandTokensDetailed(node, context);
+  if (node.type === "file_redirect")
+    return collectRedirectTokensDetailed(node, context);
   if (EXECUTION_HOST_TYPES.has(node.type)) {
-    return collectHostedExecutionTokens(node);
+    return collectHostedExecutionTokens(node, context);
   }
   if (SKIP_SUBTREE_TYPES.has(node.type)) return [];
 
-  const tokens: string[] = [];
+  const tokens: CollectedPathToken[] = [];
   for (let i = 0; i < node.childCount; i++) {
     const child = node.child(i);
-    if (child) tokens.push(...collectPathCandidateTokens(child));
+    if (child) {
+      tokens.push(...collectPathCandidateTokensDetailed(child, context));
+    }
   }
   return tokens;
 }
@@ -51,14 +112,41 @@ export function collectPathCandidateTokens(node: TSNode): string[] {
  * `collectGenericCommandTokens`.
  */
 export function collectCommandTokens(node: TSNode): string[] {
-  const commandName = extractCommandName(node);
-  const config = commandName
-    ? PATTERN_FIRST_COMMANDS.get(commandName)
-    : undefined;
+  return collectCommandTokensDetailed(node).map((token) => token.text);
+}
+
+/**
+ * The metadata-carrying form of {@link collectCommandTokens}. The command's
+ * own name becomes the tokens' `program`, and the whole argument set is
+ * `wrapped` when the command is itself a wrapper unit (`bash -c`, `eval`,
+ * `sudo`, `xargs`, …) or sits inside a nested execution context.
+ */
+export function collectCommandTokensDetailed(
+  node: TSNode,
+  context: TokenCollectionContext = TOP_LEVEL_CONTEXT,
+): CollectedPathToken[] {
+  const program = extractCommandName(node) ?? null;
+  const commandContext: TokenCollectionContext = {
+    program,
+    wrapped:
+      context.wrapped ||
+      classifyWrapperWords(readCommandWords(node)) !== undefined,
+  };
+  const config = program ? PATTERN_FIRST_COMMANDS.get(program) : undefined;
   const tokens = config
-    ? collectPatternCommandTokens(node, config)
-    : collectGenericCommandTokens(node);
-  return [...tokens, ...collectEmbeddedOptionValues(node)];
+    ? collectPatternCommandTokens(node, config, commandContext)
+    : collectGenericCommandTokens(node, commandContext);
+  return [
+    ...tokens,
+    ...collectEmbeddedOptionValues(node).map((text) => ({
+      text,
+      role: "argument" as const,
+      program,
+      // A value hidden inside `--flag=PATH` is indirection — the read-only
+      // program allowance must not extend to it.
+      wrapped: true,
+    })),
+  ];
 }
 
 /**
@@ -74,18 +162,54 @@ export function collectCommandTokens(node: TSNode): string[] {
  * argument node.
  */
 export function collectRedirectTokens(node: TSNode): string[] {
-  const tokens: string[] = [];
+  return collectRedirectTokensDetailed(node).map((token) => token.text);
+}
+
+/**
+ * The metadata-carrying form of {@link collectRedirectTokens}. The redirect
+ * operator decides the role: an operator containing `>` writes
+ * (`redirect-out`), `<` reads (`redirect-in`); when `node` is not a
+ * `file_redirect` the tokens keep the neutral `argument` role.
+ */
+export function collectRedirectTokensDetailed(
+  node: TSNode,
+  context: TokenCollectionContext = TOP_LEVEL_CONTEXT,
+): CollectedPathToken[] {
+  const role =
+    node.type === "file_redirect" ? redirectRole(node) : "argument";
+  const tokens: CollectedPathToken[] = [];
   for (let i = 0; i < node.childCount; i++) {
     const child = node.child(i);
     if (!child) continue;
     if (ARG_NODE_TYPES.has(child.type)) {
-      tokens.push(resolveNodeText(child));
+      tokens.push({
+        text: resolveNodeText(child),
+        role,
+        program: context.program,
+        wrapped: context.wrapped,
+      });
     }
-    tokens.push(...collectHostedExecutionTokens(child));
+    tokens.push(...collectHostedExecutionTokens(child, context));
   }
   return tokens;
 }
 
+/**
+ * The write/read role a `file_redirect` node's operator implies: any operator
+ * containing `>` (`>`, `>>`, `&>`, `&>>`, `>|`, `<>`, `>&`) writes;
+ * `<` reads. A missing operator defaults to the write role — the
+ * conservative answer for the protected-write slice.
+ */
+function redirectRole(node: TSNode): "redirect-out" | "redirect-in" {
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (!child || child.isNamed) continue;
+    if (child.text.includes(">")) return "redirect-out";
+    if (child.text.includes("<")) return "redirect-in";
+  }
+  return "redirect-out";
+}
+
 /**
  * Collect the path-candidate tokens of every command nested inside `node`'s
  * execution contexts, reading none of the host subtree's own text.
@@ -95,15 +219,27 @@ export function collectRedirectTokens(node: TSNode): string[] {
  *
  * `node` may be a context outright (`> $(cmd)`) or merely contain one
  * (`> ${DIR}/$(cmd)`); `forEachNestedExecution` searches strictly within a
- * subtree, so the first case is checked here.
+ * subtree, so the first case is checked here. Everything found inside is
+ * `wrapped` — the enclosing program cannot vouch for what a substitution runs.
  */
-function collectHostedExecutionTokens(node: TSNode): string[] {
+function collectHostedExecutionTokens(
+  node: TSNode,
+  context: TokenCollectionContext,
+): CollectedPathToken[] {
   if (NESTED_EXECUTION_CONTEXTS.has(node.type)) {
-    return collectPathCandidateTokens(node);
+    return collectPathCandidateTokensDetailed(node, {
+      ...context,
+      wrapped: true,
+    });
   }
-  const tokens: string[] = [];
+  const tokens: CollectedPathToken[] = [];
   forEachNestedExecution(node, (contextNode) => {
-    tokens.push(...collectPathCandidateTokens(contextNode));
+    tokens.push(
+      ...collectPathCandidateTokensDetailed(contextNode, {
+        ...context,
+        wrapped: true,
+      }),
+    );
   });
   return tokens;
 }
@@ -187,7 +323,10 @@ const PATTERN_FIRST_COMMANDS: ReadonlyMap<string, PatternCommandConfig> =
     [
       "sed",
       {
-        argConsumingFlags: new Set(["-e", "-i"]),
+        // `-i` is deliberately absent: GNU sed's in-place flag takes an
+        // attached suffix, never a separate argument, so treating it as
+        // arg-consuming would swallow the script and hide the file operand.
+        argConsumingFlags: new Set(["-e"]),
         fileConsumingFlags: new Set(["-f"]),
       },
     ],
@@ -322,13 +461,23 @@ function classifyPatternCommandFlag(
 function collectPatternCommandTokens(
   node: TSNode,
   config: PatternCommandConfig,
-): string[] {
+  context: TokenCollectionContext,
+): CollectedPathToken[] {
   const patternPositionals = config.patternPositionals ?? 1;
   let hasExplicitScript = false;
   let positionalsSeen = 0;
   let nextArgAction: "skip" | "extract" | null = null;
   let pastEndOfFlags = false;
-  const tokens: string[] = [];
+  const tokens: CollectedPathToken[] = [];
+
+  const pushArgument = (text: string): void => {
+    tokens.push({
+      text,
+      role: "argument",
+      program: context.program,
+      wrapped: context.wrapped,
+    });
+  };
 
   for (let i = 0; i < node.childCount; i++) {
     const child = node.child(i);
@@ -341,7 +490,7 @@ function collectPatternCommandTokens(
     // Only process argument-like nodes; recurse into others
     // (e.g. command_substitution) for nested commands.
     if (!ARG_NODE_TYPES.has(child.type)) {
-      tokens.push(...collectPathCandidateTokens(child));
+      tokens.push(...collectPathCandidateTokensDetailed(child, context));
       continue;
     }
 
@@ -353,7 +502,7 @@ function collectPatternCommandTokens(
       continue;
     }
     if (nextArgAction === "extract") {
-      tokens.push(text);
+      pushArgument(text);
       nextArgAction = null;
       continue;
     }
@@ -387,7 +536,7 @@ function collectPatternCommandTokens(
     }
 
     // File argument — collect as path candidate.
-    tokens.push(text);
+    pushArgument(text);
   }
 
   return tokens;
@@ -397,8 +546,11 @@ function collectPatternCommandTokens(
  * Collect all argument tokens from a generic (non-pattern-first) command node,
  * skipping the command name and variable assignments.
  */
-function collectGenericCommandTokens(node: TSNode): string[] {
-  const tokens: string[] = [];
+function collectGenericCommandTokens(
+  node: TSNode,
+  context: TokenCollectionContext,
+): CollectedPathToken[] {
+  const tokens: CollectedPathToken[] = [];
   let seenCommandName = false;
 
   for (let i = 0; i < node.childCount; i++) {
@@ -421,12 +573,17 @@ function collectGenericCommandTokens(node: TSNode): string[] {
 
     // Argument nodes: resolve their text and collect.
     if (ARG_NODE_TYPES.has(child.type)) {
-      tokens.push(resolveNodeText(child));
+      tokens.push({
+        text: resolveNodeText(child),
+        role: "argument",
+        program: context.program,
+        wrapped: context.wrapped,
+      });
       continue;
     }
 
     // Recurse into other children (e.g. command_substitution nested in args)
-    tokens.push(...collectPathCandidateTokens(child));
+    tokens.push(...collectPathCandidateTokensDetailed(child, context));
   }
 
   return tokens;

pi-permission-system/src/authority/authorizer-selection.ts

@@ -6,9 +6,11 @@ import {
   type NamedAuthorizer,
   type SelectedAuthority,
   selectAuthorizer,
+  type TerminalAuthorizer,
 } from "./authorizer";
 import { composeAuthorizerChain } from "./authorizer-chain";
 import type { AuthorizerLookup } from "./authorizer-registry";
+import { LocalUserAuthorizer } from "./local-user-authorizer";
 import type {
   PermissionPrompterApi,
   PromptPermissionDetails,
@@ -172,6 +174,27 @@ export class AuthorizerSelection
         new Error("escalate called before the session was activated"),
       );
     }
+    // A protected-write ask is human-only: it composes with zero links (no
+    // AutoReview), and a terminal that is not the local UI — a denying node,
+    // a `ParentAuthorizer` relay, or a session with no UI — cannot confirm
+    // it, so it denies without prompting.
+    if (details.humanOnly) {
+      if (!(authority.terminal instanceof LocalUserAuthorizer)) {
+        return this.deps.prompter.prompt(
+          new ProtectedWriteUnavailableAuthorizer(),
+          details,
+        );
+      }
+      return this.deps.prompter.prompt(
+        composeAuthorizerChain(
+          [],
+          authority.terminal,
+          this.deps.getPermissionQuery(),
+          this.deps.logger,
+        ),
+        details,
+      );
+    }
     const chain = composeAuthorizerChain(
       this.linksFor(authority, details.requestId),
       authority.terminal,
@@ -181,3 +204,26 @@ export class AuthorizerSelection
     return this.deps.prompter.prompt(chain, details);
   }
 }
+
+/**
+ * The human-only terminal for a protected-write ask on a node with no local
+ * UI: answers with a fixed denial, marked `confirmationUnavailable` so the
+ * review log and decision event record that no human ever ruled rather than
+ * a user denial (#719). Routed through `PermissionPrompter` so the
+ * waiting/denied review entries are written like any other escalated ask.
+ */
+class ProtectedWriteUnavailableAuthorizer implements TerminalAuthorizer {
+  authorize(): Promise<PermissionPromptDecision> {
+    return Promise.resolve({
+      approved: false,
+      state: "denied_with_reason",
+      denialReason:
+        "写入受保护文件需要人工确认，但当前没有可用的确认界面",
+      confirmationUnavailable: true,
+      decidedBy: {
+        kind: "unavailable",
+        reason: "protected_write_no_local_ui",
+      },
+    });
+  }
+}

pi-permission-system/src/authority/local-user-authorizer.ts

@@ -76,6 +76,11 @@ function buildRequestOptions(
   const notes = details.deferNotes;
   const withNotes =
     notes && notes.length > 0 ? { deferNotes: notes } : undefined;
+  // A protected-write ask offers no session grant at all — a human must
+  // confirm every write, so the option is hidden rather than unrecorded.
+  if (details.humanOnly) {
+    return { hideSessionOption: true, ...withNotes };
+  }
   if (details.forwarding && details.sessionApproval && pattern) {
     return {
       sessionScope: buildForwardedScopeLabels(

pi-permission-system/src/authority/permission-dialog.ts

@@ -119,6 +119,12 @@ export interface RequestPermissionOptions {
    * deterministic, code-authored sentence.
    */
   deferNotes?: readonly PromptDecisionNote[];
+  /**
+   * Protected-write asks only: suppress the "for this session" option
+   * entirely — a human-only write must be confirmed every time, so the
+   * session grant is not offered rather than merely unrecorded.
+   */
+  hideSessionOption?: boolean;
 }
 
 export async function requestPermissionDecisionFromUi(
@@ -130,7 +136,7 @@ export async function requestPermissionDecisionFromUi(
   const sessionOption = options?.sessionLabel ?? APPROVE_FOR_SESSION_OPTION;
   const decisionOptions = [
     APPROVE_OPTION,
-    sessionOption,
+    ...(options?.hideSessionOption ? [] : [sessionOption]),
     DENY_OPTION,
     DENY_WITH_REASON_OPTION,
   ] as const;

pi-permission-system/src/authority/permission-prompt-component.ts

@@ -16,6 +16,7 @@ import {
   type UnattributedDecision,
 } from "#src/authority/permission-dialog";
 import {
+  enabledPromptKeys,
   initialPromptState,
   type PromptEvent,
   type PromptKey,
@@ -139,8 +140,6 @@ const OPTION_LABELS: Record<PromptKey, string> = {
   r: "No, provide reason",
 };
 
-const OPTION_ORDER: readonly PromptKey[] = ["y", "s", "n", "r"];
-
 export function presentInlinePermissionPrompt(
   view: PermissionPromptView,
   title: string,
@@ -151,6 +150,7 @@ export function presentInlinePermissionPrompt(
     doublePressToConfirm: view.doublePressToConfirm,
     sessionLabel: options?.sessionLabel ?? DEFAULT_SESSION_LABEL,
     sessionScope: options?.sessionScope,
+    hideSessionOption: options?.hideSessionOption,
   };
   return view.ui.custom<UnattributedDecision>(
     (tui, theme, keybindings, done) =>
@@ -341,7 +341,9 @@ class PermissionPromptComponent implements Component {
       return { type: "cancel" };
     }
     if (this.state.step === "decision") {
-      const key = OPTION_ORDER.find((option) => matchesKey(data, option));
+      const key = enabledPromptKeys(this.config).find((option) =>
+        matchesKey(data, option),
+      );
       if (key) {
         return { type: "hotkey", key };
       }
@@ -365,7 +367,7 @@ class PermissionPromptComponent implements Component {
   private renderDecision(width: number): string[] {
     const ask = this.renderAsk(width);
     const lines = [this.theme.fg("accent", this.title), ...ask.lines, ""];
-    for (const key of OPTION_ORDER) {
+    for (const key of enabledPromptKeys(this.config)) {
       const label = key === "s" ? this.config.sessionLabel : OPTION_LABELS[key];
       const selected = this.state.highlightedKey === key;
       const marker = selected ? "▶" : " ";

pi-permission-system/src/authority/permission-prompt-decision.ts

@@ -30,6 +30,21 @@ const OPTION_VERBS: Record<PromptKey, string> = {
   r: "deny with a reason",
 };
 
+/**
+ * The keys this prompt offers: `OPTION_ORDER` minus `s` when
+ * {@link PromptModelConfig.hideSessionOption} suppresses the session grant
+ * (a protected-write ask must be confirmed every time). Shared by the
+ * reducer and the component renderer so the two never disagree about which
+ * options exist.
+ */
+export function enabledPromptKeys(
+  config: PromptModelConfig,
+): readonly PromptKey[] {
+  return config.hideSessionOption
+    ? OPTION_ORDER.filter((key) => key !== "s")
+    : OPTION_ORDER;
+}
+
 /** Static configuration for a single prompt presentation. */
 export interface PromptModelConfig {
   /** When true, a letter hotkey arms first and commits only on a second press. */
@@ -42,6 +57,11 @@ export interface PromptModelConfig {
    * default) or the whole serving session.
    */
   sessionScope?: NonNullable<RequestPermissionOptions["sessionScope"]>;
+  /**
+   * Protected-write asks only: suppress the `s` option entirely — a
+   * human-only write must be confirmed every time.
+   */
+  hideSessionOption?: boolean;
 }
 
 /** The re-render view state the component draws from. */
@@ -116,11 +136,18 @@ function reduceDecisionStep(
     case "nav":
       return render({
         ...state,
-        highlightedKey: shiftKey(state.highlightedKey, event.direction),
+        highlightedKey: shiftKey(
+          state.highlightedKey,
+          event.direction,
+          enabledPromptKeys(config),
+        ),
         armedKey: undefined,
         hint: "",
       });
     case "hotkey":
+      if (!enabledPromptKeys(config).includes(event.key)) {
+        return render(state);
+      }
       return pressHotkey(config, state, event.key);
     case "confirm":
       return commit(config, state, state.highlightedKey);
@@ -245,11 +272,16 @@ function reduceScopeStep(
   }
 }
 
-function shiftKey(current: PromptKey, direction: "up" | "down"): PromptKey {
-  const index = OPTION_ORDER.indexOf(current);
+function shiftKey(
+  current: PromptKey,
+  direction: "up" | "down",
+  keys: readonly PromptKey[],
+): PromptKey {
+  const index = keys.indexOf(current);
+  if (index === -1) return keys[0] ?? current;
   const delta = direction === "down" ? 1 : -1;
-  const next = (index + delta + OPTION_ORDER.length) % OPTION_ORDER.length;
-  return OPTION_ORDER[next] ?? current;
+  const next = (index + delta + keys.length) % keys.length;
+  return keys[next] ?? current;
 }
 
 function render(state: PromptViewState): PromptOutcome {

pi-permission-system/src/authority/permission-prompter.ts

@@ -79,6 +79,13 @@ export interface PromptPermissionDetails {
    * model-generated), `system` is a code-authored sentence.
    */
   deferNotes?: readonly DeferNote[];
+  /**
+   * Marks the protected-write escalation path: the ask must reach the local
+   * human terminal directly — no `authorizerChain` links (AutoReview), no
+   * session-grant option, and a terminal without a local UI denies without
+   * prompting. Set by `GateRunner` from the descriptor's `humanOnly` marker.
+   */
+  humanOnly?: boolean;
 }
 
 /**

pi-permission-system/src/config-loader.ts

@@ -1,11 +1,6 @@
 import { existsSync, readFileSync } from "node:fs";
-import { normalize } from "node:path";
 import type { ZodError } from "zod";
-import {
-  getGlobalConfigPath,
-  getLegacyExtensionConfigPath,
-  getLegacyGlobalPolicyPath,
-} from "./config-paths";
+import { getGlobalConfigPath } from "./config-paths";
 import {
   type ShellToolsConfig,
   type UnifiedPermissionConfig,
@@ -285,47 +280,21 @@ export interface MergedConfigResult {
 }
 
 /**
- * Load the user-global config, detect legacy global files, and collect issues.
- * Project-level `policy.jsonc` files are intentionally not loaded.
+ * Load the global bundle policy config and collect issues.
+ *
+ * The installed bundle's `config/pi-permission-policy.jsonc` is the single
+ * source of truth. Project-level `policy.jsonc` files and leftover files at
+ * legacy locations are ignored — never merged and never migrated.
  */
 export function loadAndMergeConfigs(
-  agentDir: string,
-  _cwd: string,
-  extensionRoot: string,
+  globalConfigPath: string = getGlobalConfigPath(),
 ): MergedConfigResult {
   const allIssues: string[] = [];
-  const newGlobalPath = getGlobalConfigPath(agentDir);
-  const legacyGlobalPolicyPath = getLegacyGlobalPolicyPath(agentDir);
-  const legacyExtConfigPath = getLegacyExtensionConfigPath(extensionRoot);
-  let merged: UnifiedPermissionConfig = {};
 
-  if (existsSync(legacyGlobalPolicyPath)) {
-    const legacy = loadUnifiedConfig(legacyGlobalPolicyPath);
-    allIssues.push(
-      `Legacy global policy found at '${legacyGlobalPolicyPath}'. ` +
-        `Move it to '${newGlobalPath}':\n` +
-        `  mv '${legacyGlobalPolicyPath}' '${newGlobalPath}'`,
-    );
-    merged = mergeUnifiedConfigs(merged, legacy.config);
-  }
-
-  if (
-    normalize(legacyExtConfigPath) !== normalize(newGlobalPath) &&
-    existsSync(legacyExtConfigPath)
-  ) {
-    const legacy = loadUnifiedConfig(legacyExtConfigPath);
-    allIssues.push(
-      `Legacy extension config found at '${legacyExtConfigPath}'. ` +
-        `Move it to '${newGlobalPath}':\n` +
-        `  mv '${legacyExtConfigPath}' '${newGlobalPath}'`,
-    );
-    merged = mergeUnifiedConfigs(merged, legacy.config);
-  }
-
-  const globalResult = loadUnifiedConfig(newGlobalPath);
+  const globalResult = loadUnifiedConfig(globalConfigPath);
   allIssues.push(...globalResult.issues);
   const globalConfig = globalResult.config;
-  merged = mergeUnifiedConfigs(merged, globalConfig);
+  const merged = mergeUnifiedConfigs({}, globalConfig);
 
   const bashFallbackIssue = detectPermissiveBashFallback(merged.permission);
   if (bashFallbackIssue) allIssues.push(bashFallbackIssue);

pi-permission-system/src/config-modal.ts

@@ -30,7 +30,7 @@ const COMMAND_ARGUMENTS = [
   {
     value: "path",
     label: "Show config path",
-    description: "Display the policy.jsonc path used by pi-permission-system",
+    description: "Display the pi-permission-policy.jsonc path used by pi-permission-system",
   },
   {
     value: "reset",

pi-permission-system/src/config-paths.ts

@@ -1,37 +1,41 @@
 import { join } from "node:path";
+import { fileURLToPath } from "node:url";
 
 const EXTENSION_ID = "pi-permission-system";
 
 /**
- * Bundle-owned config tree under the agent directory: install.sh / update.sh
- * delete and rebuild `my-pi/` wholesale on every run, so policy, hard guards,
- * and logs all live beneath it. Files at the former
- * `extensions/pi-permission-system/` location are ignored — never migrated.
+ * Bundle-level `config/` is the single source of truth for policy and hard
+ * guards: paths resolve relative to this source file so the installed bundle
+ * is read directly, with no deployment, seeding, or migration into the agent
+ * dir. Only disposable runtime state (logs) stays under `<agentDir>/my-pi/`.
  */
-const BUNDLE_CONFIG_DIR = "my-pi";
+const BUNDLE_CONFIG_DIR = fileURLToPath(new URL("../../config", import.meta.url));
+const BUNDLE_MANAGED_DIR = "my-pi";
 const BUNDLE_PERMISSION_DIR = "permission-system";
 
 export const DEBUG_LOG_FILENAME = `${EXTENSION_ID}-debug.jsonl`;
 export const REVIEW_LOG_FILENAME = `${EXTENSION_ID}-permission-review.jsonl`;
 
+/**
+ * Bundle-owned runtime directory under the agent dir — logs only. Stale files
+ * left here from earlier deployments are ignored, never migrated.
+ */
 export function getGlobalConfigDir(agentDir: string): string {
-  return join(agentDir, BUNDLE_CONFIG_DIR, BUNDLE_PERMISSION_DIR);
+  return join(agentDir, BUNDLE_MANAGED_DIR, BUNDLE_PERMISSION_DIR);
 }
 
-export function getGlobalConfigPath(agentDir: string): string {
-  return join(getGlobalConfigDir(agentDir), "policy.jsonc");
+export function getGlobalConfigPath(): string {
+  return join(BUNDLE_CONFIG_DIR, "pi-permission-policy.jsonc");
 }
 
-export function getHardGuardConfigPath(agentDir: string): string {
-  return join(getGlobalConfigDir(agentDir), "hard-guards.jsonc");
+export function getHardGuardConfigPath(): string {
+  return join(BUNDLE_CONFIG_DIR, "pi-permission-hard-guards.jsonc");
 }
 
-
 export function getGlobalLogsDir(agentDir: string): string {
   return join(getGlobalConfigDir(agentDir), "logs");
 }
 
-
 /**
  * Directory holding project-scoped custom agent definition files.
  *
@@ -44,12 +48,3 @@ export function getGlobalLogsDir(agentDir: string): string {
 export function getProjectAgentsDir(cwd: string): string {
   return join(cwd, ".pi", "agents");
 }
-
-export function getLegacyGlobalPolicyPath(agentDir: string): string {
-  return join(agentDir, "pi-permissions.jsonc");
-}
-
-
-export function getLegacyExtensionConfigPath(extensionRoot: string): string {
-  return join(extensionRoot, "config.json");
-}

pi-permission-system/src/config-reporter.ts

@@ -1,29 +1,13 @@
 import type { ResolvedPolicyPaths } from "./permission-manager";
 
-export interface ResolvedConfigLogEntry {
-  globalConfigPath: string;
-  globalConfigExists: boolean;
-  agentsDir: string;
-  agentsDirExists: boolean;
-  projectAgentsDir: string | null;
-  projectAgentsDirExists: boolean;
-  legacyGlobalPolicyDetected: boolean;
-  legacyExtensionConfigDetected: boolean;
-}
+export type ResolvedConfigLogEntry = ResolvedPolicyPaths;
 
 export interface BuildResolvedConfigLogEntryOptions {
   policyPaths: ResolvedPolicyPaths;
-  legacyGlobalPolicyDetected?: boolean;
-  legacyExtensionConfigDetected?: boolean;
 }
 
 export function buildResolvedConfigLogEntry(
   options: BuildResolvedConfigLogEntryOptions,
 ): ResolvedConfigLogEntry {
-  return {
-    ...options.policyPaths,
-    legacyGlobalPolicyDetected: options.legacyGlobalPolicyDetected ?? false,
-    legacyExtensionConfigDetected:
-      options.legacyExtensionConfigDetected ?? false,
-  };
+  return { ...options.policyPaths };
 }

pi-permission-system/src/config-schema.ts

@@ -262,7 +262,7 @@ export const unifiedConfigSchema = z
     description:
       "Ordinary JSONC policy combining runtime knobs, AutoReview settings, and flat permission rules for pi-permission-system.",
     markdownDescription:
-      "Global ordinary JSONC policy for [pi-permission-system](https://github.com/gotgenes/pi-packages/tree/main/packages/pi-permission-system).\n\nPlace at `~/.pi/agent/my-pi/permission-system/policy.jsonc`. Project-level policy files are not loaded. Global-only hard guards use the separate `hard-guards.jsonc` schema.",
+      "Global ordinary JSONC policy for [pi-permission-system](https://github.com/gotgenes/pi-packages/tree/main/packages/pi-permission-system).\n\nRead directly from the installed bundle's `config/pi-permission-policy.jsonc`. Project-level policy files are not loaded. Global-only hard guards use the separate `config/pi-permission-hard-guards.jsonc` schema.",
   });
 
 /** A permission decision. */

pi-permission-system/src/config-store.ts

@@ -5,22 +5,17 @@ import {
   unlinkSync,
   writeFileSync,
 } from "node:fs";
-import { dirname, normalize } from "node:path";
+import { dirname } from "node:path";
 import type {
   ExtensionCommandContext,
   ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
 
 import { loadAndMergeConfigs, loadUnifiedConfig } from "./config-loader";
-import {
-  getGlobalConfigPath,
-  getLegacyExtensionConfigPath,
-  getLegacyGlobalPolicyPath,
-} from "./config-paths";
+import { getGlobalConfigPath } from "./config-paths";
 import { buildResolvedConfigLogEntry } from "./config-reporter";
 import {
   DEFAULT_EXTENSION_CONFIG,
-  EXTENSION_ROOT,
   normalizePermissionSystemConfig,
   type PermissionSystemExtensionConfig,
 } from "./extension-config";
@@ -66,6 +61,8 @@ export interface ConfigStoreDeps {
   agentDir: string;
   policyPaths: ResolvedPolicyPathProvider;
   logger: DebugReviewLogger;
+  /** Override the policy file `save()` writes — tests inject a temp path. */
+  configPath?: string;
 }
 
 /**
@@ -98,12 +95,7 @@ export class ConfigStore implements SessionConfigStore, CommandConfigStore {
    * for lifecycle logging and active-agent trust decisions owned elsewhere.
    */
   refresh(ctx: ExtensionContext | undefined, projectTrusted: boolean): void {
-    const cwd = ctx?.cwd ?? null;
-    const mergeResult = loadAndMergeConfigs(
-      this.deps.agentDir,
-      cwd ?? "",
-      EXTENSION_ROOT,
-    );
+    const mergeResult = loadAndMergeConfigs(this.deps.configPath);
     const runtimeConfig = normalizePermissionSystemConfig(mergeResult.merged);
     this.config = runtimeConfig;
 
@@ -143,7 +135,7 @@ export class ConfigStore implements SessionConfigStore, CommandConfigStore {
     ctx: ExtensionCommandContext,
   ): void {
     const normalized = normalizePermissionSystemConfig(next);
-    const globalPath = getGlobalConfigPath(this.deps.agentDir);
+    const globalPath = this.deps.configPath ?? getGlobalConfigPath();
 
     const existing = loadUnifiedConfig(globalPath);
     const merged = {
@@ -192,20 +184,7 @@ export class ConfigStore implements SessionConfigStore, CommandConfigStore {
    */
   logResolvedPaths(_cwd?: string): void {
     const policyPaths = this.deps.policyPaths.getResolvedPolicyPaths();
-    const { agentDir } = this.deps;
-    const legacyGlobalPolicyDetected = existsSync(
-      getLegacyGlobalPolicyPath(agentDir),
-    );
-    const legacyExtConfigPath = getLegacyExtensionConfigPath(EXTENSION_ROOT);
-    const newGlobalPath = getGlobalConfigPath(agentDir);
-    const legacyExtensionConfigDetected =
-      normalize(legacyExtConfigPath) !== normalize(newGlobalPath) &&
-      existsSync(legacyExtConfigPath);
-    const entry = buildResolvedConfigLogEntry({
-      policyPaths,
-      legacyGlobalPolicyDetected,
-      legacyExtensionConfigDetected,
-    });
+    const entry = buildResolvedConfigLogEntry({ policyPaths });
     this.deps.logger.review(
       "config.resolved",
       entry as unknown as Record<string, unknown>,

pi-permission-system/src/extension-config.ts

@@ -1,6 +1,4 @@
 import { mkdirSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
 import {
   normalizeAutoReviewConfig,
   type AutoReviewConfig,
@@ -44,12 +42,6 @@ export const DEFAULT_EXTENSION_CONFIG: PermissionSystemExtensionConfig = {
   doublePressToConfirm: true,
 };
 
-function resolveExtensionRoot(moduleUrl = import.meta.url): string {
-  return join(dirname(fileURLToPath(moduleUrl)), "..");
-}
-
-export const EXTENSION_ROOT = resolveExtensionRoot();
-
 const PERMISSION_POLICY_KEYS: ReadonlySet<string> = new Set([
   "defaultPolicy",
   "tools",

pi-permission-system/src/handlers/gates/descriptor.ts

@@ -7,6 +7,22 @@ import type { PermissionCheckResult, PermissionState } from "#src/types";
 
 // ── Descriptor types ───────────────────────────────────────────────────────
 
+/**
+ * The protected-write match a `humanOnly` descriptor carries: the first
+ * protected target's display facts plus how many additional protected targets
+ * the same call writes.
+ */
+export interface ProtectedWriteTarget {
+  /** First protected target's display path. */
+  readonly path: string;
+  /** The `protectedWrites` pattern that matched it. */
+  readonly pattern: string;
+  /** The pattern's human-facing label. */
+  readonly label: string;
+  /** How many additional protected targets the same call writes. */
+  readonly extraCount: number;
+}
+
 /**
  * Pure output of a gate function — describes what to check and how to present it.
  *
@@ -33,6 +49,15 @@ export interface GateDescriptor {
    * interface — the runner never needs to know which case applies.
    */
   sessionApproval?: SessionApproval;
+  /**
+   * Set only by the protected-write gate: the write must reach the local
+   * human prompt directly — the runner skips the session-approval and yolo
+   * fast paths, the escalation bypasses `authorizerChain` links (AutoReview),
+   * no session-grant option is offered, and a terminal without a local UI
+   * denies without prompting. Carries the first protected target's facts for
+   * the system note and review log.
+   */
+  humanOnly?: ProtectedWriteTarget;
   /**
    * Details passed to the interactive permission prompt.
    *

pi-permission-system/src/handlers/gates/runner.ts

@@ -23,6 +23,7 @@ import {
   deriveResolution,
   resolveYoloGrant,
 } from "./helpers";
+import { protectedWriteDeferNote } from "./protected-write";
 import type { GateOutcome } from "./types";
 
 // ── GateRunner class ───────────────────────────────────────────────────────
@@ -129,8 +130,13 @@ export class GateRunner {
     // context holds what every resolution of this gate shares, and who decided
     // is by definition not shared (#726).
 
+    // A protected-write descriptor never takes the session or yolo fast path:
+    // the write reaches a human prompt even when a session grant covers the
+    // path or yolo mode is on.
+    const humanOnly = descriptor.humanOnly;
+
     // 2. Session-hit fast path
-    if (check.source === "session") {
+    if (!humanOnly && check.source === "session") {
       this.reporter.writeReviewLog("permission_request.session_approved", {
         ...logContext,
         resolution: "session_approved",
@@ -158,7 +164,9 @@ export class GateRunner {
     // "yolo" on the matched rule, #526) or, under yolo, an ask synthesized
     // after resolution (#712). Auto-approve without prompting, preserving the
     // single auto_approved review entry + decision event so log parity holds.
-    const yoloGrant = resolveYoloGrant(check, this.isYoloEnabled());
+    const yoloGrant = humanOnly
+      ? undefined
+      : resolveYoloGrant(check, this.isYoloEnabled());
     if (yoloGrant) {
       this.reporter.writeReviewLog("permission_request.auto_approved", {
         ...logContext,
@@ -208,6 +216,12 @@ export class GateRunner {
           ...(descriptor.sessionApproval
             ? { sessionApproval: descriptor.sessionApproval.toForwardedData() }
             : {}),
+          ...(humanOnly
+            ? {
+                humanOnly: true,
+                deferNotes: [protectedWriteDeferNote(humanOnly)],
+              }
+            : {}),
         });
         autoApproved = decision.autoApproved === true;
         confirmationUnavailable = decision.confirmationUnavailable === true;

pi-permission-system/src/handlers/gates/tool-call-gate-pipeline.ts

@@ -6,6 +6,7 @@ import {
   type ShellInvocation,
 } from "#src/access-intent/tool-kind";
 import type { ShellToolsConfig } from "#src/config-schema";
+import type { ProtectedWriteRule } from "#src/hard-guard-loader";
 import type { PathNormalizer } from "#src/path-normalizer";
 import type { ScopedPermissionResolver } from "#src/permission-resolver";
 import type { SkillPromptEntry } from "#src/skill-prompt-sanitizer";
@@ -20,6 +21,7 @@ import { resolveBashCommandCheck } from "./bash-command";
 import { describeBashPathGate } from "./bash-path";
 import type { GateResult } from "./descriptor";
 import { describePathGate } from "./path";
+import { describeProtectedWriteGate } from "./protected-write";
 import type { GateRunner } from "./runner";
 import { describeSkillReadGate } from "./skill-read";
 import { describeToolGate } from "./tool";
@@ -67,6 +69,8 @@ export class ToolCallGatePipeline {
     private readonly inputs: ToolCallGateInputs,
     private readonly customFormatters?: ToolInputFormatterLookup,
     private readonly customExtractors?: ToolAccessExtractorLookup,
+    private readonly getProtectedWrites: () => readonly ProtectedWriteRule[] = () =>
+      [],
   ) {}
 
   async evaluate(
@@ -119,6 +123,16 @@ export class ToolCallGatePipeline {
         toolDescriptor.preCheck = toolCheck;
         return toolDescriptor;
       },
+      // 5. Protected-write gate — last so ordinary/hard-guard denies from the
+      // producers above block first; its descriptor escalates to the human.
+      () =>
+        describeProtectedWriteGate(
+          tcc,
+          bashProgram,
+          shell,
+          normalizer,
+          this.getProtectedWrites(),
+        ),
     ];
 
     for (const produce of gateProducers) {

pi-permission-system/src/hard-guard-loader.ts

@@ -1,16 +1,72 @@
 import { existsSync, readFileSync, statSync } from "node:fs";
-import { dirname } from "node:path";
-import { fileURLToPath } from "node:url";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import {
   normalizeFlatPermissionValue,
   stripJsonComments,
 } from "./config-loader";
+import { expandHomePath } from "./expand-home";
 import type { PolicyLoader, ResolvedPolicyPaths } from "./policy-loader";
 import type { FlatPermissionConfig, PatternValue, ScopeConfig } from "./types";
 
 interface HardGuardDocument {
   version?: number;
   permission?: unknown;
+  protectedWrites?: unknown;
+}
+
+/**
+ * One entry of the hard-guard file's `protectedWrites` array.
+ *
+ * `pattern` uses the same wildcard syntax as the `path` surface; `{agentDir}`,
+ * `{configHome}` and a leading `~/` are expanded at load time. `label` is the
+ * human-facing name shown by the protected-write prompt and review log.
+ */
+export interface ProtectedWriteRule {
+  readonly pattern: string;
+  readonly label: string;
+}
+
+function configHome(): string {
+  const xdg = process.env.XDG_CONFIG_HOME;
+  return xdg && xdg.trim() !== "" ? xdg : join(homedir(), ".config");
+}
+
+function expandProtectedWritePattern(pattern: string): string {
+  return expandHomePath(
+    pattern
+      .replaceAll("{agentDir}", getAgentDir())
+      .replaceAll("{configHome}", configHome()),
+  );
+}
+
+function parseProtectedWrites(value: unknown): ProtectedWriteRule[] {
+  if (value === undefined) return [];
+  if (!Array.isArray(value)) {
+    throw new Error("hard guard 'protectedWrites' must be an array");
+  }
+  return value.map((entry, index) => {
+    const record =
+      typeof entry === "object" && entry !== null
+        ? (entry as Record<string, unknown>)
+        : undefined;
+    if (
+      !record ||
+      typeof record.pattern !== "string" ||
+      record.pattern.trim() === "" ||
+      typeof record.label !== "string" ||
+      record.label.trim() === ""
+    ) {
+      throw new Error(
+        `hard guard 'protectedWrites[${index}]' must be { "pattern": string, "label": string }`,
+      );
+    }
+    return {
+      pattern: expandProtectedWritePattern(record.pattern),
+      label: record.label,
+    };
+  });
 }
 
 const EMPTY_SCOPE: ScopeConfig = {};
@@ -38,7 +94,10 @@ function assertHardGuardValues(permission: FlatPermissionConfig): void {
   }
 }
 
-function readHardGuards(path: string): ScopeConfig {
+function readHardGuards(path: string): {
+  scope: ScopeConfig;
+  protectedWrites: ProtectedWriteRule[];
+} {
   const parsed = JSON.parse(stripJsonComments(readFileSync(path, "utf8"))) as HardGuardDocument;
   if (parsed.version !== undefined && parsed.version !== 1) {
     throw new Error(`unsupported hard guard version: ${String(parsed.version)}`);
@@ -48,24 +107,23 @@ function readHardGuards(path: string): ScopeConfig {
     throw new Error("hard guard permission must be an object");
   }
   assertHardGuardValues(normalized);
-  return { permission: { "*": "allow", ...normalized } };
+  return {
+    scope: { permission: { "*": "allow", ...normalized } },
+    protectedWrites: parseProtectedWrites(parsed.protectedWrites),
+  };
 }
 
 /**
- * Global-only hard boundary: deny rules plus same-file allow exceptions. It keeps the last valid snapshot and
- * falls back to the bundled defaults; if both are invalid it denies all.
+ * Global-only hard boundary: deny rules plus same-file allow exceptions. It keeps the last valid snapshot;
+ * when the bundle config file is missing or invalid it fails closed to deny-all.
  */
 export class HardGuardPolicyLoader implements PolicyLoader {
   private lastStamp = "";
   private lastGood: ScopeConfig | undefined;
+  private lastGoodProtectedWrites: ProtectedWriteRule[] = [];
   private issues: string[] = [];
 
-  constructor(
-    private readonly userPath: string,
-    private readonly fallbackPath = fileURLToPath(
-      new URL("../config/hard-guards.default.jsonc", import.meta.url),
-    ),
-  ) {}
+  constructor(private readonly userPath: string) {}
 
   loadGlobalConfig(): ScopeConfig {
     const stamp = this.getCacheStamp();
@@ -73,15 +131,15 @@ export class HardGuardPolicyLoader implements PolicyLoader {
     this.lastStamp = stamp;
     this.issues = [];
 
-    for (const candidate of [this.userPath, this.fallbackPath]) {
-      if (!existsSync(candidate)) continue;
+    if (existsSync(this.userPath)) {
       try {
-        const loaded = readHardGuards(candidate);
-        this.lastGood = loaded;
-        return loaded;
+        const loaded = readHardGuards(this.userPath);
+        this.lastGood = loaded.scope;
+        this.lastGoodProtectedWrites = loaded.protectedWrites;
+        return loaded.scope;
       } catch (error) {
         const message = error instanceof Error ? error.message : String(error);
-        this.issues.push(`Failed to load hard guards '${candidate}': ${message}`);
+        this.issues.push(`Failed to load hard guards '${this.userPath}': ${message}`);
       }
     }
 
@@ -90,21 +148,27 @@ export class HardGuardPolicyLoader implements PolicyLoader {
     return DENY_ALL;
   }
 
+  /**
+   * The `protectedWrites` snapshot of the last valid file (empty when the file
+   * was never valid — in which case every request is already denied). Reloads
+   * through the same mtime cache stamp as {@link loadGlobalConfig}.
+   */
+  getProtectedWrites(): ProtectedWriteRule[] {
+    this.loadGlobalConfig();
+    return [...this.lastGoodProtectedWrites];
+  }
+
   loadAgentConfig(): ScopeConfig { return EMPTY_SCOPE; }
   loadProjectAgentConfig(): ScopeConfig { return EMPTY_SCOPE; }
   getConfiguredMcpServerNames(): readonly string[] { return []; }
 
   getCacheStamp(): string {
-    return [this.userPath, this.fallbackPath]
-      .map((path) => {
-        try {
-          const stat = statSync(path);
-          return `${path}:${stat.mtimeMs}:${stat.size}`;
-        } catch {
-          return `${path}:missing`;
-        }
-      })
-      .join("|");
+    try {
+      const stat = statSync(this.userPath);
+      return `${this.userPath}:${stat.mtimeMs}:${stat.size}`;
+    } catch {
+      return `${this.userPath}:missing`;
+    }
   }
 
   getConfigIssues(): string[] { return [...this.issues]; }

pi-permission-system/src/index.ts

@@ -55,8 +55,14 @@ import { SessionRules } from "./session-rules";
 import { ToolAccessExtractorRegistry } from "./tool-access-extractor-registry";
 import { ToolInputFormatterRegistry } from "./tool-input-formatter-registry";
 
-export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
+export default function piPermissionSystemExtension(
+  pi: ExtensionAPI,
+  options?: { configPath?: string; hardGuardConfigPath?: string },
+): void {
   const agentDir = getAgentDir();
+  const globalConfigPath = options?.configPath ?? getGlobalConfigPath();
+  const hardGuardConfigPath =
+    options?.hardGuardConfigPath ?? getHardGuardConfigPath();
   const paths = computeExtensionPaths(agentDir);
   // The single process.platform read for the whole extension, resolved once
   // into the path-language flavor that every consumer shares (the session's
@@ -101,6 +107,7 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
 
   const permissionManager = new PermissionManager({
     agentDir,
+    globalConfigPath,
     flavor: hostFlavor,
     isYoloEnabled,
   });
@@ -115,6 +122,7 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
     agentDir,
     policyPaths: permissionManager,
     logger,
+    configPath: globalConfigPath,
   });
 
   const prompter = new PermissionPrompter({ logger });
@@ -164,8 +172,9 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
   // access-path → path-values unwrap. Constructed here (before `session`) so
   // the forwarded-request server's ServingPolicy can resolve against it; the
   // service and gates below share this one instance.
+  const hardGuardLoader = new HardGuardPolicyLoader(hardGuardConfigPath);
   const hardGuardManager = new PermissionManager({
-    policyLoader: new HardGuardPolicyLoader(getHardGuardConfigPath(agentDir)),
+    policyLoader: hardGuardLoader,
     flavor: hostFlavor,
   });
   const resolver = new PermissionResolver(
@@ -224,7 +233,7 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
   // scope (fail closed); session_start reloads with the real trust decision.
   configStore.refresh(undefined, false);
 
-  const configPath = getGlobalConfigPath(agentDir);
+  const configPath = globalConfigPath;
   registerPermissionSystemCommand(pi, {
     config: configStore,
     configPath,
@@ -295,6 +304,7 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
     session,
     formatterRegistry,
     accessExtractorRegistry,
+    () => hardGuardLoader.getProtectedWrites(),
   );
   const skillInputGatePipeline = new SkillInputGatePipeline(resolver);
   const gates = new PermissionGateHandler(

pi-permission-system/src/permission-manager.ts

@@ -108,6 +108,7 @@ export interface PermissionManagerOptions extends PolicyLoaderOptions {
 
 export class PermissionManager implements ScopedPermissionManager {
   private readonly agentDir: string | undefined;
+  private readonly globalConfigPath: string;
   private readonly flavor: PathFlavor;
   private readonly isYoloEnabled: () => boolean;
   private loader: PolicyLoader;
@@ -118,13 +119,18 @@ export class PermissionManager implements ScopedPermissionManager {
 
   constructor(options: PermissionManagerOptions = {}) {
     this.agentDir = options.agentDir;
+    this.globalConfigPath = options.globalConfigPath ?? getGlobalConfigPath();
     this.flavor = options.flavor ?? posixPathFlavor;
     this.isYoloEnabled = options.isYoloEnabled ?? YOLO_DISABLED;
     this.loader =
       options.policyLoader ??
       new FilePolicyLoader(
         options.agentDir !== undefined
-          ? derivePolicyLoaderOptions(options.agentDir, undefined)
+          ? derivePolicyLoaderOptions(
+              options.agentDir,
+              undefined,
+              this.globalConfigPath,
+            )
           : options,
       );
   }
@@ -139,7 +145,7 @@ export class PermissionManager implements ScopedPermissionManager {
   configureForCwd(cwd: string | undefined | null): void {
     if (this.agentDir !== undefined) {
       this.loader = new FilePolicyLoader(
-        derivePolicyLoaderOptions(this.agentDir, cwd),
+        derivePolicyLoaderOptions(this.agentDir, cwd, this.globalConfigPath),
       );
     }
     this.resolvedPermissionsCache.clear();
@@ -372,9 +378,10 @@ function buildCheckResult(
 function derivePolicyLoaderOptions(
   agentDir: string,
   cwd: string | undefined | null,
+  globalConfigPath: string = getGlobalConfigPath(),
 ): PolicyLoaderOptions {
   return {
-    globalConfigPath: getGlobalConfigPath(agentDir),
+    globalConfigPath,
     agentsDir: join(agentDir, "agents"),
     projectAgentsDir: cwd ? getProjectAgentsDir(cwd) : undefined,
   };

pi-permission-system/src/policy-loader.ts

@@ -101,7 +101,7 @@ export interface PolicyLoader {
 // ---------------------------------------------------------------------------
 
 function defaultGlobalConfigPath(): string {
-  return getGlobalConfigPath(getAgentDir());
+  return getGlobalConfigPath();
 }
 function defaultAgentsDir(): string {
   return join(getAgentDir(), "agents");