@bermudi/pi-delegate 0.1.12 → 0.1.13

package/manual.ts

@@ -120,6 +120,8 @@ export function getSubagentManualMarkdown(
     "",
     "Each task entry may also carry an optional `id` — a caller-provided per-dispatch correlation key. Duplicate `id` values in the same call are rejected; when omitted, tasks are identified by array index, agent, and prompt.",
     "",
+    "Vocabulary, since 'agent' does double duty elsewhere: a **task** is one job; an **agent** is a named profile — a saved bundle of system prompt, tools, workspace, and model policy — that a task references by `agent` name; a **subagent** is the live session that executes one task. Agents are templates, not processes; nothing runs until a task dispatches.",
+    "",
     "Subagents cannot call `delegate` recursively. Their tool activity runs at `cwd`, while Pi stores the runtime session transcript in its own session directory outside that `cwd`.",
     "",
     "## Touched Files (best-effort)",
@@ -142,7 +144,7 @@ export function getSubagentManualMarkdown(
     "",
     agentList,
     "",
-    "Custom agents are defined either inline in a task (using `systemPrompt`, `tools`, and `thinking`) or persisted as Markdown files in `.pi/agents/*.md` (project-local), `~/.pi/agent/agents/` (global), and `.claude/agents/` (interchange with Claude Code). Markdown agents are examples of custom agents — the parent model can shape the subagent it needs on each call. Each Markdown file is an agent with YAML frontmatter:",
+    "Custom agents are profiles, defined either inline in a task (using `systemPrompt`, `tools`, and `thinking`) or persisted as Markdown files in `.pi/agents/*.md` (project-local), `~/.pi/agent/agents/` (global), and `.claude/agents/` (interchange with Claude Code). Inline definitions let the parent model shape the subagent it needs on each call. Each Markdown file is one profile with YAML frontmatter:",
     "",
     "```markdown",
     "---",
@@ -165,26 +167,26 @@ export function getSubagentManualMarkdown(
     "## Session Reuse",
     "",
     "When `sessionId` is set, the subagent is kept alive in a pool for the duration of the pi session.",
-    "Subsequent calls with the same `sessionId` continue the conversation — the agent remembers prior context.",
+    "Subsequent calls with the same `sessionId` continue the conversation — the session retains prior context.",
     "",
     "```ts",
     "// First call — creates and runs an inline custom agent",
     'delegate({ tasks: [{ prompt: "Investigate the auth module", systemPrompt: "You are a focused investigator. Map files and dependencies.", tools: ["read", "grep", "find", "ls"], sessionId: "auth-research" }] })',
     "",
-    "// Second call — continues the same agent",
+    "// Second call — continues the same subagent",
     'delegate({ tasks: [{ prompt: "Now check the tests for that module", sessionId: "auth-research" }] })',
     "",
     "// Clean up when done",
     'delegate({ tasks: [{ sessionId: "auth-research", sessionAction: "close" }] })',
     "```",
     "",
-    'Pooled agents remain live until `sessionAction: "close"` or parent Pi session shutdown.',
+    'Pooled sessions remain live until `sessionAction: "close"` or parent Pi session shutdown.',
     "",
     "## Resuming Previous Sessions",
     "",
     "Use `resumeFrom` to continue a failed or interrupted subagent from where it left off.",
     "Pass the exact absolute path to the session `.jsonl` file copied from delegate retry output. Do not invent placeholder values or use it as a ticket ID; async resume is supported.",
-    "The agent gets the full conversation history and the new `prompt` continues naturally.",
+    "The subagent gets the full conversation history and the new `prompt` continues naturally.",
     "",
     "```ts",
     "// Copy this exact path from the failed delegate result; do not invent it.",
@@ -193,7 +195,7 @@ export function getSubagentManualMarkdown(
     "  resumeFrom: exactRetrySessionFile }] })",
     "```",
     "",
-    "Combine with `sessionId` to resume AND pool the agent for further multi-turn use:",
+    "Combine with `sessionId` to resume AND pool the subagent for further multi-turn use:",
     "",
     "```ts",
     'delegate({ tasks: [{ prompt: "Continue the investigation",',
@@ -238,6 +240,7 @@ export function getSubagentManualMarkdown(
     "- `*` 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: "..." }] }`.',
     '- Use `agent: "default"` for the parent\'s live model/thinking/native tools/base prompt. Built-ins are `default`, `scout`, `coder`, and `reviewer`; omitting `agent` creates an ad-hoc task.',
+    "- 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 `*`.",
     "- 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.`,

package/package.json

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

package/schema.ts

@@ -42,7 +42,7 @@ export const delegateTaskSchema = Type.Object({
   agent: Type.Optional(
     Type.String({
       description:
-        "Built-ins: default, scout, coder, reviewer. Reviewer defaults to one-shot scratch. Omit for ad-hoc.",
+        "Agent profile name. Built-ins: default, scout, coder, reviewer. Omit for ad-hoc.",
     }),
   ),
   cwd: Type.Optional(
@@ -77,7 +77,7 @@ export const delegateTaskSchema = Type.Object({
   thinking: Type.Optional(
     StringEnum(VALID_THINKING_LEVELS, {
       description:
-        "Thinking: off/minimal/low/medium/high/xhigh/max; default=parent; others=agent/off.",
+        "off/minimal/low/medium/high/xhigh/max. Omit for agents — it overrides delegate.json tiers; default inherits.",
     }),
   ),
   sessionId: Type.Optional(