@gotgenes/pi-subagents 9.0.0 → 10.0.0

package/CHANGELOG.md

@@ -5,6 +5,33 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [10.0.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v9.0.1...pi-subagents-v10.0.0) (2026-05-27)
+
+
+### ⚠ BREAKING CHANGES
+
+* The tool name changes from "Agent" to "subagent". Any AGENTS.md files, prompt templates, or custom agent configs that reference the tool by name will need updating.
+
+### Features
+
+* rename Agent tool to subagent ([#242](https://github.com/gotgenes/pi-packages/issues/242)) ([8b1c310](https://github.com/gotgenes/pi-packages/commit/8b1c310d8fd2d797b0d116fdaf2d4b28ea5b41ce))
+
+
+### Documentation
+
+* **pi-subagents:** add Phase 14 Step 4 — rename Agent tool to subagent ([#242](https://github.com/gotgenes/pi-packages/issues/242)) ([2a3cd9f](https://github.com/gotgenes/pi-packages/commit/2a3cd9f25dce042a77d28da1d17a6d8c7870dddf))
+* plan rename Agent tool to subagent ([#242](https://github.com/gotgenes/pi-packages/issues/242)) ([41fe2a4](https://github.com/gotgenes/pi-packages/commit/41fe2a4033a49b39fbbe3938580c6afaeefa9d47))
+* **retro:** add planning stage notes for issue [#242](https://github.com/gotgenes/pi-packages/issues/242) ([6211bed](https://github.com/gotgenes/pi-packages/commit/6211bede3cde8e283b05ed81cc1652e2e370cd9b))
+* **retro:** add TDD stage notes for issue [#242](https://github.com/gotgenes/pi-packages/issues/242) ([7ec9ead](https://github.com/gotgenes/pi-packages/commit/7ec9eadc3544a4c73ce1d3e491cc29da3fddbe16))
+* update tool name references after Agent → subagent rename ([#242](https://github.com/gotgenes/pi-packages/issues/242)) ([0b6774d](https://github.com/gotgenes/pi-packages/commit/0b6774dbe049320bb7919f1f09c6f4c090eb91c5))
+
+## [9.0.1](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v9.0.0...pi-subagents-v9.0.1) (2026-05-27)
+
+
+### Documentation
+
+* **retro:** add retro notes for issue [#238](https://github.com/gotgenes/pi-packages/issues/238) ([84f2e49](https://github.com/gotgenes/pi-packages/commit/84f2e49c1c7a28e83ca556f377d7e3f970b8a5d2))
+
 ## [9.0.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v8.0.0...pi-subagents-v9.0.0) (2026-05-27)
 
 

package/README.md

@@ -16,7 +16,7 @@ Run them in foreground or background, steer them mid-run, resume completed sessi
 
 ## Features
 
-- **Claude Code look & feel** — same tool names, calling conventions, and UI patterns (`Agent`, `get_subagent_result`, `steer_subagent`) — feels native
+- **Claude Code look & feel** — same tool names, calling conventions, and UI patterns (`subagent`, `get_subagent_result`, `steer_subagent`) — feels native
 - **Parallel background agents** — spawn multiple agents that run concurrently with automatic queuing (configurable concurrency limit, default 4) and individual completion notifications
 - **Live widget UI** — persistent above-editor widget with animated spinners, live tool activity, token counts, and colored status icons
 - **Conversation viewer** — select any agent in `/agents` to open a live-scrolling overlay of its full conversation (auto-follows new content, scroll up to pause)
@@ -49,10 +49,10 @@ pi -e ./src/index.ts
 
 ## Quick Start
 
-The parent agent spawns sub-agents using the `Agent` tool:
+The parent agent spawns sub-agents using the `subagent` tool:
 
 ```text
-Agent({
+subagent({
   subagent_type: "Explore",
   prompt: "Find all files that handle authentication",
   description: "Find auth files",
@@ -163,7 +163,7 @@ Report findings with file paths, line numbers, severity, and remediation advice.
 Then spawn it like any built-in type:
 
 ```text
-Agent({ subagent_type: "auditor", prompt: "Review the auth module", description: "Security audit" })
+subagent({ subagent_type: "auditor", prompt: "Review the auth module", description: "Security audit" })
 ```
 
 ### Frontmatter Fields
@@ -190,11 +190,11 @@ All fields are optional — sensible defaults for everything.
 
 Frontmatter is authoritative.
 If an agent file sets `model`, `thinking`, `max_turns`, `inherit_context`, `run_in_background`, `isolated`, or `isolation`, those values are locked for that agent.
-`Agent` tool parameters only fill fields the agent config leaves unspecified.
+`subagent` tool parameters only fill fields the agent config leaves unspecified.
 
 ## Tools
 
-### `Agent`
+### `subagent`
 
 Launch a sub-agent.
 
@@ -359,7 +359,7 @@ This prevents unintended tool escalation.
 Set `isolation: worktree` to run an agent in a temporary git worktree:
 
 ```text
-Agent({ subagent_type: "refactor", prompt: "...", isolation: "worktree" })
+subagent({ subagent_type: "refactor", prompt: "...", isolation: "worktree" })
 ```
 
 The agent gets a full, isolated copy of the repository.
@@ -368,7 +368,7 @@ On completion:
 - **No changes:** worktree is cleaned up automatically
 - **Changes made:** changes are committed to a new branch (`pi-agent-<id>`) and returned in the result
 
-If the worktree cannot be created (not a git repo, no commits, or `git worktree add` fails), the `Agent` tool returns a clear error instead of running unisolated — `isolation: "worktree"` is a strict guarantee, not a hint.
+If the worktree cannot be created (not a git repo, no commits, or `git worktree add` fails), the `subagent` tool returns a clear error instead of running unisolated — `isolation: "worktree"` is a strict guarantee, not a hint.
 Initialize git and commit at least once, or omit `isolation`.
 
 ## Skill Preloading

package/docs/architecture/architecture.md

@@ -69,7 +69,7 @@ flowchart TB
 
     subgraph tools["Tools domain"]
         direction TB
-        AgentTool["Agent tool\n(dispatch)"]
+        AgentTool["subagent tool\n(dispatch)"]
         ResultRenderer["result-renderer\n(pure rendering)"]
         SpawnConfig["spawn-config\n(resolve params)"]
         FgRunner["foreground-runner"]
@@ -200,14 +200,14 @@ Other terminal transitions guard against overwriting `stopped` — once an agent
 ```mermaid
 sequenceDiagram
     participant LLM as Parent LLM
-    participant Tool as Agent tool
+    participant Tool as subagent tool
     participant Spawn as spawn-config
     participant Mgr as AgentManager
     participant Runner as agent-runner
     participant Asm as assembleSessionConfig
     participant Child as Child session
 
-    LLM->>Tool: Agent(type, prompt, ...)
+    LLM->>Tool: subagent(type, prompt, ...)
     Tool->>Spawn: resolveSpawnConfig(params)
     Spawn-->>Tool: ResolvedSpawnConfig
     Tool->>Mgr: spawn(snapshot, type, prompt, config)
@@ -279,7 +279,7 @@ src/
 │   └── service-adapter.ts          SubagentsServiceAdapter class wrapping AgentManager
 │
 ├── tools/                          LLM-facing tool implementations
-│   ├── agent-tool.ts               Agent tool definition, validation, dispatch
+│   ├── agent-tool.ts               subagent tool definition, validation, dispatch
 │   ├── result-renderer.ts          pure per-status result rendering
 │   ├── spawn-config.ts             pure config resolution
 │   ├── foreground-runner.ts        foreground execution loop
@@ -323,7 +323,7 @@ flowchart TD
     subgraph core["@gotgenes/pi-subagents"]
         direction TB
         exports["SubagentsService API<br/>publish / getSubagentsService<br/>SubagentRecord, SubagentStatus"]
-        engine["Tools: Agent, get_subagent_result,<br/>steer_subagent<br/>AgentManager, agent-runner"]
+        engine["Tools: subagent, get_subagent_result,<br/>steer_subagent<br/>AgentManager, agent-runner"]
         ui_int["Internal UI: widget, viewer,<br/>/agents menu"]
     end
 
@@ -337,7 +337,7 @@ They declare this package as an optional peer dependency and use dynamic import
 
 ### What the core owns
 
-- The three tools: `Agent`, `get_subagent_result`, `steer_subagent`.
+- The three tools: `subagent` (née `Agent`), `get_subagent_result`, `steer_subagent`.
 - `AgentManager` — spawn, queue, abort, resume, concurrency control.
 - `agent-runner` — session creation, turn loop, extension binding.
 - `permission-bridge` — optional cross-extension bridge to `@gotgenes/pi-permission-system`; registers each child session with `SubagentSessionRegistry` before `bindExtensions()` so the permission system detects in-process children deterministically.
@@ -679,6 +679,7 @@ Removing it simplifies `runAgent`, shrinks `AgentConfig` and `SessionConfig`, an
 | `extensions: string[]` allowlist is tool filtering disguised as lifecycle control         | A: Overlap    | 3      | 2    | 9        |
 | `filterActiveTools` runs twice (pre-bind + post-bind) to catch extension-registered tools | B: Complexity | 3      | 1    | 6        |
 | `ToolFilterConfig` exists solely to carry filtering state through the runner              | C: Accidental | 2      | 1    | 4        |
+| `Agent` tool name is PascalCase — misaligns with Pi's lowercase built-in convention       | D: Convention | 2      | 1    | 3        |
 
 ### Step 1: Remove `disallowed_tools` — [#237] ✅ Complete
 
@@ -728,6 +729,24 @@ Inline the `extensions === false` passthrough into the callsite and reduce the f
 - Smell: B (accidental complexity), C (two-pass filter dance)
 - Outcome: `filterActiveTools` is a one-liner; `SessionConfig` loses one nested type; the pre-bind/post-bind dance is gone
 
+### Step 4: Rename `Agent` tool to `subagent` — [#242] ✅ Complete
+
+Rename the `Agent` tool to `subagent` to align with Pi's built-in tool naming convention (all lowercase: `read`, `bash`, `write`, `edit`, `find`, `grep`, `ls`).
+The PascalCase name was inherited from tintinweb/pi-subagents (mimicking Claude Code's convention), but Pi uses lowercase for all built-in tools.
+The companion tools are already lowercase snake_case (`get_subagent_result`, `steer_subagent`), and nicobailon/pi-subagents already uses `subagent`.
+
+1. Rename tool name from `"Agent"` to `"subagent"` in `agent-tool.ts`.
+2. Update `label` and `promptSnippet` in the tool definition.
+3. Update `EXCLUDED_TOOL_NAMES` in `agent-runner.ts`.
+4. Update the fallback display name in `agent-tool.ts`.
+5. Update architecture docs (tool references, domain diagrams, cross-extension section).
+6. Update pi-permission-system docs that reference the `Agent` tool name.
+7. Update tests.
+
+- Target: `tools/agent-tool.ts`, `lifecycle/agent-runner.ts`, `docs/`, `../pi-permission-system/docs/`
+- Smell: D (convention mismatch — PascalCase in a lowercase ecosystem)
+- Outcome: all three tools use consistent lowercase naming; aligns with Pi's built-in convention
+
 ### Step dependency diagram
 
 ```mermaid
@@ -735,17 +754,19 @@ flowchart LR
     S1["Step 1\nRemove disallowed_tools"]
     S2["Step 2\nRemove extensions filtering"]
     S3["Step 3\nCollapse filterActiveTools"]
+    S4["Step 4\nRename Agent to subagent"]
 
     S1 --> S3
     S2 --> S3
 ```
 
-Steps 1 and 2 are independent and can proceed in parallel.
-Step 3 depends on both.
+Steps 1, 2, and 4 are independent and can proceed in parallel.
+Step 3 depends on Steps 1 and 2.
 
 [#237]: https://github.com/gotgenes/pi-packages/issues/237
 [#238]: https://github.com/gotgenes/pi-packages/issues/238
 [#239]: https://github.com/gotgenes/pi-packages/issues/239
+[#242]: https://github.com/gotgenes/pi-packages/issues/242
 
 ## Improvement roadmap (Phase 15 — domain model evolution)
 

package/docs/plans/0242-rename-agent-tool-to-subagent.md

@@ -0,0 +1,165 @@
+---
+issue: 242
+issue_title: "Rename `Agent` tool to `subagent`"
+---
+
+# Rename `Agent` tool to `subagent`
+
+## Problem Statement
+
+The `Agent` tool is the only PascalCase tool name in the Pi ecosystem.
+Pi's built-in tools are all lowercase (`read`, `bash`, `write`, `edit`, `find`, `grep`, `ls`), and the companion tools in this package already use lowercase snake_case (`get_subagent_result`, `steer_subagent`).
+The PascalCase name was inherited from tintinweb/pi-subagents, which mimicked Claude Code's convention rather than Pi's.
+
+## Goals
+
+- Rename the tool from `"Agent"` to `"subagent"` — a **breaking change** (`feat!:`).
+- Update `label`, `promptSnippet`, and `description` text to reference `subagent` instead of `Agent`.
+- Update `EXCLUDED_TOOL_NAMES` in `agent-runner.ts`.
+- Update the fallback display name in `agent-tool.ts` `renderCall`.
+- Update architecture docs that reference the `Agent` tool name.
+- Update `README.md` tool-name references.
+- Update all affected tests.
+
+## Non-Goals
+
+- Renaming the `displayName` of the general-purpose agent type (`"Agent"` in `default-agents.ts` and `agent-types.ts` fallback) — that is a UI display name for the agent *type*, not the tool name.
+  The widget shows "Agent" as the display name for general-purpose agents; this is a separate concern.
+- Renaming the companion tools `get_subagent_result` and `steer_subagent` — they already follow the lowercase convention.
+- Updating the companion tools' `label` fields (`"Steer Agent"`, `"Get Agent Result"`) — these use "Agent" in the human-readable sense, not as the tool name.
+- Collapsing `filterActiveTools` (#239) — that step is independent within Phase 14.
+- Updating pi-permission-system docs — verified that no docs there reference the `Agent` tool name specifically.
+  All "Agent" references in that package's docs refer to the agent-name concept (per-agent overrides, agent frontmatter), not the tool.
+
+## Background
+
+Phase 14 of the architecture roadmap strips policy enforcement from pi-subagents.
+Steps 1 and 2 (#237, #238) are complete; Step 3 (#239, collapse `filterActiveTools`) is open but independent of this rename.
+This is Step 4 — the final convention-alignment step in Phase 14.
+
+### Files affected
+
+| File                                                  | Current `"Agent"` references                                                                                                                      |
+| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `src/tools/agent-tool.ts`                             | `name`, `label`, `promptSnippet`, description text, `renderCall` fallback (line 247)                                                              |
+| `src/lifecycle/agent-runner.ts`                       | `EXCLUDED_TOOL_NAMES` array (line 22)                                                                                                             |
+| `README.md`                                           | Tool name references, usage examples, tool parameter table heading                                                                                |
+| `docs/architecture/architecture.md`                   | Directory listing comment, findings table, Step 4 description                                                                                     |
+| `test/tools/agent-tool.test.ts`                       | `name` and `label` assertions                                                                                                                     |
+| `test/lifecycle/agent-runner-extension-tools.test.ts` | `"Agent"` in active-tools arrays and `not.toContain` assertion                                                                                    |
+| `test/print-mode.test.ts`                             | `tools.get("Agent")` lookup                                                                                                                       |
+| `test/widget-renderer.test.ts`                        | `"Agent"` in display-name comment and assertion                                                                                                   |
+| `test/tools/spawn-config.test.ts`                     | `displayName: "Agent"` assertions (general-purpose type display name — **no change**, these test the agent type's displayName, not the tool name) |
+| `test/tools/foreground-runner.test.ts`                | `displayName: "Agent"` in fixture data (**no change** — tests general-purpose type displayName)                                                   |
+| `test/tools/helpers.test.ts`                          | `displayName: "Agent"` in fixture data (**no change** — tests result rendering, not tool name)                                                    |
+| `test/display.test.ts`                                | `"Agent"` display name assertion (**no change** — tests `getDisplayName` for general-purpose type)                                                |
+
+## Design Overview
+
+This is a straightforward string-replacement change with no logic or type changes.
+The tool's `name` field drives Pi's tool registration, system-prompt toolbox, and LLM invocations.
+
+### Tool definition changes
+
+```typescript
+// Before
+name: "Agent" as const,
+label: "Agent",
+promptSnippet: "Agent: Launch a specialized agent for complex, multi-step tasks.",
+
+// After
+name: "subagent" as const,
+label: "Subagent",
+promptSnippet: "subagent: Launch a specialized agent for complex, multi-step tasks.",
+```
+
+The description body changes `"The Agent tool launches"` → `"The subagent tool launches"` and `"Agent results are returned"` → `"Subagent results are returned"`.
+
+### renderCall fallback
+
+```typescript
+// Before
+: "Agent";
+// After
+: "Subagent";
+```
+
+This fallback shows when no `subagent_type` is provided.
+Using `"Subagent"` (capitalized for display) is appropriate — it mirrors the tool's identity without conflating with the general-purpose agent type's `displayName`.
+
+### EXCLUDED_TOOL_NAMES
+
+```typescript
+// Before
+const EXCLUDED_TOOL_NAMES = ["Agent", "get_subagent_result", "steer_subagent"];
+// After
+const EXCLUDED_TOOL_NAMES = ["subagent", "get_subagent_result", "steer_subagent"];
+```
+
+## Module-Level Changes
+
+### `src/tools/agent-tool.ts`
+
+1. Change `name: "Agent" as const` → `name: "subagent" as const`.
+2. Change `label: "Agent"` → `label: "Subagent"`.
+3. Change `promptSnippet` to start with `subagent:` instead of `Agent:`.
+4. Change `"The Agent tool launches"` → `"The subagent tool launches"` in description.
+5. Change `"Agent results are returned"` → `"Subagent results are returned"` in description guidelines.
+6. Change fallback `"Agent"` → `"Subagent"` in `renderCall`.
+
+### `src/lifecycle/agent-runner.ts`
+
+1. Change `"Agent"` → `"subagent"` in `EXCLUDED_TOOL_NAMES`.
+
+### `README.md`
+
+1. Update tool name references in the "features" bullet (`` `Agent` `` → `` `subagent` ``).
+2. Update usage example heading and code block (`Agent({` → `subagent({`).
+3. Update tool parameter table heading (`### \`Agent\`` → `### \`subagent\``).
+4. Update prose references to the `Agent` tool ("`Agent` tool parameters", "`Agent` tool returns").
+5. Update widget example display — the widget shows `Agent` because the general-purpose type's `displayName` is `"Agent"`, so those lines stay as-is.
+
+### `docs/architecture/architecture.md`
+
+1. Update the directory listing comment: `agent-tool.ts` description → `subagent tool definition`.
+2. Update the findings table row to mark the item as resolved.
+3. Update Step 4 description to indicate completion.
+4. The `(née \`Agent\`)` parenthetical in the "What the core owns" section already anticipates the rename — keep it as-is for historical context.
+
+### Test files
+
+1. `test/tools/agent-tool.test.ts` — update `name` and `label` assertions.
+2. `test/lifecycle/agent-runner-extension-tools.test.ts` — update `"Agent"` in active-tools arrays and `.not.toContain("Agent")` → `.not.toContain("subagent")`.
+3. `test/print-mode.test.ts` — update `tools.get("Agent")` → `tools.get("subagent")`.
+4. `test/widget-renderer.test.ts` — update the comment text (the assertion tests general-purpose displayName, which stays `"Agent"`).
+
+## Test Impact Analysis
+
+1. No new tests are needed — this is a string-value change.
+2. Existing tests that assert the tool name `"Agent"` must be updated to assert `"subagent"`.
+3. Tests that assert the general-purpose agent type's `displayName` (`"Agent"`) are **not affected** — the `displayName` is an agent-type property, not the tool name.
+
+## TDD Order
+
+1. **Update tool definition and runner constant.**
+   Change `name`, `label`, `promptSnippet`, description text, and `renderCall` fallback in `agent-tool.ts`.
+   Change `EXCLUDED_TOOL_NAMES` in `agent-runner.ts`.
+   Update affected tests in `agent-tool.test.ts`, `agent-runner-extension-tools.test.ts`, `print-mode.test.ts`, and `widget-renderer.test.ts`.
+   Commit: `feat!: rename Agent tool to subagent (#242)`
+
+2. **Update documentation.**
+   Update `README.md` tool-name references and usage examples.
+   Update `docs/architecture/architecture.md` directory listing, findings table, and Step 4 status.
+   Commit: `docs: update tool name references after Agent → subagent rename (#242)`
+
+## Risks and Mitigations
+
+| Risk                                                                                            | Mitigation                                                                                                                    |
+| ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| Breaking change for users referencing `Agent` in AGENTS.md, prompt templates, or custom configs | This is intentional and documented in the issue. Fits within the Phase 14 breaking-change window. Use `feat!:` commit prefix. |
+| Forgetting a test reference to `"Agent"`                                                        | Grep all test files for `"Agent"` before committing. Distinguish tool-name references from agent-type displayName references. |
+| Companion tool labels (`"Steer Agent"`, `"Get Agent Result"`) use "Agent"                       | These use "Agent" in the human-readable sense. They are not affected by the tool-name rename and remain consistent.           |
+
+## Open Questions
+
+None — the issue scope is unambiguous.

package/docs/retro/0238-remove-extensions-filtering.md

@@ -37,3 +37,36 @@ Full suite: 62 files, 977 tests, all passing; type check and lint clean.
 - **ESLint auto-fix in step 2**: ESLint rewrote `extensions === false` to `!extensions` and `cfg.toolFilter.extensions === false` to `!cfg.toolFilter.extensions` after the type narrowed to `boolean`.
   Both are semantically identical; the changes were staged and included in the same commit.
 - The `resolveBoolExtensions` helper in `custom-agents.ts` is a clean seam — if `skills` is ever also simplified to `boolean`, the same pattern applies.
+
+## Stage: Final Retrospective (2026-05-27T01:48:04Z)
+
+### Session summary
+
+All three stages (planning, TDD, shipping) completed in a single continuous session.
+Six implementation commits landed as `pi-subagents-v9.0.0` (major bump from `feat!:`).
+Issue #238 closed; unblocks #239 (collapse `filterActiveTools`).
+
+### Observations
+
+#### What went well
+
+- The plan’s structure closely followed the successful #237 pattern, making execution predictable.
+- The implementer caught the type-narrowing cascade on the first `pnpm run check` and adapted immediately — no user intervention needed.
+- The `resolveBoolExtensions` helper extraction was a clean design choice that keeps `inheritField` reusable for `skills`.
+- ESLint auto-fix of `=== false` → `!` after the type narrowed to `boolean` was handled smoothly within the same commit.
+
+#### What caused friction (agent side)
+
+- `instruction-violation` (self-identified) — The planner did not apply the testing skill’s existing rule: “When a TDD plan lists separate steps that share a type definition, changing that type in step N breaks steps N+1…N+k.”
+  The plan assigned test-fixture fixes (removing `extensions: string[]` values) to steps 2–4, but the type change in step 1 broke them all immediately.
+  Impact: no rework — the implementer folded fixes into step 1 — but the plan’s step boundaries were misleading.
+- `missing-context` — The plan recommended `debugLog` for the deprecation warning without checking its function signature (`(context: string, err: unknown)`) or its debug-only behavior.
+  Impact: minor — switched to `console.warn` during implementation with no rework, but the plan was wrong.
+
+#### What caused friction (user side)
+
+- Nothing notable — no user corrections were needed across all three stages.
+
+### Changes made
+
+1. `.pi/skills/testing/SKILL.md` — Added type-narrowing-specific TDD planning rule: when a step narrows a union type, grep test files for fixtures using the removed variant and fold those fixes into the same step.

package/docs/retro/0242-rename-agent-tool-to-subagent.md

@@ -0,0 +1,37 @@
+---
+issue: 242
+issue_title: "Rename `Agent` tool to `subagent`"
+---
+
+# Retro: #242 — Rename `Agent` tool to `subagent`
+
+## Stage: Planning (2026-05-27T13:45:29Z)
+
+### Session summary
+
+Produced a plan for renaming the `Agent` tool to `subagent` across pi-subagents source, tests, README, and architecture docs.
+Verified that pi-permission-system docs do not reference the `Agent` tool name and require no changes.
+Scoped the plan to two commits: one `feat!:` for source + tests, one `docs:` for documentation.
+
+### Observations
+
+- The general-purpose agent type's `displayName` (`"Agent"` in `default-agents.ts` and `agent-types.ts` fallback) is a separate concept from the tool name and stays unchanged.
+  Several test files assert this `displayName` — they are not affected by the rename.
+- Issue #239 (Step 3, collapse `filterActiveTools`) is still open but independent — #242 only changes the string value in `EXCLUDED_TOOL_NAMES`, not its structure.
+- The architecture doc already contains `(née \`Agent\`)` in the "What the core owns" section, anticipating the rename.
+- The `widget-renderer.test.ts` comment references `"Agent"` as the general-purpose display name, not the tool name — only the comment text needs updating for clarity.
+
+## Stage: Implementation — TDD (2026-05-27T13:55:33Z)
+
+### Session summary
+
+Completed 2 TDD cycles: one `feat!:` commit renaming the tool in source + tests, one `docs:` commit updating `README.md` and `docs/architecture/architecture.md`.
+Baseline was 977 tests; test count unchanged at 977 after the changes.
+Pre-completion reviewer returned **PASS**.
+
+### Observations
+
+- All changes were pure string-literal replacements in 2 source files, 4 test files, `README.md`, and the architecture doc — no logic, type, or structural changes.
+- The general-purpose agent type's `displayName: "Agent"` in `default-agents.ts` and `agent-types.ts` fallback was correctly left unchanged; `display.test.ts` still passes with `"Agent"`.
+- The description body inside the `agent-tool.ts` template literal needed separate edits because the guideline lines are not tab-indented (inside a backtick template literal, tab indentation does not apply).
+- Pre-completion reviewer: PASS — all deterministic checks, conventional commits, documentation, code design, tests, Mermaid diagrams, and dead-code gate all passed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "9.0.0",
+  "version": "10.0.0",
   "type": "module",
   "exports": {
     ".": "./src/service.ts"

package/src/lifecycle/agent-runner.ts

@@ -19,7 +19,7 @@ import { type AssemblerIO, assembleSessionConfig, type ToolFilterConfig } from "
 import type { ShellExec, SubagentType, ThinkingLevel } from "#src/types";
 
 /** Names of tools registered by this extension that subagents must NOT inherit. */
-const EXCLUDED_TOOL_NAMES = ["Agent", "get_subagent_result", "steer_subagent"];
+const EXCLUDED_TOOL_NAMES = ["subagent", "get_subagent_result", "steer_subagent"];
 
 /**
  * Filter the session's active tool names according to extension rules.

package/src/tools/agent-tool.ts

@@ -156,12 +156,12 @@ export class AgentTool {
 		const registry = this.registry;
 
 		return defineTool({
-			name: "Agent" as const,
-			label: "Agent",
-			promptSnippet: "Agent: Launch a specialized agent for complex, multi-step tasks.",
+			name: "subagent" as const,
+			label: "Subagent",
+			promptSnippet: "subagent: Launch a specialized agent for complex, multi-step tasks.",
 			description: `Launch a new agent to handle complex, multi-step tasks autonomously.
 
-The Agent tool launches specialized agents that autonomously handle complex tasks. Each agent type has specific capabilities and tools available to it.
+The subagent tool launches specialized agents that autonomously handle complex tasks. Each agent type has specific capabilities and tools available to it.
 
 Available agent types:
 ${typeListText}
@@ -172,7 +172,7 @@ Guidelines:
 - Use Plan for architecture and implementation planning.
 - Use general-purpose for complex tasks that need file editing.
 - Provide clear, detailed prompts so the agent can work autonomously.
-- Agent results are returned as text — summarize them for the user.
+- Subagent results are returned as text — summarize them for the user.
 - Use run_in_background for work you don't need immediately. You will be notified when it completes.
 - Use resume with an agent ID to continue a previous agent's work.
 - Use steer_subagent to send mid-run messages to a running background agent.
@@ -244,7 +244,7 @@ Guidelines:
 			renderCall(args: Record<string, unknown>, theme: any) {
 				const displayName = args.subagent_type
 					? getDisplayName(args.subagent_type as string, registry)
-					: "Agent";
+					: "Subagent";
 				const desc = (args.description as string | undefined) ?? "";
 				return new Text(
 					"▸ " +