@bermudi/pi-delegate 0.1.18 → 0.1.19

package/manual.ts

@@ -110,7 +110,7 @@ export function getSubagentManualMarkdown(
     'delegate({ tasks: [{ agent: "default", prompt: "Investigate the auth module" }] })',
     "```",
     "",
-    'Delegate subagents to execute tasks in parallel. Each subagent gets an independent conversation. A batch with multiple write-capable tasks in one shared tree is rejected before dispatch; run them sequentially, use synchronous one-shot `workspace: "isolated"` for Git-backed ordered reconciliation, or use disposable scratch workspaces.',
+    "Delegate subagents to execute tasks in parallel. Each subagent gets an independent conversation. Start with a built-in agent and its defaults: set only `agent` and `prompt`. Overlapping shared writers in one call run in task order.",
     "",
     "The three handles have different lifetimes:",
     "",
@@ -138,9 +138,11 @@ export function getSubagentManualMarkdown(
     "",
     ...builtinLines,
     "",
-    "Prefer `default` for general work: it is the only built-in guaranteed to run the parent's exact model and thinking. `scout`/`coder`/`reviewer` apply any configured delegate.json tiers (`agentOverrides`, `agentOverridesByParentModel`) and may run a different model or thinking level than the parent. `scout` is read-only, and `reviewer` runs in a disposable scratch workspace — its writes are discarded by design. Choose a specialist for its role, not its name.",
+    "Start with a built-in and its configured defaults. Set only `agent` and `prompt`; omit `model`, `thinking`, `tools`, and `workspace` unless the user requests an override or a concrete task requirement makes the built-in default unsuitable.",
     "",
-    "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`, delegate.json overrides (`agentOverrides`, `agentOverridesByParentModel`) win over the Markdown file; `default` ignores overrides 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.",
+    "Prefer `default` for general work: it is the only built-in guaranteed to run the parent's exact model and thinking. `scout`/`coder`/`reviewer` apply any configured delegate.json tiers (`agentOverrides`, `agentOverridesByParentModel`) and may run a different model or thinking level than the parent. `scout` is read-only; `coder` and `reviewer` use the shared workspace unless overridden. Choose a specialist for its role, not its name.",
+    "",
+    "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`, delegate.json overrides (`agentOverrides`, `agentOverridesByParentModel`) win over the Markdown file; `default` ignores overrides 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 shared 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",
     "",
@@ -234,16 +236,18 @@ export function getSubagentManualMarkdown(
     "",
     `See the field tables above for the full semantics. Max ${getMaxAsyncTickets()} concurrent async tickets.`,
     "Async results arrive as follow-up messages, so Pi cannot fold their usage into the parent session total; displayed task usage remains informational.",
+    'Isolation supports sync or async one-shot `workspace: "isolated"` tasks. In async mode it prepares Git worktrees after returning the ticket, runs one-shot workers, then reconciles successful proposals in task order before settling. Cancellation never applies unfinished work; a completed proposal cancelled before source application is retained as a private ref and full patch.',
     "",
     "## Gotchas",
     "",
     "- Dispatch validation is batch-wide and runs before spawning: one invalid task rejects the call without starting its siblings.",
-    '- Shared writers that overlap tasks in the same call or a running sync/async dispatch are rejected. Unknown tools count as mutating. Run them sequentially, use `workspace: "isolated"` for Git-backed ordered reconciliation, or use `workspace: "scratch"` when changes may be discarded.',
+    "- Shared writers overlapping within one call are serialized in task order (reported in the result); overlap with a running sync/async dispatch is rejected, so wait for it to finish. Unknown tools count as mutating.",
     "- `*` means read/write/edit/bash, not every tool. `grep`, `find`, and `ls` are valid explicit tools and are the `ro` preset.",
     '- `tasks` is an array. The tool recovers common stringified calls for compatibility, but canonical calls use `{ tasks: [{ prompt: "..." }] }`.',
-    '- Prefer `agent: "default"` — the parent\'s live model/thinking/native tools/base prompt — for general tasks. Pick `scout`/`coder`/`reviewer` only when the role, tool limits, or scratch workspace fit; they follow delegate.json tiers and may not run the parent model. Omitting `agent` creates an ad-hoc task (parent model, full tools).',
-    "- Omit `thinking` for named agents unless the user asks or the task clearly needs escalation — task-level `thinking` overrides every configured tier (`agentOverrides`, `agentOverridesByParentModel`, Markdown frontmatter, `:level` model suffix), so a casual value silently defeats the configured budget. Ad-hoc tasks default to the parent's thinking.",
-    "- An ad-hoc task with no `tools` uses `*`; a named custom task uses its profile; a profile with no tools uses `*`.",
+    "- Use a built-in agent first: `default` for general work, `scout` for read-only investigation, `coder` for implementation, and `reviewer` for review. Omitting `agent` creates a custom inline task rather than selecting a default.",
+    "- Omit `model`, `thinking`, `tools`, and `workspace` for built-ins unless the user requests an override or the built-in default cannot satisfy a concrete requirement. These task fields replace configured policy.",
+    "- In particular, setting `thinking` overrides the agent's configured thinking budget. A casual effort value silently defeats that budget; leave it unset rather than estimating effort for every task.",
+    "- An inline task with no `tools` uses `*`; a named custom task uses its profile; a profile with no tools uses `*`.",
     "- Subagents inherit all skills discovered in their `cwd` (via AgentSession's resource loader). Per-task skill filtering is not supported — curate the cwd's skill set instead.",
     `- Sync \`delegate\` runs at most ${getMaxConcurrent()} tasks at once (the rest queue, not fail). Use \`async: true\` to move work to the background.`,
     "- `deadlineMs` is a per-task wall-clock budget measured from when the task starts running (after queuing). It requests cooperative abort and is not a hard kill; completed writes/commands remain. Omission disables the deadline.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bermudi/pi-delegate",
-  "version": "0.1.18",
+  "version": "0.1.19",
   "description": "Delegate tool for the Pi coding agent.",
   "keywords": [
     "pi-package"
@@ -28,6 +28,7 @@
     "@earendil-works/pi-coding-agent": "^0.84.2",
     "@earendil-works/pi-tui": "^0.84.2",
     "@marcfargas/pi-test-harness": "^0.6.1",
+    "@types/bun": "^1.4.0",
     "esbuild": "^0.28.2",
     "prettier": "^3.9.6",
     "typescript": "^5.9.3"

package/parent-context.ts

@@ -6,7 +6,7 @@ import {
 /** Render the active parent conversation as compact context for a subagent. */
 export function buildParentTranscript(
   entries: SessionEntry[],
-  leafId: string | null,
+  leafId: string | null | undefined,
 ): string | null {
   try {
     const ctx = buildSessionContext(entries, leafId);