@signalridge/pi-subagents 1.11.0 → 1.11.1

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 1.11.1
+### Patch Changes
+
+- 3364cc0: Gate project agent definitions, own settings, and custom tool descriptions on the host's fail-closed project trust decision. Reject denied definition provenance before child package resolution, including fallbacks and global aliases into denied roots; refresh configuration authority on session replacement and reload.
+- 3364cc0: Use patched Vitest 4.1.11 for development and regression testing without moving to a new major version. Refresh compatible transitive dependencies to include fixed source-map and brace-expansion releases.
+- 3364cc0: Inherit the parent's public Pi project-trust decision before child resource resolution instead of accepting the SDK's trusted default. Unknown trust and different configuration roots deny project settings, extension factories, skills (including named preloading), and MCP configuration without prompting or granting trust. Explicit project resource paths cannot bypass denial. Preserve global resources, child policy restrictions, and trusted parent configuration during worktree execution and nested delegation; bind built-in MCP configuration discovery to that same trusted configuration root.
+- 3364cc0: Preserve denied parent resource provenance when a child changes its configuration root. Reject explicit parent extensions and filter configured/discovered extensions and skills using both denied roots, including canonical aliases, before extension execution or skill injection. Named skill preloading also rejects denied sources behind global-root ancestor aliases. Genuine global resources and trusted parent configuration during worktree execution remain available; this resource trust boundary is not an OS sandbox or containment of arbitrary global extension behavior.
+- 3364cc0: Fingerprint tracked gate inputs without textconv or external diff helpers, and retain full binary-safe changes so transformed or abbreviated diffs cannot reuse a stale passing verdict.
+- 3364cc0: Declare `@sinclair/typebox` as a host-provided peer dependency with a `*` range instead of a runtime dependency, avoiding duplicate runtime modules and Pi extension-loader warnings.
+- 3364cc0: Reject native global settings and MCP configuration aliases into retained denied project roots before SDK parsing or package resolution. Walk raw path components and symlink targets without collapsing dot segments, so a traversed denied directory cannot be hidden by a later `..` or an outward relay. Preserve genuine global configuration and aliases into approved parent roots without duplicating host configuration schemas.
+- 3364cc0: Capture configuration trust before nested agent discovery and invocation defaults, and preserve denied ancestor roots across nested delegation. Reject global aliases into denied parent or child configuration roots before definition admission, model setup, or resource resolution while retaining authorized global definitions and standalone discovery defaults.
+- 3364cc0: Adopt Pi 1.0.4's host-provided dependency contract: declare imported Pi and TypeBox modules as `*` peers rather than installing duplicate runtime modules, and align Pi development pins with the repository's tested 1.0.4 baseline. The wildcard identifies host module ownership; it does not promise compatibility with every Pi version.
+- 3364cc0: Close configuration-admission gaps: apply model scope only from admitted settings at the captured configuration root, retain ancestor denials, and reject resource aliases that traverse denied project paths before escaping outside. Refresh provider-facing Agent descriptions and configuration-derived parameter descriptions through Pi's public tool-registration API when preparing prompts and continuations, preserving inactive tools. Disable gate-result caching while untracked files exist and prevent external diff commands during fingerprint inspection.
+- 3364cc0: Keep Goal terminal tools directly declared but unavailable to nested execution, where termination is not propagated. Verify direct termination and settlement-gated queue advancement against the installed Pi 1.0.4 host and codemode.
+  
+  Translate Pi exec results into the existing gate executor contract, failing killed commands even when their code is zero and enabling successful git fingerprint inspection. Exercise real-SDK exposure, nested approval, policy, and navigation regressions on Pi 1.0.4 instead of skipping them.
+- Updated dependencies [3364cc0]
+- Updated dependencies [3364cc0]
+- Updated dependencies [3364cc0]
+- Updated dependencies [3364cc0]
+  - @signalridge/pi-subagents-protocol@1.5.1
+  - @signalridge/pi-ui@1.3.3
+
 ## 1.11.0
 ### Minor Changes
 

package/README.md

@@ -46,6 +46,8 @@ From the repository root:
 pi -e ./packages/pi-subagents
 ```
 
+**Verified host baseline:** Pi 1.0.4. Wildcard peer dependency ranges and retained capability fallbacks do not establish support for older host versions.
+
 ## Lint policy
 
 Formatter checks remain disabled for this package, while legacy `noExplicitAny`, control-character regex, and empty-interface rules remain off. Signalridge additions follow the package AGENTS rules and the strict `--error-on-warnings` lint gate.
@@ -278,6 +280,16 @@ Nested children don't occupy `maxConcurrent` slots — their parent already hold
 
 Because a subagent session never activates this extension (that is what keeps a child from building a second agent manager, and it is why nested tools are injected directly instead), a subagent also gets none of the extension's other surfaces: no `/agents` command, no cross-extension RPC handlers, no `subagents:ready` event.
 
+### Child project trust
+
+Root startup and reload also gate this package's project `subagents.json`, `.pi/agents`, `.agents/agents`, and custom tool description on the public project-trust decision. Unknown or throwing trust checks skip project configuration before parsing; global definitions/settings and embedded defaults remain available. Global aliases into denied roots are not treated as global authority. The runner rejects a denied project-owned definition (including the actual fallback definition) before package resolution, even when it requests an extension outside the project or in a global package cache.
+
+On Pi 1.0.4, children capture the parent's public `isProjectTrusted()` decision and configuration root before resolving child resources. Missing or failed trust checks mean denial; children never prompt for or grant project trust. The child passes its derived trust explicitly to `SettingsManager`, governing project settings merging, resource/package discovery, and project MCP configuration. Denied project settings and MCP configuration are not merged. Before the SDK reads native global `settings.json` or `mcp.json`, the child checks their lexical and canonical sources against every retained denied root. A global file or agent-directory alias into a denied root fails child admission, even with extensions disabled; genuine global files and aliases into an approved parent remain usable.
+
+Trust belongs to the **configuration root**, not the tool execution directory. Execution in a worktree with `configCwd` pinned to the trusted parent retains that parent's resources (including MCP configuration), also for nested children. A different configuration root, including a newly copied worktree, is not implicitly trusted. Resource checks retain **all denied ancestor roots**, including the captured parent root whose trust was denied and the child's untrusted `configCwd`. Lexical and canonical path checks apply to explicit, configured, and discovered extension paths before their factories execute, and to discovered/preloaded skills before instruction injection. Changing `cwd`/`configCwd`, naming an explicit parent extension, or using a symlink/package alias cannot re-admit the denied source. Named skill preloading also checks global-root ancestor aliases against all retained denied roots.
+
+Genuine user/global resources outside denied roots remain available subject to the child's normal policy. This is a resource-source and instruction-loading boundary, **not an OS sandbox**: arbitrary allowed global extension code can perform its own I/O or register MCP servers; project trust does not contain that code's behavior. `isolated`, `extensions: false`, named extension selection, and skill restrictions still narrow access independently. Project context files and appended prompts remain suppressed in child resource loading; append-mode agents receive only the parent's already-built system prompt.
+
 ### Tool & extension scoping
 
 `extensions:` decides **which extensions load**, `tools:` decides **which tools surface to the LLM**. They compose:
@@ -310,11 +322,11 @@ A few rules the examples don't make obvious:
 - Extension names match case-insensitively (`[Mcp]` = `[mcp]`); tool names in `ext:foo/bar` stay case-sensitive.
 - Extensions that register tools **lazily** work too. MCP-backed extensions typically can't enumerate their tools until their servers connect, so they register from `session_start` or `before_agent_start` rather than at load. Subagent scoping is re-derived as tools appear, including under `ext:` selectors. Scoping does not override Pi's own exposure: `deferred`/`codemode` tools and `defaultActive: false` tools are not activated for the model, and tools deliberately deactivated during a session stay inactive on later turns. Pi may still allow nested `ctx.executeTool()` calls to deferred/codemode tools, but the child's selector and `ask_tools:` approval gate both model-issued and nested calls.
 - A configured `defaultToolTimeoutMs` bounds the public `tool_call` policy and each selected extension handler using one deadline per call, including nested calls and handlers registered later with `pi.on`. On expiry the call is blocked; a Promise race returns control but **cannot cancel side effects** of a misbehaving hook that keeps running. Interactive `ask_tools:` confirmation is human decision time, not tool execution time: the deadline starts after approval. The separate execution timeout can still abort a tool whose `execute()` hangs.
-- On Pi 0.99+, the SDK's public codemode, tool-search, and MCP factories are included as built-in extensions in children. `extensions: false` omits them; `extensions: [mcp]` selects MCP; `exclude_extensions: mcp` removes it; and `tools: ext:codemode`, `ext:tool-search`, or `ext:mcp/<tool>` narrows their tools like any other extension. Earlier supported Pi hosts use their own available extensions, without importing these newer factories. For restrictive `extensions:` or `exclude_extensions:` policies, the child uses Pi's public package resolver to select discovered paths **before** loading factories. Thus an excluded extension cannot register a conflicting `/mcp` command and displace a selected replaceable built-in before filtering. Resolution can perform configured package installs, as Pi's normal loader does, and a selected extension that fails to load is reported rather than silently dropped.
+- When the SDK exports public codemode, tool-search, and MCP factories (as on the verified Pi 1.0.4 baseline), they are included as built-in extensions in children. `extensions: false` omits them; `extensions: [mcp]` selects MCP; `exclude_extensions: mcp` removes it; and `tools: ext:codemode`, `ext:tool-search`, or `ext:mcp/<tool>` narrows their tools like any other extension. Capability checks omit factories that the host does not export; this fallback is not an older-host support guarantee. For restrictive `extensions:` or `exclude_extensions:` policies, the child uses Pi's public package resolver to select discovered paths **before** loading factories. Thus an excluded extension cannot register a conflicting `/mcp` command and displace a selected replaceable built-in before filtering. Resolution can perform configured package installs, as Pi's normal loader does, and a selected extension that fails to load is reported rather than silently dropped.
 - An installed **package** extension matches by its package short name (`@scope/pi-subagents` → `[pi-subagents]`), in addition to its path-derived name (a package whose entry is `src/index.ts` also answers to `[src]`). Prefer the package name — the path-derived one is incidental.
 - Plain `tools:` typos fail loudly: `tools: reed, grep` fires `tools-error:…` instead of silently producing an under-tooled agent.
 - `exclude_extensions:` wins over `extensions:` and over `ext:` selectors — an excluded extension never loads and a `tools: ext:` entry can't pull it back. Plain names only (no paths, no `*`); a name matching nothing fires an `extension-error:…` warning.
-- `exclude_extensions:` is **not a sandbox**: on Pi 0.99+ the restrictive prefilter prevents excluded discovered factories from loading into the child, but resolving configured packages can still install code. On earlier hosts, the post-load filter can run an excluded factory before suppressing its tools and bound lifecycle hooks; a factory that subscribes directly to the shared `pi.events` bus may remain live. Don't rely on extension selection to contain untrusted packages.
+- `exclude_extensions:` is **not a sandbox**: when the built-in factory capability enables preselection, the restrictive prefilter prevents excluded discovered factories from loading into the child, but resolving configured packages can still install code. The retained fallback without that capability filters post-load and can run an excluded factory before suppressing its tools and bound lifecycle hooks; a factory that subscribes directly to the shared `pi.events` bus may remain live. Don't rely on extension selection to contain untrusted packages.
 - Array and string forms are equivalent: `[a, b]` == `"a, b"`.
 
 ## Tools
@@ -804,7 +816,7 @@ Workflow-owned orchestration uses the `subagents:rpc:spawn-managed` channel. Its
 }
 ```
 
-The manager validates and resolves the tier, agent configuration, queue, tool, session, and worktree policy against its own Agent-tier catalogue and model scope. The resolved tier and its snapshot are retained on the managed invocation/tombstone. `spawnKey` is idempotent within a root manager; the same normalized request returns the existing agent id and a conflicting request is rejected. A named managed `thread` re-enters one sequential session only while its effective model, thinking, toolset, denylist, isolation, and agent policy fingerprint remain unchanged — including the model and thinking its tier currently resolves to, so switching the session model interrupts a thread whose tier inherits it; a policy change or concurrent call is rejected rather than silently reusing the old session. Managed agents use the normal Agent execution path, queue, FleetView, activity, transcript, compaction, and lifecycle events. Only the automatic main-session completion nudge is suppressed for an owner-scoped record. Managed requests must carry an attempt-scoped owner, and `stop-owned`/`quiesce-owned` fail closed when exact node/generation metadata is missing. During branch replacement, timed-out records are detached and late callbacks are suppressed. Pre-tree bus notifications carry the host navigation attempt's signal so workflow consumers can distinguish retries after a veto; older hosts without the signal remain supported. Active or unsettled child work vetoes a tree-navigation attempt rather than being aborted by that attempt. Pi has no post-veto, pre-leaf commit hook, so work started after preflight during asynchronous summarization can be quarantined at commit but cannot be guaranteed to finish.
+The manager validates and resolves the tier, agent configuration, queue, tool, session, and worktree policy against its own Agent-tier catalogue and model scope. The resolved tier and its snapshot are retained on the managed invocation/tombstone. `spawnKey` is idempotent within a root manager; the same normalized request returns the existing agent id and a conflicting request is rejected. A named managed `thread` re-enters one sequential session only while its effective model, thinking, toolset, denylist, isolation, and agent policy fingerprint remain unchanged — including the model and thinking its tier currently resolves to, so switching the session model interrupts a thread whose tier inherits it; a policy change or concurrent call is rejected rather than silently reusing the old session. Managed agents use the normal Agent execution path, queue, FleetView, activity, transcript, compaction, and lifecycle events. Only the automatic main-session completion nudge is suppressed for an owner-scoped record. Managed requests must carry an attempt-scoped owner, and `stop-owned`/`quiesce-owned` fail closed when exact node/generation metadata is missing. During branch replacement, timed-out records are detached and late callbacks are suppressed. Pre-tree bus notifications carry the host navigation attempt's signal so workflow consumers can distinguish retries after a veto; the event payload retains a fallback for an absent signal, without establishing support for older hosts. Active or unsettled child work vetoes a tree-navigation attempt rather than being aborted by that attempt. Pi has no post-veto, pre-leaf commit hook, so work started after preflight during asynchronous summarization can be quarantined at commit but cannot be guaranteed to finish.
 
 ### Spawn
 
@@ -900,7 +912,7 @@ skills: api-conventions, error-handling
 ---
 ```
 
-**Discovery roots** (checked in this order, first match wins):
+**Discovery roots** (checked in this order, first match wins). Both project roots are skipped when the child's configuration project is untrusted or trust is unknown; global named skills still preload unless their lexical or canonical source belongs to either the captured denied parent root or the untrusted child configuration root. Skill names are not explicit paths and cannot bypass that decision:
 
 | Scope | Path | Source |
 |---|---|---|

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signalridge/pi-subagents",
-  "version": "1.11.0",
+  "version": "1.11.1",
   "description": "Signalridge's managed subagent runtime with workflow-owned orchestration RPC.",
   "author": "tintinweb and signalridge contributors",
   "license": "MIT",
@@ -25,15 +25,15 @@
     "autonomous"
   ],
   "peerDependencies": {
-    "@earendil-works/pi-ai": "^0.84.0 || ^0.85.0 || ^0.86.0 || ^0.87.0 || ^0.99.1",
-    "@earendil-works/pi-coding-agent": "^0.84.0 || ^0.85.0 || ^0.86.0 || ^0.87.0 || ^0.99.1",
-    "@earendil-works/pi-tui": "^0.84.0 || ^0.85.0 || ^0.86.0 || ^0.87.0 || ^0.99.1"
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "@sinclair/typebox": "*"
   },
   "dependencies": {
-    "@sinclair/typebox": "^0.34.50",
     "croner": "^10.0.1",
-    "@signalridge/pi-subagents-protocol": "^1.5.0",
-    "@signalridge/pi-ui": "^1.3.2",
+    "@signalridge/pi-subagents-protocol": "^1.5.1",
+    "@signalridge/pi-ui": "^1.3.3",
     "minimatch": "^10.2.6",
     "nanoid": "^5.1.16"
   },
@@ -53,7 +53,7 @@
     "@biomejs/biome": "^2.4.14",
     "@types/node": "^25.5.0",
     "typescript": "^6.0.0",
-    "vitest": "^4.0.18"
+    "vitest": "^4.1.11"
   },
   "pi": {
     "extensions": [

package/src/agent-runner.ts

@@ -40,6 +40,7 @@ import { type ModelRegistry, resolveModel, shortModelLabel } from "./model-resol
 import { parentModelSessionOptions } from "./model-runtime-bridge.js";
 import { checkModelScope } from "./model-scope.js";
 import { createNestedSubagentTools, getMaxSubagentDepth, type NestedAgentManager } from "./nested-tools.js";
+import { captureProjectTrust, childProjectTrust, configurationMcpFactory, isProjectResource } from "./project-trust.js";
 import { buildAgentPrompt, type PromptExtras } from "./prompts.js";
 import { shutdownAndDisposeSession } from "./session-lifecycle.js";
 import { preloadSkills } from "./skill-loader.js";
@@ -331,8 +332,10 @@ export function installExtensionToolScope(session: AgentSession, inScope: () =>
  * the agent's whole result down with it.
  */
 async function runConfiguredGate(command: string, cwd: string, pi: ExtensionAPI): Promise<string> {
-  const exec: GateExec = (file, args, execOptions) =>
-    pi.exec(file, args, execOptions as Parameters<ExtensionAPI["exec"]>[2]);
+  const exec: GateExec = async (file, args, execOptions) => {
+    const result = await pi.exec(file, args, execOptions);
+    return { stdout: result.stdout, stderr: result.stderr, exitCode: result.killed ? 1 : result.code };
+  };
   try {
     const fingerprint = await workspaceFingerprint(cwd, exec);
     const verdict = await runGate({ command, cwd, exec, ...(fingerprint ? { fingerprint } : {}) });
@@ -622,9 +625,9 @@ export interface RunOptions {
    *
    * WARNING for future callers: if you pass `cwd` pointing at a directory the
    * user didn't open, you almost certainly must pass `configCwd` too —
-   * omitting it makes the target's `.pi` extensions execute in this process.
-   * (Worktree isolation is the one intentional exception: its copy IS the
-   * parent's repo, so config resolving inside it is correct.)
+   * a different configuration root does not inherit the parent's trust.
+   * Worktree execution with configCwd pointing at the parent retains trust;
+   * configuration discovered inside a new worktree is not implicitly trusted.
    */
   configCwd?: string;
   /** Called on tool start/end with activity info. */
@@ -898,8 +901,33 @@ export async function runAgent(
   // an already-cancelled caller. This matters for tool-call signals: the
   // caller may be cancelled before this async function gets its first turn.
   throwIfAborted(options.signal);
+  const parentProjectTrust = captureProjectTrust(ctx);
+  // Configuration provenance is established synchronously, before definition
+  // admission, model setup, callbacks, or any await. Execution cwd is not trust.
+  const effectiveCwd = options.cwd ?? ctx.cwd;
+  const configCwd = options.configCwd ?? effectiveCwd;
+  const projectTrust = childProjectTrust(parentProjectTrust, configCwd);
+  const projectTrusted = projectTrust.trusted;
+  const deniedProjectResource = (path: string): boolean =>
+    projectTrust.deniedRoots.some(root => isProjectResource(path, root));
+  const agentDir = getAgentDir();
+  // Native global configuration is resolved before resource-path filtering.
+  // Reject aliases into denied roots before the SDK parses their declarations;
+  // do not copy or reinterpret the host's settings/MCP schemas here.
+  for (const filename of ["settings.json", "mcp.json"]) {
+    if (deniedProjectResource(join(agentDir, filename))) {
+      throw new Error(`Project trust denied for global configuration source "${filename}".`);
+    }
+  }
 
   const loadedConfig = getConfig(type);
+  // The request's provenance matters, not just the requested extension path:
+  // a denied definition can request packages anywhere (including npm caches).
+  // getConfig carries the actual fallback definition's provenance as well.
+  if ((!parentProjectTrust.trusted && loadedConfig.source === "project") ||
+    (loadedConfig.sourcePath && deniedProjectResource(loadedConfig.sourcePath))) {
+    throw new Error(`Project trust denied for agent definition "${type}".`);
+  }
   const internalOverride = options[INTERNAL_AGENT_CONFIG_OVERRIDE];
   const loadedAgentConfig = getAgentConfig(type);
   const config = internalOverride
@@ -982,12 +1010,6 @@ export async function runAgent(
     options.onAgentTierResolved?.(agentTierSnapshot, tierModelLabel);
   }
 
-  // Resolve working directory: worktree override > parent cwd
-  const effectiveCwd = options.cwd ?? ctx.cwd;
-  // Filesystem work happens in effectiveCwd; config discovery in configCwd.
-  // They differ only for SpawnOptions.cwd spawns (config stays with the parent).
-  const configCwd = options.configCwd ?? effectiveCwd;
-
   const env = await detectEnv(options.pi, effectiveCwd);
   throwIfAborted(options.signal);
 
@@ -1010,7 +1032,7 @@ export async function runAgent(
 
   // Skill preloading: when skills is string[], preload their content into prompt
   if (Array.isArray(skills)) {
-    const loaded = preloadSkills(skills, configCwd);
+    const loaded = preloadSkills(skills, configCwd, { projectTrusted, deniedResource: deniedProjectResource });
     if (loaded.length > 0) {
       extras.skillBlocks = loaded;
     }
@@ -1060,7 +1082,7 @@ export async function runAgent(
   // skills later, so the loader override must enforce this policy on every update.
   const noSkills = skills === false || Array.isArray(skills);
 
-  const agentDir = getAgentDir();
+  const settingsManager = SettingsManager.create(configCwd, agentDir, { projectTrusted });
 
   // Extension loading:
   // - true  → all default-discovered extensions
@@ -1089,11 +1111,11 @@ export async function runAgent(
     : undefined;
   const keepNames = extensionsSpec?.names ?? new Set<string>();
   // `exclude_extensions:` is a denylist applied AFTER the include set — exclude wins.
-  // Plain canonical names only (case-insensitive). On older hosts filtering is
-  // post-factory; this is not a sandbox for extensions that already loaded.
+  // Plain canonical names only (case-insensitive). Without preselection,
+  // filtering is post-factory, not a sandbox for extensions that already loaded.
   const excludeNames = new Set((excludeExtensions ?? []).map((n) => n.toLowerCase()));
   const hasExcludes = excludeNames.size > 0;
-  // The override filters on older hosts, validates preselection on new hosts,
+  // The override filters without preselection, validates preselection when used,
   // and ALWAYS puts our tool policy first. Pi passes one mutable
   // tool_call event through handlers in extension order; if an earlier extension
   // changes event.toolName, a later gate would inspect a different name from the
@@ -1177,9 +1199,9 @@ export async function runAgent(
       });
     },
   }];
-  // Pi 0.99 exposes these as public SDK factories. Earlier supported hosts do
-  // not export them, so capability-check the namespace instead of importing a
-  // missing named export (which would prevent the whole extension from loading).
+  // Public SDK factories are verified on Pi 1.0.4. Capability-check the
+  // namespace rather than importing a potentially missing named export; this
+  // retained fallback does not establish support for older host versions.
   if ("createCodemodeExtension" in PiCodingAgent && typeof PiCodingAgent.createCodemodeExtension === "function") {
     extensionFactories.push({ name: "codemode", builtin: true, replaceable: true, factory: PiCodingAgent.createCodemodeExtension() });
   }
@@ -1187,21 +1209,26 @@ export async function runAgent(
     extensionFactories.push({ name: "tool-search", builtin: true, replaceable: true, factory: PiCodingAgent.createToolSearchExtension() });
   }
   if ("createMcpExtension" in PiCodingAgent && typeof PiCodingAgent.createMcpExtension === "function") {
-    extensionFactories.push({ name: "mcp", builtin: true, replaceable: true, factory: PiCodingAgent.createMcpExtension() });
+    extensionFactories.push({ name: "mcp", builtin: true, replaceable: true,
+      factory: configurationMcpFactory(PiCodingAgent.createMcpExtension(), configCwd, settingsManager) });
   }
 
-  const settingsManager = SettingsManager.create(configCwd, agentDir);
+  for (const path of extensionsSpec?.paths ?? []) {
+    if (deniedProjectResource(path)) {
+      throw new Error(`Project extension source "${path}" requested by agent "${type}" is not trusted.`);
+    }
+  }
   let additionalExtensionPaths = extensionsSpec?.paths.length ? extensionsSpec.paths : undefined;
   let settingsBeforeLoad: string | undefined;
   // Pi 0.99 resolves replacement conflicts BEFORE extensionsOverride. A rogue
   // discovered extension can register /mcp, replace builtin:mcp, and only then
   // get filtered out by our allowlist. Resolve configured resources through the
   // public package API first and feed only the selected paths into a loader with
-  // discovery off. Older Pi hosts have no replaceable built-ins; keep their
-  // existing post-load filter instead of relying on new host behavior.
+  // discovery off. Without the built-in factory capability, retain the
+  // post-load filtering fallback rather than assuming replacement behavior.
   const builtinNames = extensionFactories.filter((factory) => typeof factory !== "function" && factory.builtin)
     .map((factory) => factory.name);
-  const prefilter = !noExtensions && (!loadAll || hasExcludes) && builtinNames.length > 0;
+  const prefilter = !noExtensions && (!loadAll || hasExcludes || !projectTrusted) && builtinNames.length > 0;
   if (prefilter) {
     await settingsManager.reload();
     throwIfAborted(options.signal);
@@ -1219,8 +1246,13 @@ export async function runAgent(
       }
     }
     settingsBeforeLoad = JSON.stringify([settingsManager.getGlobalSettings(), settingsManager.getProjectSettings()]);
-    const enabledConfigured = configured.extensions.filter((resource) => resource.enabled).map((resource) => resource.path);
+    const enabledConfigured = configured.extensions.filter((resource) => resource.enabled && !deniedProjectResource(resource.path)).map((resource) => resource.path);
     const enabledExplicit = explicit.extensions.filter((resource) => resource.enabled);
+    for (const resource of enabledExplicit) {
+      if (deniedProjectResource(resource.path)) {
+        throw new Error(`Project extension "${resource.path}" requested by agent "${type}" is not trusted.`);
+      }
+    }
     discoveredNames = new Set([...enabledConfigured, ...enabledExplicit.map((resource) => resource.path)].flatMap(extensionCanonicalNames));
     const selectedExplicit = enabledExplicit.filter((resource) =>
       !extensionCanonicalNames(resource.path).some((name) => excludeNames.has(name)));
@@ -1258,7 +1290,11 @@ export async function runAgent(
     extensionsOverride,
     extensionFactories,
     noSkills,
-    skillsOverride: noSkills ? () => ({ skills: [], diagnostics: [] }) : undefined,
+    skillsOverride: noSkills
+      ? () => ({ skills: [], diagnostics: [] })
+      : !projectTrusted
+        ? (base) => ({ ...base, skills: base.skills.filter((skill) => !deniedProjectResource(skill.filePath)) })
+        : undefined,
     noPromptTemplates: true,
     noThemes: true,
     noContextFiles: true,
@@ -1305,7 +1341,7 @@ export async function runAgent(
   // already raised above instead of silently losing a requested capability.
   // Two remaining misconfigurations to catch:
   //   - `extensions: [foo]` but no extension named foo was discovered (typo;
-  //     on older hosts path entries also fold their canonical name into
+  //     without preselection path entries also fold their canonical name into
   //     `keepNames`, so a failed path load is warned here).
   //   - `tools: ext:foo` but foo isn't in the loaded set (because `extensions:`
   //     didn't include it). Since v0.9, `ext:` no longer pulls extensions in;
@@ -1372,7 +1408,8 @@ export async function runAgent(
     const { configuredModel, source } = agentTierSnapshot;
     const scopeVerdict = checkModelScope({
       model,
-      cwd: ctx.cwd,
+      cwd: projectTrust.cwd,
+      authority: projectTrust,
       modelRegistry: ctx.modelRegistry,
       // scopeModels polices a tier chosen per dispatch, by the host model or by
       // a workflow script alike; a tier from the agent file or the configured
@@ -1411,6 +1448,7 @@ export async function runAgent(
         maxSubagentDepth: effectiveMaxDepth,
         allowedSubagents: agentConfig.allowedSubagents,
         configCwd,
+        projectTrust,
       })
     : [];
   // `contact_supervisor` is injected separately from the nested tools and under

package/src/agent-types.ts

@@ -302,11 +302,15 @@ export function getConfig(type: string): {
   excludeExtensions?: string[];
   skills: true | string[] | false;
   promptMode: "replace" | "append";
+  source?: AgentConfig["source"];
+  sourcePath?: string;
 } {
   const key = resolveKey(type);
   const config = key ? agents.get(key) : undefined;
   if (config && config.enabled !== false) {
     return {
+      source: config.source,
+      sourcePath: config.sourcePath,
       displayName: config.displayName ?? config.name,
       color: config.color,
       description: config.description,
@@ -322,6 +326,8 @@ export function getConfig(type: string): {
   const gp = agents.get("general-purpose");
   if (gp && gp.enabled !== false) {
     return {
+      source: gp.source,
+      sourcePath: gp.sourcePath,
       displayName: gp.displayName ?? gp.name,
       color: gp.color,
       description: gp.description,

package/src/custom-agents.ts

@@ -8,6 +8,7 @@ import { getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
 import { isValidAgentTierKey } from "./agent-tiers.js";
 import { BUILTIN_TOOL_NAMES } from "./agent-types.js";
 import { DEFAULT_AGENTS } from "./default-agents.js";
+import { isProjectResource } from "./project-trust.js";
 import type { AgentConfig, MemoryScope } from "./types.js";
 import { sanitizeDisplayText } from "./ui/safe-text.js";
 
@@ -129,7 +130,8 @@ function createWarningSink(root: string): WarningSink {
   };
 }
 
-export function loadCustomAgents(cwd: string, strict = false): Map<string, AgentConfig> {
+/** Standalone callers retain discovery defaults; runtime callers must pass captured trust. */
+export function loadCustomAgents(cwd: string, strict = false, projectTrusted = true, deniedRoots: readonly string[] = []): Map<string, AgentConfig> {
   const discoveryRoot = normalizeDiscoveryRoot(cwd);
   const warningRoot = warningIdentity(cwd);
   const globalDir = join(getAgentDir(), "agents");
@@ -140,9 +142,12 @@ export function loadCustomAgents(cwd: string, strict = false): Map<string, Agent
   const agents = new Map<string, AgentConfig>();
   const priorities = new Map<string, number>();
   const skipped: SkippedAgent[] = [];
-  loadFromDir(globalDir, agents, "global", strict, warn, 0, priorities, skipped);            // lowest priority
-  loadFromDir(workspaceProjectDir, agents, "project", strict, warn, 1, priorities, skipped); // shared workspace
-  loadFromDir(projectDir, agents, "project", strict, warn, 2, priorities, skipped);          // highest priority (overwrites)
+  const denied = projectTrusted ? deniedRoots : [...deniedRoots, discoveryRoot];
+  loadFromDir(globalDir, agents, "global", strict, warn, 0, priorities, skipped, denied);
+  if (projectTrusted) {
+    loadFromDir(workspaceProjectDir, agents, "project", strict, warn, 1, priorities, skipped, denied);
+    loadFromDir(projectDir, agents, "project", strict, warn, 2, priorities, skipped, denied);
+  }
 
   // Only report a fallback when the skipped file was higher priority than the
   // definition that survived the complete discovery pass. A valid higher
@@ -164,7 +169,9 @@ function loadFromDir(
   priority: number,
   priorities: Map<string, number>,
   skipped: SkippedAgent[],
+  deniedRoots: readonly string[],
 ): void {
+  if (deniedRoots.some(root => isProjectResource(dir, root))) return;
   if (!existsSync(dir)) return;
 
   let files: string[];
@@ -184,6 +191,7 @@ function loadFromDir(
     const filenameType = basename(file, ".md");
 
     const path = join(dir, file);
+    if (deniedRoots.some(root => isProjectResource(path, root))) continue;
 
     const parsed = readAgentFile(path, strict, warn);
     if (!parsed) {

package/src/enabled-models.ts

@@ -3,7 +3,7 @@
  * + project-local `<cwd>/.pi/settings.json`, project wins) and resolves
  * entries to concrete `provider/modelId` keys for scope validation.
  *
- * **Project overrides global**, mirroring pi's own `SettingsManager`
+ * **Admitted project settings override global**, mirroring pi's own `SettingsManager`
  * deep-merge behavior and matching the precedence we use for our own
  * `subagents.json` settings (see `src/settings.ts:loadSettings`). If
  * project file has `enabledModels` set, it wholly replaces global's
@@ -25,6 +25,7 @@ import { join } from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { minimatch } from "minimatch";
 import type { ModelEntry } from "./model-resolver.js";
+import { isProjectResource, type ProjectTrust } from "./project-trust.js";
 
 /** Minimal registry shape — only the methods resolveEnabledModels actually calls. */
 export interface ModelRegistryRef {
@@ -61,11 +62,17 @@ function readField(path: string): string[] | undefined {
  * Read enabledModels from pi's settings — project-local overrides global.
  * Mirrors pi's SettingsManager deep-merge for the `enabledModels` field
  * (and matches our own loadSettings precedence in src/settings.ts).
- * Returns undefined when neither file has the field.
+ * Runtime callers pass captured configuration authority to exclude denied
+ * project sources and global aliases; standalone callers keep project defaults.
+ * Returns undefined when neither admitted file has the field.
  */
-export function readEnabledModels(cwd: string): string[] | undefined {
-  const [project, global] = settingsPaths(cwd);
-  return readField(project) ?? readField(global);
+export function readEnabledModels(cwd: string, authority?: ProjectTrust): string[] | undefined {
+  const [project, global] = settingsPaths(authority?.cwd ?? cwd);
+  // Standalone readers retain project precedence. Runtime readers must pass
+  // captured configuration authority, never infer it from execution cwd.
+  const denied = (path: string): boolean => authority?.deniedRoots.some(root => isProjectResource(path, root)) ?? false;
+  return (authority?.trusted !== false && !denied(project) ? readField(project) : undefined)
+    ?? (!denied(global) ? readField(global) : undefined);
 }
 
 /**

package/src/index.ts

@@ -165,6 +165,7 @@ import {
   streamToOutputFile,
   writeInitialEntry,
 } from "./output-file.js";
+import { captureProjectTrust, isProjectResource } from "./project-trust.js";
 import { SubagentScheduler } from "./schedule.js";
 import { resolveStorePath, ScheduleStore } from "./schedule-store.js";
 import {
@@ -582,16 +583,18 @@ export default function (pi: ExtensionAPI): void {
     if (inert) return;
     if (!rootRuntime) {
       try {
-        const startupSettings = loadSettings(ctx.cwd);
+        const trust = captureProjectTrust(ctx);
+        const startupSettings = loadSettings(trust.cwd, trust.trusted);
         const startupAgents = loadCustomAgents(
-          ctx.cwd,
+          trust.cwd,
           startupSettings.strictAgentFiles === true,
+          trust.trusted,
         );
         rootRuntime = activateRootRuntime(
           pi,
           startupSettings,
           startupAgents,
-          ctx.cwd,
+          ctx,
           unsubscribeRootContext,
         );
       } catch (error: unknown) {
@@ -611,10 +614,12 @@ function activateRootRuntime(
   pi: ExtensionAPI,
   startupSettings: SubagentsSettings,
   startupAgents: Map<string, AgentConfig>,
-  initialCwd: string,
+  initialContext: ExtensionContext,
   unsubscribeRootContext: () => void,
 ): RootRuntime {
-  let sessionCwd = initialCwd;
+  let configurationOwner = initialContext;
+  let activeTrust = captureProjectTrust(configurationOwner);
+  let sessionCwd = activeTrust.cwd;
   let strictAgentFiles = startupSettings.strictAgentFiles === true;
 
   // ---- Register custom notification renderer ----
@@ -668,7 +673,12 @@ function activateRootRuntime(
 
   /** Reload agents from project/global custom agent dirs and merge with defaults (called on init and each Agent invocation). */
   const reloadCustomAgents = (strict = false) => {
-    const userAgents = loadCustomAgents(sessionCwd, strict);
+    const trust = captureProjectTrust(configurationOwner);
+    const changed = trust.cwd !== activeTrust.cwd || trust.trusted !== activeTrust.trusted;
+    activeTrust = trust;
+    sessionCwd = trust.cwd;
+    if (changed) applyRuntimeSettings(loadSettings(trust.cwd, trust.trusted));
+    const userAgents = loadCustomAgents(trust.cwd, strict, trust.trusted);
     registerAgents(userAgents);
   };
 
@@ -1255,7 +1265,15 @@ function activateRootRuntime(
       manager.resetManagedSpawns();
     }
     sessionGeneration++;
-    sessionCwd = ctx.cwd;
+    const replacingConfiguration = currentCtx !== undefined;
+    configurationOwner = ctx;
+    const trust = captureProjectTrust(ctx);
+    sessionCwd = trust.cwd;
+    if (replacingConfiguration) {
+      activeTrust = trust;
+      applyRuntimeSettings(loadSettings(trust.cwd, trust.trusted));
+    }
+    reloadCustomAgents();
     boundSessionId = ctx.sessionManager?.getSessionId?.();
     currentCtx = ctx;
     await claimRpcRegistry(ctx, event.reason === "reload");
@@ -1386,6 +1404,8 @@ function activateRootRuntime(
     // even when subagents' session_tree handler runs first.
     pi.events.emit("subagents:session_tree_committed", { event });
     currentCtx = ctx;
+    configurationOwner = ctx;
+    reloadCustomAgents();
     scheduler.stop();
     manager.clearCompleted(true);
     manager.resetManagedSpawns();
@@ -1860,8 +1880,8 @@ function activateRootRuntime(
 
   // ---- Agent tool description mode ----
   // "full" (default) keeps the rich Claude Code-style description; "compact"
-  // swaps in a ~75% smaller one for small/local models (#91). Read once at
-  // tool registration — flipping it applies on the next pi session.
+  // swaps in a ~75% smaller one for small/local models (#91). The description
+  // getter rechecks configuration authority so replacements cannot retain denied text.
   let toolDescriptionMode: ToolDescriptionMode = "full";
   function getToolDescriptionMode(): ToolDescriptionMode {
     return toolDescriptionMode;
@@ -1961,40 +1981,47 @@ function activateRootRuntime(
 
   // Apply the already-validated session settings and emit the same lifecycle
   // event that the normal startup path exposes. Do not re-read process.cwd().
-  applySettings(startupSettings, {
-    setMaxConcurrent: (n) => manager.setMaxConcurrent(n),
-    setDefaultMaxTurns,
-    setGraceTurns,
-    setDefaultMaxTokens,
-    setDefaultMaxToolCalls,
-    setDefaultToolTimeout: (ms) => setDefaultToolTimeoutMs(ms),
-    setDefaultJoinMode,
-    setDefaultModel,
-    setSchedulingEnabled,
-    setScopeModels: setScopeModelsEnabled,
-    setStrictAgentFiles: (enabled) => {
-      strictAgentFiles = enabled;
-    },
-    setDisableDefaultAgents,
-    setToolDescriptionMode,
-    setFleetView: setFleetViewEnabled,
-    setOutputTranscript: setOutputTranscriptDefault,
-    setRememberAgents: (enabled) => manager.setRememberAgents(enabled),
-    setAgentMentions: (enabled) => {
-      agentMentionMode = enabled;
-    },
-    setSupervisorQuestions: (enabled) => {
-      supervisorQuestionsEnabled = enabled;
-      manager.setSupervisorQuestions(enabled);
-    },
-    setMaxSubagentDepth,
-    setMaxSubagentSpawnsPerBranch: (n) =>
-      manager.setMaxSubagentSpawnsPerBranch(n),
-    setFallbackSubagent,
-    setWorktreeIsolation: setWorktreeIsolationEnabled,
-    setAgentTiers: setAgentTiersSettings,
-  });
-  pi.events.emit("subagents:settings_loaded", { settings: startupSettings });
+  const baselineSettings: SubagentsSettings = { ...snapshotSettings(), strictAgentFiles: false, agentTiers: {} };
+  function applyRuntimeSettings(settings: SubagentsSettings): void {
+    // Clear optional policies as well: absence must not retain the old project's values.
+    setDefaultModel(settings.defaultModel ?? baselineSettings.defaultModel);
+    setFallbackSubagent(settings.fallbackSubagent ?? baselineSettings.fallbackSubagent);
+    applySettings({ ...baselineSettings, ...settings }, {
+      setMaxConcurrent: (n) => manager.setMaxConcurrent(n),
+      setDefaultMaxTurns,
+      setGraceTurns,
+      setDefaultMaxTokens,
+      setDefaultMaxToolCalls,
+      setDefaultToolTimeout: (ms) => setDefaultToolTimeoutMs(ms),
+      setDefaultJoinMode,
+      setDefaultModel,
+      setSchedulingEnabled,
+      setScopeModels: setScopeModelsEnabled,
+      setStrictAgentFiles: (enabled) => {
+        strictAgentFiles = enabled;
+      },
+      setDisableDefaultAgents,
+      setToolDescriptionMode,
+      setFleetView: setFleetViewEnabled,
+      setOutputTranscript: setOutputTranscriptDefault,
+      setRememberAgents: (enabled) => manager.setRememberAgents(enabled),
+      setAgentMentions: (enabled) => {
+        agentMentionMode = enabled;
+      },
+      setSupervisorQuestions: (enabled) => {
+        supervisorQuestionsEnabled = enabled;
+        manager.setSupervisorQuestions(enabled);
+      },
+      setMaxSubagentDepth,
+      setMaxSubagentSpawnsPerBranch: (n) =>
+        manager.setMaxSubagentSpawnsPerBranch(n),
+      setFallbackSubagent,
+      setWorktreeIsolation: setWorktreeIsolationEnabled,
+      setAgentTiers: setAgentTiersSettings,
+    });
+    pi.events.emit("subagents:settings_loaded", { settings });
+  }
+  applyRuntimeSettings(startupSettings);
 
   // A tier that nothing defines is a typo, and the resolver would only reach it
   // on the first spawn that needs it — possibly minutes in, mid-task. Report it
@@ -2201,7 +2228,7 @@ function activateRootRuntime(
     // In `model` mode an off-screen mention-only turn rewrites the typed task
     // without copying parent history or its request-local context hooks.
     // Nothing reaches the chat, and it starts an ordinary top-level agent.
-    const registeredAgentTool = agentToolRef;
+    const registeredAgentTool = agentToolRef ? freshAgentToolDefinition() : undefined;
     if (getAgentMentionMode() === "model" && registeredAgentTool) {
       // The hidden turn is itself a provider call. Refuse before saying
       // "Starting" or spending that call when its inherited parent model is
@@ -2294,15 +2321,13 @@ function activateRootRuntime(
   // The catalogue is injected into the description rather than left to a lookup
   // tool: the host has to pick a tier on its first call, and a tool it must
   // remember to call first is a tool it will skip.
-  const tierListText = buildAgentTierListText();
-  const compactTierListText = buildCompactAgentTierListText();
-  const tierSection = tierListText ? `\n\n${tierListText}` : "";
-  const compactTierSection = compactTierListText
-    ? `\n\n${compactTierListText}`
-    : "";
+  const tierSection = (compact = false): string => {
+    const text = compact ? buildCompactAgentTierListText() : buildAgentTierListText();
+    return text ? `\n\n${text}` : "";
+  };
 
-  const compactAgentToolDescription = `Launch an autonomous agent for complex, multi-step tasks. Agent types:
-${buildCompactTypeListText()}${compactTierSection}
+  const compactAgentToolDescription = () => `Launch an autonomous agent for complex, multi-step tasks. Agent types:
+${buildCompactTypeListText()}${tierSection(true)}
 
 Custom agents: .pi/agents/<name>.md (project) or ${getAgentDir()}/agents/<name>.md (global).
 
@@ -2314,12 +2339,12 @@ Notes:
 - isolation: "worktree" runs the agent in an isolated git worktree; changes land on a branch.
 - Raw inherit_context is unavailable; put only an explicitly sanitized summary in the task prompt.`;
 
-  const fullAgentToolDescription = `Launch a new agent to handle complex, multi-step tasks autonomously. Each agent type has specific capabilities and tools available to it.
+  const fullAgentToolDescription = () => `Launch a new agent to handle complex, multi-step tasks autonomously. Each agent type has specific capabilities and tools available to it.
 
 Available agent types and the tools they have access to:
 ${buildTypeListText()}
 
-Custom agents can be defined in .pi/agents/<name>.md (project) or ${getAgentDir()}/agents/<name>.md (global) — they are picked up automatically. Project-level agents override global ones. Creating a .md file with the same name as a default agent overrides it.${tierSection}
+Custom agents can be defined in .pi/agents/<name>.md (project) or ${getAgentDir()}/agents/<name>.md (global) — they are picked up automatically. Project-level agents override global ones. Creating a .md file with the same name as a default agent overrides it.${tierSection()}
 
 When using the Agent tool, specify a subagent_type parameter to select which agent type to use.
 
@@ -2367,8 +2392,8 @@ Terse command-style prompts produce shallow, generic work.
       // Both carry their own leading blank line, so a template that drops the
       // placeholder inline renders byte-identically to the built-in description
       // whether or not any tier is configured.
-      tierList: () => tierSection,
-      compactTierList: () => compactTierSection,
+      tierList: () => tierSection(),
+      compactTierList: () => tierSection(true),
       defaultTier: getDefaultAgentTierText,
       agentDir: getAgentDir,
       scheduleGuideline: () => scheduleGuideline,
@@ -2384,10 +2409,12 @@ Terse command-style prompts produce shallow, generic work.
   };
 
   const loadCustomToolDescription = (): string | undefined => {
+    const trust = captureProjectTrust(configurationOwner);
     for (const path of [
-      join(sessionCwd, ".pi", "agent-tool-description.md"),
+      ...(trust.trusted ? [join(trust.cwd, ".pi", "agent-tool-description.md")] : []),
       join(getAgentDir(), "agent-tool-description.md"),
     ]) {
+      if (!trust.trusted && isProjectResource(path, trust.cwd)) continue;
       try {
         if (!existsSync(path)) continue;
         const text = readFileSync(path, "utf-8").trim();
@@ -2402,9 +2429,11 @@ Terse command-style prompts produce shallow, generic work.
     return undefined;
   };
 
-  const agentToolDescription = (() => {
+  const agentToolDescription = () => {
+    const trust = captureProjectTrust(configurationOwner);
+    if (trust.cwd !== activeTrust.cwd || trust.trusted !== activeTrust.trusted) reloadCustomAgents();
     const mode = getToolDescriptionMode();
-    if (mode === "compact") return compactAgentToolDescription;
+    if (mode === "compact") return compactAgentToolDescription();
     if (mode === "custom") {
       const custom = loadCustomToolDescription();
       if (custom) return custom;
@@ -2412,16 +2441,18 @@ Terse command-style prompts produce shallow, generic work.
         '[pi-subagents] toolDescriptionMode is "custom" but no agent-tool-description.md found — using "full"',
       );
     }
-    return fullAgentToolDescription;
-  })();
+    return fullAgentToolDescription();
+  };
 
   // Captured so the mention clone can hand the copy the REAL registered tool:
   // its handler closes over this activation, which is what makes a clone-driven
   // spawn an ordinary top-level agent rather than something the fork owns.
+  const agentTypeParameterDescription = () =>
+    `The type of specialized agent to use. Available types: ${getAvailableTypes().join(", ")}. Custom agents from .pi/agents/*.md (project) or ${getAgentDir()}/agents/*.md (global) are also available.`;
   const agentTool = defineTool({
     name: SUBAGENT_TOOL_NAMES.AGENT,
     label: "Agent",
-    description: agentToolDescription,
+    get description() { return agentToolDescription(); },
     promptSnippet: "Launch autonomous sub-agents for complex multi-step tasks",
     promptGuidelines: [
       "Use Agent with specialized agents when the task matches an agent type's description. Subagents are valuable for parallelizing independent queries or for protecting the main context window from excessive results, but should not be used excessively when not needed. Importantly, avoid duplicating work that subagents are already doing — if you delegate research to a subagent, do not also perform the same searches yourself.",
@@ -2438,7 +2469,7 @@ Terse command-style prompts produce shallow, generic work.
           "A short (3-5 word) description of the task (shown in UI).",
       }),
       subagent_type: Type.String({
-        description: `The type of specialized agent to use. Available types: ${getAvailableTypes().join(", ")}. Custom agents from .pi/agents/*.md (project) or ${getAgentDir()}/agents/*.md (global) are also available.`,
+        description: agentTypeParameterDescription(),
       }),
       tier: Type.Optional(
         Type.String({
@@ -2720,7 +2751,8 @@ Terse command-style prompts produce shallow, generic work.
       if (!resolvedConfig.agentTierSelected) {
         const scopeVerdict = checkModelScope({
           model,
-          cwd: ctx.cwd,
+          cwd: activeTrust.cwd,
+          authority: activeTrust,
           modelRegistry: ctx.modelRegistry,
           callerSupplied: resolvedConfig.modelFromParams,
           agentLabel: customConfig?.displayName ?? subagentType,
@@ -3217,6 +3249,42 @@ Terse command-style prompts produce shallow, generic work.
   pi.registerTool(agentTool);
   agentToolRef = agentTool;
 
+  // Pi snapshots description and parameters when wrapping a registered tool.
+  // Trust changes alone emit no host event. Re-register before each new prompt,
+  // ahead of Pi's effective loadout snapshot, using its public post-bind refresh.
+  // Turn end also covers provider continuations after tools revoke authority.
+  // Keep the same exposure/execution policy and retain the active set.
+  function freshAgentToolDefinition() {
+    reloadCustomAgents();
+    return {
+      ...agentTool,
+      description: agentToolDescription(),
+      parameters: {
+        ...agentTool.parameters,
+        properties: {
+          ...agentTool.parameters.properties,
+          subagent_type: { ...agentTool.parameters.properties.subagent_type, description: agentTypeParameterDescription() },
+          tier: { ...agentTool.parameters.properties.tier, description: buildAgentTierParameterDescription() },
+        },
+      },
+    };
+  }
+  const refreshAgentDeclaration = () => {
+    const refreshed = freshAgentToolDefinition();
+    const activeTools = pi.getActiveTools();
+    pi.registerTool(refreshed);
+    // Pi's explicit --tools/SDK tools selector can re-activate every matching
+    // name during registry refresh. A metadata refresh must not undo a later
+    // activation/exposure decision by the host or another extension.
+    const refreshedActive = pi.getActiveTools();
+    if (activeTools.length !== refreshedActive.length || activeTools.some((name, i) => name !== refreshedActive[i])) {
+      pi.setActiveTools(activeTools);
+    }
+    agentToolRef = refreshed;
+  };
+  pi.on("before_agent_start", refreshAgentDeclaration);
+  pi.on("turn_end", refreshAgentDeclaration);
+
   // ---- get_subagent_result tool ----
 
   pi.registerTool(
@@ -4834,7 +4902,7 @@ Do not wrap the response in a markdown code fence. Return only the file contents
     //    scoped set would fail the scope check at spawn time.
     if (isScopeModelsEnabled()) {
       const enabled = resolveEnabledModels(
-        readEnabledModels(sessionCwd),
+        readEnabledModels(sessionCwd, captureProjectTrust(configurationOwner)),
         ctx.modelRegistry,
         sessionCwd,
       );

package/src/model-scope.ts

@@ -8,6 +8,7 @@
  */
 
 import { isModelInScope, type ModelRegistryRef, readEnabledModels, resolveEnabledModels } from "./enabled-models.js";
+import type { ProjectTrust } from "./project-trust.js";
 
 /**
  * When enabled, subagent model choices are validated against `enabledModels`
@@ -41,6 +42,8 @@ export type ModelScopeVerdict =
 export function checkModelScope(args: {
   model: { provider: string; id: string } | undefined;
   cwd: string;
+  /** Captured config root/trust and retained ancestor denials; omit only for standalone helpers. */
+  authority?: ProjectTrust;
   modelRegistry: ModelRegistryRef;
   /** True when the model came from the tool call rather than frontmatter. */
   callerSupplied: boolean;
@@ -52,7 +55,7 @@ export function checkModelScope(args: {
   const { model, cwd, modelRegistry, callerSupplied, agentLabel, modelInput } = args;
   if (!scopeModelsEnabled || !model) return { kind: "ok" };
 
-  const allowed = resolveEnabledModels(readEnabledModels(cwd), modelRegistry, cwd);
+  const allowed = resolveEnabledModels(readEnabledModels(cwd, args.authority), modelRegistry, cwd);
   if (!allowed || isModelInScope(model, allowed)) return { kind: "ok" };
 
   // A tier whose profile says `inherit` names no model of its own, so fall back

package/src/nested-tools.ts

@@ -27,6 +27,7 @@ import {
   streamToOutputFile,
   writeInitialEntry,
 } from "./output-file.js";
+import { configurationContext, type ProjectTrust } from "./project-trust.js";
 import { getForegroundOutcomeNote, getStatusNote, partialOutputSuffix } from "./status-note.js";
 import type {
   AgentConfig,
@@ -104,6 +105,8 @@ export interface NestedToolContext {
   allowedSubagents: "all" | string[];
   /** Root used for agent/config discovery; may differ from the agent's working directory. */
   configCwd: string;
+  /** Immutable configuration authority captured by the runner, including ancestor denials. */
+  projectTrust: ProjectTrust;
 }
 
 function textResult(text: string, isError = false) {
@@ -152,7 +155,9 @@ export function createNestedSubagentTools(context: NestedToolContext): ToolDefin
   // Agents resolve from a registry built for THIS branch's config root (under
   // worktree isolation, the copy). Never via registerAgents — that is
   // process-global state shared with the main session and every other agent.
-  const loadRegistry = () => buildAgentRegistry(loadCustomAgents(context.configCwd));
+  const loadRegistry = () => buildAgentRegistry(loadCustomAgents(
+    context.configCwd, false, context.projectTrust.trusted, context.projectTrust.deniedRoots,
+  ));
   const allowedTypesIn = (registry: Map<string, AgentConfig>): Set<string> | undefined =>
     context.allowedSubagents === "all"
       ? undefined
@@ -250,6 +255,7 @@ export function createNestedSubagentTools(context: NestedToolContext): ToolDefin
         const scopeVerdict = checkModelScope({
           model,
           cwd: context.configCwd,
+          authority: context.projectTrust,
           modelRegistry: ctx.modelRegistry,
           callerSupplied: invocation.modelFromParams,
           agentLabel: config?.displayName ?? resolvedType,
@@ -339,7 +345,7 @@ export function createNestedSubagentTools(context: NestedToolContext): ToolDefin
         }
       };
 
-      // `ctx` is forwarded to the manager unmodified, never captured at tool-build
+      // `ctx` is forwarded with configuration-root provenance, never captured at tool-build
       // time: each AgentSession builds its own ExtensionRunner from that session's
       // cwd/sessionManager/modelRegistry, so this is the CHILD's context. Capturing
       // one earlier would silently give a grandchild the wrong worktree base, the
@@ -350,7 +356,7 @@ export function createNestedSubagentTools(context: NestedToolContext): ToolDefin
       // letting it escape into the child's turn.
       try {
         if (invocation.runInBackground) {
-          const id = context.manager.spawn(context.pi, ctx, resolvedType, params.prompt, {
+          const id = context.manager.spawn(context.pi, configurationContext(ctx, context.configCwd, context.projectTrust), resolvedType, params.prompt, {
             ...options,
             isBackground: true,
           });
@@ -362,7 +368,7 @@ export function createNestedSubagentTools(context: NestedToolContext): ToolDefin
 
         const { record } = await context.manager.spawnAndWait(
           context.pi,
-          ctx,
+          configurationContext(ctx, context.configCwd, context.projectTrust),
           resolvedType,
           params.prompt,
           { ...options, signal },

package/src/project-trust.ts

@@ -0,0 +1,146 @@
+import { lstatSync, readlinkSync, realpathSync } from "node:fs";
+import { dirname, isAbsolute, parse, relative, resolve, sep } from "node:path";
+import type { ExtensionAPI, ExtensionContext, ExtensionFactory, SettingsManager } from "@earendil-works/pi-coding-agent";
+
+// Child contexts report the execution cwd, but their SettingsManager may own
+// a different configuration root. Keep that provenance package-internal when
+// nested tools forward the child's public context to the manager.
+export interface ProjectTrust {
+  readonly cwd: string;
+  readonly trusted: boolean;
+  readonly deniedRoots: readonly string[];
+}
+
+const configurationRoots = new WeakMap<ExtensionContext, {
+  cwd: string;
+  trusted?: boolean;
+  deniedRoots: readonly string[];
+}>();
+
+export function configurationContext(ctx: ExtensionContext, cwd: string, trust?: ProjectTrust): ExtensionContext {
+  const previous = configurationRoots.get(ctx);
+  configurationRoots.set(ctx, {
+    cwd,
+    trusted: trust?.trusted ?? previous?.trusted,
+    deniedRoots: Object.freeze([...new Set([...(previous?.deniedRoots ?? []), ...(trust?.deniedRoots ?? [])])]),
+  });
+  return ctx;
+}
+
+/** A changed configuration root is denied; ancestor denials survive every hop. */
+export function childProjectTrust(parent: ProjectTrust, cwd: string): ProjectTrust {
+  const trusted = parent.trusted && isSameConfiguration(cwd, parent.cwd);
+  return Object.freeze({
+    cwd: canonicalPath(cwd),
+    trusted,
+    deniedRoots: Object.freeze([...new Set([...parent.deniedRoots, ...(trusted ? [] : [canonicalPath(cwd)])])]),
+  });
+}
+
+/** Pi's MCP factory reads config from the session cwd; pin only its bootstrap to the config root. */
+export function configurationMcpFactory(factory: ExtensionFactory, cwd: string, settings: SettingsManager): ExtensionFactory {
+  return (pi) => factory(new Proxy(pi, {
+    get(target, key, receiver) {
+      if (key === "on") return ((event: string, handler: (event: unknown, ctx: ExtensionContext) => unknown) => {
+        if (event === "session_start") {
+          return target.on("session_start", async (event, ctx) => {
+            await handler(event, {
+              ...ctx,
+              cwd,
+              isProjectTrusted: () => settings.isProjectTrusted(),
+            });
+          });
+        }
+        return Reflect.apply(target.on, target, [event, handler]);
+      }) as ExtensionAPI["on"];
+      return Reflect.get(target, key, receiver);
+    },
+  }));
+}
+
+function canonicalPath(path: string): string {
+  try {
+    return realpathSync(path);
+  } catch {
+    return resolve(path);
+  }
+}
+
+/** Capture before child resolution/async work; missing or failed trust is denial. */
+export function captureProjectTrust(ctx: ExtensionContext): ProjectTrust {
+  const provenance = configurationRoots.get(ctx);
+  const cwd = canonicalPath(provenance?.cwd ?? ctx.cwd);
+  let trusted = false;
+  try {
+    // Validate the public trust API even with retained authority. If present,
+    // prefer the captured configuration trust to a late execution-cwd callback.
+    if (typeof ctx.isProjectTrusted === "function") {
+      const publicTrust = ctx.isProjectTrusted() === true;
+      trusted = provenance?.trusted ?? publicTrust;
+    }
+  } catch {
+    // A context that cannot establish trust must not authorize project code.
+  }
+  return Object.freeze({
+    cwd,
+    trusted,
+    deniedRoots: Object.freeze([...new Set([...(provenance?.deniedRoots ?? []), ...(trusted ? [] : [cwd])])]),
+  });
+}
+
+export function isSameConfiguration(cwd: string, parentCwd: string): boolean {
+  return canonicalPath(cwd) === parentCwd;
+}
+
+/**
+ * Check every traversed prefix, including intermediate symlink targets. A
+ * global alias into denied metadata cannot gain authority by pointing its
+ * descendants back outside. This is provenance admission, not a race-free
+ * filesystem sandbox; an absent leaf still has its existing ancestors checked.
+ */
+export function isProjectResource(path: string, cwd: string): boolean {
+  if (path.startsWith("builtin:")) return false;
+  const roots = [resolve(cwd), canonicalPath(cwd)];
+  const within = (file: string): boolean => roots.some(root => {
+    const rel = relative(root, file);
+    return rel === "" || (rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
+  });
+  const visited = new Set<string>();
+  const traverse = (file: string): boolean => {
+    // Normalize separator variants, never dot segments. Both resolve and join
+    // would erase a traversed symlink before a following ".." is inspected.
+    let absolute = sep === "\\" ? file.replaceAll("/", sep) : file;
+    if (!isAbsolute(absolute)) {
+      const root = parse(absolute).root;
+      // Resolve only the base (including Windows drive-relative bases), not
+      // the unexamined components supplied by the caller or readlink.
+      absolute = `${resolve(root || ".")}${sep}${absolute.slice(root.length)}`;
+    }
+    let prefix = parse(absolute).root;
+    if (within(prefix) || within(canonicalPath(prefix))) return true;
+    for (const component of absolute.slice(prefix.length).split(sep)) {
+      if (!component) continue;
+      prefix = `${prefix}${prefix.endsWith(sep) ? "" : sep}${component}`;
+      if (within(prefix) || within(canonicalPath(prefix))) return true;
+      try {
+        if (!lstatSync(prefix).isSymbolicLink()) continue;
+      } catch {
+        // No readable descendant can exist beyond an absent/invalid prefix.
+        return false;
+      }
+      // Unknown/cyclic resolution is not evidence of global authority.
+      if (visited.has(prefix) || visited.size >= 64) return true;
+      visited.add(prefix);
+      try {
+        const target = readlinkSync(prefix);
+        if (traverse(isAbsolute(target) ? target : `${dirname(prefix)}${sep}${target}`)) return true;
+      } catch {
+        return true;
+      } finally {
+        visited.delete(prefix);
+      }
+    }
+    return false;
+  };
+  return traverse(path);
+}

package/src/settings.ts

@@ -12,6 +12,7 @@ import { isManagedAgentTier, MAX_AGENT_TIER_PROFILES } from "@signalridge/pi-sub
 // edit index.ts in the same change.
 import { setDefaultToolTimeoutMs } from "./agent-runner.js";
 import { NO_FALLBACK } from "./agent-types.js";
+import { isProjectResource } from "./project-trust.js";
 import type { JoinMode, ThinkingLevel } from "./types.js";
 
 /** How a `@handle message` mention is dispatched. See `agentMentions`. */
@@ -722,11 +723,13 @@ function readSettingsFile(path: string): ReadSettings {
  * Load merged settings: global provides defaults, project overrides. Agent-tier
  * profiles are complete replacement units: a project entry never inherits one
  * field from the global entry, and an invalid project entry blocks that global
- * entry instead of silently reviving it.
+ * entry instead of silently reviving it. Runtime callers must pass captured trust;
+ * the default preserves standalone helper compatibility.
  */
-export function loadSettings(cwd: string = process.cwd()): SubagentsSettings {
-  const global = readSettingsFile(globalPath());
-  const project = readSettingsFile(projectPath(cwd));
+export function loadSettings(cwd: string = process.cwd(), projectTrusted = true): SubagentsSettings {
+  const empty = (): ReadSettings => ({ settings: {}, agentTiers: emptyAgentTiersSource() });
+  const global = projectTrusted || !isProjectResource(globalPath(), cwd) ? readSettingsFile(globalPath()) : empty();
+  const project = projectTrusted ? readSettingsFile(projectPath(cwd)) : empty();
   const { agentTiers: _globalAgentTiers, ...globalSettings } = global.settings;
   const { agentTiers: _projectAgentTiers, ...projectSettings } = project.settings;
   const agentTiers = mergeAgentTierSources(global.agentTiers, project.agentTiers);

package/src/skill-loader.ts

@@ -30,37 +30,48 @@ export interface PreloadedSkill {
   content: string;
 }
 
-export function preloadSkills(skillNames: string[], cwd: string): PreloadedSkill[] {
-  return skillNames.map((name) => ({ name, content: loadSkillContent(name, cwd) }));
+export interface PreloadSkillsOptions {
+  /** Denied/unknown project trust excludes both project roots; user skills remain available. */
+  projectTrusted: boolean;
+  /** Preserve denied source provenance even through aliases of user skill roots. */
+  deniedResource?: (path: string) => boolean;
 }
 
-function loadSkillContent(name: string, cwd: string): string {
+export function preloadSkills(skillNames: string[], cwd: string, options: PreloadSkillsOptions): PreloadedSkill[] {
+  return skillNames.map((name) => ({ name, content: loadSkillContent(name, cwd, options) }));
+}
+
+function loadSkillContent(name: string, cwd: string, options: PreloadSkillsOptions): string {
   if (isUnsafeName(name)) {
     return `(Skill "${name}" skipped: name contains path traversal characters)`;
   }
   const roots = [
-    join(cwd, ".pi", "skills"), // project — Pi standard
-    join(cwd, ".agents", "skills"), // project — Agent Skills spec
+    ...(options.projectTrusted === true ? [
+      join(cwd, ".pi", "skills"), // project — Pi standard
+      join(cwd, ".agents", "skills"), // project — Agent Skills spec
+    ] : []),
     join(getAgentDir(), "skills"), // user — Pi standard
     join(homedir(), ".agents", "skills"), // user — Agent Skills spec
     join(homedir(), ".pi", "skills"), // legacy global, pre-Pi
   ];
   for (const root of roots) {
-    const content = findInRoot(root, name);
+    if (options.deniedResource?.(root)) continue;
+    const content = findInRoot(root, name, options.deniedResource);
     if (content !== undefined) return content;
   }
   return `(Skill "${name}" not found in .pi/skills/, .agents/skills/, or global skill locations)`;
 }
 
-function findInRoot(root: string, name: string): string | undefined {
+function findInRoot(root: string, name: string, deniedResource?: (path: string) => boolean): string | undefined {
   if (isSymlink(root)) return undefined; // reject symlinked roots entirely
-  const flat = safeReadFile(join(root, `${name}.md`))?.trim();
+  const flatPath = join(root, `${name}.md`);
+  const flat = deniedResource?.(flatPath) ? undefined : safeReadFile(flatPath)?.trim();
   if (flat !== undefined) return flat;
-  return findSkillDirectory(root, name);
+  return findSkillDirectory(root, name, deniedResource);
 }
 
 /** BFS under `root` for a directory named `name` containing `SKILL.md`. Pi-conforming filters. */
-function findSkillDirectory(root: string, name: string): string | undefined {
+function findSkillDirectory(root: string, name: string, deniedResource?: (path: string) => boolean): string | undefined {
   if (!existsSync(root)) return undefined;
   const queue: string[] = [root];
 
@@ -85,6 +96,7 @@ function findSkillDirectory(root: string, name: string): string | undefined {
       // Symlinked dirs already filtered by entry.isDirectory() — Dirent uses lstat semantics.
       const path = join(current, entry.name);
       const skillMd = join(path, "SKILL.md");
+      if (deniedResource?.(skillMd)) continue;
       const isSkillDir = existsSync(skillMd);
 
       if (isSkillDir) {