@bermudi/pi-delegate 0.1.8 → 0.1.10

package/README.md

@@ -47,9 +47,17 @@ The other built-ins are:
   default. Set `workspace: "shared"` when a reviewer needs a persistent
   `sessionId`.
 
-Fresh built-ins inherit the parent's exact model object and thinking level.
-Task-level overrides win; settings can provide unconditional overrides or exact
-parent-model overrides under `delegate.agentOverridesByParentModel`.
+A same-named Markdown file can override any built-in (first definition wins
+across `.pi/agents/`, `~/.pi/agent/agents/`, `~/.agents/`, `.claude/agents/`,
+`~/.claude/agents/`). A prompt-only override keeps the built-in's tools and
+workspace — `scout` stays read-only and `reviewer` stays scratch unless the
+file explicitly sets `tools` or `workspace`. Fresh built-ins inherit the
+parent's exact model object and thinking level; an explicit `model`/`thinking`
+in the Markdown file replaces that inheritance. Task fields always win, and for
+`scout`/`coder`/`reviewer` settings overrides (`settings.json`
+`delegate.agentOverrides` / `delegate.agentOverridesByParentModel`) win over the
+Markdown file, while `default` ignores settings and uses only an explicit
+Markdown `model`/`thinking` when present.
 
 ### Disposable scratch workspace
 
@@ -142,15 +150,22 @@ over an installed extension.
   model by default.
 - **Default subagent** — The reserved built-in `agent: "default"` profile. It
   mirrors the live parent's model, thinking level, delegatable native tools, and
-  base system prompt while preserving delegate's extension/context isolation.
+  base system prompt while preserving delegate's extension/context isolation;
+  a `default.md` Markdown file can override its prompt/tools/model/thinking
+  (first definition wins — a prompt-only file keeps the parent-mirrored tools
+  and thinking/model inheritance).
 - **Custom agent** — A subagent profile defined by the parent, either inline in
   a delegate task (`systemPrompt`, `tools`, and `thinking`) or persisted as a
   Markdown file. The subagent inherits the parent model by default; `model` is a
   rare override. Markdown agents are examples of custom agents.
 - **Named agent** / **Markdown agent** — A reusable custom agent persisted as a
-  Markdown file in `.pi/agents/*.md` or `~/.pi/agent/agents/*.md`. The frontmatter
-  defines its name, description, model, tools, and thinking level; the
-  Markdown body is its system prompt.
+  Markdown file in `.pi/agents/*.md`, `~/.pi/agent/agents/*.md`, `~/.agents/*.md`,
+  `.claude/agents/*.md`, or `~/.claude/agents/*.md` (first definition wins). The frontmatter defines its name, description,
+  model, tools, and thinking level; the Markdown body is its system prompt. A
+  same-named file for a built-in (`default`/`scout`/`coder`/`reviewer`)
+  overrides that built-in; a prompt-only override keeps the built-in's tools
+  and workspace, and an explicit `model`/`thinking` replaces parent inheritance
+  (for `default` settings are ignored, for others settings win over the file).
 - **Ad-hoc subagent** — A subagent created from inline task fields instead of a
   named Markdown agent profile. In current output this is labeled `ad-hoc`.
 - **Inline task** — The task object itself when its configuration is supplied

package/agents.ts

@@ -115,7 +115,7 @@ export function parseFrontmatter(
 
 // ── Agent Discovery ───────────────────────────────────────────────────────
 
-/** Built-in profiles are always available and cannot vary with Markdown files. */
+/** Built-in profiles are always available but can be overridden by a same-named Markdown file. */
 export const BUILTIN_AGENT_CONFIGS: Readonly<Record<string, AgentConfig>> = {
   [DEFAULT_AGENT_NAME]: {
     name: DEFAULT_AGENT_NAME,
@@ -253,12 +253,14 @@ export function loadAgentFile(filePath: string): AgentConfig | null {
   }
   const { data, body } = parseFrontmatter(content, filePath);
   if (!data.name || !data.description) return null;
+  const model = data.model?.trim() || undefined;
+  const thinking = data.thinking?.trim();
   return {
     name: data.name,
     description: data.description,
-    model: data.model,
-    thinking: VALID_THINKING.has(data.thinking ?? "")
-      ? (data.thinking as ThinkingLevel)
+    model,
+    thinking: VALID_THINKING.has(thinking ?? "")
+      ? (thinking as ThinkingLevel)
       : "off",
     // Omitted/blank `tools:` → inherit the full agent set (`*`), matching
     // CC/OpenCode/Devin. A previous version rejected empty tools; that was
@@ -295,6 +297,8 @@ export function loadClaudeAgentFile(filePath: string): AgentConfig | null {
   }
   const { data, body } = parseFrontmatter(content, filePath);
   if (!data.name || !data.description) return null;
+  const model = data.model?.trim();
+  const thinking = data.thinking?.trim();
 
   // Track whether the user wrote an explicit `tools:` allowlist. Omitted or
   // blank means "inherit the full default set" (`*`), and only in that case
@@ -327,13 +331,13 @@ export function loadClaudeAgentFile(filePath: string): AgentConfig | null {
     name: data.name,
     description: data.description,
     // `inherit` is Claude's "use parent" default — drop it so we fall through
-    // to parent-model inheritance. Any other value passes through verbatim.
+    // to parent-model inheritance. Other values are stored trimmed.
     model:
-      data.model && data.model.toLowerCase() === "inherit"
+      model && model.toLowerCase() === "inherit"
         ? undefined
-        : data.model,
-    thinking: VALID_THINKING.has(data.thinking ?? "")
-      ? (data.thinking as ThinkingLevel)
+        : model || undefined,
+    thinking: VALID_THINKING.has(thinking ?? "")
+      ? (thinking as ThinkingLevel)
       : "off",
     tools,
     systemPrompt: body,
@@ -382,6 +386,7 @@ export function discoverAgents(cwd: string): Map<string, AgentConfig> {
   const agents = new Map<string, AgentConfig>(
     Object.entries(BUILTIN_AGENT_CONFIGS),
   );
+  const overriddenBuiltins = new Set<string>();
   const loadDir = (
     { dir, scope }: { dir: string; scope: AgentConfig["scope"] },
     loader: (fp: string) => AgentConfig | null,
@@ -396,13 +401,134 @@ export function discoverAgents(cwd: string): Map<string, AgentConfig> {
       if (!e.name.endsWith(".md") || e.name.endsWith(".chain.md")) continue;
       const filePath = path.join(dir, e.name);
       const cfg = loader(filePath);
-      if (cfg && isBuiltinAgentName(cfg.name)) {
-        console.warn(
-          `[delegate] ignoring agent profile '${cfg.name}' from ${filePath}: the name is reserved for a built-in delegate profile.`,
-        );
+      if (!cfg) continue;
+      if (isBuiltinAgentName(cfg.name)) {
+        const existing = agents.get(cfg.name);
+        if (existing?.builtin && !overriddenBuiltins.has(cfg.name)) {
+          // Markdown can override a built-in: first definition wins, replacing
+          // the default config. This lets users customize systemPrompt, tools,
+          // etc. via a Markdown file. Preserve builtin workspace when the file
+          // does not specify one (Markdown profiles have no workspace
+          // frontmatter today), and preserve builtin tools when the file omits
+          // the tools key so a prompt-only override does not silently escalate
+          // privileges (e.g. scout staying read-only).
+          // `disallowedTools` is only meaningful for Claude profiles (which
+          // actually implement the denylist); for native Pi loaders it is
+          // ignored, so it must not be treated as an explicit tools change.
+          let rawTools: string | undefined;
+          let rawWorkspace: string | undefined;
+          let rawDisallowedTools: string | undefined;
+          let rawModel: string | undefined;
+          let rawThinking: string | undefined;
+          try {
+            const content = fs.readFileSync(filePath, "utf-8");
+            const { data } = parseFrontmatter(content, filePath);
+            rawTools = data.tools;
+            rawWorkspace = (data as Record<string, string>).workspace;
+            rawDisallowedTools = (data as Record<string, string>)
+              .disallowedTools;
+            rawModel = data.model;
+            rawThinking = data.thinking;
+          } catch {
+            // ignore, keep parsed tools/workspace
+          }
+          const hasExplicitAllowlist =
+            rawTools !== undefined && rawTools.trim() !== "";
+          const hasDenylist =
+            scope === "claude" &&
+            rawDisallowedTools !== undefined &&
+            rawDisallowedTools.trim() !== "";
+          const hasExplicitTools = hasExplicitAllowlist || hasDenylist;
+          const hasExplicitWorkspace =
+            rawWorkspace === "shared" || rawWorkspace === "scratch";
+          const hasInvalidWorkspace =
+            rawWorkspace !== undefined &&
+            rawWorkspace.trim() !== "" &&
+            !hasExplicitWorkspace;
+          const hasExplicitModel =
+            rawModel !== undefined &&
+            rawModel.trim() !== "" &&
+            rawModel.trim().toLowerCase() !== "inherit";
+          const hasExplicitThinking =
+            rawThinking !== undefined &&
+            rawThinking.trim() !== "" &&
+            VALID_THINKING.has(rawThinking.trim());
+          if (
+            cfg.name === DEFAULT_AGENT_NAME &&
+            !hasExplicitAllowlist &&
+            hasDenylist
+          ) {
+            // For `default`, a deny-only override must be applied to the
+            // parent's actual tools at resolution, not to the static
+            // DEFAULT_TOOLS at discovery. Materializing against DEFAULT_TOOLS
+            // would grant write/edit when the parent is read-only.
+            const denied = new Set(
+              (rawDisallowedTools ?? "")
+                .split(",")
+                .map((s) => s.trim())
+                .filter(Boolean)
+                .map(
+                  (n) =>
+                    (CLAUDE_TOOL_ALIASES as Record<string, string>)[
+                      n.toLowerCase()
+                    ] ?? null,
+                )
+                .filter((n): n is string => n !== null),
+            );
+            cfg.deniedTools = [...denied];
+            cfg.explicitTools = false;
+            // Keep tools display as the built-in default; resolution will
+            // filter parentNativeTools instead.
+            cfg.tools = existing.tools;
+          } else if (!hasExplicitAllowlist && hasDenylist && existing.tools) {
+            // No explicit allowlist but a Claude denylist is present – apply
+            // the denylist to the built-in's own toolset, not the generic
+            // full set, to avoid turning a denylist into an escalation
+            // (e.g. scout `disallowedTools: Bash` should stay read-only).
+            const denied = new Set(
+              (rawDisallowedTools ?? "")
+                .split(",")
+                .map((s) => s.trim())
+                .filter(Boolean)
+                .map(
+                  (n) =>
+                    (CLAUDE_TOOL_ALIASES as Record<string, string>)[
+                      n.toLowerCase()
+                    ] ?? null,
+                )
+                .filter((n): n is string => n !== null),
+            );
+            cfg.tools = existing.tools.filter((t) => !denied.has(t));
+            cfg.explicitTools = true;
+          } else {
+            if (!hasExplicitTools && existing.tools) {
+              cfg.tools = existing.tools;
+            }
+            cfg.explicitTools = hasExplicitTools;
+          }
+          cfg.explicitModel = hasExplicitModel;
+          cfg.explicitThinking = hasExplicitThinking;
+          // Preserve built-in semantics for model/thinking/workspace handling
+          // in task-resolution – the overridden profile is still a built-in
+          // by name, just with a custom prompt/tools.
+          cfg.builtin = true;
+          if (!rawWorkspace?.trim() && existing.workspace) {
+            cfg.workspace = existing.workspace;
+          } else if (hasExplicitWorkspace) {
+            cfg.workspace = rawWorkspace as AgentConfig["workspace"];
+          } else if (hasInvalidWorkspace) {
+            console.warn(
+              `[delegate] invalid workspace '${rawWorkspace}' in ${filePath}; preserving built-in '${existing.workspace}'. Expected "shared" or "scratch".`,
+            );
+            if (existing.workspace) cfg.workspace = existing.workspace;
+          }
+          cfg.scope = scope;
+          agents.set(cfg.name, cfg);
+          overriddenBuiltins.add(cfg.name);
+        }
         continue;
       }
-      if (cfg && !agents.has(cfg.name)) {
+      if (!agents.has(cfg.name)) {
         cfg.scope = scope;
         agents.set(cfg.name, cfg);
       }

package/config.ts

@@ -129,10 +129,17 @@ function normalizeProviderExtensions(
 // Provider-scoped opt-in extension map for subagents. Keep this aligned with
 // the currently shipped codex remote-compaction integration. `delegate.json`
 // `providerExtensions` replaces a provider's entries (it does not append); an
-// empty array is ignored so the default persists.
-const DEFAULT_PROVIDER_EXTENSIONS: Record<string, readonly string[]> = {
-  "openai-codex": ["git:github.com/bermudi/manaflow-pi-codex"],
-};
+// empty array is ignored so the default persists. Provenance is classification
+// by config presence: every source the user lists is required and fails
+// closed when missing, unverifiable, or broken — including an exact re-listing
+// of a shipped default. Shipped defaults (providers the user never mentioned)
+// are best-effort: they degrade silently to extension-free subagents on Pi's
+// native compaction, because absence of an optional integration is not a
+// warning condition — that is Pi's normal operation.
+const DEFAULT_PROVIDER_EXTENSIONS: Record<string, readonly string[]> =
+  Object.assign(Object.create(null) as Record<string, readonly string[]>, {
+    "openai-codex": ["npm:@bermudi/pi-codex"],
+  });
 
 function resolveProviderExtensions(
   raw: unknown,
@@ -155,7 +162,7 @@ const DEFAULT_DELEGATE_CONFIG: DelegateConfig = {
     wholeTaskMaxRetries: 3,
     wholeTaskBaseDelayMs: 1_000,
   },
-  providerExtensions: DEFAULT_PROVIDER_EXTENSIONS,
+  providerExtensions: {},
   telemetry: {
     enabled: true,
   },
@@ -174,7 +181,15 @@ let __delegateConfig: DelegateConfig = {
 };
 let stallTimeoutOverrideForTesting: number | undefined;
 
-/** Read delegate config from disk. Returns defaults if file missing or corrupt. */
+/** Read delegate config from disk. Returns defaults if file missing or corrupt.
+ *
+ *  The returned `providerExtensions` is the *user-only* view — exactly what the
+ *  file said, defaults excluded. `getSubagentProviderExtensionMap()` is the
+ *  merged (defaults + user) view, and
+ *  `getSubagentProviderExtensionSourcesForProvider()` is the provenance-tagged
+ *  view. Keeping the raw user map here is what lets the sources getter
+ *  distinguish "the user listed this" from "this is a shipped default" by
+ *  config presence rather than string identity. */
 export function loadDelegateConfig(): DelegateConfig {
   try {
     const raw = fs.readFileSync(DELEGATE_CONFIG_PATH, "utf-8");
@@ -191,7 +206,9 @@ export function loadDelegateConfig(): DelegateConfig {
         ...(parsed.concurrency ?? {}),
       },
       retry: { ...DEFAULT_DELEGATE_CONFIG.retry, ...(parsed.retry ?? {}) },
-      providerExtensions: resolveProviderExtensions(parsed.providerExtensions),
+      providerExtensions: normalizeProviderExtensions(
+        parsed.providerExtensions,
+      ),
       telemetry: normalizeTelemetryConfig(parsed.telemetry),
       output: { ...DEFAULT_DELEGATE_CONFIG.output, ...(parsed.output ?? {}) },
     } as DelegateConfig;
@@ -255,7 +272,7 @@ export function _setDelegateConfigForTesting(
       ...DEFAULT_DELEGATE_CONFIG.retry,
       ...(config.retry ?? {}),
     },
-    providerExtensions: resolveProviderExtensions(config.providerExtensions),
+    providerExtensions: normalizeProviderExtensions(config.providerExtensions),
     telemetry: normalizeTelemetryConfig(config.telemetry),
     output: {
       ...DEFAULT_DELEGATE_CONFIG.output,
@@ -266,7 +283,11 @@ export function _setDelegateConfigForTesting(
 }
 
 /**
- * Get the configured provider-scoped extension allowlist for subagents.
+ * Get the configured provider-scoped extension allowlist for subagents:
+ * the merged view (shipped defaults + user config, user entries replacing a
+ * provider's defaults). The stored `config.providerExtensions` itself is the
+ * user-only view; the merge happens here so provenance survives until a
+ * consumer asks for it (`getSubagentProviderExtensionSourcesForProvider`).
  * Explicit configs are normalized here too, so callers using the injected
  * config form get the same case-insensitive and replace-per-provider
  * semantics as the file-backed singleton.
@@ -295,6 +316,60 @@ export function getSubagentProviderExtensionsForProvider(
     : [];
 }
 
+/** A provider-extension source together with how it entered the config. */
+export interface ProviderExtensionSource {
+  /** The normalized source string, as the package manager consumes it. */
+  readonly source: string;
+  /**
+   * Whether the user configured this source themselves (required) or it is a
+   * shipped default for a provider the user never mentioned (best-effort).
+   * Required sources fail closed when missing, unverifiable, or broken;
+   * best-effort defaults degrade silently to extension-free subagents on
+   * Pi's native compaction.
+   */
+  readonly required: boolean;
+}
+
+/**
+ * Get the provenance-tagged extension sources for a provider's subagents.
+ * Classification is by config presence, never by string identity: everything
+ * the user lists in `providerExtensions` is `required: true` — including an
+ * exact re-listing of a shipped default, because typing it into the config
+ * expresses intent. Providers the user never configured fall back to the
+ * shipped defaults, tagged `required: false` (best-effort).
+ */
+export function getSubagentProviderExtensionSourcesForProvider(
+  provider: string | undefined,
+  config: DelegateConfig = __delegateConfig,
+): readonly ProviderExtensionSource[] {
+  const normalized = provider?.trim().toLowerCase();
+  if (!normalized) return [];
+  // Normalize the injected config map so an unnormalized key like " Custom-Provider "
+  // is handled, matching getSubagentProviderExtensionMap / getSubagentProviderExtensionsForProvider.
+  const rawUserMap = config.providerExtensions;
+  const userMap = rawUserMap
+    ? normalizeProviderExtensions(rawUserMap)
+    : (Object.create(null) as Record<string, readonly string[]>);
+  if (Object.prototype.hasOwnProperty.call(userMap, normalized)) {
+    return (userMap[normalized] ?? []).map((source) => ({
+      source,
+      required: true,
+    }));
+  }
+  if (
+    !Object.prototype.hasOwnProperty.call(
+      DEFAULT_PROVIDER_EXTENSIONS,
+      normalized,
+    )
+  ) {
+    return [];
+  }
+  return (DEFAULT_PROVIDER_EXTENSIONS[normalized] ?? []).map((source) => ({
+    source,
+    required: false,
+  }));
+}
+
 // ── Config Getters ───────────────────────────────────────────────────────
 
 /**

package/extension.ts

@@ -18,7 +18,10 @@ import {
 } from "./dispatch.ts";
 import { renderDelegateCall, renderDelegateResult } from "./render-result.ts";
 import { hostCompatError } from "./host-compat.ts";
-import { invalidateHostDepsCache } from "./host.ts";
+import {
+  invalidateHostDepsCache,
+  registerProviderExtensionNotifier,
+} from "./host.ts";
 import { recordTreeNavigation, resetLeafTracking } from "./leaf.ts";
 import { closeAllPooledAgents } from "./pool.ts";
 import {
@@ -122,6 +125,12 @@ export default function delegateExtension(pi: ExtensionAPI): void {
     prepareArguments: normalizeDelegateArguments,
 
     async execute(_id, params: DelegateArguments, signal, onUpdate, ctx) {
+      // Prime the UI notice for best-effort provider extensions that load for
+      // subagents (host.ts consumes it where the fact is discovered). Every
+      // execute re-primes so a stale ctx never sticks.
+      registerProviderExtensionNotifier((message) =>
+        ctx.ui.notify(message, "info"),
+      );
       const parentModelId = ctx.model?.id;
       const tasks = params.tasks ?? [];
       const parentSessionFile = (
@@ -347,6 +356,7 @@ export default function delegateExtension(pi: ExtensionAPI): void {
       // captured pi) to touch. The cancelled completion path still writes one
       // final aggregate after late task results arrive, but never delivers UI.
       clearDelegateStatusContext();
+      registerProviderExtensionNotifier(undefined);
       // A replacement session starts on its own leaf; stale tracking would make
       // every ticket look cross-leaf (or, worse, look same-leaf by accident).
       resetLeafTracking();

package/host.ts

@@ -16,7 +16,8 @@
  * must not run the parent's interactive extensions (custom UI, slash commands,
  * hooks that call `pi.appendEntry()`/`pi.sendMessage()`). A narrow,
  * provider-scoped allowlist is injected as `additionalExtensionPaths` for
- * safety-critical integrations. Those extension-bearing dependencies are
+ * provider-specific integrations (best-effort for shipped defaults). Those
+ * extension-bearing dependencies are
  * deliberately built per session: `AgentSession._buildRuntime` hands the
  * loader's `extensionsResult.runtime` to a new `ExtensionRunner`, whose
  * `bindCore()` overwrites mutable methods on that runtime (`sendMessage`,
@@ -37,7 +38,15 @@
 import { execFileSync } from "node:child_process";
 import { homedir } from "node:os";
 import { existsSync, realpathSync } from "node:fs";
-import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import {
+  basename,
+  dirname,
+  isAbsolute,
+  join,
+  relative,
+  resolve,
+  sep,
+} from "node:path";
 import {
   DefaultPackageManager,
   DefaultResourceLoader,
@@ -49,7 +58,7 @@ import {
 } from "@earendil-works/pi-coding-agent";
 import {
   getSubagentProviderExtensionMap,
-  getSubagentProviderExtensionsForProvider,
+  getSubagentProviderExtensionSourcesForProvider,
 } from "./config.ts";
 
 export interface HostDeps {
@@ -94,6 +103,14 @@ const hostDepsInflight = new Map<string, Promise<HostDeps>>();
 /** Prevent a pre-invalidation build from repopulating or clearing newer state. */
 let hostDepsCacheGeneration = 0;
 
+// When the shipped best-effort default (npm:@bermudi/pi-codex) is absent — the
+// normal state for most users — Pi's DefaultPackageManager.getInstalledPath
+// would synchronously spawn `npm root -g` to check the legacy global fallback.
+// Doing that once per task in a fan-out blocks the event loop N times and
+// serializes the fan-out. Cache the *absence* per dispatch so only the first
+// task in a fan-out pays the cost; the rest skip the lookup entirely.
+const missingBestEffortNpmCache = new Set<string>();
+
 function canonicalPath(candidate: string): string {
   try {
     return realpathSync(candidate);
@@ -508,17 +525,84 @@ async function assertConfiguredNpmVersion(
   }
 }
 
+/** Result of resolving a provider's allowlisted extension sources. */
+interface ProviderExtensionResolution {
+  /** User-scope package roots to inject as subagent extension paths. */
+  paths: string[];
+  /** Roots originating from shipped best-effort defaults; these may degrade
+   * silently — see the drop-site comments for why silence is the design. */
+  bestEffortPaths: Set<string>;
+}
+
+/**
+ * UI notifier for the provider-extension-loaded notice, primed from
+ * extension.ts `execute` (the only place the real, ui-bearing ctx exists —
+ * host-dep construction itself has no UI context). Consumed defensively:
+ * a throw means the ctx went stale (headless run, torn-down TUI) and simply
+ * un-primes the notifier so the next live execute re-primes it.
+ */
+let providerExtensionNotifier: ((message: string) => void) | undefined;
+
+/**
+ * Prime the UI notifier used for the best-effort extension-loaded notice.
+ * Idempotent and cheap; called at the top of every delegate execute. Pass
+ * `undefined` to un-prime (tests) — an un-primed notifier makes the notice a
+ * no-op, which is also the default state in headless/test runs.
+ */
+export function registerProviderExtensionNotifier(
+  notify: ((message: string) => void) | undefined,
+): void {
+  providerExtensionNotifier = notify;
+}
+
+/** provider+root pairs already noticed this process. */
+const noticedProviderExtensionRoots = new Set<string>();
+
+/**
+ * Announce that a shipped best-effort provider integration actually loaded
+ * for delegated subagents. This is the deliberate inverse of the silent
+ * drop: absence of an optional integration is normal and never mentioned,
+ * but a default that IS active changes subagent behavior (remote compaction
+ * on codex models) invisibly — so it gets one info notice per process per
+ * provider+root, not one per dispatch. User-configured sources never get
+ * here: the user installed them knowingly and they fail closed.
+ */
+function noticeProviderExtensionLoaded(
+  provider: string | undefined,
+  root: string,
+): void {
+  const providerName = provider?.trim() || "provider";
+  const key = `${providerName.toLowerCase()}\0${root}`;
+  if (noticedProviderExtensionRoots.has(key)) return;
+  const notify = providerExtensionNotifier;
+  if (!notify) return;
+  const label = basename(root) || root;
+  try {
+    notify(`⚡ ${label} integration active for ${providerName} subagents`);
+    noticedProviderExtensionRoots.add(key);
+  } catch {
+    // Cosmetic notice on a stale ctx — fail open (status.ts precedent for
+    // cached-ctx notify): drop the notifier, keep the key un-noticed so a
+    // live ctx can still surface it later. Delegation is unaffected.
+    providerExtensionNotifier = undefined;
+  }
+}
+
 async function getProviderExtensionPaths(
   provider: string | undefined,
   cwd: string,
   agentDir: string,
   packageLookupSettingsManager: SettingsManager,
-): Promise<string[]> {
-  // Provider-key normalization (trim + lowercase) lives in `config.ts` —
-  // `getSubagentProviderExtensionsForProvider` is the single owner of that
-  // logic, so this module never re-implements it.
-  const requested = getSubagentProviderExtensionsForProvider(provider);
-  if (!requested.length) return [];
+): Promise<ProviderExtensionResolution> {
+  // Provider-key normalization (trim + lowercase) lives in `config.ts` — the
+  // sources getter is the single owner of that logic, so this module never
+  // re-implements it. Provenance (required vs best-effort) is decided there
+  // too, by config presence: user-listed sources fail closed; shipped
+  // defaults degrade silently — the extension-free path is Pi's normal
+  // operation, not a warning condition.
+  const requested = getSubagentProviderExtensionSourcesForProvider(provider);
+  if (!requested.length)
+    return { paths: [], bestEffortPaths: new Set<string>() };
 
   const packageManager = new DefaultPackageManager({
     cwd,
@@ -567,12 +651,34 @@ async function getProviderExtensionPaths(
 
   const installedPaths = new Map<string, string>();
   const missing: string[] = [];
-  for (const source of requested) {
+  for (const { source, required } of requested) {
+    // For best-effort npm defaults that are absent — the normal state for the
+    // shipped optional integration — avoid Pi's legacy global npm fallback
+    // (`npm root -g`) on every task in a fan-out. The first task in a dispatch
+    // still pays the cost to discover the absence, but subsequent tasks with
+    // the same agentDir+source skip the synchronous spawn entirely. The cache
+    // is per-dispatch and cleared on invalidateHostDepsCache.
+    if (!required && source.trim().toLowerCase().startsWith("npm:")) {
+      const missingKey = `${agentDir}\0${source}`;
+      if (missingBestEffortNpmCache.has(missingKey)) {
+        continue;
+      }
+      const userPath = packageManager.getInstalledPath(source, "user");
+      if (!userPath) {
+        missingBestEffortNpmCache.add(missingKey);
+        continue;
+      }
+      installedPaths.set(source, userPath);
+      continue;
+    }
     // Deliberately resolve only the user scope. Project-local packages are
     // untrusted input and must never become executable subagent extensions.
     const userPath = packageManager.getInstalledPath(source, "user");
     if (!userPath) {
-      missing.push(source);
+      if (required) missing.push(source);
+      // A best-effort default that is not installed is skipped silently: for
+      // most users the package was never installed at all, and its absence is
+      // the normal, correct state — not something to warn about.
       continue;
     }
     installedPaths.set(source, userPath);
@@ -587,23 +693,29 @@ async function getProviderExtensionPaths(
   }
 
   const paths = new Set<string>();
-  for (const source of requested) {
+  const bestEffortPaths = new Set<string>();
+  for (const { source, required } of requested) {
     const userPath = installedPaths.get(source);
-    // Every requested source was collected above; this guard keeps the map
-    // boundary explicit if that invariant changes later.
-    if (!userPath) {
-      throw new Error(
-        "A configured provider extension disappeared before validation; delegation stopped.",
-      );
-    }
-    validateInstalledPath(source, userPath);
-    if (hasNpmVersionSpecifier(source)) {
-      await assertConfiguredNpmVersion(packageManager, source, userPath);
+    // Best-effort defaults that were not installed never reached the map.
+    if (!userPath) continue;
+    try {
+      validateInstalledPath(source, userPath);
+      if (hasNpmVersionSpecifier(source)) {
+        await assertConfiguredNpmVersion(packageManager, source, userPath);
+      }
+    } catch (error) {
+      if (required) throw error;
+      // A best-effort default that cannot be verified is skipped, not loaded
+      // and not fatal. Silent by design: an installed-but-broken package also
+      // fails in the parent's own extension inventory, where Pi surfaces it;
+      // this path only mirrors a signal the user has already seen.
+      continue;
     }
     paths.add(userPath);
+    if (!required) bestEffortPaths.add(userPath);
   }
 
-  return [...paths];
+  return { paths: [...paths], bestEffortPaths };
 }
 
 /**
@@ -646,14 +758,16 @@ export async function getHostDeps(options: HostDepsOptions): Promise<HostDeps> {
       .map(([provider, entries]) => [provider, [...entries]] as const),
   );
   const providerConfigs = options.providerConfigs ?? [];
-  const requestedExtensions = getSubagentProviderExtensionsForProvider(
+  const requestedExtensions = getSubagentProviderExtensionSourcesForProvider(
     options.modelProvider,
   );
 
-  // Resolve provider extensions before deciding whether to use the cache. This
-  // fails closed for missing sources while keeping both package lookup and child
-  // resource loading isolated from executable project settings.
+  // Resolve provider extensions before deciding whether to use the cache.
+  // User-configured sources fail closed when missing; shipped defaults are
+  // best-effort and silently drop instead. Both package lookup and child
+  // resource loading stay isolated from executable project settings.
   let additionalExtensionPaths: string[] = [];
+  let bestEffortExtensionRoots = new Set<string>();
   if (requestedExtensions.length > 0) {
     // Package lookup is a user-scope trust boundary. Pi's legacy npm fallback
     // may execute the configured npmCommand to discover the global npm root,
@@ -663,12 +777,14 @@ export async function getHostDeps(options: HostDepsOptions): Promise<HostDeps> {
       agentDir,
       { projectTrusted: false },
     );
-    additionalExtensionPaths = await getProviderExtensionPaths(
+    const resolution = await getProviderExtensionPaths(
       options.modelProvider,
       options.cwd,
       agentDir,
       packageLookupSettingsManager,
     );
+    additionalExtensionPaths = resolution.paths;
+    bestEffortExtensionRoots = resolution.bestEffortPaths;
   }
 
   // Provider configs may contain functions (custom stream/OAuth handlers), so a
@@ -731,65 +847,111 @@ export async function getHostDeps(options: HostDepsOptions): Promise<HostDeps> {
     if (testRetryBaseMs !== undefined) {
       installFastRetry(resolvedSettingsManager, testRetryBaseMs);
     }
-    const resourceLoader = new DefaultResourceLoader({
-      cwd: options.cwd,
-      agentDir,
-      settingsManager: resolvedSettingsManager,
-      // Subagents are headless workers — they must not load the parent's
-      // interactive extension inventory. The only paths supplied here are the
-      // explicitly allowlisted, user-scoped provider extensions.
-      noExtensions: true,
-      // Global AGENTS.md files describe the parent harness, not the delegated
-      // task. Keep cwd/ancestor project context discovery, but remove Pi's
-      // global file and the legacy ~/.agents equivalent. This override also
-      // handles symlinked global files because it compares discovered paths.
-      agentsFilesOverride: ({ agentsFiles }) => ({
-        agentsFiles: agentsFiles.filter(
-          ({ path: contextPath }) =>
-            !isExcludedGlobalContextFile(contextPath, agentDir),
-        ),
-      }),
-      ...(additionalExtensionPaths.length ? { additionalExtensionPaths } : {}),
-      // When a named agent supplies a custom prompt, it becomes the loader's
-      // customPrompt — overriding the default system prompt AgentSession would
-      // otherwise build. `systemPrompt` (the source) wins over file discovery.
-      ...(options.systemPrompt !== undefined
-        ? { systemPrompt: options.systemPrompt }
-        : {}),
-    });
-    await resourceLoader.reload();
-
-    const extensionsResult = resourceLoader.getExtensions();
-    const extensionErrors = extensionsResult.errors;
-    const loadedExtensionPaths = extensionsResult.extensions.map(
-      (extension) => extension.resolvedPath || extension.path,
-    );
-    // A package can resolve successfully while exposing only skills/prompts,
-    // or a malformed manifest can expose no loadable extension at all. Treat
-    // that as a failed provider integration rather than silently delegating
-    // without the safety-critical behavior the allowlist requested.
-    const missingExtensionRoots = additionalExtensionPaths.filter(
-      (root) =>
-        !loadedExtensionPaths.some((extensionPath) =>
-          isPathWithinDirectory(root, extensionPath),
-        ),
-    );
-    if (extensionErrors.length > 0 || missingExtensionRoots.length > 0) {
+    // Best-effort default sources that fail to load are dropped and the loader
+    // is rebuilt without them, so the subagent runs extension-free on Pi's
+    // native compaction — silently, per the drop-site rationale above.
+    // User-configured sources still fail closed below.
+    //
+    // Loop invariant: pi's ResourceLoader.reload() never *throws* for an
+    // extension's own failure — its loader wraps module import AND factory
+    // invocation in try/catch and returns them as `extensionsResult.errors`
+    // (verified in pi 0.80.x, core/extensions/loader.ts). A reload() throw is
+    // therefore environmental (settings reload, package resolution) and not
+    // attributable to any supplied root; letting it propagate is correct even
+    // when best-effort roots are present.
+    let extensionPaths = additionalExtensionPaths;
+    let resourceLoader: DefaultResourceLoader;
+    for (;;) {
+      resourceLoader = new DefaultResourceLoader({
+        cwd: options.cwd,
+        agentDir,
+        settingsManager: resolvedSettingsManager,
+        // Subagents are headless workers — they must not load the parent's
+        // interactive extension inventory. The only paths supplied here are
+        // the explicitly allowlisted, user-scoped provider extensions.
+        noExtensions: true,
+        // Global AGENTS.md files describe the parent harness, not the
+        // delegated task. Keep cwd/ancestor project context discovery, but
+        // remove Pi's global file and the legacy ~/.agents equivalent. This
+        // override also handles symlinked global files because it compares
+        // discovered paths.
+        agentsFilesOverride: ({ agentsFiles }) => ({
+          agentsFiles: agentsFiles.filter(
+            ({ path: contextPath }) =>
+              !isExcludedGlobalContextFile(contextPath, agentDir),
+          ),
+        }),
+        ...(extensionPaths.length
+          ? { additionalExtensionPaths: extensionPaths }
+          : {}),
+        // When a named agent supplies a custom prompt, it becomes the loader's
+        // customPrompt — overriding the default system prompt AgentSession
+        // would otherwise build. `systemPrompt` (the source) wins over file
+        // discovery.
+        ...(options.systemPrompt !== undefined
+          ? { systemPrompt: options.systemPrompt }
+          : {}),
+      });
+      await resourceLoader.reload();
+
+      const extensionsResult = resourceLoader.getExtensions();
+      const extensionErrors = extensionsResult.errors;
+      const loadedExtensionPaths = extensionsResult.extensions.map(
+        (extension) => extension.resolvedPath || extension.path,
+      );
+      // A package can resolve successfully while exposing only skills/prompts,
+      // or a malformed manifest can expose no loadable extension at all.
+      const missingExtensionRoots = extensionPaths.filter(
+        (root) =>
+          !loadedExtensionPaths.some((extensionPath) =>
+            isPathWithinDirectory(root, extensionPath),
+          ),
+      );
       const failedRoots = new Set(
         missingExtensionRoots.concat(
-          additionalExtensionPaths.filter((root) =>
+          extensionPaths.filter((root) =>
             extensionErrors.some((error) =>
               isPathWithinDirectory(root, error.path),
             ),
           ),
         ),
       );
-      const failureCount = Math.max(failedRoots.size, extensionErrors.length);
-      const providerName =
-        options.modelProvider?.trim() || "the selected provider";
-      throw new Error(
-        `Failed to load ${failureCount} allowlisted provider extension(s) for ${providerName}; delegation stopped instead of running without the required integration.`,
+      // An error inside a best-effort root is attributable to that root; any
+      // other error (including one no supplied root claims) stays fatal.
+      const fatalErrors = extensionErrors.filter(
+        (error) =>
+          ![...bestEffortExtensionRoots].some((root) =>
+            isPathWithinDirectory(root, error.path),
+          ),
+      );
+      const fatalRoots = [...failedRoots].filter(
+        (root) => !bestEffortExtensionRoots.has(root),
+      );
+      if (fatalErrors.length > 0 || fatalRoots.length > 0) {
+        const failureCount = Math.max(fatalRoots.length, fatalErrors.length);
+        const providerName =
+          options.modelProvider?.trim() || "the selected provider";
+        throw new Error(
+          `Failed to load ${failureCount} allowlisted provider extension(s) for ${providerName}; delegation stopped instead of running without the required integration.`,
+        );
+      }
+      const droppableRoots = [...failedRoots].filter((root) =>
+        bestEffortExtensionRoots.has(root),
       );
+      if (droppableRoots.length === 0) break;
+      extensionPaths = extensionPaths.filter(
+        (root) => !droppableRoots.includes(root),
+      );
+    }
+
+    // Positive visibility for the invisible-by-design path: surviving
+    // best-effort roots each produced at least one loaded extension, and
+    // that changes subagent behavior without any user action — the one
+    // state worth a notice. Once per process per provider+root.
+    for (const root of extensionPaths) {
+      if (bestEffortExtensionRoots.has(root)) {
+        noticeProviderExtensionLoaded(options.modelProvider, root);
+      }
     }
 
     return {
@@ -840,6 +1002,7 @@ export function invalidateHostDepsCache(): void {
   hostDepsCacheGeneration++;
   hostDepsCache.clear();
   hostDepsInflight.clear();
+  missingBestEffortNpmCache.clear();
 }
 
 /** Test-only alias retained for existing test setup. */
@@ -860,6 +1023,7 @@ export function _setModelRuntimeFactoryForTesting(
   testModelRuntimeFactory = factory;
   hostDepsCache.clear();
   hostDepsInflight.clear();
+  missingBestEffortNpmCache.clear();
 }
 
 /**
@@ -883,6 +1047,7 @@ export function _setHostRetryBaseMsForTesting(
     // ensures newly-built ones come back unpatched.
     hostDepsCache.clear();
     hostDepsInflight.clear();
+    missingBestEffortNpmCache.clear();
     return;
   }
   for (const deps of hostDepsCache.values()) {

package/manual.ts

@@ -1,4 +1,6 @@
 import {
+  BUILTIN_AGENT_NAMES,
+  DEFAULT_AGENT_NAME,
   DEFAULT_TOOLS,
   OUTPUT_SPILL_THRESHOLD_CHARS,
   OUTPUT_SPILL_TAIL_CHARS,
@@ -7,6 +9,7 @@ import { getMaxAsyncTickets, getMaxConcurrent } from "./config.ts";
 import type { TSchema } from "@sinclair/typebox";
 import { delegateArgumentsSchema, delegateTaskSchema } from "./schema.ts";
 import type { AgentConfig } from "./types.ts";
+import { BUILTIN_AGENT_CONFIGS } from "./agents.ts";
 
 function schemaType(schema: TSchema): string {
   if (Array.isArray(schema.enum)) {
@@ -39,7 +42,41 @@ function schemaTable(properties: Record<string, TSchema>): string {
 export function getSubagentManualMarkdown(
   agents: Map<string, AgentConfig>,
 ): string {
-  const entries = [...agents].filter(([, a]) => !a.builtin);
+  const builtinNames = new Set<string>(
+    BUILTIN_AGENT_NAMES as readonly string[],
+  );
+  const entries = [...agents].filter(
+    ([name, a]) => !a.builtin && !builtinNames.has(name),
+  );
+  const builtinLines = (BUILTIN_AGENT_NAMES as readonly string[]).map(
+    (name) => {
+      const cfg = agents.get(name) ?? BUILTIN_AGENT_CONFIGS[name]!;
+      const isDefault = name === DEFAULT_AGENT_NAME;
+      // `default` normally mirrors the parent's native tools; only show a
+      // fixed list when the file explicitly overrode them. This avoids
+      // advertising `read, write, edit, bash` when runtime will actually use
+      // the parent's active set. A deny-only `default` (deniedTools with no
+      // explicit allowlist) filters the parent at runtime and must surface.
+      let toolsPart: string;
+      if (isDefault && cfg.deniedTools?.length && !cfg.explicitTools) {
+        toolsPart = ` Tools: parent tools minus \`${cfg.deniedTools.join(", ")}\`.`;
+      } else {
+        const showTools = !isDefault || !!cfg.explicitTools;
+        toolsPart = showTools ? ` Tools: \`${cfg.tools.join(", ")}\`.` : "";
+      }
+      const modelPart =
+        cfg.explicitModel && cfg.model ? ` Model: \`${cfg.model}\`.` : "";
+      const thinkingPart =
+        cfg.explicitThinking && cfg.thinking
+          ? ` Thinking: \`${cfg.thinking}\`.`
+          : "";
+      const workspace =
+        cfg.workspace === "scratch"
+          ? `Defaults to a disposable scratch workspace; set \`workspace: "shared"\` for a persistent ${name} with \`sessionId\`.`
+          : "Shared workspace.";
+      return `- **${name}**: ${cfg.description}${toolsPart}${modelPart}${thinkingPart} ${workspace}`;
+    },
+  );
   const agentList = entries.length
     ? entries
         .map(([n, a]) => {
@@ -97,12 +134,9 @@ export function getSubagentManualMarkdown(
     "",
     "## Built-in Agents",
     "",
-    "- **default**: mirrors the live parent model, thinking level, delegatable native tools, and base prompt. It uses the shared workspace.",
-    "- **scout**: investigates without modifying files. Tools: `read`, `grep`, `find`, `ls`. Shared workspace.",
-    "- **coder**: implements and verifies changes. Tools: `read`, `write`, `edit`, `bash`. Shared workspace.",
-    '- **reviewer**: reviews the current snapshot and reports findings. Tools: `read`, `bash`. Defaults to a disposable scratch workspace; set `workspace: "shared"` for a persistent reviewer with `sessionId`.',
+    ...builtinLines,
     "",
-    "Fresh built-ins inherit the parent's exact model object and thinking level unless task fields or settings override them. Parent extension/MCP tools are not copied. Parent-global `AGENTS.md` instructions are also excluded. Project-local context and skills are rebuilt for the task's `cwd`; per-task fields remain explicit overrides.",
+    "Fresh built-ins inherit the parent's exact model object and thinking level. A same-named Markdown file can override any built-in (first definition wins); an explicit `model` or `thinking` in that file replaces parent inheritance. Task-level `model`/`thinking`/`tools` always win. For `scout`/`coder`/`reviewer`, settings overrides (`settings.json` `delegate.agentOverrides` and `delegate.agentOverridesByParentModel`) win over the Markdown file; `default` ignores settings and uses only an explicit Markdown `model`/`thinking` when present. A prompt-only Markdown override keeps the built-in's tools and workspace, so `scout` stays read-only and `reviewer` stays scratch unless the file explicitly changes them. Parent extension/MCP tools are not copied. Parent-global `AGENTS.md` instructions are also excluded. Project-local context and skills are rebuilt for the task's `cwd`; per-task fields remain explicit overrides.",
     "",
     "## Available Custom Agents",
     "",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bermudi/pi-delegate",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "description": "Delegate tool for the Pi coding agent.",
   "keywords": [
     "pi-package"

package/task-resolution.ts

@@ -274,11 +274,29 @@ export function resolveTasks(
     // "continue with only sessionId" works without re-supplying tools.
     // Explicit overrides that don't match get rejected by acquireAgentSession.
     if (t.sessionAction !== "close" && t.sessionAction !== "list") {
+      // For `default` a deny-only override (no explicit allowlist) is not
+      // materialized at discovery; apply its denylist to the parent's actual
+      // tools here so a read-only parent stays read-only.
+      let effectiveParentTools = parentNativeTools;
+      if (
+        isDefaultAgent &&
+        agent?.deniedTools?.length &&
+        !agent?.explicitTools
+      ) {
+        const denied = new Set(agent.deniedTools);
+        effectiveParentTools = parentNativeTools.filter(
+          (t) => !denied.has(t),
+        );
+      }
       tools = resolveToolGroups(
         t.tools ??
           parentModelOverride?.tools ??
           agentOverride?.tools ??
-          (isDefaultAgent ? parentNativeTools : undefined) ??
+          (isDefaultAgent
+            ? agent?.explicitTools
+              ? agent.tools
+              : effectiveParentTools
+            : undefined) ??
           (isBuiltinAgent ? agent?.tools : undefined) ??
           agent?.tools ??
           (isPoolHit ? pooledConfig?.tools : undefined) ??
@@ -369,10 +387,16 @@ export function resolveTasks(
       // task and settings.json model overrides, but deliberately ignore the
       // legacy delegate.json agent model map so they inherit the parent unless
       // an explicit modern override wins.
+      // Overridden built-ins can still provide an explicit `model` in their
+      // Markdown frontmatter – when `explicitModel` is set, honor it instead
+      // of silently ignoring it (which would contradict the Markdown contract).
       const modelSpec = isDefaultAgent
-        ? t.model
+        ? (t.model ?? (agent?.explicitModel ? agent.model : undefined))
         : isBuiltinAgent
-          ? (t.model ?? parentModelOverride?.model ?? agentOverride?.model)
+          ? (t.model ??
+            parentModelOverride?.model ??
+            agentOverride?.model ??
+            (agent?.explicitModel ? agent.model : undefined))
           : resolveModelSpec({
               taskModel:
                 t.model ?? parentModelOverride?.model ?? agentOverride?.model,
@@ -449,6 +473,7 @@ export function resolveTasks(
           ? (t.thinking ??
             parentModelOverride?.thinking ??
             agentOverride?.thinking ??
+            (agent?.explicitThinking ? agent.thinking : undefined) ??
             modelSuffix ??
             parentDefaults.thinking ??
             (isPoolHit ? pooledConfig?.thinking : undefined) ??
@@ -456,6 +481,7 @@ export function resolveTasks(
           : (t.thinking ??
             parentModelOverride?.thinking ??
             agentOverride?.thinking ??
+            (agent?.explicitThinking ? agent.thinking : undefined) ??
             (isPoolHit ? pooledConfig?.thinking : undefined) ??
             modelSuffix ??
             parentDefaults.thinking ??

package/types.ts

@@ -23,12 +23,20 @@ export interface AgentConfig {
   thinking?: ThinkingLevel;
   tools: string[];
   systemPrompt: string;
-  /** Built-in profiles are immutable and cannot be shadowed by Markdown. */
+  /** Built-in profiles can be overridden by a same-named Markdown file. */
   builtin?: boolean;
   /** Default workspace for a built-in profile. Custom agents use shared. */
   workspace?: WorkspaceMode;
   /** Origin of the profile. `claude` denotes imported .claude/agents files. */
   scope?: "project" | "global" | "claude";
+  /** Whether `tools` was explicitly set in the Markdown frontmatter (vs inherited default). */
+  explicitTools?: boolean;
+  /** Whether `model` was explicitly set in the Markdown frontmatter. */
+  explicitModel?: boolean;
+  /** Whether `thinking` was explicitly set in the Markdown frontmatter. */
+  explicitThinking?: boolean;
+  /** Denylist applied to a built-in `default` override with no explicit allowlist – materialized against parentNativeTools at resolution. */
+  deniedTools?: string[];
 }
 
 // ── Tool parameter types — derived from the TypeBox schema ────────────────