@gotgenes/pi-subagents 9.0.1 → 10.0.1

package/CHANGELOG.md

@@ -5,6 +5,37 @@ 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.1](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v10.0.0...pi-subagents-v10.0.1) (2026-05-27)
+
+
+### Documentation
+
+* mark Phase 14 Step 3 complete in architecture ([fb374ba](https://github.com/gotgenes/pi-packages/commit/fb374ba5829945a4d2f71d8a611bc5128cdd3bf1))
+* plan collapse filterActiveTools to recursion guard ([#239](https://github.com/gotgenes/pi-packages/issues/239)) ([411b22e](https://github.com/gotgenes/pi-packages/commit/411b22ef8186e5fe73bfa81672edfe473ad9d76a))
+* **retro:** add planning stage notes for issue [#239](https://github.com/gotgenes/pi-packages/issues/239) ([c0383b1](https://github.com/gotgenes/pi-packages/commit/c0383b1d9333b70d61a80b75cd1e6e2724d91ad3))
+* **retro:** add retro notes for issue [#242](https://github.com/gotgenes/pi-packages/issues/242) ([69c8cc2](https://github.com/gotgenes/pi-packages/commit/69c8cc269f6dfd6552aecb6d073ea86bb22267dd))
+* **retro:** add TDD stage notes for issue [#239](https://github.com/gotgenes/pi-packages/issues/239) ([f4098a0](https://github.com/gotgenes/pi-packages/commit/f4098a084564dd75bd683449a2aa3926ae36cba3))
+
+## [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)
 
 

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.
@@ -453,7 +453,7 @@ The target state eliminates this overlap and flips the dependency direction.
 
 ### Responsibilities to remove
 
-- **Tool policy** (`disallowed_tools`, `ToolFilterConfig.disallowedSet`) — access control belongs in pi-permission-system's `permission:` frontmatter.
+- **Tool policy** (`disallowed_tools`) — access control belongs in pi-permission-system's `permission:` frontmatter.
 - **Extension filtering** (`extensions: string[]` allowlist) — tool visibility is pi-permission-system's job.
 - **Permission bridge** (`permission-bridge.ts`) — outbound coupling to pi-permission-system.
   Replaced by lifecycle events that pi-permission-system listens for.
@@ -496,7 +496,7 @@ Bags with 10+ fields are the highest priority for decomposition.
 | `ResolvedSpawnConfig`       | 3 nested                                               | foreground-runner, background-spawner, agent-tool | ✓ done    |
 | `AgentSpawnConfig`          | 13 → 13 (ParentSessionInfo nested)                     | agent-manager (internal)                          | ✓ done    |
 | `RunOptions`                | 9 (`RunContext` nested)                                | agent-runner                                      | ✓ done    |
-| `SessionConfig`             | 8 (ToolFilterConfig nested)                            | agent-runner (output of assembler)                | ✓ done    |
+| `SessionConfig`             | 8 (flat fields, ToolFilterConfig removed)              | agent-runner (output of assembler)                | ✓ done    |
 | `NotificationDetails`       | 10                                                     | notification                                      | Low (DTO) |
 | `ResourceLoaderOptions`     | 10                                                     | agent-runner (SDK bridge)                         | Low (SDK) |
 | `RunnerIO`                  | split → `EnvironmentIO` (3) + `SessionFactoryIO` (5+1) | agent-runner                                      | ✓ done    |
@@ -677,8 +677,9 @@ Removing it simplifies `runAgent`, shrinks `AgentConfig` and `SessionConfig`, an
 | ----------------------------------------------------------------------------------------- | ------------- | ------ | ---- | -------- |
 | `disallowed_tools` duplicates pi-permission-system's `permission:` frontmatter            | A: Overlap    | 4      | 2    | 12       |
 | `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        |
+| `filterActiveTools` ran twice (pre-bind + post-bind) to catch extension-registered tools  | B: Complexity | 3      | 1    | ✓ done   |
+| `ToolFilterConfig` existed solely to carry filtering state through the runner             | C: Accidental | 2      | 1    | ✓ done   |
+| `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
 
@@ -712,22 +713,40 @@ The `extensions: false` case (used by `isolated`) is retained in this step and r
 - Smell: A (tool filtering disguised as extension lifecycle control)
 - Outcome: `filterActiveTools` reduces to two concerns: recursion guard and `extensions: false` passthrough
 
-### Step 3: Collapse `filterActiveTools` to recursion guard — [#239]
+### Step 3: Collapse `filterActiveTools` to recursion guard — [#239] ✅ Complete
 
-With Steps 1–2 complete, `filterActiveTools` has only two remaining branches: the `EXCLUDED_TOOL_NAMES` recursion guard and the `extensions === false` passthrough.
-Inline the `extensions === false` passthrough into the callsite and reduce the function to its essential purpose.
+With Steps 1–2 complete, `filterActiveTools` had only two remaining branches: the `EXCLUDED_TOOL_NAMES` recursion guard and the `extensions === false` passthrough.
+Inlined the `extensions === false` passthrough into the callsite and reduced the function to its essential purpose.
 
-1. Simplify `filterActiveTools` to filter only `EXCLUDED_TOOL_NAMES`.
-2. Remove `ToolFilterConfig` — the function no longer needs a config bag.
-3. Remove the pre-bind filter call — extension tools aren't in the active set yet, so filtering built-in tools pre-bind is only needed for denylist/allowlist logic that no longer exists.
-4. Keep a single post-bind filter call for the recursion guard.
-5. Simplify `SessionConfig` — remove the `toolFilter` field, keep `toolNames` as a flat field.
-6. Update tests.
+1. Simplified `filterActiveTools` to filter only `EXCLUDED_TOOL_NAMES`.
+2. Removed `ToolFilterConfig` — the function no longer needs a config bag.
+3. Removed the pre-bind filter call — extension tools aren't in the active set pre-bind, so the guard is a no-op there.
+4. Kept a single post-bind filter call for the recursion guard.
+5. Flattened `SessionConfig` — removed `toolFilter: ToolFilterConfig`; `toolNames` and `extensions` are top-level fields.
+6. Updated tests.
 
 - Target: `agent-runner.ts`, `session-config.ts`
 - 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/0239-collapse-filter-active-tools.md

@@ -0,0 +1,217 @@
+---
+issue: 239
+issue_title: "Collapse filterActiveTools to recursion guard (Phase 14, Step 3)"
+---
+
+# Collapse `filterActiveTools` to recursion guard
+
+## Problem Statement
+
+With `disallowed_tools` (#237) and `extensions` filtering (#238) removed, `filterActiveTools` retains two branches that no longer justify a config bag or two-pass pre-bind/post-bind dance:
+
+1. The `extensions === false` early return — a passthrough that belongs at the callsite.
+2. The `EXCLUDED_TOOL_NAMES` recursion guard — the function's sole essential purpose.
+
+The `builtinToolNameSet` membership check always returns `true` now (no string-array `extensions` filtering remains), making it dead logic.
+`ToolFilterConfig` exists only to carry two fields (`toolNames`, `extensions`) through the assembler→runner boundary, but after this change they travel independently: `toolNames` feeds `createSession`, `extensions` feeds the resource loader's `noExtensions` flag, and neither is consumed by the filter function.
+
+## Goals
+
+- Reduce `filterActiveTools` to a one-liner: filter out `EXCLUDED_TOOL_NAMES`.
+- Delete the `ToolFilterConfig` interface.
+- Flatten `SessionConfig.toolFilter` back into two top-level fields: `toolNames` and `extensions`.
+- Remove the pre-bind filter call — without denylist/allowlist logic, filtering before `bindExtensions` serves no purpose.
+- Keep a single post-bind filter call for the recursion guard.
+- Update tests to reflect the simplified flow.
+
+## Non-Goals
+
+- Removing `extensions` from `SessionConfig` entirely — it's still needed for the `noExtensions` flag on the resource loader.
+- Renaming `EXCLUDED_TOOL_NAMES` or moving it to a separate module.
+- Phase 15 domain model changes (#227–#232) — those operate on the simplified codebase this change produces.
+
+## Background
+
+`filterActiveTools` was extracted as part of Phase 10 (#168) to group `toolNames`, `disallowedSet`, and `extensions` into a `ToolFilterConfig` bag.
+Issue #237 removed `disallowedSet`; #238 narrowed `extensions` from `true | string[] | false` to `boolean`.
+Both are now closed.
+
+The two-pass filter dance (Patch 2, RepOne #443) exists to catch extension-registered tools that join the active set during `bindExtensions`.
+With the only remaining filter logic being the `EXCLUDED_TOOL_NAMES` guard, a single post-bind pass suffices.
+
+Current `filterActiveTools` body:
+
+```typescript
+function filterActiveTools(
+  activeTools: string[],
+  config: ToolFilterConfig,
+): string[] {
+  const { toolNames, extensions } = config;
+  if (!extensions) {
+    return activeTools;
+  }
+  const builtinToolNameSet = new Set(toolNames);
+  return activeTools.filter((t) => {
+    if (EXCLUDED_TOOL_NAMES.includes(t)) return false;
+    if (builtinToolNameSet.has(t)) return true;
+    return true;
+  });
+}
+```
+
+The `builtinToolNameSet` check is dead — both branches return `true`.
+The `!extensions` early return belongs at the callsite.
+
+### Affected files
+
+- `src/lifecycle/agent-runner.ts` — `filterActiveTools`, pre-bind/post-bind calls, `ToolFilterConfig` import
+- `src/session/session-config.ts` — `ToolFilterConfig` interface, `SessionConfig.toolFilter` field, assembler return literal
+- `test/lifecycle/agent-runner-extension-tools.test.ts` — pre-bind/post-bind assertions
+- `test/session/session-config.test.ts` — `toolFilter.*` assertions
+- `test/lifecycle/agent-runner.test.ts` — session mock (`setActiveToolsByName` calls)
+- `docs/architecture/architecture.md` — references to `ToolFilterConfig`, `filterActiveTools`, Phase 14 status
+
+## Design Overview
+
+### `filterActiveTools` simplification
+
+The function reduces to:
+
+```typescript
+function filterActiveTools(activeTools: string[]): string[] {
+  return activeTools.filter((t) => !EXCLUDED_TOOL_NAMES.includes(t));
+}
+```
+
+No config parameter.
+The `extensions === false` guard moves to the callsite: `if (cfg.extensions)`.
+
+### `SessionConfig` flattening
+
+```typescript
+export interface SessionConfig {
+  effectiveCwd: string;
+  systemPrompt: string;
+  toolNames: string[];       // was toolFilter.toolNames
+  extensions: boolean;        // was toolFilter.extensions
+  model: unknown;
+  thinkingLevel: ThinkingLevel | undefined;
+  noSkills: boolean;
+  extras: PromptExtras;
+  agentMaxTurns: number | undefined;
+}
+```
+
+### `runAgent` callsite changes
+
+Before (two-pass):
+
+```typescript
+if (cfg.toolFilter.extensions) {
+  const filtered = filterActiveTools(session.getActiveToolNames(), cfg.toolFilter);
+  session.setActiveToolsByName(filtered);
+}
+// ... bindExtensions ...
+if (cfg.toolFilter.extensions) {
+  const refiltered = filterActiveTools(session.getActiveToolNames(), cfg.toolFilter);
+  session.setActiveToolsByName(refiltered);
+}
+```
+
+After (single post-bind pass):
+
+```typescript
+// ... bindExtensions ...
+if (cfg.extensions) {
+  const filtered = filterActiveTools(session.getActiveToolNames());
+  session.setActiveToolsByName(filtered);
+}
+```
+
+Other `cfg.toolFilter.*` references update to `cfg.toolNames` and `cfg.extensions`.
+
+## Module-Level Changes
+
+### `src/session/session-config.ts`
+
+1. Delete the `ToolFilterConfig` interface.
+2. Replace `toolFilter: ToolFilterConfig` on `SessionConfig` with two flat fields: `toolNames: string[]` and `extensions: boolean`.
+3. Update the return literal in `assembleSessionConfig` from `toolFilter: { toolNames, extensions }` to `toolNames, extensions`.
+4. Update the JSDoc on `SessionConfig` — remove "Tool filtering cluster" comment.
+
+### `src/lifecycle/agent-runner.ts`
+
+1. Remove the `ToolFilterConfig` import.
+2. Simplify `filterActiveTools` to `(activeTools: string[]) => string[]` — just the `EXCLUDED_TOOL_NAMES` filter.
+3. Remove the pre-bind filter block (the first `if (cfg.toolFilter.extensions)` block).
+4. Update the post-bind filter block: `cfg.toolFilter.extensions` → `cfg.extensions`, remove the config argument from the `filterActiveTools` call.
+5. Update `noExtensions: !cfg.toolFilter.extensions` → `noExtensions: !cfg.extensions`.
+6. Update `tools: cfg.toolFilter.toolNames` → `tools: cfg.toolNames`.
+7. Update or remove the Patch 2 comments — the two-pass dance is gone; the remaining call is just a recursion guard.
+
+### `test/lifecycle/agent-runner-extension-tools.test.ts`
+
+1. Remove the pre-bind/post-bind ordering assertions — there is only one post-bind call now.
+2. Update `setActiveToolsByName` call count expectations from 2 to 1.
+3. Update assertions to check `setActiveToolsByName.mock.calls[0][0]` (was `calls[1][0]` for the second call).
+4. The `extensions: false` test continues to assert that `setActiveToolsByName` is not called.
+
+### `test/session/session-config.test.ts`
+
+1. Update `result.toolFilter.toolNames` → `result.toolNames`.
+2. Update `result.toolFilter.extensions` → `result.extensions`.
+
+### `test/lifecycle/agent-runner.test.ts`
+
+1. No structural changes needed — the session mock already has `setActiveToolsByName: vi.fn()`, and the default test config has `extensions: false` (so the filter doesn't run).
+   If any test asserts on `setActiveToolsByName` call counts, verify they still pass.
+
+### `docs/architecture/architecture.md`
+
+1. Update the Phase 14 Step 3 entry to mark it complete.
+2. Update the structural analysis table: `SessionConfig` field count changes, `ToolFilterConfig` is removed.
+3. Update the smell table to mark the two-pass filter and `ToolFilterConfig` smells as resolved.
+
+## Test Impact Analysis
+
+1. **New tests enabled:** None — the simplification doesn't introduce new testable surface.
+2. **Tests that become redundant:** The pre-bind/post-bind ordering test in `agent-runner-extension-tools.test.ts` — the pre-bind call is removed.
+   The test that the post-bind filter includes extension tools stays; it verifies the recursion guard runs after `bindExtensions`.
+3. **Tests that stay as-is:** The `extensions: false` skip test, the `EXCLUDED_TOOL_NAMES` exclusion test, all `session-config.test.ts` tests (with property path updates).
+
+## TDD Order
+
+1. **Flatten `SessionConfig` and delete `ToolFilterConfig`** — Replace `toolFilter: ToolFilterConfig` with `toolNames: string[]` and `extensions: boolean` on `SessionConfig`.
+   Delete the `ToolFilterConfig` interface.
+   Update the assembler return literal.
+   Update `session-config.test.ts` property paths (`result.toolFilter.toolNames` → `result.toolNames`, `result.toolFilter.extensions` → `result.extensions`).
+   Run `pnpm run check` to verify downstream compile errors (expected in `agent-runner.ts`).
+   Commit: `refactor: flatten SessionConfig and remove ToolFilterConfig`
+
+2. **Simplify `filterActiveTools` and remove pre-bind call** — Reduce `filterActiveTools` to `(activeTools: string[]) => string[]`.
+   Remove the `ToolFilterConfig` import.
+   Remove the pre-bind filter block.
+   Update the post-bind filter block to use `cfg.extensions` and pass no config to `filterActiveTools`.
+   Update `noExtensions` and `tools` references to `cfg.extensions` and `cfg.toolNames`.
+   Update `agent-runner-extension-tools.test.ts`: change `setActiveToolsByName` call count from 2 to 1, update assertion indices from `calls[1]` to `calls[0]`, remove the pre-bind/post-bind ordering test, update comments.
+   Verify `agent-runner.test.ts` still passes.
+   Commit: `refactor: simplify filterActiveTools to recursion guard`
+
+3. **Update architecture docs** — Mark Phase 14 Step 3 as complete.
+   Update `SessionConfig` field count and remove `ToolFilterConfig` references from the structural analysis.
+   Mark the two-pass filter and `ToolFilterConfig` smells as resolved.
+   Commit: `docs: mark Phase 14 Step 3 complete in architecture`
+
+## Risks and Mitigations
+
+1. **Pre-bind filter removal may miss a recursion-guard edge case** — If a subagent's own tools (`subagent`, `get_subagent_result`, `steer_subagent`) were in the built-in tool set before `bindExtensions`, removing the pre-bind filter could leave them active during the bind phase.
+   Mitigation: These tools are registered by this extension during `bindExtensions`, not before.
+   They cannot be in the pre-bind active set.
+   The post-bind filter is sufficient.
+
+2. **Flattening `SessionConfig` may break external consumers** — `SessionConfig` is not exported from the package entry point; it's an internal interface between `session-config.ts` and `agent-runner.ts`.
+   No external consumers exist.
+
+## Open Questions
+
+None — the issue's changes are unambiguous and all dependencies are complete.

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/0239-collapse-filter-active-tools.md

@@ -0,0 +1,37 @@
+---
+issue: 239
+issue_title: "Collapse filterActiveTools to recursion guard (Phase 14, Step 3)"
+---
+
+# Retro: #239 — Collapse filterActiveTools to recursion guard
+
+## Stage: Planning (2026-05-27T20:00:00Z)
+
+### Session summary
+
+Produced a 3-step TDD plan to flatten `SessionConfig.toolFilter` into top-level `toolNames` and `extensions` fields, simplify `filterActiveTools` to a one-liner recursion guard, remove the pre-bind filter call, and update architecture docs.
+Both dependencies (#237, #238) are confirmed closed.
+
+### Observations
+
+- The `builtinToolNameSet` membership check in `filterActiveTools` is fully dead code — both branches return `true` after #238 removed the `string[]` extensions path.
+- `ToolFilterConfig` is only imported by `agent-runner.ts` and never referenced in test files, so deletion is clean.
+- The pre-bind filter call is safe to remove because `EXCLUDED_TOOL_NAMES` tools (`subagent`, `get_subagent_result`, `steer_subagent`) are registered by this extension during `bindExtensions`, not before — they cannot appear in the pre-bind active set.
+- The `agent-runner-extension-tools.test.ts` file has 4 tests; 1 becomes structurally impossible (pre-bind/post-bind ordering) and the remaining 3 need assertion index adjustments (`calls[1]` → `calls[0]`).
+- `SessionConfig` is internal-only (not package-exported), so flattening has no external API impact.
+
+## Stage: Implementation — TDD (2026-05-27T22:00:00Z)
+
+### Session summary
+
+Completed all 3 TDD cycles: (1) flattened `SessionConfig` and deleted `ToolFilterConfig`, (2) simplified `filterActiveTools` to a one-liner and removed the pre-bind filter call, (3) updated architecture docs to mark Phase 14 Step 3 complete.
+Test count held at 977 (no net change — the extension-tools test file was rewritten, removing 1 test and updating 3 others while keeping the same total count).
+A follow-up skill maintenance commit updated `.pi/skills/package-pi-subagents/SKILL.md` to remove stale Patch 2 references.
+
+### Observations
+
+- The plan's step order (SessionConfig first → expected compile errors in `agent-runner.ts` → green after runner update) worked exactly as designed with no surprises.
+- `agent-runner.test.ts` needed no changes — the default test config has `extensions: false`, so the filter call never ran in those tests.
+- Pre-completion reviewer returned **WARN** for stale `package-pi-subagents` skill content: the "Patch 2 scheduled for removal" note and the `// Patch 2 (RepOne` grep instruction were both stale after #239 completion.
+  Fixed immediately as a follow-up `docs:` commit before writing retro notes.
+- `pnpm fallow dead-code` passed with 0 issues — no orphaned exports left behind.

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

@@ -0,0 +1,82 @@
+---
+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.
+
+## Stage: Final Retrospective (2026-05-27T14:07:32Z)
+
+### Session summary
+
+Completed the full plan→TDD→ship→retro lifecycle for #242 in a single session.
+Released as `pi-subagents-v10.0.0` (major bump from `feat!:` breaking change).
+Found and fixed one stale `Agent` tool reference in `.pi/skills/pre-completion/SKILL.md`.
+
+### Observations
+
+#### What went well
+
+- Three-model pipeline (opus for planning, sonnet for TDD, deepseek-flash for shipping) matched task complexity to model capability with no quality issues.
+- The plan's distinction between tool name (`"Agent"`) and agent-type `displayName` (`"Agent"`) prevented false-positive test updates — 8 test files reference `"Agent"` but only 4 needed changes.
+- Pre-completion reviewer caught no issues (PASS), confirming thorough planning.
+
+#### What caused friction (agent side)
+
+1. `missing-context` — Two failed `Edit` calls on `agent-tool.ts` line 175: the template literal's guideline lines have no tab indentation, but the agent initially assumed tab depth from the surrounding function.
+   Impact: 3 extra tool calls (grep to inspect actual indentation, then successful edit); no rework.
+   Self-identified.
+2. `wrong-abstraction` — Retro file edit duplicated Planning observations into the TDD stage because the `Edit` `oldText` matched from the Observations heading and the replacement included both old and new content.
+   Impact: 2 extra tool calls (read file, full `write` to fix); no rework.
+   Self-identified.
+3. `missing-context` — `.pi/skills/pre-completion/SKILL.md` line 32 references the `Agent` tool by name but was not in the plan's scope.
+   The plan checked pi-permission-system docs, `README.md`, and architecture docs but did not grep skill files for the old tool name.
+   Impact: discovered during retro; fixed as a retro change.
+
+#### What caused friction (user side)
+
+- None — the full pipeline ran with zero user corrections.
+
+### Diagnostic details
+
+- **Model-performance correlation** — Pre-completion reviewer ran as a default-model subagent (292.7s, 36 tool uses, 63.9k tokens).
+  Appropriate for the judgment-heavy review task.
+  Ship stage on `deepseek-v4-flash` was notably efficient for purely mechanical work.
+- **Feedback-loop gap analysis** — Verification was incremental: baseline check before TDD, per-file tests after Red and Green phases, full suite after implementation, then check + lint + fallow.
+  No gaps.
+
+### Changes made
+
+1. `.pi/skills/pre-completion/SKILL.md` — updated stale `Agent` tool reference to `subagent` on line 32.
+2. `.pi/agents/pre-completion-reviewer.md` — added rename-grep heuristic to the Skills bullet under Forward documentation checks: "When the change renames a symbol, grep `.pi/skills/` and `.pi/prompts/` for the old name."

package/package.json

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

package/src/lifecycle/agent-runner.ts

@@ -15,37 +15,22 @@ import { registerChildSession, unregisterChildSession } from "#src/lifecycle/per
 import { extractAssistantContent } from "#src/session/content-items";
 import { extractText } from "#src/session/context";
 import type { EnvInfo } from "#src/session/env";
-import { type AssemblerIO, assembleSessionConfig, type ToolFilterConfig } from "#src/session/session-config";
+import { type AssemblerIO, assembleSessionConfig } from "#src/session/session-config";
 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.
+ * Filter the session's active tool names: remove recursion-guard tools.
  *
- * Run twice - once before `bindExtensions` (filters built-in tools) and once after
- * (filters extension-registered tools, which only join the active set during
- * `bindExtensions`). Extracting this keeps the two callsites consistent and makes
- * the post-bind re-filter trivial.
+ * Run once after `bindExtensions` so extension-registered tools (added during
+ * `bindExtensions`) are also covered by the guard.
  *
  * @param activeTools  Names currently active on the session.
- * @param config       Tool filtering configuration from the assembled session config.
  */
-function filterActiveTools(
-  activeTools: string[],
-  config: ToolFilterConfig,
-): string[] {
-  const { toolNames, extensions } = config;
-  if (!extensions) {
-    return activeTools;
-  }
-  const builtinToolNameSet = new Set(toolNames);
-  return activeTools.filter((t) => {
-    if (EXCLUDED_TOOL_NAMES.includes(t)) return false;
-    if (builtinToolNameSet.has(t)) return true;
-    return true;
-  });
+function filterActiveTools(activeTools: string[]): string[] {
+  return activeTools.filter((t) => !EXCLUDED_TOOL_NAMES.includes(t));
 }
 
 /** Normalize max turns. undefined or 0 = unlimited, otherwise minimum 1. */
@@ -305,7 +290,7 @@ export async function runAgent(
   const loader = io.createResourceLoader({
     cwd: cfg.effectiveCwd,
     agentDir,
-    noExtensions: !cfg.toolFilter.extensions,
+    noExtensions: !cfg.extensions,
     noSkills: cfg.noSkills,
     noPromptTemplates: true,
     noThemes: true,
@@ -329,18 +314,11 @@ export async function runAgent(
     settingsManager: io.createSettingsManager(cfg.effectiveCwd, agentDir),
     modelRegistry: snapshot.modelRegistry,
     model: cfg.model,
-    tools: cfg.toolFilter.toolNames,
+    tools: cfg.toolNames,
     resourceLoader: loader,
     thinkingLevel: cfg.thinkingLevel,
   });
 
-  // Filter active tools: remove our own tools to prevent nesting.
-  // First pass - over built-in tools, before bindExtensions registers extension tools.
-  if (cfg.toolFilter.extensions) {
-    const filtered = filterActiveTools(session.getActiveToolNames(), cfg.toolFilter);
-    session.setActiveToolsByName(filtered);
-  }
-
   // Register with pi-permission-system's SubagentSessionRegistry before
   // bindExtensions() so isSubagentExecutionContext() hits the registry on the
   // first check during child extension initialization. Unregistered in the
@@ -356,14 +334,13 @@ export async function runAgent(
   // respect the active tool set. All ExtensionBindings fields are optional.
   await session.bindExtensions({});
 
-  // Patch 2 (RepOne #443): re-filter active tools after bindExtensions.
-  // Extension-registered tools (added during bindExtensions) are not in the
-  // session's active set when the first filter pass runs above. Without this
-  // re-filter, EXCLUDED_TOOL_NAMES would not be applied to extension-registered
-  // tools. Run the same filter against the post-bind active set.
-  if (cfg.toolFilter.extensions) {
-    const refiltered = filterActiveTools(session.getActiveToolNames(), cfg.toolFilter);
-    session.setActiveToolsByName(refiltered);
+  // Apply recursion guard: remove our own tools from the child's active set.
+  // Runs after bindExtensions so extension-registered tools are included in the
+  // post-bind active set. Only needed when extensions are loaded (extensions: false
+  // means no extension tools were registered, so the guard is a no-op).
+  if (cfg.extensions) {
+    const filtered = filterActiveTools(session.getActiveToolNames());
+    session.setActiveToolsByName(filtered);
   }
 
   options.onSessionCreated?.(session);

package/src/session/session-config.ts

@@ -18,19 +18,6 @@ import type { AgentPromptConfig, SubagentType, ThinkingLevel } from "#src/types"
 
 // ── Public interfaces ────────────────────────────────────────────────────────
 
-/**
- * Tool filtering configuration — consumed by `filterActiveTools` in `agent-runner.ts`.
- *
- * Groups the two fields that travel together through the assembly→runner boundary:
- * the built-in tool allowlist and the extensions setting.
- */
-export interface ToolFilterConfig {
-  /** Built-in tool name allowlist for this agent type. */
-  toolNames: string[];
-  /** Resolved extensions setting: true = inherit all, false = none. */
-  extensions: boolean;
-}
-
 /**
  * IO collaborators injected into `assembleSessionConfig`.
  *
@@ -98,8 +85,10 @@ export interface SessionConfig {
   effectiveCwd: string;
   /** Fully-assembled system prompt string (ready for `systemPromptOverride`). */
   systemPrompt: string;
-  /** Tool filtering cluster — tool allowlist, denylist, and extensions setting. */
-  toolFilter: ToolFilterConfig;
+  /** Built-in tool name allowlist for this agent type. */
+  toolNames: string[];
+  /** Resolved extensions setting: true = inherit all, false = none. */
+  extensions: boolean;
   /**
    * Resolved model instance (undefined → use parent model as passed to SDK).
    * Opaque handle — the assembler passes it through without inspection.
@@ -222,7 +211,8 @@ export function assembleSessionConfig(
   return {
     effectiveCwd,
     systemPrompt,
-    toolFilter: { toolNames, extensions },
+    toolNames,
+    extensions,
     model,
     thinkingLevel,
     noSkills,

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(
 					"▸ " +