@gotgenes/pi-permission-system 9.1.0 → 10.0.0

package/CHANGELOG.md

@@ -5,6 +5,41 @@ 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).
 
+## [10.0.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v9.2.0...pi-permission-system-v10.0.0) (2026-06-02)
+
+
+### ⚠ BREAKING CHANGES
+
+* **pi-permission-system:** the permissions:ready event payload no longer includes protocolVersion. Consumers that read it must rely on package semver instead.
+
+### Features
+
+* **pi-permission-manager:** broadcast permission prompts on permissions:prompt channel ([8540f3b](https://github.com/gotgenes/pi-packages/commit/8540f3b462b76a4789c4c17a75fadf254ae39feb))
+* **pi-permission-system:** drop protocolVersion from permissions:ready ([6728a93](https://github.com/gotgenes/pi-packages/commit/6728a93af7edbc6953d20f448f1c3f54f9b7893f))
+* **pi-permission-system:** harden prompt broadcasts ([067bafd](https://github.com/gotgenes/pi-packages/commit/067bafd80ef983fd8b9ab00914cf1cec9b6db915))
+* **pi-permission-system:** make ready and decision broadcasts best-effort ([00a895f](https://github.com/gotgenes/pi-packages/commit/00a895f9377bcb7b598acbc6c95d7bc7cc83c515))
+* **pi-permission-system:** preserve display fields for forwarded prompts ([9970912](https://github.com/gotgenes/pi-packages/commit/997091228736bbd4395d8bd16aeb9f4a4ae7e0b2))
+* **pi-permission-system:** slim ui_prompt payload and centralize construction ([7a1ec56](https://github.com/gotgenes/pi-packages/commit/7a1ec56a827e90fe80a0f7de48e1222b5271700d))
+
+
+### Bug Fixes
+
+* **pi-permission-system:** drop manual CHANGELOG Unreleased section ([f14e4f5](https://github.com/gotgenes/pi-packages/commit/f14e4f5d9b5ae1d6b207a913aefdd71980a46dd6))
+
+
+### Documentation
+
+* **pi-permission-system:** document the lean ui_prompt contract ([0b3c11c](https://github.com/gotgenes/pi-packages/commit/0b3c11c57a7b718d2f73a184802f8c5dcb95fbe7))
+
+## [9.2.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v9.1.0...pi-permission-system-v9.2.0) (2026-06-02)
+
+
+### Features
+
+* flag relative paths conservatively after a non-literal cd ([6e631a0](https://github.com/gotgenes/pi-packages/commit/6e631a0c62633e0be3a498752a3bf3614d357d65)), closes [#307](https://github.com/gotgenes/pi-packages/issues/307)
+* fold sequential current-shell cd into the bash effective directory ([7fd8e95](https://github.com/gotgenes/pi-packages/commit/7fd8e9525196ffa558a2b59ea9f4cf66943f9010)), closes [#307](https://github.com/gotgenes/pi-packages/issues/307)
+* scope cd inside subshells and persist it across brace groups ([37b948c](https://github.com/gotgenes/pi-packages/commit/37b948c7e9fd5d9ddac3aa8c6b456039132f7c4e)), closes [#307](https://github.com/gotgenes/pi-packages/issues/307)
+
 ## [9.1.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v9.0.1...pi-permission-system-v9.1.0) (2026-06-02)
 
 

package/README.md

@@ -20,6 +20,7 @@ Permission enforcement extension for the [Pi](https://pi.mariozechner.at/) codin
 - **Protects sensitive file patterns** — cross-cutting `path` rules deny `.env`, `~/.ssh/*`, etc. across all tools and bash at once
 - **Guards external paths** — prompts before file tools or bash commands reach outside `cwd`
 - **Forwards prompts from subagents** — `ask` policies work even in non-UI execution contexts
+- **Broadcasts UI prompt events** — `permissions:ui_prompt` fires only when the permission system is about to invoke the active user-facing permission UI
 - **Native [`@gotgenes/pi-subagents`](https://github.com/gotgenes/pi-subagents) integration** — in-process child sessions register with the permission system automatically, enabling per-agent policy enforcement and `ask`-state forwarding to the parent UI without configuration
 
 ## Install
@@ -89,16 +90,16 @@ For the full reference — all surfaces, runtime knobs, per-agent overrides, mer
 
 ## Documentation
 
-| Document                                                                                                                       | Contents                                                                     |
-| ------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------- |
-| [docs/configuration.md](docs/configuration.md)                                                                                 | Full policy reference, runtime knobs, per-agent overrides, recipes           |
-| [docs/session-approvals.md](docs/session-approvals.md)                                                                         | Session-scoped rules, pattern suggestions, bash arity table                  |
-| [docs/cross-extension-api.md](docs/cross-extension-api.md)                                                                     | Cross-extension service accessor, event bus integration, decision broadcasts |
-| [docs/subagent-integration.md](docs/subagent-integration.md)                                                                   | Permission forwarding, coexistence with subagent extensions                  |
-| [docs/guides/permission-frontmatter-for-subagent-extensions.md](docs/guides/permission-frontmatter-for-subagent-extensions.md) | Convention guide for subagent extension authors                              |
-| [docs/opencode-compatibility.md](docs/opencode-compatibility.md)                                                               | OpenCode compatibility — shared concepts, divergences, porting guide         |
-| [docs/troubleshooting.md](docs/troubleshooting.md)                                                                             | Common issues, diagnostic logging, threat model                              |
-| [docs/migration/legacy-to-flat.md](docs/migration/legacy-to-flat.md)                                                           | Migration from pre-v2 config layout                                          |
+| Document                                                                                                                       | Contents                                                                                |
+| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------- |
+| [docs/configuration.md](docs/configuration.md)                                                                                 | Full policy reference, runtime knobs, per-agent overrides, recipes                      |
+| [docs/session-approvals.md](docs/session-approvals.md)                                                                         | Session-scoped rules, pattern suggestions, bash arity table                             |
+| [docs/cross-extension-api.md](docs/cross-extension-api.md)                                                                     | Cross-extension service accessor, event bus integration, prompt and decision broadcasts |
+| [docs/subagent-integration.md](docs/subagent-integration.md)                                                                   | Permission forwarding, coexistence with subagent extensions                             |
+| [docs/guides/permission-frontmatter-for-subagent-extensions.md](docs/guides/permission-frontmatter-for-subagent-extensions.md) | Convention guide for subagent extension authors                                         |
+| [docs/opencode-compatibility.md](docs/opencode-compatibility.md)                                                               | OpenCode compatibility — shared concepts, divergences, porting guide                    |
+| [docs/troubleshooting.md](docs/troubleshooting.md)                                                                             | Common issues, diagnostic logging, threat model                                         |
+| [docs/migration/legacy-to-flat.md](docs/migration/legacy-to-flat.md)                                                           | Migration from pre-v2 config layout                                                     |
 
 ## Development
 

package/package.json

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

package/src/forwarded-permissions/io.ts

@@ -10,6 +10,7 @@ import {
 } from "node:fs";
 
 import { isPermissionDecisionState } from "#src/permission-dialog";
+import type { PermissionUiPromptSource } from "#src/permission-events";
 import {
   createPermissionForwardingLocation,
   type ForwardedPermissionRequest,
@@ -17,6 +18,29 @@ import {
   type PermissionForwardingLocation,
 } from "#src/permission-forwarding";
 
+/** Valid `permissions:ui_prompt` source values, for tolerant request reads. */
+const UI_PROMPT_SOURCES = [
+  "tool_call",
+  "skill_input",
+  "skill_read",
+  "rpc_prompt",
+] as const satisfies readonly PermissionUiPromptSource[];
+
+/** Narrow an unknown value to a valid prompt source, or `undefined`. */
+function asUiPromptSource(
+  value: unknown,
+): PermissionUiPromptSource | undefined {
+  return UI_PROMPT_SOURCES.find((source) => source === value);
+}
+
+/** Narrow an unknown value to a nullable display string, or `undefined`. */
+function asNullableDisplayString(value: unknown): string | null | undefined {
+  if (value === null || typeof value === "string") {
+    return value;
+  }
+  return undefined;
+}
+
 type LogFn = (event: string, details: Record<string, unknown>) => void;
 
 export interface ForwardedPermissionLogger {
@@ -285,6 +309,11 @@ export function readForwardedPermissionRequest(
       targetSessionId: parsed.targetSessionId,
       requesterAgentName: parsed.requesterAgentName,
       message: parsed.message,
+      // Tolerant read: display fields are optional and may be absent (older
+      // child) or malformed; reconstruct only the well-formed ones.
+      source: asUiPromptSource(parsed.source),
+      surface: asNullableDisplayString(parsed.surface),
+      value: asNullableDisplayString(parsed.value),
     };
   } catch (error) {
     logPermissionForwardingWarning(

package/src/forwarded-permissions/polling.ts

@@ -11,15 +11,21 @@ import type {
   PermissionPromptDecision,
   RequestPermissionOptions,
 } from "#src/permission-dialog";
+import {
+  emitUiPromptEvent,
+  type PermissionEventBus,
+} from "#src/permission-events";
 import {
   type ForwardedPermissionRequest,
   type ForwardedPermissionResponse,
+  type ForwardedPromptDisplay,
   isForwardedPermissionRequestForSession,
   PERMISSION_FORWARDING_POLL_INTERVAL_MS,
   PERMISSION_FORWARDING_TIMEOUT_MS,
   resolvePermissionForwardingTargetSessionId,
   SUBAGENT_PARENT_SESSION_ENV_CANDIDATES,
 } from "#src/permission-forwarding";
+import { buildForwardedUiPrompt } from "#src/permission-ui-prompt";
 import { isSubagentExecutionContext } from "#src/subagent-context";
 import type { SubagentSessionRegistry } from "#src/subagent-registry";
 
@@ -43,6 +49,8 @@ export interface PermissionForwardingDeps {
   subagentSessionsDir: string;
   /** In-process subagent session registry for detection and forwarding target resolution. */
   registry?: SubagentSessionRegistry;
+  /** Event bus used for UI prompt broadcasts. */
+  events?: PermissionEventBus;
   logger: ForwardedPermissionLogger;
   writeReviewLog: (event: string, details: Record<string, unknown>) => void;
   requestPermissionDecisionFromUi: (
@@ -103,6 +111,7 @@ export async function waitForForwardedPermissionApproval(
   ctx: ExtensionContext,
   message: string,
   deps: PermissionForwardingDeps,
+  forwarded?: ForwardedPromptDisplay,
 ): Promise<PermissionPromptDecision> {
   const requesterSessionId = getSessionId(ctx);
   const targetSessionId = resolvePermissionForwardingTargetSessionId({
@@ -155,6 +164,13 @@ export async function waitForForwardedPermissionApproval(
     targetSessionId,
     requesterAgentName,
     message,
+    ...(forwarded
+      ? {
+          source: forwarded.source,
+          surface: forwarded.surface,
+          value: forwarded.value,
+        }
+      : {}),
   };
 
   const requestPath = join(location.requestsDir, `${requestId}.json`);
@@ -296,10 +312,25 @@ export async function processForwardedPermissionRequests(
         forwardedPermissionLogDetails,
       );
       try {
+        const forwardedMessage = formatForwardedPermissionPrompt(request);
+        if (deps.events) {
+          emitUiPromptEvent(
+            deps.events,
+            buildForwardedUiPrompt({
+              requestId: request.id,
+              message: forwardedMessage,
+              requesterAgentName: request.requesterAgentName || null,
+              requesterSessionId: request.requesterSessionId || null,
+              source: request.source ?? null,
+              surface: request.surface ?? null,
+              value: request.value ?? null,
+            }),
+          );
+        }
         decision = await deps.requestPermissionDecisionFromUi(
           ctx.ui,
           "Permission Required (Subagent)",
-          formatForwardedPermissionPrompt(request),
+          forwardedMessage,
         );
       } catch (error) {
         logPermissionForwardingError(
@@ -359,6 +390,7 @@ export async function confirmPermission(
   message: string,
   deps: PermissionForwardingDeps,
   options?: RequestPermissionOptions,
+  forwarded?: ForwardedPromptDisplay,
 ): Promise<PermissionPromptDecision> {
   if (ctx.hasUI) {
     return deps.requestPermissionDecisionFromUi(
@@ -375,5 +407,5 @@ export async function confirmPermission(
     return { approved: false, state: "denied" };
   }
 
-  return waitForForwardedPermissionApproval(ctx, message, deps);
+  return waitForForwardedPermissionApproval(ctx, message, deps, forwarded);
 }

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

@@ -1,5 +1,5 @@
 import { createRequire } from "node:module";
-import { basename, resolve } from "node:path";
+import { basename, isAbsolute, join, resolve } from "node:path";
 
 import {
   classifyTokenAsPathCandidate,
@@ -75,6 +75,29 @@ export interface BashCommand {
   readonly context?: BashCommandContext;
 }
 
+/**
+ * The working directory in force where a path candidate appears.
+ *
+ * A `known` base carries an `offset` to be joined with `cwd` at resolution time
+ * (the parse-time walk never sees `cwd`): a relative-or-absolute path string
+ * built by folding the literal targets of current-shell `cd` commands (`""` =
+ * `cwd`); an absolute offset (from `cd /abs`) ignores `cwd` at resolution time.
+ * An `unknown` base marks a non-literal `cd` target (`cd "$DIR"`, `cd $(…)`,
+ * `cd -`, bare `cd`, `cd ~…`) that made the effective directory unresolvable.
+ */
+type EffectiveBase =
+  | { readonly kind: "known"; readonly offset: string }
+  | { readonly kind: "unknown" };
+
+/**
+ * A path-candidate token paired with the effective working directory projected
+ * onto the point in the command stream where it appears.
+ */
+interface PathCandidate {
+  readonly token: string;
+  readonly base: EffectiveBase;
+}
+
 /**
  * A bash command parsed once into a reusable representation.
  *
@@ -87,29 +110,29 @@ export interface BashCommand {
  */
 export class BashProgram {
   private constructor(
-    private readonly rawTokens: readonly string[],
-    private readonly leadingCdTarget: string | undefined,
+    private readonly rawCandidates: readonly PathCandidate[],
     private readonly commandUnits: readonly BashCommand[],
   ) {}
 
   /**
    * Parse a bash command into a `BashProgram`.
    *
-   * Uses tree-sitter-bash to build the full AST, walks command-argument and
-   * redirect-destination nodes once into raw candidate tokens, and records the
-   * leading `cd` target. Heredoc bodies, comments, and other non-argument
-   * content are skipped. An unparseable command yields an empty program.
+   * Uses tree-sitter-bash to build the full AST and walks command-argument and
+   * redirect-destination nodes once into raw candidate tokens, each tagged with
+   * the effective working directory projected onto its position by folding
+   * current-shell `cd` commands. Heredoc bodies, comments, and other
+   * non-argument content are skipped. An unparseable command yields an empty
+   * program.
    */
   static async parse(command: string): Promise<BashProgram> {
     const parser = await getParser();
     const tree = parser.parse(command);
-    if (!tree) return new BashProgram([], undefined, []);
+    if (!tree) return new BashProgram([], []);
 
     try {
-      const leadingCdTarget = extractLeadingCdTarget(tree.rootNode);
-      const rawTokens = collectPathCandidateTokens(tree.rootNode);
+      const rawCandidates = collectPathCandidates(tree.rootNode);
       const commandUnits = collectCommands(tree.rootNode);
-      return new BashProgram(rawTokens, leadingCdTarget, commandUnits);
+      return new BashProgram(rawCandidates, commandUnits);
     } finally {
       tree.delete();
     }
@@ -125,7 +148,7 @@ export class BashProgram {
   pathTokens(): string[] {
     const seen = new Set<string>();
     const result: string[] = [];
-    for (const token of this.rawTokens) {
+    for (const { token } of this.rawCandidates) {
       const candidate = classifyTokenAsRuleCandidate(token);
       if (!candidate) continue;
       if (!seen.has(candidate)) {
@@ -156,21 +179,42 @@ export class BashProgram {
   /**
    * Deduplicated paths that resolve outside `cwd`.
    *
-   * When the command begins with `cd <dir> && …`, relative candidate paths are
-   * resolved against `<dir>` (if it stays within CWD) rather than CWD itself,
-   * mirroring how the shell would resolve them.
+   * Each candidate is resolved against the effective working directory in force
+   * where it appears, projected by folding a sequence of current-shell `cd`
+   * commands (joined by `&&`, `||`, `;`, or a newline). A `cd` inside a
+   * pipeline or a backgrounded command runs in a subshell and does not update
+   * the running directory.
    */
   externalPaths(cwd: string): string[] {
-    const resolveBase = computeEffectiveResolveBase(this.leadingCdTarget, cwd);
     const normalizedCwd = normalizePathForComparison(cwd, cwd);
 
     const seen = new Set<string>();
     const externalPaths: string[] = [];
 
-    for (const token of this.rawTokens) {
+    for (const { token, base } of this.rawCandidates) {
       const candidate = classifyTokenAsPathCandidate(token);
       if (!candidate) continue;
 
+      // Unknown effective directory: a relative candidate could resolve
+      // anywhere, so flag it conservatively (resolving against `cwd` only for a
+      // display path). Absolute / `~` candidates are base-independent and
+      // resolve normally below.
+      if (base.kind === "unknown" && isRelativeCandidate(candidate)) {
+        const normalized = normalizePathForComparison(candidate, cwd);
+        if (
+          normalized &&
+          normalizedCwd !== "" &&
+          !isSafeSystemPath(normalized) &&
+          !seen.has(normalized)
+        ) {
+          seen.add(normalized);
+          externalPaths.push(normalized);
+        }
+        continue;
+      }
+
+      const resolveBase =
+        base.kind === "known" ? resolve(cwd, base.offset) : cwd;
       const normalized = normalizePathForComparison(candidate, resolveBase);
       if (!normalized) continue;
 
@@ -733,75 +777,199 @@ function collectSubstitutionCommands(node: TSNode, out: BashCommand[]): void {
   }
 }
 
-// ── Leading cd detection ───────────────────────────────────────────────────
+// ── Effective working directory projection ─────────────────────────────────
+
+/** The working directory in force at the start of a program (`cwd`). */
+const CWD_BASE: EffectiveBase = { kind: "known", offset: "" };
+
+/** The effective directory after a non-literal or unresolvable `cd`. */
+const UNKNOWN_BASE: EffectiveBase = { kind: "unknown" };
 
 /**
- * Walk down from the root to find the first `command` node in the program.
+ * Walk the AST once, collecting every path-candidate token tagged with the
+ * effective working directory projected onto its position.
  *
- * Only descends into `program` and `list` nodes — subshells, pipelines, and
- * other compound statements are ignored because a `cd` inside them does not
- * affect the outer shell's working directory.
+ * The effective directory is stateful: it starts at `cwd` and each current-shell
+ * `cd <literal>` (joined by `&&`, `||`, `;`, or a newline) folds into it for
+ * subsequent commands. A `cd` inside a pipeline or a backgrounded command runs
+ * in a subshell and does not update the running directory; subshell and
+ * brace-group interiors inherit the enclosing base without folding their own
+ * `cd`s (a conservative first tier).
  */
-function findFirstCommand(node: TSNode): TSNode | null {
-  if (node.type === "command") return node;
-  if (node.type === "program" || node.type === "list") {
-    const firstChild = node.child(0);
-    if (firstChild) return findFirstCommand(firstChild);
+function collectPathCandidates(rootNode: TSNode): PathCandidate[] {
+  const out: PathCandidate[] = [];
+  walkForCandidates(rootNode, CWD_BASE, out);
+  return out;
+}
+
+/**
+ * Collect a single node's candidates tagged with `base`, returning the
+ * effective base in force *after* the node (the input base unless the node is a
+ * current-shell `cd <literal>` that folds the running directory).
+ */
+function walkForCandidates(
+  node: TSNode,
+  base: EffectiveBase,
+  out: PathCandidate[],
+): EffectiveBase {
+  switch (node.type) {
+    case "program":
+    case "list":
+    case "redirected_statement":
+      return walkCurrentShellSequence(node, base, out);
+    case "command":
+      tagTokens(collectCommandTokens(node), base, out);
+      return foldCd(node, base);
+    case "subshell":
+      // A subshell runs in a child shell: its interior `cd`s fold within the
+      // subshell but reset on exit, so the folded base is discarded.
+      walkCurrentShellSequence(node, base, out);
+      return base;
+    case "compound_statement":
+      // A `{ … }` brace group runs in the current shell, so its `cd`s persist
+      // to following commands — thread and return the folded base.
+      return walkCurrentShellSequence(node, base, out);
+    default:
+      // Pipelines, control-flow bodies, redirect targets, and command/process
+      // 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);
+      return base;
   }
-  return null;
 }
 
 /**
- * Extract the target directory of a leading `cd` command from the parsed AST.
- *
- * When a bash command begins with `cd <dir> && …`, the shell resolves
- * subsequent relative paths against `<dir>`, not the original working
- * directory.  The external-directory guard must do the same, otherwise a
- * path that the shell keeps inside the working directory can appear to
- * escape it and trigger a spurious permission prompt.
- *
- * Returns `undefined` when the first command is not `cd`, or when the
- * target cannot be meaningfully resolved (`cd -`, bare `cd`, or `cd ~…`).
+ * Fold a current-shell sequence (`program` / `list` / `redirected_statement`):
+ * thread the effective base left-to-right through the children so a `cd` updates
+ * the base for following siblings. A statement immediately followed by the
+ * background operator (`&`) runs in a subshell, so its folded base is discarded.
+ */
+function walkCurrentShellSequence(
+  seqNode: TSNode,
+  base: EffectiveBase,
+  out: PathCandidate[],
+): EffectiveBase {
+  let current = base;
+  for (let i = 0; i < seqNode.childCount; i++) {
+    const child = seqNode.child(i);
+    if (!child?.isNamed) continue;
+    if (SKIP_SUBTREE_TYPES.has(child.type)) continue;
+    const after = walkForCandidates(child, current, out);
+    current = isBackgrounded(seqNode, i) ? current : after;
+  }
+  return current;
+}
+
+/**
+ * True when the statement at `index` is immediately followed by the background
+ * operator (`&`) — distinct from the `&&` / `||` / `;` current-shell separators.
+ */
+function isBackgrounded(seqNode: TSNode, index: number): boolean {
+  const next = seqNode.child(index + 1);
+  if (!next || next.isNamed) return false;
+  return next.type === "&";
+}
+
+function tagTokens(
+  tokens: readonly string[],
+  base: EffectiveBase,
+  out: PathCandidate[],
+): void {
+  for (const token of tokens) out.push({ token, base });
+}
+
+/**
+ * True when a path candidate is relative (resolved against the effective
+ * directory) rather than absolute (`/…`) or home-relative (`~…`), which are
+ * base-independent. Used to decide which candidates an unknown base affects.
  */
-function extractLeadingCdTarget(rootNode: TSNode): string | undefined {
-  const firstCmd = findFirstCommand(rootNode);
-  if (!firstCmd) return undefined;
+function isRelativeCandidate(candidate: string): boolean {
+  return !candidate.startsWith("/") && !candidate.startsWith("~");
+}
 
-  const cmdName = extractCommandName(firstCmd);
-  if (cmdName !== "cd") return undefined;
+/**
+ * Compute the effective base after a command runs. Returns `base` unchanged
+ * unless the command is `cd`:
+ *
+ * - `cd /abs` (absolute literal) → a fresh known base, recovering from an
+ *   earlier unknown base.
+ * - `cd rel` (relative literal) → fold into a known base, or stay unknown if the
+ *   base was already unknown.
+ * - `cd "$DIR"` / `cd $(…)` / `cd -` / bare `cd` / `cd ~…` (non-literal) →
+ *   unknown.
+ */
+function foldCd(commandNode: TSNode, base: EffectiveBase): EffectiveBase {
+  if (extractCommandName(commandNode) !== "cd") return base;
+  const target = cdLiteralTarget(commandNode);
+  if (target === null) return UNKNOWN_BASE;
+  if (isAbsolute(target)) return { kind: "known", offset: target };
+  if (base.kind === "unknown") return UNKNOWN_BASE;
+  return { kind: "known", offset: join(base.offset, target) };
+}
 
-  for (let i = 0; i < firstCmd.childCount; i++) {
-    const child = firstCmd.child(i);
+/**
+ * Resolve the literal target of a `cd` command, or `null` when the first
+ * argument is not a static literal (contains an expansion or command
+ * substitution) or cannot be resolved against the working directory (`cd -`,
+ * `cd ~…`, bare `cd`).
+ */
+function cdLiteralTarget(commandNode: TSNode): string | null {
+  for (let i = 0; i < commandNode.childCount; i++) {
+    const child = commandNode.child(i);
     if (!child) continue;
     if (child.type === "command_name" || child.type === "variable_assignment")
       continue;
-    if (!ARG_NODE_TYPES.has(child.type)) continue;
-
-    const text = resolveNodeText(child);
-    // Skip `--` (end-of-flags marker)
-    if (text === "--") continue;
-    // `cd -` jumps to $OLDPWD; `cd ~…` is home-relative — neither can be
-    // resolved against the working directory.
-    if (text === "-" || text.startsWith("~")) return undefined;
-    return text;
+    if (!child.isNamed) continue;
+    // Skip the `--` end-of-flags marker; the next argument is the target.
+    if (child.type === "word" && child.text === "--") continue;
+    if (!ARG_NODE_TYPES.has(child.type)) return null;
+    return literalTextOf(child);
   }
-  return undefined;
+  return null;
 }
 
 /**
- * Compute the effective base directory for resolving relative path candidates.
- *
- * When the leading `cd` target stays within the working directory, subsequent
- * relative paths should be resolved against it.  An escaping target is itself
- * an external access (reported via its own candidate token) and must never
- * silence checks on subsequent paths, so the function falls back to `cwd`.
+ * The literal string value of an argument node, or `null` when it contains a
+ * variable expansion / command substitution or is a non-resolvable `cd`
+ * destination (`-`, `~…`).
  */
-function computeEffectiveResolveBase(
-  cdTarget: string | undefined,
-  cwd: string,
-): string {
-  if (cdTarget === undefined) return cwd;
-  const resolved = resolve(cwd, cdTarget);
-  const normalizedCwd = resolve(cwd);
-  return isPathWithinDirectory(resolved, normalizedCwd) ? resolved : cwd;
+function literalTextOf(node: TSNode): string | null {
+  switch (node.type) {
+    case "word": {
+      const text = node.text;
+      if (text === "-" || text.startsWith("~")) return null;
+      return text;
+    }
+    case "raw_string": {
+      const text = node.text;
+      return text.length >= 2 && text.startsWith("'") && text.endsWith("'")
+        ? text.slice(1, -1)
+        : text;
+    }
+    case "concatenation": {
+      let result = "";
+      for (let i = 0; i < node.childCount; i++) {
+        const child = node.child(i);
+        if (!child) continue;
+        const part = literalTextOf(child);
+        if (part === null) return null;
+        result += part;
+      }
+      return result;
+    }
+    case "string": {
+      let result = "";
+      for (let i = 0; i < node.childCount; i++) {
+        const child = node.child(i);
+        if (!child) continue;
+        if (child.type === '"') continue;
+        if (child.type !== "string_content") return null;
+        result += child.text;
+      }
+      return result;
+    }
+    default:
+      return null;
+  }
 }

package/src/index.ts

@@ -54,6 +54,7 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
     subagentSessionsDir: runtime.subagentSessionsDir,
     forwardingDir: runtime.forwardingDir,
     registry: subagentRegistry,
+    events: pi.events,
     requestPermissionDecisionFromUi,
   });
 
@@ -61,6 +62,7 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
     forwardingDir: runtime.forwardingDir,
     subagentSessionsDir: runtime.subagentSessionsDir,
     registry: subagentRegistry,
+    events: pi.events,
     logger: {
       writeReviewLog: runtime.writeReviewLog.bind(runtime),
       writeDebugLog: runtime.writeDebugLog.bind(runtime),