@bermudi/pi-delegate 0.1.9 → 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/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.9",
+  "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 ────────────────