@gotgenes/pi-permission-system 21.0.0 → 22.0.0

package/CHANGELOG.md

@@ -5,6 +5,27 @@ 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).
 
+## [22.0.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v21.0.0...pi-permission-system-v22.0.0) (2026-07-24)
+
+
+### ⚠ BREAKING CHANGES
+
+* **pi-permission-system:** In an untrusted project, project-scoped permission configuration (project config.json and project-agent frontmatter) and project-scoped runtime config (yoloMode, permissionReviewLog, etc.) are no longer loaded until the user grants project trust. Only global policy applies. Grant project trust, or set defaultProjectTrust, to restore the prior behavior.
+
+### Features
+
+* **pi-permission-system:** support skipping project scope in loadAndMergeConfigs ([e5a2e57](https://github.com/gotgenes/pi-packages/commit/e5a2e57b39c7bae44e7ac126b24094c2d5dce155))
+
+
+### Bug Fixes
+
+* **pi-permission-system:** gate project-scoped config on project trust ([f264e71](https://github.com/gotgenes/pi-packages/commit/f264e711b90c7947d805bec654bc78199a76fada))
+
+
+### Documentation
+
+* **pi-permission-system:** document project-trust gating for project config ([e955a29](https://github.com/gotgenes/pi-packages/commit/e955a299156215be57144000d5157481615d8060))
+
 ## [21.0.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v20.10.0...pi-permission-system-v21.0.0) (2026-07-24)
 
 

package/README.md

@@ -107,6 +107,7 @@ Config lives in one JSON file per scope:
 | Project | `<cwd>/.pi/extensions/pi-permission-system/config.json`   |
 
 Project overrides global; per-agent YAML frontmatter overrides both.
+Project config (policy and runtime knobs) is loaded only once the project is trusted — in an untrusted directory only global config applies, so an untrusted repository cannot loosen your global policy (see [Upgrading](#2200--project-config-requires-project-trust)).
 
 Within a surface map like `bash` or `mcp`, **last matching rule wins** — put broad catch-alls first and specific overrides after.
 
@@ -120,6 +121,13 @@ For the full reference — all surfaces, runtime knobs, per-agent overrides, mer
 
 ## Upgrading
 
+### 22.0.0 — project config requires project trust
+
+Project-scoped configuration (the project `config.json` and project-agent frontmatter — both permission policy and runtime knobs such as `yoloMode`) is now loaded only when Pi reports the project as trusted.
+In an untrusted directory, only global config applies; a skip is surfaced with a warning and a `project_trust.skipped` review-log entry.
+Grant project trust (or set `defaultProjectTrust`) to load a project's config.
+See [docs/migration/0644-project-trust-gating.md](docs/migration/0644-project-trust-gating.md).
+
 ### 16.0.0 — the bash gate now fails closed
 
 The permission gate fails closed: an internal gate error blocks the tool (with a `gate_error` review-log entry) instead of running it ungated, and a non-empty bash command that cannot be parsed resolves to `ask` (sentinel `<unparseable-bash-command>`) rather than falling through to a permissive top-level `*`.
@@ -140,6 +148,7 @@ If you relied on the old permissive behavior for bash, set an explicit permissiv
 | [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                                                           |
 | [docs/migration/strict-config-validation.md](docs/migration/strict-config-validation.md)                                       | Strict config validation (breaking) — rejected configs, and the cross-scope fail-closed clamp |
+| [docs/migration/0644-project-trust-gating.md](docs/migration/0644-project-trust-gating.md)                                     | Project-trust gating (breaking) — project config loads only after project trust               |
 
 ## Development
 

package/docs/configuration.md

@@ -11,6 +11,12 @@ One unified config file per scope:
 
 Project config overrides global config; per-agent frontmatter overrides both.
 
+**Project config requires project trust.**
+Project and project-agent scopes (both permission policy and runtime config such as `yoloMode`) are loaded only when Pi reports the project as trusted (`ctx.isProjectTrusted()`).
+In an untrusted directory, only global (and global-agent) config applies, so an untrusted repository cannot loosen your global policy; the extension surfaces a loud warning plus a `project_trust.skipped` review-log entry when it skips a project scope.
+Grant project trust (or configure `defaultProjectTrust`) to load the project's config; a trust grant reloads project policy on the next `resources_discover` reload.
+See [migration/0644-project-trust-gating.md](migration/0644-project-trust-gating.md).
+
 > **Coming from OpenCode?**
 > This extension's permission model was inspired by OpenCode's.
 > See [OpenCode Compatibility](opencode-compatibility.md) for shared concepts, divergences, and a porting guide.

package/docs/migration/0644-project-trust-gating.md

@@ -0,0 +1,32 @@
+# Migration guide: project-trust gating
+
+Starting with the release that closes #644, the permission-system loads project-scoped configuration only after Pi reports the project as **trusted** (`ctx.isProjectTrusted()`).
+This is a **breaking change** in how config is loaded in an untrusted directory.
+
+## What changed
+
+The extension used to load project-scoped config from the current working directory unconditionally — it never consulted Pi's project-trust decision.
+Because project scope has higher precedence than global, an untrusted repository could ship a `.pi/extensions/pi-permission-system/config.json` that **loosened** an operator's global policy before the user granted trust — for example flipping a global `bash: deny` to `bash: allow`, or setting `yoloMode: true`.
+
+Now, when the project is **not** trusted:
+
+- Project and project-agent **permission policy** scopes are not loaded — only global (and global-agent) policy participates in resolution.
+- Project **runtime config** (`yoloMode`, `permissionReviewLog`, `piInfrastructureReadPaths`, `shellTools`, `authorizerChain`, …) is not merged.
+- Each skip is surfaced loudly: a UI warning and a `project_trust.skipped` entry in the permission review log.
+
+This aligns the extension with Pi's own trust model, which already withholds project-local skills, prompts, and agents from untrusted directories.
+
+## Timing and recovery
+
+Pi resolves the trust decision (including any `defaultProjectTrust` setting) before `session_start`, so the guard sees the effective decision from the first tool call.
+If you grant trust after the session starts, Pi fires `resources_discover` with `reason: "reload"`, and the extension re-reads trust and loads the project **policy** at that point.
+Project **runtime** config (e.g. `yoloMode`) is re-read on the next session start.
+
+## What you need to do
+
+If you only use global config, nothing changes.
+
+If you rely on a project's `.pi/extensions/pi-permission-system/config.json`, **grant the project trust** when Pi prompts (or configure `defaultProjectTrust` to always trust).
+Until then, the project's permission rules and runtime knobs are ignored and only your global policy applies.
+
+If a project's rules stop taking effect after upgrading (surfaces you allowed at the project scope start prompting or denying per global policy), check whether the project is trusted — the review log will contain a `project_trust.skipped` entry naming the untrusted `cwd`.

package/package.json

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

package/src/config-loader.ts

@@ -286,12 +286,20 @@ export interface MergedConfigResult {
  * Legacy files are detected and warned about. Their content is parsed with the
  * flat-format parser — legacy-format keys (defaultPolicy, tools, bash, etc.)
  * are not translated and contribute no permission rules.
+ *
+ * When `options.includeProjectScope` is `false`, the project-scope steps (4 and
+ * 5) are skipped entirely — neither the legacy project policy nor the new
+ * project config is read or merged. This gates project-local config on project
+ * trust: an untrusted repository cannot loosen the operator's global policy
+ * (#644). It defaults to `true`, preserving the trusted / caller-agnostic path.
  */
 export function loadAndMergeConfigs(
   agentDir: string,
   cwd: string,
   extensionRoot: string,
+  options: { includeProjectScope?: boolean } = {},
 ): MergedConfigResult {
+  const includeProjectScope = options.includeProjectScope !== false;
   const allIssues: string[] = [];
 
   const newGlobalPath = getGlobalConfigPath(agentDir);
@@ -339,8 +347,8 @@ export function loadAndMergeConfigs(
   const globalConfig = globalResult.config;
   merged = mergeUnifiedConfigs(merged, globalConfig);
 
-  // 4. Legacy project policy
-  if (existsSync(legacyProjectPolicyPath)) {
+  // 4. Legacy project policy — skipped when the project scope is withheld.
+  if (includeProjectScope && existsSync(legacyProjectPolicyPath)) {
     const legacy = loadUnifiedConfig(legacyProjectPolicyPath);
     allIssues.push(
       `Legacy project policy found at '${legacyProjectPolicyPath}'. ` +
@@ -351,8 +359,11 @@ export function loadAndMergeConfigs(
     merged = mergeUnifiedConfigs(merged, legacy.config);
   }
 
-  // 5. New project config
-  const projectResult = loadUnifiedConfig(newProjectPath);
+  // 5. New project config — skipped when the project scope is withheld, so an
+  // untrusted project contributes nothing and `project` reports empty.
+  const projectResult = includeProjectScope
+    ? loadUnifiedConfig(newProjectPath)
+    : { config: {}, issues: [] };
   allIssues.push(...projectResult.issues);
   const projectConfig = projectResult.config;
   merged = mergeUnifiedConfigs(merged, projectConfig);

package/src/config-store.ts

@@ -41,7 +41,7 @@ export interface ConfigReader {
  * coupling between the class and test doubles.
  */
 export interface SessionConfigStore extends ConfigReader {
-  refresh(ctx?: ExtensionContext): void;
+  refresh(ctx: ExtensionContext | undefined, projectTrusted: boolean): void;
   logResolvedPaths(cwd?: string): void;
 }
 
@@ -96,14 +96,17 @@ export class ConfigStore implements SessionConfigStore, CommandConfigStore {
    * Reload merged config from disk.
    *
    * If `ctx` is provided, uses it to derive the cwd and sync UI status.
-   * Equivalent to `refreshExtensionConfig(runtime, ctx?)`.
+   * When `projectTrusted` is `false`, the project scope is withheld so an
+   * untrusted repository's runtime config (`yoloMode`, `permissionReviewLog`,
+   * …) cannot loosen the operator's global config (#644).
    */
-  refresh(ctx?: ExtensionContext): void {
+  refresh(ctx: ExtensionContext | undefined, projectTrusted: boolean): void {
     const cwd = ctx?.cwd ?? null;
     const mergeResult = loadAndMergeConfigs(
       this.deps.agentDir,
       cwd ?? "",
       EXTENSION_ROOT,
+      { includeProjectScope: projectTrusted },
     );
     const runtimeConfig = normalizePermissionSystemConfig(mergeResult.merged);
     this.config = runtimeConfig;
@@ -127,6 +130,7 @@ export class ConfigStore implements SessionConfigStore, CommandConfigStore {
       debugLog: runtimeConfig.debugLog,
       permissionReviewLog: runtimeConfig.permissionReviewLog,
       yoloMode: runtimeConfig.yoloMode,
+      projectTrusted,
     });
   }
 

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

@@ -62,7 +62,11 @@ export class AgentPrepHandler {
     // to whole-string matching.
     this.warmParser();
     this.session.activate(ctx);
-    this.session.refreshConfig(ctx);
+    // Gate the mid-session runtime-config refresh on project trust too, so an
+    // untrusted project cannot slip its runtime config (e.g. `yoloMode`) in
+    // right before agent start after session_start withheld it (#644). The
+    // session_start handler already warned; do not re-warn on every start.
+    this.session.refreshConfig(ctx, ctx.isProjectTrusted());
 
     const agentName = this.session.resolveAgentName(ctx, event.systemPrompt);
     const activeTools = this.toolRegistry.getActive();

package/src/handlers/lifecycle.ts

@@ -17,6 +17,15 @@ interface ResourcesDiscoverPayload {
   reason: string;
 }
 
+/**
+ * Shown when project config is skipped because the project is untrusted, so the
+ * reduced-scope state is never silent (#644). Exported for assertion in tests.
+ */
+export const UNTRUSTED_PROJECT_MESSAGE =
+  "pi-permission-system: project is not trusted — skipping project-scoped " +
+  "permission configuration. Only global policy applies. Grant project trust " +
+  "to load this project's permission rules.";
+
 /**
  * Handles session lifecycle events: start, reload, and shutdown.
  *
@@ -42,9 +51,13 @@ export class SessionLifecycleHandler {
     event: SessionStartPayload,
     ctx: ExtensionContext,
   ): Promise<void> {
-    this.session.refreshConfig(ctx);
-    this.session.resetForNewSession(ctx);
+    const projectTrusted = ctx.isProjectTrusted();
+    this.session.refreshConfig(ctx, projectTrusted);
+    this.session.resetForNewSession(ctx, projectTrusted);
     this.session.logResolvedConfigPaths();
+    if (!projectTrusted) {
+      this.warnProjectUntrusted(ctx, "session_start");
+    }
 
     const agentName = this.session.resolveAgentName(ctx);
     const policyIssues = this.resolver.getConfigIssues(agentName ?? undefined);
@@ -68,12 +81,19 @@ export class SessionLifecycleHandler {
     return Promise.resolve();
   }
 
-  handleResourcesDiscover(event: ResourcesDiscoverPayload): Promise<void> {
+  handleResourcesDiscover(
+    event: ResourcesDiscoverPayload,
+    ctx: ExtensionContext,
+  ): Promise<void> {
     if (event.reason !== "reload") {
       return Promise.resolve();
     }
 
-    this.session.reload();
+    const projectTrusted = ctx.isProjectTrusted();
+    this.session.reload(projectTrusted);
+    if (!projectTrusted) {
+      this.warnProjectUntrusted(ctx, "resources_discover");
+    }
     this.logger.debug("lifecycle.reload", {
       triggeredBy: "resources_discover",
       reason: event.reason,
@@ -82,6 +102,18 @@ export class SessionLifecycleHandler {
     return Promise.resolve();
   }
 
+  /**
+   * Record the project-trust skip in the review log and surface a loud warning
+   * to the user, so the reduced (global-only) scope is never silent (#644).
+   */
+  private warnProjectUntrusted(
+    ctx: ExtensionContext,
+    phase: "session_start" | "resources_discover",
+  ): void {
+    this.logger.review("project_trust.skipped", { cwd: ctx.cwd, phase });
+    this.logger.warn(UNTRUSTED_PROJECT_MESSAGE);
+  }
+
   handleSessionShutdown(): Promise<void> {
     const ctx = this.session.getRuntimeContext();
     if (ctx) {

package/src/index.ts

@@ -171,7 +171,9 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
   // refresh() must run after `session` is assigned: a debug-write IO failure
   // triggers the logger's notify sink — `session.notify(m)` — which no-ops
   // on the null context but requires `session` to be bound.
-  configStore.refresh();
+  // No ctx/trust decision exists at factory init, so withhold the project
+  // scope (fail closed); session_start reloads with the real trust decision.
+  configStore.refresh(undefined, false);
 
   const configPath = getGlobalConfigPath(agentDir);
   registerPermissionSystemCommand(pi, {
@@ -258,8 +260,8 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
   pi.on("session_start", (event, ctx) =>
     lifecycle.handleSessionStart(event, ctx),
   );
-  pi.on("resources_discover", (event) =>
-    lifecycle.handleResourcesDiscover(event),
+  pi.on("resources_discover", (event, ctx) =>
+    lifecycle.handleResourcesDiscover(event, ctx),
   );
   pi.on("session_shutdown", () => lifecycle.handleSessionShutdown());
   pi.on("before_agent_start", (event, ctx) => agentPrep.handle(event, ctx));

package/src/permission-session.ts

@@ -99,11 +99,15 @@ export class PermissionSession implements ToolCallGateInputs {
   /**
    * Reset all mutable state for a new session.
    *
-   * Configures the injected PermissionManager for `ctx.cwd`, clears skill
+   * Configures the injected PermissionManager for `ctx.cwd` (or global-only
+   * when `projectTrusted` is `false`, withholding the project cwd so an
+   * untrusted project's policy scopes are not loaded, #644), clears skill
    * entries, and activates the new context.
    */
-  resetForNewSession(ctx: ExtensionContext): void {
-    this.permissionManager.configureForCwd(ctx.cwd);
+  resetForNewSession(ctx: ExtensionContext, projectTrusted: boolean): void {
+    this.permissionManager.configureForCwd(
+      projectTrusted ? ctx.cwd : undefined,
+    );
     this.skillEntries = [];
     this.activate(ctx);
   }
@@ -121,9 +125,15 @@ export class PermissionSession implements ToolCallGateInputs {
   /**
    * Reload permission manager and clear skill entries for the current context.
    * Used on config reload (e.g. `resources_discover` with reason "reload").
+   *
+   * When `projectTrusted` is `false` the project cwd is withheld, so a reload
+   * in an untrusted project reloads only global policy; a trust grant on a
+   * later reload re-includes the project scope (#644).
    */
-  reload(): void {
-    this.permissionManager.configureForCwd(this.context?.cwd);
+  reload(projectTrusted: boolean): void {
+    this.permissionManager.configureForCwd(
+      projectTrusted ? this.context?.cwd : undefined,
+    );
     this.skillEntries = [];
   }
 
@@ -168,9 +178,16 @@ export class PermissionSession implements ToolCallGateInputs {
 
   // ── Config ─────────────────────────────────────────────────────────────
 
-  /** Reload merged config from disk; optionally update the stored runtime context. */
-  refreshConfig(ctx?: ExtensionContext): void {
-    this.configStore.refresh(ctx);
+  /**
+   * Reload merged config from disk; optionally update the stored runtime
+   * context. When `projectTrusted` is `false`, the project scope is withheld
+   * so an untrusted project's runtime config is not merged (#644).
+   */
+  refreshConfig(
+    ctx: ExtensionContext | undefined,
+    projectTrusted: boolean,
+  ): void {
+    this.configStore.refresh(ctx, projectTrusted);
   }
 
   /** Write the resolved config path set to the review and debug logs. */