@fradser/pi-agent-teams 0.10.0 → 1.0.0

package/README.md

@@ -1,89 +1,112 @@
 # @fradser/pi-agent-teams
 
-Agent Teams provides one final coordination surface for Pi:
+Agent Teams combines subagent execution, the task set, and point-to-point messages.
+The four intent tools are the only child tool surface:
 
-```text
-agent
-work
-agent_event
-/agent-teams
+```ts
+agent_start({ identity: "reviewer", prompt: "Audit authentication" });
+agent_input({ session: "session:reviewer:<incarnation>", prompt: "Review the correction", delivery: "next" });
+agent_input({ session: "session:reviewer:<incarnation>", prompt: "Keep this read-only", delivery: "steer" });
+agent_list({});
+agent_stop({ session: "session:reviewer:<incarnation>" });
 ```
 
-`agent` manages Agent sessions through strict actions:
+Next input has a bounded FIFO queue and rechecks the original host's task policy.
+A label changes display only; an identity selects saved instructions and private data.
+Read [the intent contract](../subagents/README.md#intent-tools) for results, cancellation, and compatibility.
+The `/agent-teams` console remains available.
 
-```ts
-agent({ action: "delegate", name: "reviewer", prompt: "Audit authentication" })
-agent({ action: "start", name: "reviewer" })
-agent({ action: "inspect", name: "reviewer", session: "session:reviewer-...:spawn-..." })
-agent({ action: "stop", session: "session:reviewer-...:spawn-..." })
-```
+## The retired `agent` tool
 
-A delegate action can include an inline definition. It is session-local unless
-`persist: true` is explicitly supplied in that definition. Choose explicit minimal
-canonical tool IDs (`read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`,
-`powershell`); extension aliases such as `ffgrep` are not inherited. Omitted
-`tools` or `tools: []` grants only `agent_event` and `work`, never default shell
-or file access. Delegate/start results and inspection expose the recorded
-`session.tools` grant, with a coordination-only warning when applicable.
-Inspection uses the session's recorded grant, not a changed role definition;
-legacy records without a grant leave it unknown rather than claiming no tools.
+The `agent` tool and its six actions are gone, and no compatibility adapter
+remains. A recorded branch that named `agent` receives the intent family on its
+next session start. No user data moves. Read
+[ADR-0008](../../docs/adr/0008-retire-the-legacy-agent-tool.md) for the decision.
 
-For an unknown role, provide a compact inline definition:
+An unknown role takes a compact inline definition:
 
 ```ts
-agent({ action: "delegate", name: "reader", prompt: "Read README.md and cite its install command",
-  definition: { description: "Read evidence", prompt: "Read the assigned file and cite evidence", tools: ["read"] } })
+agent_start({ label: "reader", prompt: "Read README.md and cite its install command",
+  description: "Read evidence", role_prompt: "Read the assigned file and cite evidence", tools: ["read"] })
 ```
 
-`agent start` creates an unassigned resident without a synthetic Work ID or an
-initial model turn. Presence stays `starting` until a one-shot native readiness
-acknowledgement, then becomes `idle` and eligible for exact-session assignment.
-The public start call awaits that bounded acknowledgement before returning, so
-its exact returned session accepts an immediate assignment without a caller wait.
-Rejected readiness, timeout, or early exit fails the start call; a process ID is
-not readiness. Reassigning the same still-claimed Work to its exact current owner
-returns the existing Assignment Attempt without a second delivery. Later claimable-board notices can still wake
-the resident and activate deliberate autonomous claims. Start is not a permanent
-assignment-only scheduling mode.
-
-`work` is activated only in valid assignment/board contexts.
-
-`work` owns Work lifecycle. Leaders create/list/assign/release/reopen completed
-Work/supersede; Workers list/claim/submit/release their current Work.
-
-Failed, interrupted, or crash-released Work returns to the board as
+Only a user-authored disk `agent.md` declares durable identity. Disk definitions
+always outrank inline input; invocation tools may narrow their grant, never widen it.
+There are no persistence, Memory opt-in, worktree or promotion parameters. Choose minimal
+canonical tool IDs (`read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`,
+`powershell`); extension aliases such as `ffgrep` are not inherited. Omitted
+`tools` or `tools: []` grants only `message` and `task` for temporary team children,
+never default shell or file access. Disk identities also receive `agent_memory`.
+Start receipts and inspection expose the recorded effective grant, with a
+coordination-only warning when applicable.
+Inspection uses the session's recorded grant, not a changed role definition;
+a record without a grant leaves it unknown rather than claiming no tools.
+
+`agent_start` always takes a prompt and awaits the correlated
+native input acknowledgement, not merely a writable pipe. It never creates an idle
+child. Rejected, handled, timed-out or closed input never reports acceptance.
+A receipt is not a result.
+
+Every temporary or durable child remains **IDLE after a settled result** and accepts
+next input in that exact incarnation. Steer guides active work; `agent_stop` and
+parent shutdown close it. Later tasks notices can wake an idle team participant.
+No child survives the parent Pi process. Hosted next input awaits native input acceptance
+in the same process and history, publishing a new attempt before a later independent
+input. Hosted steer awaits native steering acceptance without changing the
+current sequence or attempt. An uncertain acknowledgement retains authority: inspect
+or stop before retrying, rather than submitting competing input.
+
+Canonical definitions are `<agent-dir>/agents/<name>/agent.md`,
+`<project>/.pi/agents/<name>/agent.md`, and
+`<project>/.pi/agents/<name>.local/agent.md`; precedence is project-local > project >
+user > session. Every disk scope receives private Memory, an ordinary scratch directory
+and project history at `<agent-dir>/agents/<name>/projects/<slug>/session/`.
+Project overrides do not create a user-scope definition. Temporary roles use the
+original project cwd with no-session and no private data. Durable children also launch
+in the original project; scratch is data, not a checkout:
+project edits change the original working tree directly. There is no Git isolation,
+branch, automatic commit, merge or write confinement.
+
+Identity, data provisioning and offline list entries belong to
+[@fradser/pi-subagents](../subagents/VISION.md); team coordination does not create,
+promote or clear that package's role registry.
+
+`task` is activated only in valid assignment/tasks contexts and owns create/list/
+update/complete/reopen. A Task describes what must be done, not who must do it;
+participants take available Tasks with `update status=in_progress`.
+
+Failed, interrupted, or crash-released Work returns to the tasks as
 `pending/recovery-required`: the evidence stays available for inspection, and the
-harness deliberately excludes it from autonomous claim notices. Only an explicit
-leader `work assign` opens the next attempt, so a transient failure is never
-silently retried by whichever resident happens to be idle. A retained superseded
-holder keeps `work` disclosed for exactly one failed cancellation acknowledgement.
+harness deliberately excludes it from autonomous notices. A participant must
+proceed with a stated recovery reason, so a transient failure is never silently
+retried. A retained superseded holder keeps `task` disclosed for exactly one failed
+cancellation acknowledgement.
 
 ```ts
-work({ action: "create", subject: "Fix storage", resources: ["firmware/storage"] })
-work({ action: "assign", id: "fix-storage", target: { session: "session:worker-...:spawn-..." } })
-work({ action: "claim" })
-work({ action: "submit", outcome: "success", result: "Verification evidence" })
+task({ action: "create", subject: "Fix storage", resources: ["firmware/storage"] })
+task({ action: "update", id: "fix-storage", status: "in_progress" })
+task({ action: "complete", id: "fix-storage", outcome: "success", result: "Verification evidence" })
 ```
 
-`agent_event` is communication-only. It accepts a message, a recipient or bound
-reply route, and optional `inform`/`request` intent. Work lifecycle authority is
+`message` is communication-only. It accepts a body, a recipient or bound
+reply route, and optional `inform`/`request` kind. Work lifecycle authority is
 never inferred from message text.
 
 ```ts
-agent_event({ to: "session:reviewer-...:spawn-...", message: "The policy changed", intent: "inform" })
+message({ to: "session:reviewer:spawn-...", body: "The policy changed", kind: "inform" })
 ```
 
 Automatic final answers (including autonomously claimed Work) and explicit Work
 submission use the same attempt-bound acceptance pipeline. Explicit submission
 ends the worker turn without a second automatic submission. Successful results
 reach the Leader once, after execution settles and any verification gate passes.
-Execution failures are reported after settlement without claiming acceptance.
-`work list` includes bounded result evidence for deliberate recovery.
+Execution failures are reported after settlement without claiming acceptance. A refused task transition does not produce an accepted completion or failure report.
+`task list` includes bounded result evidence for deliberate recovery.
 Verification freezes execution and retains deferred mail as Work history.
 An ordinary final answer is a successful candidate, not independent verification;
 ungated acceptance does not independently verify its claims. If requested work
 cannot be performed, including missing tools, workers must explicitly submit
-`work({ action: "submit", outcome: "failed", result: "Blocker and unverified work" })`.
+`task({ action: "complete", outcome: "failed", result: "Blocker and unverified work" })`.
 Blocker prose is not classified as failure. Failed submission produces one failed
 report, not completion or dependent unlock; a rejecting verification gate also
 prevents acceptance. Leaders should delegate concrete acceptance criteria and an
@@ -92,30 +115,43 @@ acknowledgment unless a decision or action changes.
 Do not narrate repeated reports. This guidance does not suppress event transport
 or infer lifecycle changes from communication.
 
+A clean process exit while the resident is idle and owes no result stays in the console mailbox.
+It records the stopped state and confirmed stop time without an unexpected-stop notification or another leader turn.
+Unread mail addressed to the current incarnation prevents passive closure, even before inbox routing.
+Malformed or incomplete unread records also prevent passive closure. Valid JSON alone does not prove that a message is valid.
+The close check changes no inbox bytes, offsets, or delivery records. Stale or already-delivered messages do not create a new alarm.
+Process failures, interrupted assignments, and unresolved results still reach the leader. Accepted results remain available after closure.
+
 After delegation, continue independent work or end the turn: results resume the
-session automatically. Use `agent inspect` for deliberate diagnosis, not repeated
-polling or sleep loops. `agent_event` never creates or retries Work; messaging a
+session automatically. `agent_list` is a status summary, not a way to wait, and a
+child's complete answer arrives with its Session Result rather than on request.
+polling or sleep loops. `message` never creates or retries Work; messaging a
 completed assignment returns its recorded result without waking the worker.
 Worker communication and submissions are bound to the Assignment Attempt that
 started the turn, so an old turn cannot report or submit as replacement Work, and
 nonterminal coordination from a retired attempt stays in session history as
 evidence without acting as a current instruction.
-Recovery reuses the existing Work ID. Request explicit `work release` and await
-authoritative release before `work assign` to the chosen exact session; a queued
-release is not yet released authority. Do not create competing recovery Work via
-`agent delegate`. Read-only/no-write messages are steering, not cancellation or
+Recovery reuses the existing Task ID. A message does not release authority: wait
+for the attempt to end or stop its stale exact session before taking the Task with
+a stated recovery reason. Do not create competing recovery work through another startup. Read-only/no-write messages are steering, not cancellation or
 proof that the current tool batch stopped. Native steering takes effect at safe
 tool boundaries, before peer follow-up; it cannot undo already executed writes.
-Parked verification requires explicit Work release and reassignment; ordinary
+Parked verification requires explicit Task recovery; ordinary
 messages remain deferred. Exact session handles are incarnation-bound, so a stale
 handle cannot stop or inspect a replacement resident. Work persists for later inspection,
 but a different session file does not import another session's tasks automatically.
 
 ## Coordination and delivery
 
+Leader and worker guidance use the owned `agent_teams_leader` and `agent_teams_worker` prompt sections at run start.
+These sections remain present with either Pi's default preamble or an authored `customPrompt`.
+They do not replace the complete system prompt or add context through custom messages.
+Custom-message starts have no user prompt; worker disclosure checks the current assignment without assuming a task notice.
+Historical report filtering and report delivery remain separate from these prompt contributions.
+
 Leader guidance uses the same delivery contract before and after a team starts:
 
-- Delegate separable work with a task-scoped baseline, acceptance criteria and safe local checks. Use `work create` with `dependsOn` for prerequisites and shared `resources` tags for conflicting writes; then assign eligible Work. Independent delegation is not a substitute for dependencies.
+- Delegate separable work with a task-scoped baseline, acceptance criteria and safe local checks. Use `task create` with `dependsOn` for prerequisites and shared `resources` tags for conflicting writes; participants take eligible Tasks. Independent delegation is not a substitute for dependencies.
 - Implementers own assigned local checks. One integration owner checks shared behavior against the integrated candidate. Determine isolation needs before verification; commands running locally may still access user data or production credentials.
 - Record a revision or scoped snapshot for the candidate and exclude unrelated dirty changes. Review and integration checks judge that same candidate; later edits invalidate affected evidence rather than automatically requiring every Agent to rerun every suite.
 - A completed review Work Item can report REWORK. It is not a PASS on the implementation. Review-only work ends with that report, without editing the implementation or waiting for repairs; the implementation owner owns remediation. Implementation delivery stays pending until required Work and blocking reviews have returned, findings are resolved, and applicable evidence matches the final candidate. If only results remain outstanding, yield without announcing completion.
@@ -125,6 +161,38 @@ Leader guidance uses the same delivery contract before and after a team starts:
 
 Read [the role reference](references/agent-roles.md#assignment-brief) when preparing an assignment brief.
 
+## Child environment
+
+A spawned Agent receives an explicit non-secret environment, never the leader's
+complete one. The allowlist covers runtime and locale, editor and pager, Git and
+`SSH_AUTH_SOCK`, proxy and trust anchors, Node and language toolchain locations,
+and the Pi process markers and configuration. `PI_CODING_AGENT_DIR` passes
+through so the child resolves the same `auth.json` and `models.json` as the
+leader; that is where Pi keeps OAuth credentials and literal `apiKey` values, so
+a child needs the config directory rather than the parent's credential set.
+
+Add an exact name to `PI_TEAMMATE_ENV_ALLOW` (comma-separated) when a provider
+resolves credentials through environment interpolation:
+
+```bash
+export PI_TEAMMATE_ENV_ALLOW="MY_PROVIDER_API_KEY,AWS_PROFILE"
+```
+
+Opting in a credential-shaped name works and is reported, so a widening stays
+visible. The allowlist variable itself does not travel to the child, so a nested
+spawn reaches its own strict default. Spawn bindings the harness supplies always
+win over both the allowlist and the leader environment.
+
+The withheld count, the credential-shaped names, and the recovery instruction
+appear in the `/agent-teams` detail view. That stays passive console telemetry
+and never wakes the leader. Names embedding a private URL — npm's
+`npm_config_//registry.example.com/:_authToken` shape — are redacted to a
+recognizable prefix, and no withheld value is ever rendered.
+
+This is leakage defense, not containment. A child granted `bash` can still read
+`~/.pi/agent/auth.json`, `~/.aws/credentials`, or a project `.env` from disk;
+kernel write and read confinement is a separate layer that does not exist yet.
+
 ## Message display
 
 Collapsed `[message]` rows use the current terminal width for their preview and

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fradser/pi-agent-teams",
-  "version": "0.10.0",
-  "description": "Multi-agent team system for Pi — resident teammates, shared task board, and peer-to-peer messaging",
+  "version": "1.0.0",
+  "description": "Agent-to-Agent communication for Pi — point-to-point messaging, notices, Agent Presence, and the Team Console. A bundle: it registers `message` and loads the pi-subagents and pi-tasks extensions, so installing it gives the subagent intent tools plus `task` and `message` with one registrant per tool.",
   "keywords": [
     "pi-package",
     "teammates",
@@ -35,10 +35,18 @@
   },
   "pi": {
     "extensions": [
-      "./index.ts"
+      "./index.ts",
+      "./node_modules/@fradser/pi-subagents/index.ts",
+      "./node_modules/@fradser/pi-tasks/index.ts"
     ]
   },
   "dependencies": {
-    "@fradser/pi-kit": "0.5.1"
+    "@fradser/pi-kit": "0.6.0",
+    "@fradser/pi-subagents": "0.2.0",
+    "@fradser/pi-tasks": "0.2.0"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "1.5.0",
+    "@earendil-works/pi-tui": "1.5.0"
   }
-}
+}

package/references/agent-roles.md

@@ -3,8 +3,11 @@
 Abstract reference for generating new agent definitions on demand. This file
 is NOT discoverable and CANNOT be spawned directly. Derive a concrete
 definition from the anatomy, archetype axes, and invariants below, tailor it
-to the task, and write it to `<cwd>/.pi/agents/<name>.md` (git-managed
-project role) or `<name>.local.md` (personal override).
+to the task, and pass it as an inline session role. Only a user-authored disk
+`agent.md` declares durable identity: `<agent-dir>/agents/<name>/agent.md`,
+`<cwd>/.pi/agents/<name>/agent.md`, or `<cwd>/.pi/agents/<name>.local/agent.md`.
+Project-local overrides project, which overrides user, which overrides session.
+Creating a disk definition requires explicit user authorization, not a tool flag.
 
 ## Definition anatomy
 
@@ -15,12 +18,19 @@ Frontmatter:
   role, phrased as "use when ...". This is the most load-bearing field.
 - `tools` — the explicit minimal set; follows the mutability axis (see below).
   Canonical built-ins are `read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`,
-  `powershell` (kept in sync with `src/worker-tools.ts`).
-  Omitted tools or `[]` grant only coordination tools (`agent_event`, `work`),
+  `powershell` (declared by `@fradser/pi-subagents`).
+  Omitted tools or `[]` grant only coordination tools (`message`, `task`),
   not file or shell access. No aliases or implicit default `bash`.
-- optional `model`, `verify`, `worktree`. `verify` is an independent completion-gate
-  reviewer prompt, not a shell command. State the evidence and acceptance criteria
-  the gate should inspect; a concrete local gate is not a second broad project review.
+- optional `model`, `verify`. `verify` is an independent completion-gate
+  reviewer prompt, not a shell command. State evidence and acceptance criteria; a concrete
+  local gate is not a second broad project review.
+
+Every disk scope has private Memory, an ordinary scratch workspace and project-scoped
+Pi history under the configured agent directory. Inline session roles have none and
+run in the original project cwd with no-session. Scratch is not a project checkout:
+project edits change the original working tree directly, with no write confinement,
+Git isolation or automatic commit. Never invent persistence, Memory or workspace flags.
+Results leave both kinds IDLE for `send`; only `stop` or parent shutdown closes them.
 
 The Markdown body is the role prompt, built from five parts:
 
@@ -30,8 +40,8 @@ The Markdown body is the role prompt, built from five parts:
 3. Boundaries — what must never be touched or changed.
 4. Evidence — what every claim or finding must carry.
 5. Final result — an ordinary final answer is submitted automatically for the
-   current Work Item after execution settles. A Worker may explicitly use
-   `work({ action: "submit", outcome, result? })`; communication events never
+   current Task after execution settles. A Worker may explicitly use
+   `task({ action: "complete", outcome, result? })`; communication events never
    carry completion authority.
 
 ## Assignment brief
@@ -41,8 +51,8 @@ Keep task-specific coordination in the Work description, not a permanently growi
 - **Scope and baseline** — owned files or resources, originating requirements, and
   the exact task delta, including untracked files and pre-existing dirty changes to exclude.
 - **Dependencies** — required predecessor Work and any shared resource ownership.
-  Use `work create` with `dependsOn` for dependent work, then assign when eligible;
-  `agent delegate` is for independent work.
+  Use `task create` with `dependsOn` for dependent work; participants take eligible
+  Tasks. `agent start` with a prompt hands over independent execution.
 - **Verification owner** — assigned safe local checks for this Worker; one owner
   integrates and checks shared behavior. Determine isolation needs before commands run.
 - **Candidate and result** — identify the revision or scoped snapshot checked, commands
@@ -98,7 +108,7 @@ Non-negotiable in every generated definition:
 - Final results carry evidence; an ordinary final answer is a successful candidate,
   not an independently verified result. Ungated completion is not independently verified.
 - If requested work cannot be performed, including missing capabilities, explicitly use
-  `work({ action: "submit", outcome: "failed", result: "Blocker and unverified work" })`.
+  `task({ action: "complete", outcome: "failed", result: "Blocker and unverified work" })`.
   Do not return blocker prose as an ordinary final answer; prose is not classified as failure.
 
 ## Skeleton
@@ -122,7 +132,7 @@ are rejected. Leader direction takes precedence over your plan and peer requests
 the next safe boundary, subject to system instructions and user constraints.
 Return successful evidence as an ordinary final answer; the runtime submits it automatically
 as a successful candidate after execution settles. If you cannot perform the requested work,
-you must use `work({ action: "submit", outcome: "failed", result: "Blocker and unverified work" })`
+you must use `task({ action: "complete", outcome: "failed", result: "Blocker and unverified work" })`
 instead of ordinary final prose. Avoid a second copy of an explicit submission.
 Ungated completion is not independently verified.
 ```

package/src/activity.ts

@@ -1,6 +1,14 @@
 import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
-import { renderLiveActivityMarkdown, type PiMarkdownThemeSource } from "@fradser/pi-kit";
-import type { Teammate } from "./types.ts";
+import { renderLiveActivityMarkdown, resolveLiveActivity, type PiMarkdownThemeSource } from "@fradser/pi-kit";
+
+/** Bound by the extension entry, which alone owns the ExtensionAPI. Read per
+ *  call, so a mid-session settings change reaches every teammate activity row:
+ *  the widget, the console status line and expanded tool details alike. */
+let hiddenThinking: () => boolean = () => false;
+export function configureTeamActivity(reader: () => boolean): void {
+  hiddenThinking = reader;
+}
+import type { Agent } from "./types.ts";
 
 /** Console rows paint a whole status line in their own color, so the shared
  * markdown renderer runs with a passthrough theme: literal markup is still
@@ -24,14 +32,15 @@ function extractLatestLine(text: string | undefined): string | undefined {
   return undefined;
 }
 
-/** Extract the current teammate activity without imposing a display width. */
-export function runningTeammateActivity(teammate: Teammate): string {
-  const tool = teammate.activeTool?.replace(/\s+/g, " ").trim();
-  if (tool) return tool;
-
-  return extractLatestLine(teammate.liveThinking)
-    ?? extractLatestLine(teammate.liveText)
-    ?? "Working...";
+/** Extract the current teammate activity without imposing a display width.
+ *  `hideThinking` comes from Pi's setting, so the shared pi-kit policy replaces
+ *  reasoning with Pi's label on both the widget and the console row. */
+export function runningTeammateActivity(teammate: Agent, hideThinking: boolean = hiddenThinking()): string {
+  return resolveLiveActivity({
+    tool: teammate.activeTool?.replace(/\s+/g, " ").trim(),
+    thinking: extractLatestLine(teammate.liveThinking),
+    text: extractLatestLine(teammate.liveText),
+  }, hideThinking) ?? "Working...";
 }
 
 export interface TeammateRowWidths {
@@ -54,7 +63,7 @@ export function teammateRowWidths(spinner: string, agent: string, width: number)
 }
 
 /** Fit a console status label to the requested activity width. */
-export function formatTeammateLabel(
+export function formatAgentLabel(
   spinner: string,
   activity: string,
   maxActivityWidth?: number,

package/src/agent-actions.ts

@@ -1,23 +1,22 @@
-import { randomUUID } from "node:crypto";
-import { WORKER_BUILTIN_TOOLS } from "./worker-tools.ts";
+import { AGENT_BUILTIN_TOOLS } from "@fradser/pi-subagents";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { isValidTeammateName, listTeammates } from "./state.ts";
-import { resolveAgent } from "./agents.ts";
-import { shutdownTeammateExact, spawnTeammate } from "./team-machine.ts";
-import { normalizeCoordinationParams, requireParsedParams, type Teammate } from "./types.ts";
-import { snapshotWorkContext } from "./work-context.ts";
+import { isValidAgentName, listAgents } from "./state.ts";
+import { resolveAgent } from "@fradser/pi-subagents";
+import { shutdownAgentExact, spawnAgent } from "./team-machine.ts";
+import { normalizeCoordinationParams, requireParsedParams, type Agent } from "./types.ts";
+import { snapshotWorkContext } from "@fradser/pi-subagents";
 import { exactSessionRoute, resolveExactSession } from "./recipient.ts";
 
 export interface AgentActionRuntime {
-  spawnTeammate: typeof spawnTeammate;
-  shutdownTeammateExact: typeof shutdownTeammateExact;
+  spawnAgent: typeof spawnAgent;
+  shutdownAgentExact: typeof shutdownAgentExact;
 }
 
-type Definition = Parameters<typeof spawnTeammate>[0]["definition"];
+type Definition = Parameters<typeof spawnAgent>[0]["definition"];
 
-function session(teammate: Teammate) {
+function session(teammate: Agent) {
   const tools = teammate.tools;
-  const coordinationOnly = tools !== undefined && tools.every((tool) => tool === "agent_event" || tool === "work");
+  const coordinationOnly = tools !== undefined && tools.every((tool) => tool === "message" || tool === "task");
   return {
     tools,
     ...(coordinationOnly ? { warning: "coordination-only: no file or shell tools granted. Delegate execution work with explicit canonical tools; no bash is granted by default." } : {}),
@@ -29,17 +28,15 @@ function session(teammate: Teammate) {
 }
 
 function requireName(name: string): void {
-  if (!isValidTeammateName(name)) throw new Error(`Invalid Agent name "${name}".`);
+  if (!isValidAgentName(name)) throw new Error(`Invalid Agent name "${name}".`);
 }
 
 export function runAgentAction(
   params: {
-    action: "delegate" | "start" | "inspect" | "stop";
+    action: "start" | "inspect" | "stop";
     name?: string;
     prompt?: string;
     definition?: Definition;
-    resources?: string[];
-    verify?: string;
     model?: string;
     fork?: boolean;
     session?: string;
@@ -55,50 +52,78 @@ export function runAgentAction(
     if (!params.name) throw new Error("Agent inspect requires a name.");
     requireName(params.name);
     if (!params.session) throw new Error("Agent inspect requires an exact session handle.");
-    const matched = resolveExactSession(params.session, listTeammates());
-    if (!matched || matched.agent !== params.name) throw new Error(`No current session "${params.session}" belongs to @${params.name}.`);
+    const matched = resolveExactSession(params.session, listAgents());
+    if (!matched || matched.name !== params.name) throw new Error(`No current session "${params.session}" belongs to @${params.name}.`);
     return { action: "inspect", outcome: "inspected", agent: params.name, sessions: [session(matched)] };
   }
   if (params.action === "stop") {
     if (!params.session) throw new Error("Agent stop requires an exact session handle.");
-    const matched = resolveExactSession(params.session, listTeammates());
+    const matched = resolveExactSession(params.session, listAgents());
     if (!matched) throw new Error(`No living session named "${params.session}".`);
-    return runtime.shutdownTeammateExact(matched.name, matched.spawnId).then((result) => {
+    return runtime.shutdownAgentExact(matched.name, matched.spawnId).then((result) => {
       if (!result.ok) throw new Error(result.error);
-      return { action: "stop", outcome: "stopped", session: params.session, body: result.body };
+      // The name comes from the resolved session, not from the request: a stop
+      // carries only a handle, so a receipt keyed on the request would be unnamed
+      // and a row drawn from it would have nothing to show.
+      return { action: "stop", outcome: "stopped", agent: matched.name, session: params.session, body: result.body };
     });
   }
-  if (!params.name) throw new Error(`Agent ${params.action} requires a name.`);
+  if (!params.name) throw new Error("Agent start requires a name.");
   requireName(params.name);
-  if (!params.definition && !resolveAgent(params.name, _cwd)) {
-    throw new Error(`Unknown Agent @${params.name}. Define it inline through agent action=delegate or start; for example definition: { description: "Read evidence", prompt: "Read the assigned file and report evidence", tools: ["read"] }. Choose only needed canonical tools: ${WORKER_BUILTIN_TOOLS.join(", ")}. Omitted tools or [] grant coordination-only access.`);
+  if (params.definition !== undefined) {
+    const role = params.definition as { description?: string; prompt?: string };
+    const hasDescription = typeof role.description === "string" && role.description.trim().length > 0;
+    const hasPrompt = typeof role.prompt === "string" && role.prompt.trim().length > 0;
+    // Both halves or neither. Half a role produces a child that reports a result
+    // nobody asked for, because it has no instructions and nothing told it to
+    // wait.
+    if (hasDescription !== hasPrompt) {
+      throw new Error("An inline role needs both description and role_prompt, or neither.");
+    }
   }
-  const prompt = params.action === "delegate" ? params.prompt?.trim() : undefined;
-  if (params.action === "delegate" && !prompt) throw new Error("Agent delegate requires a prompt.");
-  if (params.action === "start" && params.fork !== undefined) throw new Error("Agent start cannot fork context.");
+  // A prompt needs a role; an idle resident does not. A prompted child with no
+  // role would run without instructions and report a result nobody asked for,
+  // which is worse than refusing. A child started with no prompt is waiting for
+  // work, and requiring a role up front would make the normal two spawn shapes —
+  // do this one thing, or sit ready — behave differently from the tool.
+  if (params.prompt && !params.definition && !resolveAgent(params.name, _cwd)) {
+    throw new Error(`A prompt needs a role. @${params.name} has no definition: pass description and role_prompt, or use a name that already has one. Choose only needed canonical tools: ${AGENT_BUILTIN_TOOLS.join(", ")}. Omitted tools or [] grant coordination-only access.`);
+  }
+  // One spawn verb with an optional prompt. `delegate` and `start` were the same
+  // operation dispatched twice, and the only difference was whether a prompt was
+  // delivered; two names meant a caller had to pick between two identically
+  // shaped paths and the wrong pick was invisible.
+  const prompt = params.prompt?.trim();
+  if (params.prompt !== undefined && !prompt) throw new Error("An empty prompt is not a task. Omit it to leave the agent idle.");
   const context = params.fork ? snapshotWorkContext(sessionManager) : undefined;
-  const result = runtime.spawnTeammate({
+  const result = runtime.spawnAgent({
     name: params.name,
-    agent: params.name,
-    ...(params.action === "delegate" ? { workId: `work:${randomUUID()}`, prompt, resources: params.resources as string[] | undefined, verify: params.verify, context } : {}),
+    role: params.name,
+    // A prompt is delivered, not recorded: spawning creates no task, so there is
+    // no work id, no resource lease, and no verify gate to attach. Anything that
+    // needs a record is a task the caller creates and the participant takes.
+    ...(prompt ? { prompt } : {}),
     ...(params.model ? { model: params.model } : {}),
     ...(params.definition ? { definition: params.definition } : {}),
+    ...(context ? { context } : {}),
   });
   if (!result.ok) throw new Error(result.error);
-  const receipt = (teammate: Teammate) => ({
-    action: params.action,
+  const receipt = (teammate: Agent) => ({
+    action: "start",
     outcome: "started",
     agent: params.name,
+    prompted: Boolean(prompt),
     session: session(teammate),
-    ...(params.action === "delegate" ? { work: { id: teammate.workId, state: "claimed" }, assignment: { id: teammate.assignment?.id } } : {}),
   });
-  if (params.action === "start" && result.readiness) {
+  // The machine offers one bounded startup receipt: native readiness without
+  // input, or correlated accepted input with a kickoff. Neither means completed.
+  if (result.readiness) {
     return result.readiness.then((error) => {
       if (error) throw new Error(error);
-      const current = resolveExactSession(exactSessionRoute(result.teammate.name, result.teammate.spawnId), listTeammates());
+      const current = resolveExactSession(exactSessionRoute(result.agent.name, result.agent.spawnId), listAgents());
       if (!current || current.status === "stopped") throw new Error("Resident exited or was replaced before startup readiness completed.");
       return receipt(current);
     });
   }
-  return receipt(result.teammate);
+  return receipt(result.agent);
 }