@bermudi/pi-delegate 0.1.9 → 0.1.11

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/delegate.ts

@@ -5,7 +5,6 @@ export type {
   SessionAction,
   WorkspaceMode,
   TicketAction,
-  DelegateAction,
   DelegateArguments,
   TaskDef,
   AsyncTicket,
@@ -72,9 +71,10 @@ export {
   notifyWaiters,
   deliverTicketResults,
   resolveFinalTicketStatus,
+  settleTicket,
   formatCompletedTicket,
 } from "./tickets.ts";
-export type { TicketDelivery } from "./tickets.ts";
+export type { TicketDelivery, SettleTicketOptions } from "./tickets.ts";
 export {
   recordTreeNavigation,
   getCurrentLeafId,
@@ -98,6 +98,7 @@ export {
 export type { ActiveTicketSummary } from "./status.ts";
 export { getHostDeps, invalidateHostDepsCache } from "./host.ts";
 export type { HostDeps, HostDepsOptions } from "./host.ts";
+export { registerProviderExtensionNotifier } from "./provider-extensions.ts";
 export {
   aggregateTaskResults,
   emptyUsage,

package/dispatch.ts

@@ -6,7 +6,7 @@ import {
   deliverTicketResults,
   sweepTickets,
   resolveFinalTicketStatus,
-  syncTicketBusyIndex,
+  settleTicket,
   notifyWaiters,
 } from "./tickets.ts";
 import { getConcurrencyLimit, getMaxAsyncTickets } from "./config.ts";
@@ -319,6 +319,16 @@ export function dispatchAsync(input: AsyncDispatchInput): DelegateToolResult {
   // Worker must store the TaskResult back into ticket.results, since
   // formatCompletedTicket/handlePoll read from there. Without the write,
   // completed async tasks would be reported as PENDING.
+  //
+  // Worker settlement is complete before these live-runtime observers run.
+  // In particular, result delivery is allowed to fail without re-entering the
+  // worker completion path; the terminal ticket remains available to poll.
+  const finishLiveSettlement = (t: AsyncTicket): void => {
+    syncDelegateStatus();
+    settleAsyncCall(t, callSpan);
+    finishTicketDelivery(pi, t);
+  };
+
   const completion = mapConcurrentByModel(
     resolved,
     (t) => getModelKey(t.model),
@@ -346,21 +356,16 @@ export function dispatchAsync(input: AsyncDispatchInput): DelegateToolResult {
       // NOT be marked "done" — that would mask incomplete work as
       // complete. resolveFinalTicketStatus returns "failed" for that
       // case and for any case with a failed task.
-      if (ticket.status === "running") {
-        ticket.status = resolveFinalTicketStatus(ticket);
-        ticket.completedAt = Date.now();
-        syncTicketBusyIndex(ticket);
-      } else if (ticket.status === "cancelling") {
-        // Cancellation was requested while tasks were still settling. The
-        // per-task results record what actually happened; the ticket state
-        // reports that the batch was aborted by the caller.
-        ticket.status = "cancelled";
-        ticket.completedAt = Date.now();
-        syncTicketBusyIndex(ticket);
-      }
-      syncDelegateStatus();
-      settleAsyncCall(ticket, callSpan);
-      finishTicketDelivery(pi, ticket);
+      // A "cancelling" ticket that outlived its workers settles as
+      // "cancelled": the per-task results record what actually happened;
+      // the ticket state reports that the batch was aborted by the caller.
+      settleTicket(ticket, {
+        status:
+          ticket.status === "running"
+            ? resolveFinalTicketStatus(ticket)
+            : "cancelled",
+      });
+      finishLiveSettlement(ticket);
     })
     .catch((err) => {
       // Defense-in-depth — should not happen if individual tasks catch properly.
@@ -370,17 +375,11 @@ export function dispatchAsync(input: AsyncDispatchInput): DelegateToolResult {
         settleAsyncCall(ticket, callSpan);
         return;
       }
-      if (ticket.status === "cancelling") {
-        ticket.status = "cancelled";
-      } else if (ticket.status === "running") {
-        ticket.status = "failed";
-      }
-      ticket.error = err instanceof Error ? err.message : String(err);
-      ticket.completedAt = Date.now();
-      syncTicketBusyIndex(ticket);
-      syncDelegateStatus();
-      settleAsyncCall(ticket, callSpan);
-      finishTicketDelivery(pi, ticket);
+      settleTicket(ticket, {
+        status: ticket.status === "cancelling" ? "cancelled" : "failed",
+        error: err instanceof Error ? err.message : String(err),
+      });
+      finishLiveSettlement(ticket);
     });
   ticket.completion = completion;
 

package/extension.ts

@@ -18,10 +18,8 @@ import {
 } from "./dispatch.ts";
 import { renderDelegateCall, renderDelegateResult } from "./render-result.ts";
 import { hostCompatError } from "./host-compat.ts";
-import {
-  invalidateHostDepsCache,
-  registerProviderExtensionNotifier,
-} from "./host.ts";
+import { invalidateHostDepsCache } from "./host.ts";
+import { registerProviderExtensionNotifier } from "./provider-extensions.ts";
 import { recordTreeNavigation, resetLeafTracking } from "./leaf.ts";
 import { closeAllPooledAgents } from "./pool.ts";
 import {

package/format.ts

@@ -442,7 +442,7 @@ export function formatCompletedTask(
 
 // ── Shared live-progress row helpers ───────────────────────────────────────
 // These dedupe the per-task computations the LLM-facing poll view
-// (tickets.handlePoll) and the TUI branches (render-branches) both need. Each is
+// (ticket-format.ts) and the TUI branches (render-branches) both need. Each is
 // pure over TaskProgress/TaskResult, so it tests without a renderer.
 
 /** The in-flight tool activity (no result yet), or null — the "current thing
@@ -499,7 +499,7 @@ export function waitingLabel(runningCount: number, cap: number): string {
 
 /** Touched-files summary relative to cwd ("src/a.ts, src/b.ts"), or null when
  *  none resolve under cwd. Was byte-for-byte duplicated in formatCompletedTask
- *  and tickets.handlePoll. */
+ *  and ticket-format.ts. */
 export function relativeTouchedSummary(
   files: string[],
   cwd: string,

package/host-cache.ts

@@ -0,0 +1,70 @@
+/**
+ * A generation-guarded async memo.
+ *
+ * Host deps are expensive (`ResourceLoader.reload()` is ~1.2s cold) and are
+ * shared across the parallel tasks of a single delegate dispatch, then thrown
+ * away so the next dispatch observes edits to auth, models, settings, and
+ * context files. That gives three requirements the plain
+ * `Map<string, Promise<T>>` pattern does not meet:
+ *
+ *   - **in-flight dedup** — concurrent tasks with the same key must await one
+ *     build, not start N reloads;
+ *   - **generation guard** — an invalidation during a build must not let that
+ *     older build install its now-stale value, nor let it delete the in-flight
+ *     marker a newer build has since installed for the same key;
+ *   - **one invalidation path** — every reset goes through `invalidate()`.
+ *     Before this was factored out, two test-only helpers cleared the maps
+ *     directly without bumping the generation, leaving exactly the stale-write
+ *     window the guard exists to close.
+ */
+export class GenerationCache<T> {
+  private entries = new Map<string, T>();
+  private inflight = new Map<string, Promise<T>>();
+  private generation = 0;
+
+  /**
+   * Return the cached value for `key`, joining an in-flight build or starting
+   * one. When `cacheable` is false the value is built and returned without ever
+   * being stored or shared.
+   */
+  async resolve(
+    key: string,
+    cacheable: boolean,
+    build: () => Promise<T>,
+  ): Promise<T> {
+    if (!cacheable) return build();
+
+    const cached = this.entries.get(key);
+    if (cached !== undefined) return cached;
+    const pending = this.inflight.get(key);
+    if (pending) return pending;
+
+    const generation = this.generation;
+    const promise = build().then((value) => {
+      // A build that outlived its generation is stale by definition; return it
+      // to its own caller but never publish it.
+      if (this.generation === generation) this.entries.set(key, value);
+      return value;
+    });
+    this.inflight.set(key, promise);
+    try {
+      return await promise;
+    } finally {
+      // An invalidation can let a newer generation install its own in-flight
+      // build for this key. Never let the older promise delete that marker.
+      if (this.inflight.get(key) === promise) this.inflight.delete(key);
+    }
+  }
+
+  /** Drop every cached and in-flight value, invalidating builds already running. */
+  invalidate(): void {
+    this.generation++;
+    this.entries.clear();
+    this.inflight.clear();
+  }
+
+  /** Cached values only — in-flight builds are not observable here. */
+  values(): Iterable<T> {
+    return this.entries.values();
+  }
+}