@tranhoangnguyen0310/pi-flow-external 3.2.1-external.0 → 4.0.0-external.0

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to pi-flow external are documented here.
 
+## [4.0.0-external.0] - 2026-10-13
+
+### Breaking
+- Renamed the direct delegation tool **`Agent` → `external_delegate`** (#85). Flow no longer registers `Agent`; there is no alias or automatic translation. Update `tools.Agent(...)` → `tools.external_delegate(...)`, `describeTool("Agent")` → `describeTool("external_delegate")`, exact-name hooks, tool allow-lists, and receipt checks. Stale calls may reach another extension's `Agent` tool rather than fail.
+- New direct receipts report `tool: "external_delegate"`. Envelope `contractVersion: 1`, `action: "delegate"`, run `kind: "agent"`, and workflow `agent()` remain unchanged. Settings remain version 5; no settings conversion or saved-run rewrite is required.
+- Update Flow's entry in `pi-cc-extensions` `excludeRenderers` to `"external_delegate"` (alongside `"workflow"` and `"external_runs"`). Preserve unrelated entries, including `"Agent"` if another extension needs it, and restart Pi. See the [tool migration guide](docs/migration-agent-to-external-delegate.md).
+
+### Changed
+- Current documentation, coordinator guidance, and help use the namespaced direct tool name. Background guidance explicitly states that runs do not notify or resume the parent session: collect them through `external_runs` (`wait`, then `inspect` with `view: "final"` for a successful answer; inspect outcomes and diagnostics for failures).
+
 ## [3.2.1-external.0] - 2026-10-05
 
 ### Changed

package/README.md

@@ -76,7 +76,7 @@ Pi recognizes the request and delegates:
 *(Programmatic / Codemode equivalent):*
 
 ```ts
-const receipt = await tools.Agent({
+const receipt = await tools.external_delegate({
   description: "Map repository architecture",
   role: "explorer",
   harness: "claude",
@@ -130,7 +130,7 @@ Pi automatically packages recent conversation turns into the briefing:
 *(Codemode):*
 
 ```ts
-await tools.Agent({
+await tools.external_delegate({
   description: "Review refactoring plan",
   role: "reviewer",
   harness: "codex",
@@ -154,7 +154,7 @@ Pi launches the run in the background, gives you a run ID, and keeps your chat s
 *(Codemode):*
 
 ```ts
-const receipt = await tools.Agent({
+const receipt = await tools.external_delegate({
   description: "Audit security-sensitive endpoints",
   role: "reviewer",
   harness: "claude",
@@ -216,6 +216,10 @@ Settings use version 5. If upgrading from an older version:
 2. Existing configurations, overrides, and disabled states are preserved.
 3. See [Migration Guide](docs/migration-v4-to-v5.md) for full details and optional file purging.
 
+### Upgrading from the `Agent` tool
+
+The direct delegation tool `Agent` is now `external_delegate`, with no alias. Update codemode calls, hooks, and renderer exclusions. See [Tool Rename Migration](docs/migration-agent-to-external-delegate.md).
+
 ---
 
 ## Documentation

package/docs/README.md

@@ -17,6 +17,7 @@ Core reference guides for configuring and using the extension with Pi:
 | **[Workflows](workflows.md)** | Scripting API, parallel fan-out (`parallel()`), `ChildRunError` handling, structured schemas, and replay cache. |
 | **[Troubleshooting](troubleshooting.md)** | Diagnostic recipes, authentication checks, and `pi-cc-extensions` renderer compatibility. |
 | **[Migration Guide (v4 → v5)](migration-v4-to-v5.md)** | Upgrading from older configurations, backups, command mappings, and safe file purging. |
+| **[Tool Rename Migration (`Agent` → `external_delegate`)](migration-agent-to-external-delegate.md)** | Updating codemode calls, hooks, receipt checks, and renderer exclusions after the direct tool rename. |
 
 ---
 
@@ -25,7 +26,7 @@ Specifications for programmatic subagent delegation and tool outputs:
 
 | Document | Status | Purpose |
 |---|---|---|
-| **[Public Contract v1](public-contract.md)** | `Normative Contract` | Schema definitions, envelope shapes (`{ ok, data, error }`), and delivery invariants for `Agent`, `workflow`, and `external_runs`. |
+| **[Public Contract v1](public-contract.md)** | `Normative Contract` | Schema definitions, envelope shapes (`{ ok, data, error }`), and delivery invariants for `external_delegate`, `workflow`, and `external_runs`. |
 
 ---
 

package/docs/migration-agent-to-external-delegate.md

@@ -0,0 +1,69 @@
+# Migration Guide: `Agent` Tool Renamed to `external_delegate`
+
+The direct delegation tool formerly named `Agent` is now `external_delegate` ([issue #85](https://github.com/tranhoangnguyen03/pi-flow-external/issues/85)). It joins `external_help` and `external_runs` as one tool family and no longer shares a name with Claude Code's built-in `Agent` tool.
+
+This guide covers only the tool rename. For settings conversion, see the [v4 → v5 Migration Guide](migration-v4-to-v5.md).
+
+---
+
+## No Alias
+
+`Agent` is not kept as a second name, and old calls are not translated. Keeping both names would bring back the name clash and add a duplicate tool to every session. A stale `Agent` call fails, or reaches another extension's `Agent` tool if one is registered, so update every caller.
+
+The rename was motivated by `Agent` going missing when Claude runs through `pi-claude-bridge`. A live smoke test on 2026-10-13 still reported the renamed tool unavailable while the other three Flow tools were visible. No delegation was made. The rename is therefore not a confirmed fix for bridge visibility; that integration remains unresolved.
+
+---
+
+## What to Update
+
+| Where | Before | After |
+|---|---|---|
+| Codemode calls | `tools.Agent({...})` | `tools.external_delegate({...})` |
+| Codemode discovery | `describeTool("Agent")` | `describeTool("external_delegate")` |
+| Hooks and handlers that match an exact tool name (`tool_call`, `tool_result`, `event.toolName === ...`) and tool allow-lists such as `--tools` | `"Agent"` | `"external_delegate"` |
+| Result discriminator: the envelope `tool` field | `tool: "Agent"` | `tool: "external_delegate"` |
+| `pi-cc-extensions` `excludeRenderers` | `"Agent"` | `"external_delegate"`, then restart Pi. Keep `"Agent"` only if another extension needs it (see [Troubleshooting](troubleshooting.md#third-party-ui-compatibility-pi-cc--ccstyle)) |
+
+Example:
+
+```ts
+const receipt = await tools.external_delegate({
+  description: "Check build",
+  role: "worker",
+  prompt: "Run the build and report.",
+});
+if (!receipt.ok) return receipt.error;
+return receipt.data.run;
+```
+
+---
+
+## What Does Not Change
+
+- **Input parameters:** `role`, `harness`, `subagent_type`, `permission`, `context`, `resume`, `background`, and the other arguments are the same.
+- **Envelope:** `contractVersion` is still `1`. `action` is still `"delegate"`, and runs still report `kind: "agent"`. `ok`, `data`, `error`, and `warnings` keep their meaning. See [Public Contract v1](public-contract.md).
+- **Settings and saved runs:** settings stay at version 5. No settings conversion or saved-run rewrite is needed.
+- **Workflows:** the workflow `agent()` function keeps its name. It exists only inside workflow scripts and never appears in a tool list.
+- **Other tools:** `workflow`, `external_runs`, and `external_help` keep their names.
+
+---
+
+## Background Runs Still Need Collecting
+
+A background run does not notify or resume the session when it finishes. Ending the turn does not bring the result back. Collect it with `external_runs`:
+
+```ts
+const receipt = await tools.external_delegate({
+  description: "Audit endpoints",
+  role: "reviewer",
+  prompt: "Audit the endpoints read-only.",
+  background: true,
+});
+if (!receipt.ok) return receipt.error;
+const runId = receipt.data.run.runId;
+
+await tools.external_runs({ action: "wait", runIds: [runId], mode: "all" });
+const final = await tools.external_runs({ action: "inspect", runIds: [runId], view: "final" });
+```
+
+`final` holds only a verified successful answer. For a failed run, read the outcome from `wait` and the details with `view: "diagnostics"`.

package/docs/public-contract.md

@@ -1,9 +1,9 @@
-# Public contract v1: Agent, workflow and external_runs
+# Public contract v1: external_delegate, workflow and external_runs
 
-`Agent`, `workflow` and `external_runs` declare `outputSchema` and return matching `structuredContent`. Human `content` and renderer `details` stay separate. Native Pi codemode receives the structured result, including failures. **Check `ok`**, not just whether the call threw.
+`external_delegate`, `workflow` and `external_runs` declare `outputSchema` and return matching `structuredContent`. Human `content` and renderer `details` stay separate. Native Pi codemode receives the structured result, including failures. **Check `ok`**, not just whether the call threw.
 
 ```js
-const receipt = await tools.Agent({ role: "worker", description: "Check build", prompt: "Run the build and report." });
+const receipt = await tools.external_delegate({ role: "worker", description: "Check build", prompt: "Run the build and report." });
 if (!receipt.ok) return receipt.error;
 return receipt.data.run;
 ```
@@ -22,7 +22,7 @@ Every result carries:
 
 | Tool | `action` | Success `data` | Failure `data` |
 |---|---|---|---|
-| `Agent` | `delegate` | `{run}` | `{run}`, or `{run: null}` before registration |
+| `external_delegate` | `delegate` | `{run}` | `{run}`, or `{run: null}` before registration |
 | `workflow` | `run` | `{run}` | `{run}`, or `{run: null}` before registration |
 | `external_runs` | the requested action | the action's payload (below) | `null` |
 
@@ -107,4 +107,4 @@ A host redaction hook that replaces content drops structured content unless it e
 
 ## Discovery
 
-Pi 0.99.2 generates discriminated return types from these schemas through native `describeTool`. The `Agent` input declaration currently loses its input properties, because Pi renders the root `anyOf` constraints before the properties; input validation itself remains intact. This is a known input-discovery limitation, not a runtime validation bypass.
+Pi 0.99.2 generates discriminated return types from these schemas through native `describeTool`. The `external_delegate` input declaration currently loses its input properties, because Pi renders the root `anyOf` constraints before the properties; input validation itself remains intact. This is a known input-discovery limitation, not a runtime validation bypass.

package/docs/supervision-and-runtime.md

@@ -33,12 +33,12 @@ Workspace /path/to/project
 
 ## Background Runs & Lifecycle
 
-By default, calls to `Agent` and `workflow` are blocking: the caller waits until the child process completes.
+By default, calls to `external_delegate` and `workflow` are blocking: the caller waits until the child process completes.
 
 Setting `background: true` queues and starts the work asynchronously while returning an immediate receipt containing a stable handle:
 
 ```ts
-const receipt = await tools.Agent({
+const receipt = await tools.external_delegate({
   description: "Audit security-sensitive endpoints",
   role: "reviewer",
   harness: "claude",
@@ -54,6 +54,8 @@ if (!receipt.ok) {
 const runId = receipt.data.run.runId; // e.g. "run_..."
 ```
 
+Background runs do not notify or resume this session when they finish. Collect them with `external_runs`: `wait`, then `inspect` with view `final` for a successful answer. For a failed run, read the `wait` outcome and `inspect` view `diagnostics`.
+
 ### Ownership Invariants
 - **Session-Owned:** Background children belong to the active Pi session, not a persistent OS daemon.
 - **Orderly Shutdown:** Closing Pi gracefully signals cancellation and waits for bounded cleanup.

package/docs/troubleshooting.md

@@ -41,7 +41,7 @@ Solutions to common issues, authentication questions, and environment quirks whe
 ### 8. Child Missing Earlier Conversation Context
 - **Fix:** Explicitly pass conversation turns using `context`:
   ```ts
-  Agent({ description: "Follow-up review", role: "reviewer", context: { mode: "recent", turns: 5 }, prompt: "..." })
+  external_delegate({ description: "Follow-up review", role: "reviewer", context: { mode: "recent", turns: 5 }, prompt: "..." })
   ```
 
 ### 9. Workflow Rejected Before Launch
@@ -66,7 +66,7 @@ Add `pi-flow-external` tool names to `excludeRenderers` in `~/.pi/agent/pi-cc-ex
 
 ```json
 {
-  "excludeRenderers": ["Agent", "workflow", "external_runs"]
+  "excludeRenderers": ["external_delegate", "workflow", "external_runs"]
 }
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tranhoangnguyen0310/pi-flow-external",
-  "version": "3.2.1-external.0",
+  "version": "4.0.0-external.0",
   "description": "External Claude Code, Codex CLI, Antigravity, Grok Build CLI, Muse Code, and OpenCode delegation for pi.",
   "type": "module",
   "main": "./index.ts",
@@ -20,6 +20,7 @@
     "docs/workflows.md",
     "docs/troubleshooting.md",
     "docs/migration-v4-to-v5.md",
+    "docs/migration-agent-to-external-delegate.md",
     "docs/public-contract.md"
   ],
   "keywords": [

package/src/contract/agent.ts

@@ -1,11 +1,12 @@
 import { type JsonObject } from "@earendil-works/pi-ai";
 import { Type, type Static } from "typebox";
+import { EXTERNAL_DELEGATE_TOOL } from "../tool-names.ts";
 import type { RegisteredRunEntry } from "../core/run-registry.ts";
 import { contractEnvelope, envelope, INLINE_RESULT_BYTES, type PublicError } from "./envelope.ts";
 import { agentRunSchema, liveAgentRun, type EvidenceIntegrity } from "./run.ts";
 
 const agentData = Type.Object({ run: Type.Union([Type.Null(), agentRunSchema]) });
-export const agentOutputSchema = contractEnvelope("Agent", Type.Literal("delegate"), agentData, agentData);
+export const agentOutputSchema = contractEnvelope(EXTERNAL_DELEGATE_TOOL, Type.Literal("delegate"), agentData, agentData);
 export type AgentReceipt = Static<typeof agentOutputSchema>;
 
 /** Only registry-confirmed entries may supply a public handle. Never infer liveness from disk. */
@@ -25,5 +26,5 @@ export function agentReceipt({ entry, integrity = "unknown", error, inspectable
       error = { code: entry.outcome.outcome === "succeeded" ? "failed" : entry.outcome.outcome, message: entry.outcome.error ?? "Child execution failed" };
     }
   }
-  return envelope({ tool: "Agent", action: "delegate", data: { run }, warnings, error, redact: true }) as AgentReceipt & JsonObject;
+  return envelope({ tool: EXTERNAL_DELEGATE_TOOL, action: "delegate", data: { run }, warnings, error, redact: true }) as AgentReceipt & JsonObject;
 }

package/src/core/progress.ts

@@ -1,4 +1,5 @@
 import type { AgentSessionEvent } from "@earendil-works/pi-coding-agent";
+import { EXTERNAL_DELEGATE_TOOL } from "../tool-names.ts";
 import type {
   SubagentBackend,
   SubagentAssistantOutput,
@@ -138,7 +139,7 @@ function getToolArgPreview(args: unknown): string {
 
 export function updateProgressFromEvent(progress: SubagentProgressNode, event: AgentSessionEvent): void {
   if (event.type === "tool_execution_start") {
-    if (event.toolName === "Agent") {
+    if (event.toolName === EXTERNAL_DELEGATE_TOOL) {
       return;
     }
     const preview = getToolArgPreview(event.args);

package/src/core/spawn.ts

@@ -45,14 +45,14 @@ import { runRecordsDirectory } from "./retention.ts";
 import { createTimeoutSignal, markSubagentTimedOut } from "./timeout.ts";
 import type { PermissionResolution } from "./permissions.ts";
 import { effectivePiResourcePreset, isValidThinkingLevel, VALID_THINKING_LEVELS } from "../harnesses.ts";
-
+import { EXTERNAL_DELEGATE_TOOL } from "../tool-names.ts";
 
 /**
  * The delegation tools a spawned child must never receive, so subagents cannot
  * recursively fan out. Owned by the spawn core and used as the default exclude
  * list so no caller can accidentally under-specify the nesting block.
  */
-export const CHILD_EXCLUDED_TOOLS: readonly string[] = ["Agent", "workflow"];
+export const CHILD_EXCLUDED_TOOLS: readonly string[] = [EXTERNAL_DELEGATE_TOOL, "workflow"];
 
 /**
  * Parameters for a single subagent run. This is the shared spawn primitive used

package/src/external-help.ts

@@ -95,9 +95,9 @@ function workflowHelp(workflowsEnabled: boolean, workflows: ReturnType<typeof li
 
 Provide exactly one workflow source: name, scriptPath, or script. Every script starts with the literal current declaration export const meta = { apiVersion: 1, name, description }, calls agent() at least once, awaits every started call, and returns JSON-serializable data. Missing/unsupported API versions fail before any child launches. Project .pi/workflows are visible only when the project is trusted.
 
-APIs: agent(prompt, { description, label, role, harness, subagent_type, permission, max_budget_usd, resume, context, schema, phase }); parallel(thunks); pipeline(items, ...stages); phase(title); log(message). Globals: args and cwd. Agent options other than the profile selector are optional. "description" is the common task-name option shared with the direct Agent tool; "label" is a compatible alias — set only one, or both to the same value. Choose role/harness or legacy exact subagent_type, never both. Use unique descriptions/labels and clear task prompts. An agent() succeeds with its value or throws ChildRunError { runId, outcome, message, outputRef, diagnosticsRef }; catch optional failures explicitly. Uncaught failures terminate the workflow and drain siblings. Helpers never convert failures to null. Context options: {mode:"none"} (default), {mode:"recent",turns:N} (positive integer, includes current user turn), or {mode:"full"} (available context after compaction). All children share invocation-time context/settings; earlier child results must still be passed explicitly. Context excludes thinking/system instructions and pending calls; images and snapshots over 1 MiB fail without truncation. Context sharing cannot be combined with resume. Use schema for results that control branching or aggregation. Imports, filesystem globals, Date APIs, and Math.random() are unavailable.
+APIs: agent(prompt, { description, label, role, harness, subagent_type, permission, max_budget_usd, resume, context, schema, phase }); parallel(thunks); pipeline(items, ...stages); phase(title); log(message). Globals: args and cwd. Agent options other than the profile selector are optional. "description" is the common task-name option shared with the direct external_delegate tool; "label" is a compatible alias — set only one, or both to the same value. Choose role/harness or legacy exact subagent_type, never both. Use unique descriptions/labels and clear task prompts. An agent() succeeds with its value or throws ChildRunError { runId, outcome, message, outputRef, diagnosticsRef }; catch optional failures explicitly. Uncaught failures terminate the workflow and drain siblings. Helpers never convert failures to null. Context options: {mode:"none"} (default), {mode:"recent",turns:N} (positive integer, includes current user turn), or {mode:"full"} (available context after compaction). All children share invocation-time context/settings; earlier child results must still be passed explicitly. Context excludes thinking/system instructions and pending calls; images and snapshots over 1 MiB fail without truncation. Context sharing cannot be combined with resume. Use schema for results that control branching or aggregation. Imports, filesystem globals, Date APIs, and Math.random() are unavailable.
 
-Background and supervision: blocking by default — an ordinary call waits for its child and returns the result, run everything this way unless the parent has other work to do first. Set background:true only when the parent can proceed before completion, then use external_runs on the returned stable run ID while session-owned work continues. Parallel same-harness work (e.g. three agy workers) runs concurrently under the shared maxConcurrentSubagents cap: call parallel([() => agent(...), ...]) in a workflow, or issue separate Agent calls with background:true in one turn, then external_runs wait/inspect/cancel. Awaiting agent() calls sequentially stays serial by construction. external_runs selects targets with runIds. list takes optional workflowRunId, cursor, workflowCursor, and limit. inspect with one id reads any view (summary, output, diagnostics, or final) and pages with an opaque cursor and limitBytes; several ids (up to 20) batch summary only. wait takes runIds in mode any or all (up to 100). cancel takes one id and an optional reason. Follow nextCursor/nextWorkflowCursor for complete results. Wait returns selected terminal outcomes and pending IDs, never cancels pending work, and returns an unsuccessful workflow early; interrupting wait stops only the wait. Cancelling a workflow stops active children, while cancelling one child is a catchable workflow error. Blocking-call interruption cancels that call; background work survives tool return but is cancelled on orderly owning-session shutdown. It is not a daemon: crashes leave unfinished evidence interrupted/uncertain, restart does not adopt work, and live steering is unavailable.
+Background and supervision: blocking by default — an ordinary call waits for its child and returns the result, run everything this way unless the parent has other work to do first. Set background:true only when the parent can proceed before completion, then use external_runs on the returned stable run ID while session-owned work continues. Background runs do not notify or resume this session; collect them with external_runs (wait, then inspect with view final). Check failed outcomes and diagnostics; view final only supplies verified successful answers. Parallel same-harness work (e.g. three agy workers) runs concurrently under the shared maxConcurrentSubagents cap: call parallel([() => agent(...), ...]) in a workflow, or issue separate external_delegate calls with background:true in one turn, then external_runs wait/inspect/cancel. Awaiting agent() calls sequentially stays serial by construction. external_runs selects targets with runIds. list takes optional workflowRunId, cursor, workflowCursor, and limit. inspect with one id reads any view (summary, output, diagnostics, or final) and pages with an opaque cursor and limitBytes; several ids (up to 20) batch summary only. wait takes runIds in mode any or all (up to 100). cancel takes one id and an optional reason. Follow nextCursor/nextWorkflowCursor for complete results. Wait returns selected terminal outcomes and pending IDs, never cancels pending work, and returns an unsuccessful workflow early; interrupting wait stops only the wait. Cancelling a workflow stops active children, while cancelling one child is a catchable workflow error. Blocking-call interruption cancels that call; background work survives tool return but is cancelled on orderly owning-session shutdown. It is not a daemon: crashes leave unfinished evidence interrupted/uncertain, restart does not adopt work, and live steering is unavailable.
 
 Replay: resumeFromRunId works only with persisted scriptPath and starts an explicit new attempt. It reuses the longest unchanged prefix of successful child calls; the first changed/failed/cancelled/timed-out call and its suffix run again. Script recomposition is cheap, but child reruns can cost money or repeat side effects. There is no automatic repaired-script replay.
 

package/src/pi-subagent.ts

@@ -50,6 +50,7 @@ import { registerProfileCreator, startRoleInterview, startHarnessInterview } fro
 import { registerExternalCommand } from "./external-command.ts";
 import { DEFAULT_EXTERNAL_SETTINGS, loadExternalSettings, resolveCtxDefaultHarness, resolveExternalSettings, renderDefaultHarness } from "./settings.ts";
 import { EXTERNAL_HARNESSES } from "./types.ts";
+import { EXTERNAL_DELEGATE_TOOL } from "./tool-names.ts";
 import type {
   PermissionTier,
   SubagentBackend,
@@ -359,8 +360,8 @@ function createAgentTool(
   options: CreateAgentToolOptions,
 ): ToolDefinition<typeof agentToolParameters, SubagentToolDetails> {
   return defineTool({
-    name: "Agent",
-    label: "Agent",
+    name: EXTERNAL_DELEGATE_TOOL,
+    label: EXTERNAL_DELEGATE_TOOL,
     description: "Delegate one task to an external Claude Code, Codex CLI, Antigravity, Grok CLI, Muse Code, OpenCode, or registered Pi harness role.",
     promptSnippet: AGENT_PROMPT_SNIPPET,
     parameters: agentToolParameters,
@@ -882,7 +883,7 @@ export function createSubagentExtension(options: SubagentExtensionOptions = {}):
 
     pi.on("before_agent_start", (event, ctx) => {
       const tools = pi.getAllTools();
-      if (!tools.some((tool) => tool.name === "Agent")) {
+      if (!tools.some((tool) => tool.name === EXTERNAL_DELEGATE_TOOL)) {
         return;
       }
       // No per-turn counter reset: the shared ConcurrencyLimiter takes a slot

package/src/profile-creator.ts

@@ -36,13 +36,13 @@ A role is shared authoring only: one markdown file under pi-flow-external/roles/
 
 Describe read-only or editing intent in the instructions. Do not ask for a permission tier: a role does not grant authority. The caller passes permission, or the global defaultPermission applies. Do not ask about backend, model, or thinking: shared roles never pin those, and backend-specific execution settings belong in /external config role set <role> --harness <name>; instruction replacements use /external config role edit <role> --harness <name>. When ready, summarize once and call ${ROLE_TOOL_NAME}.
 
-Do not write files yourself and do not run Agent or workflow. The tool will show what will be created for review, request confirmation, and write it offline without a backend smoke test. A role is not an authenticated connection; readiness smoke testing belongs to harness registration.`;
+Do not write files yourself and do not run external_delegate or workflow. The tool will show what will be created for review, request confirmation, and write it offline without a backend smoke test. A role is not an authenticated connection; readiness smoke testing belongs to harness registration.`;
 
 export const HARNESS_INTERVIEW_PROMPT = `Help me register one named Pi harness configuration through an AI-assisted interview.
 
 Ask for a "pi-<label>" name, a provider/model id (validated live against the model registry), an optional thinking level (off/minimal/low/medium/high/xhigh; default off), and a resource preset. The preset is a simple choice of minimal or skills. minimal is the default and loads no skills. skills loads installed skills; project skills load only when the project is trusted. The six canonical roles (explorer, planner, implementer, reviewer, qa, worker) become automatically available on this harness the moment it is registered — no per-role file needed. When ready, summarize once and call ${HARNESS_TOOL_NAME}.
 
-Do not write files yourself and do not run Agent or workflow in this branch. The tool will show what will be registered for review, request confirmation, stage it, run a real in-process pi smoke test, and either install it or roll it back.`;
+Do not write files yourself and do not run external_delegate or workflow in this branch. The tool will show what will be registered for review, request confirmation, stage it, run a real in-process pi smoke test, and either install it or roll it back.`;
 
 const roleParameters = Type.Object({
   name: Type.String({ description: "Lowercase shared role name, such as security-reviewer. No backend prefix; reviewer replaces the built-in reviewer." }),

package/src/profiles.ts

@@ -264,7 +264,7 @@ export function loadExternalCatalog(agentDir = getAgentDir(), options: { legacyI
           const { frontmatter } = parseFrontmatter<Record<string, unknown>>(content);
           const obsolete = ["permission", "capabilitySet"].filter((key) => Object.prototype.hasOwnProperty.call(frontmatter, key));
           if (obsolete.length) {
-            throw new Error(`obsolete metadata ${obsolete.join(", ")} does not grant authority. Remove it. A role describes intent; pass permission on the Agent or workflow call, or set defaultPermission. Pi skills follow the harness preset.`);
+            throw new Error(`obsolete metadata ${obsolete.join(", ")} does not grant authority. Remove it. A role describes intent; pass permission on the external_delegate or workflow call, or set defaultPermission. Pi skills follow the harness preset.`);
           }
           if (Object.keys(frontmatter).some((key) => key !== "description")) throw new Error("shared roles support description only; use an exact override for execution settings");
         } else {
@@ -442,7 +442,7 @@ export function reconcilePiProfileWithHarness(
  * once, skipping any `<harness>-<role>` key that already has a real on-disk
  * entry (same override precedence resolveExternalProfile applies at
  * resolution time). This is the single shared merge every consumer that
- * needs a *complete* roster reuses: the Agent tool's catalog/help text, the
+ * needs a *complete* roster reuses: the external_delegate tool's catalog/help text, the
  * workflow tool's frozen per-run profile+model snapshot (so a workflow can
  * actually execute a synthesized pi role, not just resolve its name), and
  * /external's doctor/settings/profiles text. Real on-disk profiles are never
@@ -456,7 +456,7 @@ export function reconcilePiProfileWithHarness(
  * omits `model`/`thinking` (the common case, inheriting from its harness)
  * would carry `model: undefined` into that map and fail with "no model
  * selected" even though the exact same profile resolves and runs fine
- * through the Agent tool's resolveExternalProfile path.
+ * through the external_delegate tool's resolveExternalProfile path.
  *
  * A genuine conflict is deliberately *not* thrown here: this function runs
  * on every turn (coordinator prompt catalog) and at the top of every

package/src/prompts.ts

@@ -92,13 +92,13 @@ export function buildCoordinatorPrompt(
 
 ${formatExternalRoleCatalog(profiles, defaultHarness, configuredHarnessNames)}
 
-Own the result and verify it yourself. Do the work directly unless a separate harness, a fresh context, or a bounded parallel review earns the overhead. A role is the job. A harness (${EXTERNAL_HARNESSES.join(", ")}, or a registered pi-* name) is the environment. Prefer the configured default harness unless the user asks for another or the task needs a capability the default lacks. Select both through Agent or workflow. Follow the user's own approval policy before widening a delegation. This extension has no fixed multi-agent approval threshold.
+Own the result and verify it yourself. Do the work directly unless a separate harness, a fresh context, or a bounded parallel review earns the overhead. A role is the job. A harness (${EXTERNAL_HARNESSES.join(", ")}, or a registered pi-* name) is the environment. Prefer the configured default harness unless the user asks for another or the task needs a capability the default lacks. Select both through external_delegate or workflow. Follow the user's own approval policy before widening a delegation. This extension has no fixed multi-agent approval threshold.
 
 Give every child an objective, the context it needs, the changes it may make, a deliverable, and the check you will run. Use absolute paths and say whether the task is read-only or may edit. Permission is the call's tier, otherwise defaultPermission (danger unless changed). Omit it when the child should keep that default, including a reviewer that may use a shell and still must not edit. A danger tier still has to stay inside the authorization the user gave you. agy accepts only danger and rejects readonly and edit.
 
 Choose a fresh child or resume on purpose. Omit context for independent work. context {mode:"recent", turns:N} shares the last N user turns, including the current turn; {mode:"full"} shares the available post-compaction conversation. Snapshots drop thinking, system instructions, and pending calls, reject images and payloads over 1 MiB, and are sent to that harness. resume continues the same CLI child and cannot be combined with sharing. A named pi-* harness has no persisted session and no enforced budget. Prefer resume for the same task and a new child for an independent review.
 
-Calls block unless background:true. Then supervise with external_runs and judge view "final" yourself. Same-harness parallel work shares one maxConcurrentSubagents cap: parallel([() => agent(...), ...]) or separate background Agent calls in one turn. Sequential awaits stay serial. Report milestones. Retry a failed run, or switch its model or harness, only when the user authorized that step. agy alone may make one disclosed infrastructure retry. Nested agents may start in another workspace.
+Calls block unless background:true. Background runs do not notify or resume this session; collect them with external_runs (wait, then inspect with view "final"). Check failed outcomes and diagnostics instead of expecting a final answer from a failed run. Same-harness parallel work shares one maxConcurrentSubagents cap: parallel([() => agent(...), ...]) or separate background external_delegate calls in one turn. Sequential awaits stay serial. Report milestones. Retry a failed run, or switch its model or harness, only when the user authorized that step. agy alone may make one disclosed infrastructure retry. Nested agents may start in another workspace.
 
 Catalog availability reflects enabled harnesses and built-in/authored roles, not CLI installation or authentication. Disabled harnesses reject calls without fallback; manage them through /external config. Harness and role lifecycle commands live under /external config harness and /external config role. Role selection never falls back. external_help topic usage is the playbook; roles, permissions, and workflow are the references.`;
 }
@@ -115,7 +115,7 @@ export interface UsageAgentExample {
   context?: { mode: "none" } | { mode: "recent"; turns: number } | { mode: "full" };
 }
 
-/** One self-contained Agent call. Valid against the Agent tool schema. Permission stays omitted. */
+/** One self-contained external_delegate call. Valid against the external_delegate tool schema. Permission stays omitted. */
 export const USAGE_ONE_AGENT: UsageAgentExample = {
   description: "Map the repository",
   prompt: "Map /absolute/repo. Read only. Return the important files and how they fit together. Do not edit.",
@@ -203,7 +203,7 @@ function jsonBlock(value: unknown): string {
 /** Worked playbook served by external_help topic "usage". Examples are the exported constants. */
 export function formatUsagePlaybook(): string {
   const script = usageWorkflowScript();
-  return `Practical delegation playbook. A role is the work. A harness is the environment: ${EXTERNAL_HARNESSES.join(", ")}, or a registered pi-* name. Agent and workflow select every one of those harnesses the same way. Prefer the configured default harness. Name another when the user asks for it or the task needs a capability the default lacks. Do the task directly unless a separate environment, an independent context, or bounded parallel work is worth the coordination. You still own the outcome: read the result and check the deliverable. Follow the user's approval policy before widening a delegation. There is no fixed team-size threshold here.
+  return `Practical delegation playbook. A role is the work. A harness is the environment: ${EXTERNAL_HARNESSES.join(", ")}, or a registered pi-* name. external_delegate and workflow select every one of those harnesses the same way. Prefer the configured default harness. Name another when the user asks for it or the task needs a capability the default lacks. Do the task directly unless a separate environment, an independent context, or bounded parallel work is worth the coordination. You still own the outcome: read the result and check the deliverable. Follow the user's approval policy before widening a delegation. There is no fixed team-size threshold here.
 
 A named pi-* harness runs in-process on the SDK's built-in tools. Preset minimal leaves skills unloaded. Preset skills loads installed skills, and project skills only when the project is trusted. Those presets select skill loading. They are not this extension's tools and they are not web search. Resume does not continue a pi-* child, and a budget there is recorded without enforcement.
 
@@ -211,9 +211,9 @@ Tell each child the objective, the context it needs, what it may change, the del
 
 Choose fresh context or resume deliberately. Omit context, or pass {"mode":"none"}, for independent work such as a review. {"mode":"recent","turns":N} and {"mode":"full"} share parent conversation and cannot be combined with resume. resume continues one prior CLI run that recorded a session id, on the same backend: ${EXTERNAL_HARNESSES.join(", ")}. A named pi-* harness has no persisted session, so resume does not continue it. Prefer resume for the same task and a new child when you want an independent judgment.
 
-Calls block until the child finishes. background true returns a run id while the originating session still owns the work. Use external_runs to wait, then read view final, and judge that answer yourself. A failed or aborted run stays failed. Retry it, or switch model or harness, only when the user authorized that step. agy may make one disclosed infrastructure retry; that exception is not yours to extend.
+Calls block until the child finishes. background true returns a run id while the originating session still owns the work. Background runs do not notify or resume this session. Use external_runs to wait, then inspect with view final, and judge that answer yourself. For failed runs, check the outcome and diagnostics; view final only provides verified successful answers. A failed or aborted run stays failed. Retry it, or switch model or harness, only when the user authorized that step. agy may make one disclosed infrastructure retry; that exception is not yours to extend.
 
-One Agent call. Permission stays omitted; the prompt carries the no-edit intent:
+One external_delegate call. Permission stays omitted; the prompt carries the no-edit intent:
 ${jsonBlock(USAGE_ONE_AGENT)}
 
 Independent review. Fresh context, a reviewer role, the default tier, no resume:

package/src/tool-names.ts

@@ -0,0 +1,2 @@
+/** Public tool names owned by pi-flow-external. */
+export const EXTERNAL_DELEGATE_TOOL = "external_delegate" as const;

package/src/workflow/tool.ts

@@ -394,7 +394,7 @@ export function createWorkflowTool(
               }),
             });
             // Seed an initial queued observation immediately, mirroring the
-            // direct Agent tool's own top-of-executeRun registry.update: a
+            // direct external_delegate tool's own top-of-executeRun registry.update: a
             // registered entry otherwise carries no observation at all until
             // the backend's first progress event fires deep inside
             // spawnSubagent (after limiter acquisition), so a workflow child
@@ -512,7 +512,7 @@ export function createWorkflowTool(
               // Transition this child's OWN registry entry (not just the
               // workflow's aggregate snapshot above) from queued to running
               // immediately after the concurrency limiter granted its slot —
-              // mirroring the direct Agent tool's own top-of-executeRun
+              // mirroring the direct external_delegate tool's own top-of-executeRun
               // registry.update — and BEFORE any backend progress arrives.
               // Without this, the child's entry only left "queued" once
               // spawnSubagent's own onProgress first fired deep inside