@gotgenes/pi-permission-system 39.0.2 → 39.0.4

package/CHANGELOG.md

@@ -5,6 +5,26 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [39.0.4](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v39.0.3...pi-permission-system-v39.0.4) (2026-10-05)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** show a broken config file's error once, not twice, at session start ([67ddf4f](https://github.com/gotgenes/pi-packages/commit/67ddf4f637bd6f4e15246093dc3d1c459552c7f2)), closes [#953](https://github.com/gotgenes/pi-packages/issues/953)
+* **pi-permission-system:** report a policy file that fails closed mid-session ([100a0d3](https://github.com/gotgenes/pi-packages/commit/100a0d3e1b49c92454163b270df52df7cc78ca1f)), closes [#953](https://github.com/gotgenes/pi-packages/issues/953)
+
+## [39.0.3](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v39.0.2...pi-permission-system-v39.0.3) (2026-10-03)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** match a home-prefixed bash rule against a command typed with ~ or $HOME ([af2d24a](https://github.com/gotgenes/pi-packages/commit/af2d24af90e77156cc7a58b5a75d70d1154cce3c)), closes [#981](https://github.com/gotgenes/pi-packages/issues/981)
+
+### Documentation
+
+* **pi-permission-system:** document bash command spellings ([e6cd84f](https://github.com/gotgenes/pi-packages/commit/e6cd84fe1ff5fa3ab7938f576ace1e574cc46409)), closes [#981](https://github.com/gotgenes/pi-packages/issues/981)
+* **pi-permission-system:** accept the HOME-rebinding residual for bash command spellings ([3c787e4](https://github.com/gotgenes/pi-packages/commit/3c787e43e79400fd132cbb6597c51c0448e2b39a)), closes [#981](https://github.com/gotgenes/pi-packages/issues/981)
+
 ## [39.0.2](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v39.0.1...pi-permission-system-v39.0.2) (2026-10-03)
 
 

package/docs/configuration.md

@@ -451,6 +451,8 @@ A quoted heredoc delimiter (`<<'EOF'` or `<<"EOF"`) does not interpolate, so its
 The enclosing command is still matched without its redirect, so a rule like `npm install` keeps matching `npm install > out.txt`.
 Control-flow bodies (`if`/`while`/`for`/`case`) and `{ … }` brace groups are not descended into; their contents are matched as part of the enclosing statement's text.
 
+A command that starts with `~`, `$HOME`, or `${HOME}` also matches a home-anchored pattern spelled any of those ways, or with the absolute home directory (see [Home Directory Expansion in Patterns](#home-directory-expansion-in-patterns)).
+
 A leading environment-variable assignment prefix is stripped before matching, so the rule gates the underlying command rather than the prefix.
 So `AWS_PROFILE=prod aws ec2 …` is matched as `aws ec2 …` — a `aws *` rule applies even though the invocation begins with `AWS_PROFILE=`.
 Prefixes like `PGPASSWORD=` and `KUBECONFIG=` are handled the same way.
@@ -1120,6 +1122,21 @@ Path **values** supplied by bash commands and extension tools are expanded the s
 This means `~/...`, `$HOME/...`, `${HOME}/...`, and the fully-expanded absolute form all match a single home-anchored pattern: `cat ~/.ssh/config`, `cat $HOME/.ssh/config`, or `cat /Users/me/.ssh/config` is caught by a `"~/.ssh/*": "deny"` rule.
 Pi's built-in file tools expand only `~`, as Pi itself does: a `read` of `~/.ssh/config` or `/Users/me/.ssh/config` is caught, while a `read` of `$HOME/.ssh/config` opens `<cwd>/$HOME/.ssh/config` and is matched as that file.
 
+A `bash` command that **starts** with a home prefix matches a home-anchored command pattern the same way.
+With `"~/bin/tool *": "deny"`, the commands `~/bin/tool --now`, `$HOME/bin/tool --now`, `${HOME}/bin/tool --now`, and `/Users/me/bin/tool --now` are all denied, and an allow written with `~` covers each of those spellings too.
+The command is still shown, logged, and offered for session approval as typed.
+Three limits apply:
+
+- On Windows, a home-anchored `bash` pattern is compiled with backslash separators, so it matches only a command typed with the backslashed absolute path ([issue #1020](https://github.com/gotgenes/pi-packages/issues/1020)).
+- A command that reassigns `HOME` earlier in the same invocation (`HOME=/tmp/x; ~/bin/tool`, or a `HOME=/tmp/x` prefix) is matched only as typed, because its `~` no longer names your home directory.
+  A reassignment the parser cannot see, such as one through a variable holding the name (`n=HOME; read $n`), is not detected, so the command still matches your home-anchored rules.
+  Writing a command that way takes deliberate effort to evade a rule; run an agent you would not trust with that inside a sandbox rather than relying on command patterns.
+- A home prefix later in the command, in argument position, is matched as typed: a pattern `cat ~/notes` matches the command `cat ~/notes` but not `cat /Users/me/notes`.
+  Gate file access by any spelling on the `path` and `external_directory` surfaces instead.
+
+The `bash` surface matches text, so a `*` in a home-anchored pattern also matches `..`: `~/bin/*` allows `~/bin/../../tmp/x`, exactly as it allows `/Users/me/bin/../../tmp/x`.
+Anchor an allow on the full command (`~/bin/tool *`) rather than a directory wildcard when that matters.
+
 ---
 
 ## Per-Agent Overrides

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-permission-system",
-  "version": "39.0.2",
+  "version": "39.0.4",
   "description": "Permission enforcement extension for the Pi coding agent.",
   "type": "module",
   "exports": {

package/src/access-intent/access-intent.ts

@@ -52,16 +52,48 @@ export interface AccessPathAccessIntent {
   agentName?: string;
 }
 
-/** What a gate emits — a raw tool input or an `AccessPath`. */
-export type AccessIntent = ToolAccessIntent | AccessPathAccessIntent;
+/** What a gate emits: a raw tool input, an `AccessPath`, or a bash command unit. */
+export type AccessIntent =
+  | ToolAccessIntent
+  | AccessPathAccessIntent
+  | BashCommandAccessIntent;
+
+/**
+ * One bash command unit, with the other spellings the shell runs identically.
+ *
+ * `command` is the unit as typed: the prompt, the decision value, and the
+ * session-approval suggestion read it. `spellings` come from the program
+ * analysis, the only party that knows what a spelling means in this program
+ * (a `~` names the startup home only while the program leaves `HOME` alone),
+ * and the manager evaluates them with `command` as aliases of one invocation:
+ * the last rule matching any of them decides.
+ *
+ * String-only, so it stays on the manager's side of the ADR-0002 boundary.
+ */
+export interface BashCommandAccessIntent {
+  kind: "bash-command";
+  /**
+   * Always `"bash"`. Typed `string` because the resolver re-surfaces every
+   * intent across a surface family (`{ ...intent, surface }`); `bash` is never
+   * a family, so that never happens to this one.
+   */
+  surface: string;
+  command: string;
+  spellings: readonly string[];
+  agentName?: string;
+}
 
 /**
  * What the manager consumes — the `access-path` variant has already been
- * unwrapped to `path-values` by the resolver via `path.matchValues()`.
+ * unwrapped to `path-values` by the resolver via `path.matchValues()`; a
+ * `bash-command` intent passes through as emitted.
  *
  * The manager stays string-based and never imports `AccessPath`: this is the
  * deliberate boundary formalized in ADR-0002
  * (`docs/decisions/0002-path-values-string-boundary.md`), guarded by a
  * `no-restricted-imports` lint rule on `permission-manager.ts`.
  */
-export type ResolvedAccessIntent = ToolAccessIntent | PathValuesAccessIntent;
+export type ResolvedAccessIntent =
+  | ToolAccessIntent
+  | PathValuesAccessIntent
+  | BashCommandAccessIntent;

package/src/access-intent/bash/command-enumeration.ts

@@ -73,6 +73,15 @@ export interface BashCommand {
    * unreachable.
    */
   readonly salvaged?: true;
+  /**
+   * Other spellings of {@link text} the shell runs identically, matched with
+   * it as aliases of one invocation. Absent when there are none.
+   *
+   * Today the only spelling is the home-expanded one, for a unit whose text
+   * opens with `~`, `$HOME`, or `${HOME}` in a program that leaves `HOME`
+   * alone ({@link WordReader.spellHomeAtStart}).
+   */
+  readonly spellings?: readonly string[];
 }
 
 /**
@@ -409,19 +418,23 @@ function unresolvedScope(node: TSNode, scope: UnitScope): UnitScope {
     : scope;
 }
 
-/** The wrapper facts a `command` node's words establish about its unit. */
-interface WrapperFacts {
+/**
+ * The facts a `command` node's words establish about its unit: the three
+ * wrapper answers, and the other spellings its text has.
+ */
+interface UnitFacts {
   readonly wrapperKind?: WrapperKind;
   readonly executedUnit?: string;
   readonly floorExemption?: FloorExemption;
+  readonly spellings?: readonly string[];
 }
 
 function makeUnit(
   text: string,
   scope: UnitScope,
-  wrapper: WrapperFacts = {},
+  facts: UnitFacts = {},
 ): BashCommand {
-  const { wrapperKind, executedUnit, floorExemption } = wrapper;
+  const { wrapperKind, executedUnit, floorExemption, spellings } = facts;
   const scoped: BashCommand = scope.context
     ? { text, context: scope.context }
     : { text };
@@ -433,7 +446,10 @@ function makeUnit(
   const marked: BashCommand = scope.parseUnresolved
     ? { ...exempted, parseUnresolved: true }
     : exempted;
-  return scope.salvaged ? { ...marked, salvaged: true } : marked;
+  const salvaged: BashCommand = scope.salvaged
+    ? { ...marked, salvaged: true }
+    : marked;
+  return spellings === undefined ? salvaged : { ...salvaged, spellings };
 }
 
 /**
@@ -447,7 +463,9 @@ function makeUnit(
  */
 function makeCommandUnit(node: TSNode, scope: UnitScope): BashCommand {
   const { text, words } = readCommandUnit(node, scope.words);
+  const homeSpelling = scope.words.spellHomeAtStart(text);
   return makeUnit(text, scope, {
+    spellings: homeSpelling === undefined ? undefined : [homeSpelling],
     wrapperKind: classifyWrapperWords(words),
     executedUnit: executedUnitOf(text, words) ?? undefined,
     floorExemption: isTransparentWrapper(words, redirectedScope(node, scope))

package/src/access-intent/bash/node-text.ts

@@ -102,6 +102,11 @@ export class WordReader {
   spellsReboundHome(token: string): boolean {
     return this.variables.spellsReboundHome(token);
   }
+
+  /** A command unit's text with its leading home prefix spelled out ({@link ShellVariables.spellHomeAtStart}). */
+  spellHomeAtStart(text: string): string | undefined {
+    return this.variables.spellHomeAtStart(text);
+  }
 }
 
 /**

package/src/access-intent/bash/shell-variable-expansion.ts

@@ -17,7 +17,7 @@
  * See `docs/decisions/0009-bash-path-projection-completeness-contract.md`.
  */
 import { homedir } from "node:os";
-import { hasHomePrefix } from "#src/path/expand-home";
+import { hasHomePrefix, splitHomePrefix } from "#src/path/expand-home";
 
 import type { TSNode } from "./parser";
 
@@ -87,6 +87,24 @@ export class ShellVariables {
     return this.rebound.has("HOME") && hasHomePrefix(token);
   }
 
+  /**
+   * `text` with a leading `~` / `$HOME` / `${HOME}` spelled as the startup
+   * home, or `undefined` when it opens with none or the program rebinds `HOME`.
+   *
+   * The complement of {@link spellsReboundHome}: the spelling a command-pattern
+   * rule written with a home prefix is compiled to, so the rule matches the
+   * command as the shell runs it. The rest is kept verbatim, never
+   * path-normalized, because `..` in an argument is not a path step of the
+   * command's name. A backslash after the prefix gets none, because bash does
+   * not expand a tilde prefix holding a quoted character.
+   */
+  spellHomeAtStart(text: string): string | undefined {
+    if (this.rebound.has("HOME")) return undefined;
+    const rest = splitHomePrefix(text);
+    if (rest === undefined || rest.startsWith("\\")) return undefined;
+    return homedir() + rest;
+  }
+
   /**
    * How a word's leading unquoted text expands when it opens with a tilde
    * prefix that reads `HOME` (`~` or `~/…`; `~user` reads the password

package/src/access-intent/input-normalizer.ts

@@ -125,10 +125,10 @@ export interface NormalizedInput {
   surface: string;
   /**
    * Alternative lookup names for this one access, most-specific first.
-   * MCP is the only surface producing more than one; every other surface
-   * produces a single-element array. Order does not decide which rule wins
-   * (rule position does) — it decides which name the decision is reported
-   * under when the winning rule matches several.
+   * MCP targets and a bash command's spellings are the only sources of more
+   * than one; every other surface produces a single-element array. Order does
+   * not decide which rule wins (rule position does); it decides which name the
+   * decision is reported under when the winning rule matches several.
    */
   values: string[];
   /**
@@ -175,16 +175,7 @@ export function normalizeInput(
     case "bash": {
       const record = toRecord(input);
       const command = typeof record.command === "string" ? record.command : "";
-      // Strip leading shell comment lines so pattern matching operates on the
-      // actual command, not a `# description` prefix agents often prepend.
-      // Fall back to the raw command when stripping leaves nothing, so an
-      // all-comment command still evaluates against its literal text.
-      const matchValue = stripBashCommentLines(command) || command;
-      return {
-        surface: "bash",
-        values: [matchValue],
-        resultExtras: { command },
-      };
+      return normalizeBashCommand(command, []);
     }
 
     // --- MCP ---
@@ -226,3 +217,26 @@ function normalizeMcpTargets(targets: readonly string[]): NormalizedInput {
     resultExtras: { target: values[0] },
   };
 }
+
+/**
+ * The `bash` surface's normalized form: the command as typed, then the other
+ * spellings the shell runs identically, matched as aliases of one invocation.
+ *
+ * Leading shell comment lines are stripped from the typed command so pattern
+ * matching operates on the actual command, not a `# description` prefix agents
+ * often prepend; when stripping leaves nothing, an all-comment command still
+ * evaluates against its literal text. A spelling comes from the program
+ * analysis and is matched as given. `command` stays the typed text, because the
+ * prompt, the decision value, and the session-approval suggestion read it.
+ */
+export function normalizeBashCommand(
+  command: string,
+  spellings: readonly string[],
+): NormalizedInput {
+  const matchValue = stripBashCommentLines(command) || command;
+  return {
+    surface: "bash",
+    values: [...new Set([matchValue, ...spellings])],
+    resultExtras: { command },
+  };
+}

package/src/config/config-store.ts

@@ -101,7 +101,7 @@ export class ConfigStore
    *
    * This store answers; `ConfigIssueReporter` decides whether the operator has
    * heard it yet (#933). Not to be confused with
-   * `PermissionResolver.getConfigIssues(agentName?)`, which answers for the
+   * `PermissionResolver.getPolicyIssues(agentName?)`, which answers for the
    * *policy* files rather than the extension config.
    */
   getConfigIssues(): readonly string[] {

package/src/config/policy-issue-reporter.ts

@@ -0,0 +1,55 @@
+/**
+ * policy-issue-reporter.ts — Tell the operator what composing their policy
+ * revealed, once per notice, for as long as it holds.
+ *
+ * The policy side answers only what it alone knows: the fail-closed notice for
+ * a rejected non-global scope (its `allow` rules are clamped to `ask`) and the
+ * port notice for relocated MCP tool keys. A config file's own schema errors
+ * are `ConfigIssueReporter`'s; both reporters reading them showed the operator
+ * each one twice (#953).
+ *
+ * Policy is re-read from file mtimes whenever it is consulted, so a file broken
+ * mid-session is clamped mid-session. Reporting only at `session_start` left
+ * that clamp unexplained; this is driven there and on every
+ * `before_agent_start`, so the operator hears about it on the next turn.
+ *
+ * The notices are agent-scoped, so the agent name is an argument rather than
+ * something this reads for itself: `AgentPrepHandler` resolves it from the
+ * `<active_agent>` prompt tag — the only name a pi-subagents child has — after
+ * turn prep runs, and hands it here.
+ *
+ * The latch is `ConfigIssueReporter`'s: per notice, delivered as one joined
+ * message per report, and *replaced* each report rather than added to — so a
+ * file fixed and broken again, or an agent switched away from and back into
+ * with a broken scope, is announced again.
+ */
+
+import type { ConfigIssueWarner } from "./config-issue-reporter";
+
+/** The policy seam this reads (ISP): the notices composing an agent's policy produced. */
+export interface PolicyIssueSource {
+  getPolicyIssues(agentName?: string): readonly string[];
+}
+
+/** The seam the session-start and agent-prep handlers drive. */
+export interface PolicyIssueReporting {
+  report(agentName: string | undefined): void;
+}
+
+export class PolicyIssueReporter implements PolicyIssueReporting {
+  private reported: ReadonlySet<string> = new Set();
+
+  constructor(
+    private readonly source: PolicyIssueSource,
+    private readonly log: ConfigIssueWarner,
+  ) {}
+
+  report(agentName: string | undefined): void {
+    const current = this.source.getPolicyIssues(agentName);
+    const unreported = current.filter((issue) => !this.reported.has(issue));
+    if (unreported.length > 0) {
+      this.log.warn(unreported.join("\n"));
+    }
+    this.reported = new Set(current);
+  }
+}

package/src/config/policy-loader.ts

@@ -81,8 +81,8 @@ export interface ResolvedPolicyPaths {
 
 /**
  * Abstraction over file I/O for loading permission policy from disk.
- * Implementations handle caching, path resolution, and config-issue
- * accumulation.  `PermissionManager` depends on this interface so that
+ * Implementations handle caching, path resolution, and marking a rejected
+ * scope `invalid`.  `PermissionManager` depends on this interface so that
  * merge + evaluation logic can be tested with an in-memory stub.
  */
 export interface PolicyLoader {
@@ -93,8 +93,6 @@ export interface PolicyLoader {
   getConfiguredMcpServerNames(): readonly string[];
   /** Combined mtime stamp for cache invalidation. */
   getCacheStamp(agentName?: string): string;
-  /** Accumulated config-parse issues across all loads. */
-  getConfigIssues(): string[];
   /** Resolved paths for the /permission-system show command. */
   getResolvedPolicyPaths(): ResolvedPolicyPaths;
 }
@@ -172,7 +170,6 @@ export class FilePolicyLoader implements PolicyLoader {
   private configuredMcpServerNamesCache: FileCacheEntry<
     readonly string[]
   > | null = null;
-  private accumulatedConfigIssues: string[] = [];
 
   constructor(options: PolicyLoaderOptions = {}) {
     this.globalConfigPath =
@@ -194,21 +191,11 @@ export class FilePolicyLoader implements PolicyLoader {
       : null;
   }
 
-  // ── Config issue accumulation ────────────────────────────────────────
-
-  private accumulateConfigIssues(issues: string[]): void {
-    for (const issue of issues) {
-      if (!this.accumulatedConfigIssues.includes(issue)) {
-        this.accumulatedConfigIssues.push(issue);
-      }
-    }
-  }
-
-  getConfigIssues(): string[] {
-    return [...this.accumulatedConfigIssues];
-  }
-
   // ── Scope loaders ────────────────────────────────────────────────────
+  //
+  // A config file's schema errors are not kept here: `ConfigStore` loads the
+  // same files through the same `loadUnifiedConfig` and reports them, so this
+  // loader reads them only to decide whether a scope fails closed (#953).
 
   loadGlobalConfig(): ScopeConfig {
     const stamp = getFileStamp(this.globalConfigPath);
@@ -216,8 +203,7 @@ export class FilePolicyLoader implements PolicyLoader {
       return this.globalConfigCache.value;
     }
 
-    const { config, issues } = loadUnifiedConfig(this.globalConfigPath);
-    this.accumulateConfigIssues(issues);
+    const { config } = loadUnifiedConfig(this.globalConfigPath);
 
     const value: ScopeConfig = {
       permission: config.permission,
@@ -238,7 +224,6 @@ export class FilePolicyLoader implements PolicyLoader {
     }
 
     const { config, issues } = loadUnifiedConfig(this.projectGlobalConfigPath);
-    this.accumulateConfigIssues(issues);
 
     // A present-but-rejected file yields issues (parse error or schema
     // rejection); an absent file yields none. Fail closed on the former.

package/src/handlers/before-agent-start.ts

@@ -4,6 +4,7 @@ import type {
   NormalizedBuildSystemPromptOptions,
 } from "@earendil-works/pi-coding-agent";
 import type { SubagentDetector } from "#src/authority/subagent-detection";
+import type { PolicyIssueReporting } from "#src/config/policy-issue-reporter";
 import {
   visibleSkillPromptEntries,
   withoutDeniedSkills,
@@ -78,6 +79,10 @@ export function shouldExposeTool(
  * - `logger` — records each change to the effective tool surface
  * - `detector` — tells a subagent child from a root, which decides whether a
  *   custom prompt gets this node's tool surface
+ * - `policyIssues` — reports what composing policy revealed for the agent the
+ *   prompt names; driven here rather than in turn prep because the
+ *   `<active_agent>` tag, the only name a pi-subagents child has, is read here
+ *   (#953)
  *
  * The active set is recomputed from the session's pre-filter tool surface
  * every turn, so relaxing a rule restores the tool it had withheld (#873).
@@ -90,6 +95,7 @@ export class AgentPrepHandler {
     private readonly toolRegistry: ToolRegistry,
     private readonly logger: DebugLogger,
     private readonly detector: SubagentDetector,
+    private readonly policyIssues: PolicyIssueReporting,
   ) {}
 
   // eslint-disable-next-line @typescript-eslint/require-await
@@ -105,6 +111,9 @@ export class AgentPrepHandler {
         ? event.systemPrompt
         : event.systemPrompt.join("\n");
     const agentName = this.session.resolveAgentName(ctx, systemPrompt);
+    // Policy is re-read by mtime, so this turn may compose a clamp the file
+    // just caused; say so for the agent this turn runs as.
+    this.policyIssues.report(agentName ?? undefined);
     const registered = readRegisteredTools(this.toolRegistry.getAll());
     const surface = this.session.resolveExposedTools(
       this.observeToolSurface(registered),

package/src/handlers/gates/bash-command.ts

@@ -75,7 +75,7 @@ export function resolveBashCommandCheck(
   resolver: ScopedPermissionResolver,
 ): PermissionCheckResult {
   if (isTriviallyEmptyCommand(command)) {
-    return resolveOnBashSurface(command, agentName, resolver);
+    return resolveOnBashSurface(command, [], agentName, resolver);
   }
 
   if (!commands.some((cmd) => cmd.salvaged !== true)) {
@@ -86,7 +86,7 @@ export function resolveBashCommandCheck(
     // from the wreckage: `> f <<'M' 2>&1 | rm -rf /tmp/x` has zero primary
     // units and one salvaged one, and keying the check on the combined list
     // would silently drop a `deny` the pre-salvage gate reached (#875).
-    const whole = resolveOnBashSurface(command, agentName, resolver);
+    const whole = resolveOnBashSurface(command, [], agentName, resolver);
     if (whole.state === "deny") {
       return whole;
     }
@@ -107,7 +107,7 @@ export function resolveBashCommandCheck(
   );
   return (
     pickMostRestrictive(results) ??
-    resolveOnBashSurface(command, agentName, resolver)
+    resolveOnBashSurface(command, [], agentName, resolver)
   );
 }
 
@@ -122,7 +122,12 @@ function resolveCommandUnit(
   agentName: string | undefined,
   resolver: ScopedPermissionResolver,
 ): PermissionCheckResult {
-  const base = resolveOnBashSurface(cmd.text, agentName, resolver);
+  const base = resolveOnBashSurface(
+    cmd.text,
+    cmd.spellings ?? [],
+    agentName,
+    resolver,
+  );
   const floored =
     cmd.wrapperKind && base.state === "allow"
       ? resolveWrapperUnit(cmd, cmd.wrapperKind, base, agentName, resolver)
@@ -204,7 +209,7 @@ function resolveWrapperUnit(
   // `command`, and naming a fragment of the command line there would offer a
   // grant that does not cover what the user is looking at.
   return {
-    ...resolveOnBashSurface(inner, agentName, resolver),
+    ...resolveOnBashSurface(inner, [], agentName, resolver),
     command: base.command,
     floorExemption: cmd.floorExemption,
   };
@@ -225,21 +230,26 @@ function isTriviallyEmptyCommand(command: string): boolean {
 }
 
 /**
- * Resolve one command string against the `bash` surface's rules.
+ * Resolve one command string, and the other spellings the shell runs it by,
+ * against the `bash` surface's rules.
  *
  * Three callers share it: each command unit of the chain, the whole command
  * when the chain yields no units, and the inner command of a wrapper the floor
- * no longer covers.
+ * no longer covers. Only a unit has spellings: they come from the program
+ * analysis that produced it, and the whole command or a wrapper's inner text
+ * has no unit of its own to carry them.
  */
 function resolveOnBashSurface(
   command: string,
+  spellings: readonly string[],
   agentName: string | undefined,
   resolver: ScopedPermissionResolver,
 ): PermissionCheckResult {
   return resolver.resolve({
-    kind: "tool",
+    kind: "bash-command",
     surface: "bash",
-    input: { command },
+    command,
+    spellings,
     agentName,
   });
 }

package/src/handlers/lifecycle.ts

@@ -1,10 +1,10 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { AskDialogRelease } from "#src/authority/ask-dialog-queue";
 import type { ConfigIssueReporting } from "#src/config/config-issue-reporter";
+import type { PolicyIssueReporting } from "#src/config/policy-issue-reporter";
 import { PERMISSION_SYSTEM_STATUS_KEY } from "#src/config/status";
 import type { DecisionSummaryWriter } from "#src/logging/decision-audit";
 import type { SessionLogger } from "#src/logging/session-logger";
-import type { PermissionResolver } from "#src/policy/permission-resolver";
 import type { ServiceLifecycle } from "#src/service/service-lifecycle";
 import type { PermissionSession } from "#src/session/permission-session";
 
@@ -41,7 +41,9 @@ export const UNTRUSTED_PROJECT_MESSAGE =
  *
  * Constructor deps:
  * - `session` — encapsulates all mutable session state and lifecycle operations
- * - `resolver` — owns permission-query surface: `getConfigIssues`
+ * - `policyIssues` — reports what composing policy revealed (a fail-closed clamp,
+ *   a port notice) for the agent the session names, latched per notice; driven
+ *   here and on every turn, so a clamp caused mid-session is explained (#953)
  * - `serviceLifecycle` — owns the process-global service publication;
  *   `activate` publishes (skipped for registered subagent children) and emits
  *   the ready event; `teardown` unsubscribes all session listeners and unpublishes
@@ -56,7 +58,7 @@ export const UNTRUSTED_PROJECT_MESSAGE =
 export class SessionLifecycleHandler {
   constructor(
     private readonly session: PermissionSession,
-    private readonly resolver: PermissionResolver,
+    private readonly policyIssues: PolicyIssueReporting,
     private readonly serviceLifecycle: ServiceLifecycle,
     private readonly logger: SessionLogger,
     private readonly audit: DecisionSummaryWriter,
@@ -84,10 +86,7 @@ export class SessionLifecycleHandler {
     }
 
     const agentName = this.session.resolveAgentName(ctx);
-    const policyIssues = this.resolver.getConfigIssues(agentName ?? undefined);
-    for (const issue of policyIssues) {
-      this.logger.warn(issue);
-    }
+    this.policyIssues.report(agentName ?? undefined);
 
     if (event.reason === "reload") {
       this.logger.debug("lifecycle.reload", {

package/src/index.ts

@@ -41,6 +41,7 @@ import { ConfigStore } from "#src/config/config-store";
 import { resolveDialogKeys } from "#src/config/dialog-keys";
 import { isYoloModeEnabled } from "#src/config/extension-config";
 import { computeExtensionPaths } from "#src/config/extension-paths";
+import { PolicyIssueReporter } from "#src/config/policy-issue-reporter";
 import { GateRunner } from "#src/handlers/gates/runner";
 import { SkillInputGatePipeline } from "#src/handlers/gates/skill-input-gate-pipeline";
 import { ToolCallGatePipeline } from "#src/handlers/gates/tool-call-gate-pipeline";
@@ -322,9 +323,12 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
   // was recorded as delivered and never shown (#933). Driven at session_start
   // and on every turn; the latch keeps an unchanged issue quiet.
   const configIssueReporter = new ConfigIssueReporter(configStore, logger);
+  // What composing policy revealed (a fail-closed clamp, a port notice) is
+  // agent-scoped, so each driver hands over the agent name it resolved (#953).
+  const policyIssueReporter = new PolicyIssueReporter(resolver, logger);
   const lifecycle = new SessionLifecycleHandler(
     session,
-    resolver,
+    policyIssueReporter,
     serviceLifecycle,
     logger,
     audit,
@@ -346,6 +350,7 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
     toolRegistry,
     logger,
     subagentDetection,
+    policyIssueReporter,
   );
 
   const gateRunner = new GateRunner(

package/src/path/expand-home.ts

@@ -29,7 +29,7 @@ const HOME_PREFIXES = ["~", "$HOME", "${HOME}"] as const;
  * All other patterns are returned unchanged.
  */
 export function expandHomePath(pattern: string): string {
-  const rest = afterHomePrefix(pattern);
+  const rest = splitHomePrefix(pattern);
   if (rest === undefined) return pattern;
   return rest === "" ? homedir() : join(homedir(), rest.slice(1));
 }
@@ -39,14 +39,18 @@ export function expandHomePath(pattern: string): string {
  * directory.
  */
 export function hasHomePrefix(value: string): boolean {
-  return afterHomePrefix(value) !== undefined;
+  return splitHomePrefix(value) !== undefined;
 }
 
 /**
  * What follows a recognized home prefix (`""`, or a separator and the rest),
  * or `undefined` when `value` has none.
+ *
+ * Exported so a caller that must not path-normalize the rest (a bash command
+ * string, which {@link expandHomePath}'s `join` would rewrite across its
+ * arguments) reads the same prefix table.
  */
-function afterHomePrefix(value: string): string | undefined {
+export function splitHomePrefix(value: string): string | undefined {
   for (const prefix of HOME_PREFIXES) {
     if (!value.startsWith(prefix)) continue;
     const rest = value.slice(prefix.length);

package/src/policy/permission-manager.ts

@@ -1,6 +1,9 @@
 import { join } from "node:path";
 import type { ResolvedAccessIntent } from "#src/access-intent/access-intent";
-import { normalizeInput } from "#src/access-intent/input-normalizer";
+import {
+  normalizeBashCommand,
+  normalizeInput,
+} from "#src/access-intent/input-normalizer";
 import { surfaceFamilyOf } from "#src/access-intent/path-surfaces";
 import { classifyToolKind } from "#src/access-intent/tool-kind";
 import {
@@ -59,12 +62,12 @@ type ResolvedPermissions = {
   /**
    * Non-global scopes whose config file failed to load or validate. When
    * non-empty the composed ruleset has been floored allow→ask (#646); the
-   * names also drive the fail-closed notice in {@link getConfigIssues}.
+   * names also drive the fail-closed notice in {@link getPolicyIssues}.
    */
   failClosedScopes: RuleOrigin[];
   /**
    * Top-level permission keys naming Pi MCP tools, relocated onto the `mcp`
-   * surface; they drive the port notice in {@link getConfigIssues}.
+   * surface; they drive the port notice in {@link getPolicyIssues}.
    */
   legacyMcpToolKeys: string[];
 };
@@ -89,7 +92,7 @@ export interface ScopedPermissionManager {
   ): PermissionCheckResult;
   getToolPermission(toolName: string, agentName?: string): PermissionState;
   isToolFullyDenied(toolName: string, agentName?: string): boolean;
-  getConfigIssues(agentName?: string): string[];
+  getPolicyIssues(agentName?: string): string[];
 }
 
 export interface PermissionManagerOptions extends PolicyLoaderOptions {
@@ -155,11 +158,20 @@ export class PermissionManager implements ScopedPermissionManager {
     this.resolvedPermissionsCache.clear();
   }
 
-  getConfigIssues(agentName?: string): string[] {
-    // Trigger a load/resolve to ensure issues are collected.
+  /**
+   * What composing `agentName`'s policy revealed: the fail-closed notice for
+   * a rejected non-global scope and the port notice for relocated MCP tool
+   * keys. Recomputed on every resolve, so a notice disappears once its cause is
+   * fixed.
+   *
+   * A config file's own schema errors are not here: `ConfigStore` loads the
+   * same files through the same `loadUnifiedConfig` and owns reporting them,
+   * so listing them here too showed the operator each one twice (#953).
+   */
+  getPolicyIssues(agentName?: string): string[] {
     const { failClosedScopes, legacyMcpToolKeys } =
       this.resolvePermissions(agentName);
-    const issues = [...this.loader.getConfigIssues()];
+    const issues: string[] = [];
     if (failClosedScopes.length > 0) {
       issues.push(
         `Invalid ${failClosedScopes.join(", ")} configuration detected — ` +
@@ -321,9 +333,11 @@ export class PermissionManager implements ScopedPermissionManager {
    * extension surfaces). Path-bearing surfaces arrive as `"path-values"` via
    * the access-path gate (#502) or service/RPC builder (#503).
    * `"path-values"` → evaluates the precomputed values directly.
+   * `"bash-command"` → evaluates a bash command unit and its spellings as
+   * aliases through `normalizeBashCommand`.
    *
    * The manager stays string-based by design: it consumes `ResolvedAccessIntent`
-   * (`tool | path-values`) and never imports `AccessPath`. This deliberate
+   * (`tool | path-values | bash-command`) and never imports `AccessPath`. This deliberate
    * boundary is formalized in ADR-0002
    * (`docs/decisions/0002-path-values-string-boundary.md`) and guarded by a
    * `no-restricted-imports` lint rule on this file.
@@ -357,6 +371,22 @@ export class PermissionManager implements ScopedPermissionManager {
       );
     }
 
+    if (intent.kind === "bash-command") {
+      const { surface, values, resultExtras } = normalizeBashCommand(
+        intent.command,
+        intent.spellings,
+      );
+      return buildCheckResult(
+        surface,
+        values,
+        resultExtras,
+        surface,
+        surface,
+        fullRules,
+        this.flavor,
+      );
+    }
+
     // kind === "tool"
     const toolName = intent.surface.trim();
     const { surface, values, resultExtras } = normalizeInput(

package/src/policy/permission-resolver.ts

@@ -4,6 +4,7 @@ import type {
   ResolvedAccessIntent,
 } from "#src/access-intent/access-intent";
 import { surfaceFamilyMembers } from "#src/access-intent/path-surfaces";
+import type { PolicyIssueSource } from "#src/config/policy-issue-reporter";
 import type { SkillPermissionChecker } from "#src/exposure/skill-prompt-sanitizer";
 import type { SessionRules } from "#src/session/session-rules";
 import type { PermissionCheckResult, PermissionState } from "#src/types";
@@ -64,7 +65,7 @@ function toResolvedIntent(
  * - `sessionRules` — narrowed to `getRuleset` (ISP: the resolver only reads, never records)
  */
 export class PermissionResolver
-  implements ScopedPermissionResolver, SkillPermissionChecker
+  implements ScopedPermissionResolver, SkillPermissionChecker, PolicyIssueSource
 {
   constructor(
     private readonly permissionManager: ScopedPermissionManager,
@@ -139,7 +140,7 @@ export class PermissionResolver
     return this.permissionManager.isToolFullyDenied(toolName, agentName);
   }
 
-  getConfigIssues(agentName?: string): string[] {
-    return this.permissionManager.getConfigIssues(agentName);
+  getPolicyIssues(agentName?: string): string[] {
+    return this.permissionManager.getPolicyIssues(agentName);
   }
 }

package/src/policy/wildcard-matcher.ts

@@ -42,6 +42,16 @@ function escapeRegExp(value: string): string {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 
+/**
+ * Compile `pattern` once for repeated matching.
+ *
+ * A leading `~` / `$HOME` / `${HOME}` is expanded on the pattern only. The value
+ * side is not expanded here, because what a home prefix means depends on where
+ * the value came from: a bash program can rebind `HOME`. A value arrives
+ * already spelled by the producer that knows, as an alias matched alongside the
+ * typed text (`AccessPath.matchValues()` for a path, a bash command unit's
+ * `spellings`).
+ */
 export function compileWildcardPattern<TState>(
   pattern: string,
   state: TState,