pi-subagents-lite 1.3.0 → 1.4.1

package/README.md

@@ -5,11 +5,11 @@
 
 **Sub-agents for [pi](https://pi.dev) — schema-first, zero-fluff.**
 
-Spawn specialized agents with isolated sessions, custom tools, and per-type models — all at minimal token cost.
+Spawn specialized agents with isolated sessions, custom tools, and per-type models at minimal token cost.
 
 ## Schema-First Design
 
-Every tool the LLM sees costs tokens — in the system prompt, and in every turn's context. Most extensions add description text, prompt snippets, and usage guidelines that compound across the session. This extension takes a **schema-first** approach: the tool name and parameter names **are** the schema. No bloated descriptions, no prose.
+Every tool the LLM sees costs tokens — in the system prompt and in every turn. Most extensions layer on descriptions, prompt snippets, and usage guidelines that compound across the session. This extension takes a **schema-first** approach: the tool name and parameter names *are* the schema. No bloated descriptions, no prose.
 
 | Standard | Schema-first |
 |---|---|
@@ -18,100 +18,113 @@ Every tool the LLM sees costs tokens — in the system prompt, and in every turn
 | `promptGuidelines` with rules | _(none)_ |
 | Parameters with `.description()` | Bare `Type.String()` |
 
-Tool names like `Agent`, `StopAgent`, and `AgentStatus`, and parameter names like `prompt`, `description`, `run_in_background` are self-documenting. The LLM infers usage from the schema — no verbose descriptions needed. Tool results reinforce correct usage with clear success/error messages.
+Names like `Agent`, `StopAgent`, `AgentStatus`, `run_in_background`, `worktree_path` are self-documenting. Results reinforce correct usage with clear success/error messages.
 
-**Result:** foreground and background agents, custom agent types, per-model concurrency, cost tracking, steering, model overrides, agent status — all with minimal token overhead.
+**Result:** foreground and background agents, custom agent types, per-model concurrency, cost tracking, steering, model overrides, and agent status — all with minimal token overhead.
 
 ## Features
 
-- **Three tools** — `Agent` (spawn), `StopAgent` (stop), and `AgentStatus` (list agents)
-- **Manual spawn** — spawn agents from the `/agents` menu without asking the LLM. Full control over model, thinking, turns, and background mode.
-- **Foreground & background** — block or fire-and-forget with auto-delivered results
-- **Custom agent types** — define via `.md` files with YAML frontmatter (tools, model, thinking, turn limits)
-- **Smart model resolution** — 6-level precedence: session → config → frontmatter → parent. Set once, forget
-- **Concurrency control** — per-model and per-provider slot limits with automatic queuing
-- **Cost tracking** — input/output/cache tokens and dollar cost per agent
-- **Cost display** — toggle agent cost in stats and status bar (OFF by default)
-- **Live widget** — persistent status bar above the editor showing running/completed agents
-- **Widget settings** — force compact mode, max lines, opt-in ctrl+o sync
-- **Result viewer** — fullscreen markdown viewer with stats
-- **Steer** — inject mid-execution guidance into running agents
-- **Output logs** — human-readable, `tail -f` friendly
-- **Grace turns** — configurable grace turns after `max_turns` before hard abort
-- **Reload safety** — warns when active agents are killed by session reload
-- **Worktree support** — `worktree_path` parameter runs agents in a git worktree with validated path, worktree agent discovery, and UI label
+- **Three tools** — `Agent` (spawn), `StopAgent` (stop), `AgentStatus` (list)
+- **Foreground & background** — block, or fire-and-forget with auto-delivered results
+- **Custom agent types** — `.md` files with YAML frontmatter (tools, model, thinking, turn/token limits)
+- **Manual spawn** — from `/agents`, no LLM round-trip; full control over model, thinking, turns, tokens, background
+- **Model resolution** — 6-level precedence chain; set once, forget
+- **Concurrency** — per-model and per-provider slot limits with automatic queuing
+- **Steering** — inject mid-execution guidance into running agents
+- **Cost & usage tracking** — input/output/cache tokens and dollar cost per agent (toggle in stats)
+- **Live widget** — persistent status bar with running/completed agents, full and compact modes
+- **Result viewer** — fullscreen markdown with stats
+- **Worktrees** — run agents in a git worktree via `worktree_path`
+- **Output logs** — `tail -f` friendly, ISO-timestamped
 
 ## Install
 
 ```bash
 pi install npm:pi-subagents-lite
-pi install -l npm:pi-subagents-lite        # project-local
-pi -e npm:pi-subagents-lite                # try without installing
+pi install -l npm:pi-subagents-lite   # project-local
+pi -e npm:pi-subagents-lite           # try without installing
 ```
 
 ## Quick Start
 
-The LLM calls the `Agent` tool like any other tool. A foreground agent returns its result inline with stats; a background agent acknowledges immediately and auto-delivers the result when done.
+The LLM calls `Agent` like any other tool. Foreground agents return inline with stats; background agents acknowledge immediately and auto-deliver on completion.
 
-```
- ⠹ Working...
+Running agents appear in the live widget:
 
+```
 ● Agents
-├─ ⠙ Agent  Write model precedence unit tests  6🛠 ·3⟳ ·8.1k(6%)·12s
+├─ ⠙ Agent  Write model precedence unit tests  6🛠 ·3⟳ ·↑6.8k↓1.3k 6%·12s
 │  │ tail -f /tmp/pi-agent-outputs/bb3382a9-1f7e-474.log
 │  └ The file already exists but is ~175 lines. The user wants a …
-├─ ⠙ Agent  Code review of agent-runner.ts  4🛠 ·2⟳ ·8.7k(4%)·12s
-│  │ tail -f /tmp/pi-agent-outputs/23689696-3cd3-400.log
+├─ ⠙ Agent  Code review of agent-runner.ts  4🛠 ·2⟳ ·↑7.2k↓1.5k 4%·12s
 │  └ Now let me check the types and related files for context on …
-└─ ⠙ Explore  Explore codebase architecture  13🛠 ·4⟳ ·19.0k(15%)·12s
-   │ tail -f /tmp/pi-agent-outputs/4f6b0f08-7a9a-419.log
+└─ ⠙ Explore  Explore codebase architecture  13🛠 ·4⟳ ·↑16.1k↓2.9k 15%·12s
    └ ## Architecture Summary: pi-subagents-lite
 ```
-Then you are notified like this for async (background) invocation:
+
+Background agents deliver a result notification when done:
 
 ```
  Subagent Result
 
- ✓ Explore (model-name)·13🛠 ·5⟳ ·30.8k(15%)·21s
+ ✓ Explore (model-name)·13🛠 ·5⟳ ·↑25.9k↓4.9k 15%·21s
    Explore codebase architecture
    tail -f /tmp/pi-agent-outputs/4f6b0f08-7a9a-419.log
 ```
 
-or inline:
+Foreground results land inline:
 
 ```
  ▸ Explore
- ✓ 31🛠 ·6⟳ ·57.3k(28%)·39s
+ ✓ 31🛠 ·6⟳ ·↑48.1k↓9.2k 28%·39s
    Explore project directory structure
 ```
 
-Stop a running agent at any time via /agents command
+Stop a running agent from `/agents`:
 
 ```
 ○ Agents
-└─ ■ Agent  Code review of agent-runner.ts  12🛠 ·10⟳ ·39.0k(8%)·52s stopped
-     tail -f /tmp/pi-agent-outputs/23689696-3cd3-400.log
+└─ ■ Agent  Code review of agent-runner.ts  12🛠 ·10⟳ ·↑32.8k↓6.2k 8%·52s stopped
+    tail -f /tmp/pi-agent-outputs/23689696-3cd3-400.log
 ```
 
-### Agent Tool Parameters
+## Tools
+
+### `Agent`
+
+Spawn a sub-agent.
 
 | Parameter | Required | Description |
 |---|---|---|
 | `prompt` | ✅ | The task for the sub-agent |
-| `description` | | Brief description for the LLM caller (optional — if omitted, derived from prompt) |
-| `agent` | | Type name — `general-purpose`, `Explore`, or any custom type you define (see [Custom Agent Types](#custom-agent-types)). The available values are **auto-populated** from `.md` files in your agent directories — drop a file, it appears in the enum. Set `hidden: true` in frontmatter to hide a type from this list (still callable by name). |
+| `description` | | Brief description for the caller (optional — derived from `prompt` if omitted) |
+| `agent` | | Type name — `general-purpose`, `Explore`, or any custom type. **Auto-populated** from `.md` files in your agent directories; drop a file, it appears in the enum. `hidden: true` hides a type from the list (still callable by name). |
 | `run_in_background` | | Fire-and-forget; result delivered automatically when done |
-| `worktree_path` | | Absolute path to a git worktree. Agent runs in that worktree's context, discovers agents from its `.pi/agents/` directory, and displays a worktree label in the widget and menus. Path is validated against the parent repo's git common dir. |
+| `worktree_path` | | Absolute path to a git worktree. Agent runs in that worktree's context, discovers agents from its `.pi/agents/`, and shows a worktree label in the UI. Validated against the parent repo's git common dir. |
 
-> `model`, `max_turns`, and `thinking` are **not visible to the LLM** through tool introspection — the extension injects them at call time from agent config and frontmatter. `model` is resolved via the [Model Resolution](#model-resolution) chain; `max_turns`/`thinking` come from the agent's config. See [Custom Agent Types](#custom-agent-types) to set them.
+> `model`, `max_turns`, `max_tokens`, and `thinking` are **not visible to the LLM** — injected at call time from agent config and frontmatter. See [Custom Agent Types](#custom-agent-types).
 
-## Custom Agent Types
+### `StopAgent`
+
+Stop a running agent by ID.
+
+| Parameter | Required | Description |
+|---|---|---|
+| `agent_id` | ✅ | The agent ID returned by `Agent` at spawn |
 
-Drop a `.md` file into `.pi/agents/` (project) or `~/.pi/agent/agents/` (global). The frontmatter configures the agent; the body is its system prompt.
+IDs come from the `Agent` result, the `StopAgent` error (lists all running IDs), or `/agents` → **Running agents**.
 
-The file's `name` frontmatter field (or the filename without extension) becomes the agent type name and **automatically populates the `agent` parameter's enum** in the tool schema. No registration step needed — the extension scans these directories at session start and makes every discovered agent available to the LLM. Files added during a session are discovered on the next call that references them — no restart required.
+### `AgentStatus`
 
-Built-in types (`general-purpose`, `Explore`) are always available. User agents override built-ins with the same name; project agents override user agents (see [Merge precedence](#merge-precedence)).
+List all agents with type, short ID, and status. Output: `type·short_id·status, ...` (e.g. `general-purpose·a1b2c3·running, Explore·d4e5f6·completed`).
+
+The result nudges the LLM to wait for automatic notifications instead of polling — preventing wasteful repeated calls while still letting it discover agents when needed.
+
+## Custom Agent Types
+
+Drop a `.md` file into `.pi/agents/` (project) or `~/.pi/agent/agents/` (global). Frontmatter configures the agent; the body is its system prompt. The `name` field (or filename) becomes the agent type and **auto-populates the `agent` parameter's enum** — no registration. Files added mid-session are picked up on the next call that references them.
+
+Built-ins `general-purpose` and `Explore` are always available. **Project agents override user agents, which override built-ins.**
 
 ```markdown
 ---
@@ -121,165 +134,108 @@ description: Review code for security issues
 tools: [read, bash, grep]
 extensions: false
 skills: false
-model: anthropic/claude-sonnet-4-5-20250514
+model: zai/glm-5.2
 thinking: high
-max_turns: 10
+max_turns: 80
 ---
 
 You are a security review specialist. Analyze code for vulnerabilities,
 focusing on injection flaws, auth bypasses, and insecure defaults.
 ```
 
-**Minimal agent — just name and description:**
+A minimal agent — just `name` and `description` — gets everything: all tools, extensions, and skills, same as `general-purpose`. Set restrictions only when you want them.
 
-```markdown
----
-name: my-agent
-description: Does something
----
-
-System prompt here.
-```
-
-This agent gets everything: all tools, all extensions, all skills. Same as `general-purpose`. No boilerplate needed — set restrictions only when you want them.
-
-**Frontmatter reference:**
+### Frontmatter reference
 
 | Field | Type | Default | Description |
 |---|---|---|---|
-| `name` | string | filename | Agent type name. Used as the enum value in the `agent` parameter. Must be unique across all agent types. |
-| `display_name` | string | `name` | Human-readable label shown in the UI widget, `/agents` menu, and result viewer. |
-| `description` | string | `""` | Short description displayed in the `/agents` type list and tool rendering. Keep it one sentence. |
-| `tools` | `true` \| `string[]` \| `false` | `true` | **Tool whitelist.** Controls which tool schemas the LLM sees. Accepts built-in names and extension tool references (see below). `true` = all tools visible; `false` = no tools; `string[]` = only listed tools visible. Mutually exclusive with `exclude_tools`. |
-| `exclude_tools` | `string[]` | none | **Tool blacklist.** All tools except these are visible. Mutually exclusive with `tools` (when `tools` is `string[]`). |
-| `extensions` | `true` \| `string[]` \| `false` | `true` | **Extension loader.** Controls which extensions load (hooks + commands fire). Does NOT control tool visibility. `true` = load all; `false` = load none; `string[]` = load only listed extensions. Mutually exclusive with `exclude_extensions`. |
-| `exclude_extensions` | `string[]` | none | **Extension blacklist.** All extensions except these load. Mutually exclusive with `extensions` (when `extensions` is `string[]`). |
-| `skills` | `true` \| `string[]` \| `false` | `true` | **Skill whitelist.** Controls which skills are available (metadata injected into system prompt). `true` = all skills; `false` = no skills; `string[]` = only listed skills. |
-| `preload_skills` | `string[]` \| `false` | `false` | **Full skill injection.** Dumps complete SKILL.md content into system prompt instead of metadata-only. `string[]` = list of skills to preload; `false` = none. |
-| `model` | string | inherit parent | Default model as `"provider/model-id"`. Override via `/agents` or `subagents-lite.json`. See [Model Resolution](#model-resolution). |
-| `thinking` | string | inherit parent | Default thinking level. One of: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`. |
-| `max_turns` | number | unlimited | Soft turn limit. Agent gets a steer message at the limit, then `max_turns + 5` grace turns before hard abort. |
-| `hidden` | `true` \| `false` | `false` | `true` hides the agent type from the tool schema's enum (LLM can't see or invoke it). Agent is still callable by name. Running agents unaffected. |
-
-#### `tools` field values
-
-The `tools` field accepts built-in tool names and extension tool references:
-
-| Value | Meaning | Example |
-|---|---|---|
-| `true` | All tools visible (default) | `tools: true` or omit the field |
-| `false` | No tools visible | `tools: false` |
-| `[read, bash, grep]` | Only listed built-in tools | `tools: [read, bash]` |
-| `[web_search]` | Extension tool by name | `tools: [read, web_search]` |
-| `[tavily/*]` | All tools from an extension | `tools: [read, tavily/*]` |
-| `[tavily/web_search]` | Specific tool from extension | `tools: [read, tavily/web_search]` |
-| Mixed | Combine the above | `tools: [read, bash, tavily/*, exa_search]` |
+| `name` | string | filename | Agent type name (the `agent` enum value). Must be unique. |
+| `display_name` | string | `name` | Label in the widget, `/agents` menu, and result viewer. |
+| `description` | string | `""` | One-sentence description in the `/agents` list and tool rendering. |
+| `tools` | `true` \| `string[]` \| `false` | `true` | **Tool whitelist** — which tool schemas the LLM sees. Accepts built-in names and extension tool references (see below). Mutually exclusive with `exclude_tools`. |
+| `exclude_tools` | `string[]` | none | **Tool blacklist** — all tools except these are visible. Supports `ext/*` syntax. Mutually exclusive with `tools` (when `tools` is `string[]`). |
+| `extensions` | `true` \| `string[]` \| `false` | `true` | **Extension loader** — which extensions load (hooks + commands fire). Does NOT control tool visibility. Mutually exclusive with `exclude_extensions`. |
+| `exclude_extensions` | `string[]` | none | **Extension blacklist** — all extensions except these load. Mutually exclusive with `extensions` (when `extensions` is `string[]`). |
+| `skills` | `true` \| `string[]` \| `false` | `true` | **Skill whitelist** — which skills are available (metadata in system prompt). |
+| `preload_skills` | `string[]` \| `false` | `false` | **Full skill injection** — dump complete SKILL.md content into the system prompt instead of metadata-only. |
+| `model` | string | inherit parent | Default model as `"provider/model-id"`. See [Model Resolution](#model-resolution). |
+| `thinking` | string | inherit parent | One of: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`. |
+| `max_turns` | number | unlimited | Soft turn limit. Agent gets a steer at the limit, then `max_turns + graceTurns` before hard abort. |
+| `max_tokens` | number | unlimited | Max output tokens per LLM response. Injected into provider request payloads. |
+| `hidden` | `true` \| `false` | `false` | `true` hides the type from the enum (LLM can't see or invoke it). Still callable by name. |
+
+### Tool control (`tools` / `exclude_tools`)
+
+Use a whitelist (`tools`) when an agent needs few tools, or a blacklist (`exclude_tools`) when it needs most. You can use **either**, not both; if both are set, the whitelist wins.
 
 Built-in tool names: `read`, `bash`, `edit`, `write`, `grep`.
 
-#### Blacklist mode (`exclude_tools` and `exclude_extensions`)
-
-When you have many tools or extensions and want to disable a few, use the blacklist fields:
+| Value | Meaning |
+|---|---|
+| `true` / omitted | All tools visible |
+| `false` | No tools visible |
+| `[read, bash]` | Only listed built-in tools |
+| `[web_search]` | Extension tool by name |
+| `[tavily/*]` | All tools from an extension |
+| `[tavily/web_search]` | Specific tool from an extension |
 
 ```yaml
----
-name: restricted-agent
-description: Agent with write disabled
-exclude_tools: [write]              # all tools except write
-exclude_extensions: [quality-monitor]  # all extensions except quality-monitor
----
-```
-
-`exclude_tools` supports the same `ext/*` syntax as `tools`:
+# Read-only via whitelist
+tools: [read, bash, grep]
+extensions: false
 
-```yaml
-exclude_tools: [tavily/*]           # hide all tavily tools (extension still loads)
-exclude_tools: [write, tavily/*]    # hide write + all tavily tools
-exclude_tools: [tavily/web_search]  # hide only web_search from tavily
+# Same result via blacklist (easier to maintain as the toolset grows)
+exclude_tools: [edit, write]
 ```
 
-| Field | Mutually exclusive with | Behavior |
-|---|---|---|
-| `exclude_tools` | `tools` (when `tools` is `string[]`) | All tools except listed ones visible. Supports `ext/*` syntax. |
-| `exclude_extensions` | `extensions` (when `extensions` is `string[]`) | All extensions except listed ones load. |
-
-**Constraint:** You can use EITHER `tools` OR `exclude_tools`, not both. Same for `extensions`/`exclude_extensions`. If both are set, the whitelist (`tools`/`extensions`) wins.
+> `exclude_tools: [tavily/*]` hides tavily's tools but the extension still loads (hooks fire). Use `exclude_extensions: [tavily]` to prevent loading entirely.
 
-**Note:** `exclude_tools: [tavily/*]` hides tavily's tools but the extension still loads (hooks fire). Use `exclude_extensions: [tavily]` to prevent the extension from loading entirely.
+### Extensions & skills
 
-#### `extensions` field values
+**What they are:**
+- **Tools** are callable functions — `read`, `bash`, `edit`, `write`, `grep` (built-in), or `web_search` / `tavily/*` (from extensions). The `tools` whitelist controls which tool schemas the LLM sees.
+- **Skills** are reusable instruction files (`SKILL.md`) that teach an agent how to do a task — e.g. `debug`, `tdd`. By default the agent sees only skill metadata (name, description, path) in its system prompt and reads the full content on-demand via `read`.
+- **Extensions** are pi plugins (e.g. `tavily`, `pi-tokf`) that register tools and hooks. Loading one makes its hooks fire and its tools *available* — but those tools still need to pass the `tools` whitelist to be visible.
 
-The `extensions` field controls which extensions load. It does NOT affect tool visibility.
-
-| Value | Meaning | Example |
-|---|---|---|
-| `true` | Load all extensions (default) | `extensions: true` or omit the field |
-| `false` | Load no extensions | `extensions: false` |
-| `[tavily]` | Load only listed extensions | `extensions: [tavily, pi-tokf]` |
-| `[tavily/web_search]` | Load extension (tool part ignored) | `extensions: [tavily/web_search]` loads all of tavily |
+`extensions` controls which extensions **load** (hooks + tool registration), not tool visibility. `skills` and `preload_skills` control skill availability. Same whitelist/blacklist rules and `ext/*` syntax as `tools`.
 
-#### `skills` and `preload_skills` field values
-
-Skills have two injection modes:
-
-| Field | Value | Effect |
-|---|---|---|
-| `skills` | `true` | All skills available (metadata-only in system prompt) |
-| `skills` | `false` | No skills |
-| `skills` | `[debug, tdd]` | Only listed skills (metadata-only) |
-| `preload_skills` | `[debug]` | Dump full SKILL.md content into system prompt |
-| `preload_skills` | `false` | No preloading (default) |
-
-Metadata-only means the agent sees skill name, description, and file path. It reads the full content on-demand via the `read` tool. Preloading injects the full content upfront — higher token cost but no read latency.
-
-### Token-Saving Frontmatter Settings
-
-Every tool schema and every skill snippet you inject costs tokens — in every turn. These frontmatter fields are your main levers:
+| `extensions` value | Meaning |
+|---|---|
+| `true` / omitted | Load all extensions |
+| `false` | Load none |
+| `[tavily, pi-tokf]` | Load only listed extensions |
 
-| Setting | What it controls | Token impact |
+| Skill field | Value | Effect |
 |---|---|---|
-| `tools: [a, b, c]` | Which tool schemas the LLM sees (built-in + extension tools) | High — each tool has a schema (name, params, description) injected every turn. Fewer tools = fewer tokens. |
-| `tools: [ext-name/*]` | All tools from a specific extension | Medium — lazy shorthand for listing each tool individually. |
-| `extensions: false` | Disables all extensions (no hooks, no commands) | Medium — extensions can register hooks that fire every turn. |
-| `extensions: ["my-ext"]` | Load only specific extensions | Medium — pick only what the agent needs. |
-| `skills: ["skill-a"]` | Whitelist skills — injects metadata only (name, description, location) | Low — agent reads full content on-demand via `read` tool. No prose in system prompt. |
-| `skills: false` | Disables all skills | Zero skill tokens. |
-| `preload_skills: ["skill-a"]` | Dump full SKILL.md content into system prompt | **Highest** — skill prompts are prose, not schemas. A verbose skill can be 10-50x the token cost of a tool schema. |
-| `exclude_tools: [write]` | Disable specific tools (blacklist mode) | High — same as whitelist but without listing everything. |
-| `exclude_extensions: [ext]` | Disable specific extensions (blacklist mode) | Medium — same as whitelist but without listing everything. |
-
-**Practical examples:**
-
-```yaml
-# Read-only agent: whitelist approach
-tools: [read, bash, grep]
-extensions: false
-skills: false
+| `skills` | `true` / `[debug, tdd]` / `false` | All / listed / no skills (metadata-only in system prompt) |
+| `preload_skills` | `[debug]` / `false` | Dump full SKILL.md content / none (default) |
 
-# Read-only agent: blacklist approach (same result, easier to maintain)
-exclude_tools: [edit, write]
+**Implicit loading.** `loadSkillsImplicitly` and `loadExtensionsImplicitly` are config globals that decide what an agent gets when its frontmatter **omits** `skills` / `extensions`. They default ON, so an agent that says nothing about either gets everything. Turn them OFF (in config, or `/agents` → System prompt) to default every new agent to nothing — isolated sessions and minimal token cost, with agents opting in explicitly via `skills: [debug]` / `extensions: [tavily]`. A concrete frontmatter value always overrides the global.
 
-# Agent that uses all tools except write, and all extensions except quality-monitor
-exclude_tools: [write]
-exclude_extensions: [quality-monitor]
-```
-
-### Merge precedence
-
-Project agents override user agents, which override built-ins (`general-purpose`, `Explore`). Agent types discovered from `.md` files automatically appear in the `agent` parameter's enum — no registration required. Files added during a session are discovered on the next call that references them.
+**Token cost ranking** (highest → lowest): `preload_skills` ≫ `tools`/`exclude_tools` (each tool schema every turn) > `extensions` (hooks fire every turn) > `skills` (metadata-only, agent reads full content on-demand) > `skills: false` (zero). Prefer metadata skills over preloading; whitelist tools aggressively for narrow agents.
 
 ## Model Resolution
 
 The extension picks the right model automatically. Precedence (highest first):
 
-1. **Session per-type override** — `/agents > Model settings`, lasts the session
+1. **Session per-type override** — `/agents` → Model settings, lasts the session
 2. **Session global default** — temporary
 3. **Config per-type override** — `~/.pi/agent/subagents-lite.json`
 4. **Config global default**
-5. **Agent frontmatter** — `model` in `.md` file
+5. **Agent frontmatter** — `model` in `.md`
 6. **Parent model** — inherit from the calling agent
 
-The LLM never passes `model` — it's injected at call time via the `tool_call` listener. Set it once in config or frontmatter and forget about it.
+The LLM never passes `model` — it's injected at call time. Set it once in config or frontmatter and forget.
+
+## System Prompt Mode
+
+Control how the subagent system prompt is built via `systemPromptMode` (default: `replace`):
+
+- **`replace`** — minimal generic prompt plus the agent's own `<agent_instructions>`. Lowest token cost, most isolated.
+- **`inherit`** — parent's system prompt (scaffolding stripped to avoid duplication) plus `<agent_instructions>`. Best when agents need parent context and guidelines.
+- **`custom`** — content of `~/.pi/agent/subagents-lite-prompt.md` plus `<agent_instructions>`. Full control.
+
+When `includeContextFiles` is `true` (default), AGENTS.md files from the project root and `~/.pi/agent/` load as `<project_context>` before agent-specific instructions — shared static context improves KV cache prefix hit rates. Toggle off to cut token cost.
 
 ## Commands
 
@@ -287,121 +243,114 @@ The LLM never passes `model` — it's injected at call time via the `tool_call`
 
 Management menu with four sections:
 
-- **Running agents** — list with status and description; per-agent actions: view snapshot, view result, view error, steer, stop; bulk stop all running
-- **Spawn agent** — manually spawn an agent without asking the LLM. Pick a type, enter a prompt, configure options (model, thinking, max turns, grace turns, background), and spawn. Options are pre-filled from agent config and current settings. Spawn immediately or customize first.
-- **Settings** — model, concurrency, and widget settings grouped together
-  - **Model settings** — global default, per-type overrides, force background mode, cost display toggle, grace turns
+- **Running agents** — status and description; per-agent actions (view snapshot, result, error; steer; stop) and bulk stop
+- **Spawn agent** — manually spawn without the LLM. Pick a type, enter a prompt, tune options (model, thinking, max turns, max tokens, grace turns, background), then spawn. Options pre-fill from agent config.
+- **Settings**
+  - **Model settings** — global default, per-type overrides, session overrides, clear all
+  - **Spawn options** — force background, grace turns, default max turns, default thinking, disable default agents
+  - **System prompt** — mode, custom prompt file, include AGENTS.md, load skills/extensions implicitly
   - **Concurrency** — default limit, per-provider and per-model slots, reset to defaults
-  - **Widget settings** — force compact mode, max lines (full/compact), ctrl+o shortcut
-- **Debug** — agent types, agent briefing (sends capabilities to the LLM)
+  - **Widget settings** — force compact, max lines, description length, ctrl+o shortcut, usage stats (toggle tools, turns, input/output tokens, context %, cost, time)
 
 ## Interface
 
-### Live Widget
-
-Persistent bar above the editor showing running and completed agents. Updates live during execution.
+### Live widget
 
-- Running agents show a spinner, current tool activity, turn count, token usage (with optional context-fill percent), and elapsed time
-- Completed agents show a check mark with final stats
-- Click `tail -f` path to follow output logs in real time
-- Two display modes: **full** (header + `tail -f` path + activity) and **compact** (single line, description truncated to 30 chars, activity inline)
+Persistent bar above the editor showing running and completed agents, updating live. Running agents show a spinner, current tool activity, turn count, token usage (with optional context-fill %), and elapsed time. Completed agents show a check mark with final stats. Click the `tail -f` path to follow output logs.
 
-**Full mode** (tree structure with branch connectors):
+**Full mode** (tree, header + `tail -f` path + activity):
 ```
-├─ ⠙ Explore  description  3🛠 ·5≤30⟳ ·12.0k(45%)·1h 2m 3s
+├─ ⠙ Explore  description  3🛠 ·5≤30⟳ ·↑10.2k↓1.8k 45%·1h 2m 3s
 │  │ tail -f /tmp/pi-agent-outputs/...
 │  └ thinking…
 ```
 
-**Compact mode** (single line, description truncated):
+**Compact mode** (single line, description truncated, activity inline):
 ```
-├─ ⠙ Explore  description trunc…  3🛠 ·5≤30⟳ ·12.0k(45%)·1h 2m 3s  thinking…
+├─ ⠙ Explore  description trunc…  3🛠 ·5≤30⟳ ·↑10.2k↓1.8k 45%·1h 2m 3s  thinking…
 ```
 
-Turn format uses `≤` and `⟳` glyphs (`5≤30⟳` = 5 of 30 turns). Token count uses compact notation (`12.0k`) with optional context-fill percent in parentheses. No "tokens" label — the glyphs are self-explanatory.
-
-**Compact mode is active when:**
-- **Force compact mode** is ON (in `/agents > Widget settings`), OR
-- **Ctrl+o shortcut** is ON and the user has pressed ctrl+o to collapse tool expansion
-
-Force compact always wins. When force compact is ON, ctrl+o state changes are ignored.
+Turn format uses `≤` and `⟳` (`5≤30⟳` = 5 of 30 turns). Turn count is colored by usage: normal < 80%, warning 80–99%, error at 100%. The max is hidden when well below the limit. Token glyphs (`↑` input, `↓` output) are self-explanatory — no "tokens" label.
 
-### Result Viewer
+Compact mode is active when **Force compact** is ON, or **ctrl+o shortcut** is ON and the user has collapsed tool expansion. Force compact always wins.
 
-Fullscreen markdown viewer for agent results. Opens automatically when viewing a completed agent's result from the `/agents` menu.
+### Result viewer
 
-Key bindings: `↑↓` navigate · `PgUp/PgDn` · `g`/`G` top/bottom · `f` toggle fullscreen · `r` refresh · `q`/`Esc` close
+Fullscreen markdown viewer for completed agent results — opens automatically from `/agents`. Keys: `↑↓` / `PgUp/PgDn` navigate · `g`/`G` top/bottom · `f` fullscreen · `r` refresh · `q`/`Esc` close. Stats line: `↑12.0k · ↓8.0k · W3.0k · $0.024 · 15 turns · 47s`.
 
-Stats line: ` ↑12.0k · ↓8.0k · W3.0k · $0.024 · 15 turns · 47s`
-
-When **Cost display** is enabled (ON), agent stats show dollar cost: `✓ Builder·2🛠 ·5⟳ ·12.3k·$0.008·10s`. The status bar shows total agent cost: `agents: $0.008` or `2 agents: $0.008`.
+With **Cost display** ON, stats show dollar cost (`✓ Builder·2🛠 ·5⟳ ·↑10.2k↓1.8k $0.008·10s`) and the status bar totals it (`agents: $0.008`). Toggle as a session override from Model settings.
 
 ## Configuration
 
-`~/.pi/agent/subagents-lite.json` — managed via `/agents` menu, or edit directly:
+`~/.pi/agent/subagents-lite.json` — managed via `/agents`, or edit directly. Per-type model overrides (e.g. `"Explore"`) are dynamic keys alongside the special fields.
 
 ```json
 {
   "agent": {
-    "default": null,
-    "forceBackground": false,
-    "showCost": true,
+    "default": "zai/glm-5.2",
+    "forceBackground": true,
     "graceTurns": 6,
+    "showCost": true,
+    "showTools": false,
+    "showTurns": true,
+    "showInput": true,
+    "showOutput": true,
+    "showContext": true,
+    "showTime": true,
     "widgetMaxLines": 12,
     "widgetMaxLinesCompact": 6,
-    "widgetCompact": false,
+    "widgetDescLengthFull": 50,
+    "widgetCompact": true,
     "widgetShortcut": false,
-    "Explore": "anthropic/claude-haiku-4-5-20251001"
+    "systemPromptMode": "inherit",
+    "includeContextFiles": true,
+    "loadSkillsImplicitly": false,
+    "loadExtensionsImplicitly": false,
+    "disableDefaultAgents": false,
+    "Explore": "xiaomi/mimo-v2.5",
+    "builder": "xiaomi/mimo-v2-pro",
+    "architecture-reviewer": "zai/glm-5.2",
+    "planner": "zai/glm-5.2"
   },
   "concurrency": {
     "default": 4,
-    "providers": { "ollama": 2 },
-    "models": {
-      "anthropic/claude-sonnet-4-5-20250514": 3
-    }
+    "providers": {
+      "llamacpp": 1,
+      "ai.lan": 2
+    },
+    "models": {}
   }
 }
 ```
 
-> **Note:** `agent.default` (global fallback), `agent.forceBackground` (flag), `agent.showCost` (toggle cost display), `agent.graceTurns` (grace turns after `max_turns` before hard abort), widget settings (`widgetMaxLines`, `widgetMaxLinesCompact`, `widgetCompact`, `widgetShortcut`), and per-type overrides like `"Explore"` are peers in the same object. Agent type names become dynamic keys alongside the special fields.
-
 ### Widget settings
 
 | Field | Default | Description |
 |---|---|---|
-| `widgetMaxLines` | `12` | Maximum body lines in full mode (excluding the heading). |
-| `widgetMaxLinesCompact` | half of `widgetMaxLines` | Maximum body lines in compact mode. |
+| `widgetMaxLines` | `12` | Max body lines in full mode (excluding heading). |
+| `widgetMaxLinesCompact` | half of `widgetMaxLines` | Max body lines in compact mode. |
+| `widgetDescLengthFull` | `50` | Max description length in full mode. |
+| `widgetDescLengthCompact` | `30` | Max description length in compact mode. |
 | `widgetCompact` | `false` | Force compact mode regardless of ctrl+o state. |
-| `widgetShortcut` | `false` | Opt-in: when ON, ctrl+o (tool expansion toggle) syncs with widget compact mode. When OFF, compact mode is manual-only via `widgetCompact`. |
+| `widgetShortcut` | `false` | When ON, ctrl+o (tool expansion toggle) syncs with widget compact mode. When OFF, compact is manual via `widgetCompact`. |
 
-> **Reload safety:** if a session reload (e.g. `/reload` or extension reload) kills running agents, the UI notifies you with the count of lost agents. Output logs and completed results are preserved on disk.
+### Stats visibility
 
-## StopAgent Tool
-
-Stop a running agent by ID. Returns a success message or an error if the agent isn't found.
-
-| Parameter | Required | Description |
+| Field | Default | Description |
 |---|---|---|
-| `agent_id` | ✅ | The agent ID returned by the `Agent` tool when the agent was spawned |
-
-Agent IDs can be discovered from:
-- The `Agent` tool's result (shown on spawn)
-- The `StopAgent` error message, which lists all running agent IDs
-- The `/agents` menu's **Running agents** section
-
-## AgentStatus Tool
-
-List all agents with their type, short ID, and status. Returns a formatted list of all agents (running, queued, completed, stopped, error) and a nudge message reminding the LLM not to poll.
-
-**Usage:** The LLM calls `AgentStatus` to check on agents, but the extension nudges it to wait for automatic notifications instead of polling. This prevents wasteful repeated calls while still allowing the LLM to discover agents when needed.
-
-**Output format:** `type·short_id·status, type·short_id·status, ...`
+| `showTools` | `true` | Tool count (🛠). |
+| `showTurns` | `true` | Turn count (⟳). |
+| `showInput` | `true` | Input tokens (↑). |
+| `showOutput` | `true` | Output tokens (↓). |
+| `showContext` | `true` | Context-fill percent (%). |
+| `showCost` | `false` | Dollar cost ($). |
+| `showTime` | `true` | Elapsed time. |
 
-Example: `general-purpose·a1b2c3·running, Explore·d4e5f6·completed`
+> **Reload safety:** if a session reload (`/reload`, extension reload) kills running agents, the UI reports the count lost. Output logs and completed results are preserved on disk.
 
 ## Output Logs
 
-`/tmp/pi-agent-outputs/<agentId>.log` — append-only, human-readable, `tail -f` friendly. Every line is prefixed with an ISO 8601 timestamp:
+`/tmp/pi-agent-outputs/<agentId>.log` — append-only, human-readable, `tail -f` friendly. Every line is ISO-8601 timestamped:
 
 ```
 2026-05-27T12:00:00.000Z [USER] Find all authentication files

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-subagents-lite",
-  "version": "1.3.0",
+  "version": "1.4.1",
   "description": "Lightweight sub-agents for pi — spawn specialized agents with isolated sessions, tools, and models.",
   "keywords": [
     "pi-package",