pi-subagents-lite 0.4.0 → 1.0.0

package/README.md

@@ -13,18 +13,18 @@ Every tool the LLM sees costs tokens — in the system prompt, and in every turn
 
 | Standard | Schema-first |
 |---|---|
-| `description: "Spawn a sub-agent"` | `description: "."` |
+| `description: "Spawn a sub-agent"` | _(removed)_ |
 | `promptSnippet` with usage examples | _(none)_ |
 | `promptGuidelines` with rules | _(none)_ |
 | Parameters with `.description()` | Bare `Type.String()` |
 
 Tool names like `Agent` and `StopAgent`, 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.
 
-**Result:** foreground and background agents, custom agent types, per-model concurrency, cost tracking, steering, resume, model overrides — all with minimal token overhead.
+**Result:** foreground and background agents, custom agent types, per-model concurrency, cost tracking, steering, model overrides — all with minimal token overhead.
 
 ## Features
 
-- **Two tools** — `Agent` (spawn) and `StopAgent` (kill)
+- **Two tools** — `Agent` (spawn) and `StopAgent` (stop)
 - **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
@@ -32,7 +32,7 @@ Tool names like `Agent` and `StopAgent`, and parameter names like `prompt`, `des
 - **Cost tracking** — input/output/cache tokens and dollar cost per agent
 - **Live widget** — persistent status bar above the editor showing running/completed agents
 - **Result viewer** — fullscreen markdown viewer with stats
-- **Steer & resume** — inject mid-execution guidance or continue a previous conversation
+- **Steer** — inject mid-execution guidance into running agents
 - **Output logs** — human-readable, `tail -f` friendly
 
 ## Install
@@ -93,26 +93,25 @@ Stop a running agent at any time via /agents command
 |---|---|---|
 | `prompt` | ✅ | The task for the sub-agent |
 | `description` | ✅ | Brief description for the LLM caller |
-| `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 `enabled: false` in frontmatter to remove a type from this list. |
+| `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). |
 | `run_in_background` | | Fire-and-forget; result delivered automatically when done |
-| `resume` | | Agent ID to continue a previous conversation |
 
-> `model`, `max_turns`, `isolated`, 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`/`isolated`/`thinking` come from the agent's config. See [Custom Agent Types](#custom-agent-types) to set them.
+> `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.
 
 ## Custom Agent Types
 
 Drop a `.md` file into `.pi/agents/` (project) or `~/.pi/agent/agents/` (global). The frontmatter configures the agent; the body is its system prompt.
 
-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.
+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.
 
-Built-in types (`general-purpose`, `Explore`) are always present. User agents override built-ins with the same name; project agents override user agents (see [Merge precedence](#merge-precedence)).
+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)).
 
 ```markdown
 ---
 name: security-review
 display_name: Security Review
 description: Review code for security issues
-tools: [read, bash, grep, find, ls]
+tools: [read, bash, grep]
 extensions: false
 skills: false
 model: anthropic/claude-sonnet-4-5-20250514
@@ -124,22 +123,107 @@ You are a security review specialist. Analyze code for vulnerabilities,
 focusing on injection flaws, auth bypasses, and insecure defaults.
 ```
 
-**Frontmatter quick reference:**
+**Minimal agent — just name and description:**
 
-| Field | Type | Description |
+```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:**
+
+| 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]` |
+
+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:
+
+```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`:
+
+```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
+```
+
+| 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.
+
+**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` field values
+
+The `extensions` field controls which extensions load. It does NOT affect tool visibility.
+
+| Value | Meaning | Example |
 |---|---|---|
-| `name` | string | Agent type name. Used as the enum value in the `agent` parameter (defaults to filename). |
-| `display_name` | string | Human-readable label shown in the UI. |
-| `description` | string | Short description — displayed in the `/agents` type list and tool rendering. |
-| `tools` | string[] | Built-in tool allowlist: `read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`. If omitted, inherits all. |
-| `disallowed_tools` | string[] | Tool denylist — removes these from the agent's toolset even if allowlisted by `tools` or extensions. |
-| `extensions` | bool \| string[] | `false` = no extension tools; `true` = inherit all; `["ext-a"]` = allowlist. |
-| `skills` | bool \| string[] | `false` = no skill prompts; `true` = inherit all; `["skill-a"]` = only these. |
-| `model` | string | Default model as `"provider/model-id"`. Override via `/agents` or `subagents-lite.json`. |
-| `thinking` | string | Default thinking level: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`. |
-| `max_turns` | number | Turn limit (soft stop with steer). |
-| `enabled` | bool | `false` removes the agent type from the tool schema's enum (LLM can't see or invoke it). Running agents unaffected. Default: `true`. |
-| `isolated` | bool | Shorthand for `extensions: false` + `skills: false`. Reduces token footprint per turn. |
+| `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 |
+
+#### `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
 
@@ -147,18 +231,35 @@ Every tool schema and every skill snippet you inject costs tokens — in every t
 
 | Setting | What it controls | Token impact |
 |---|---|---|
-| `tools: [a, b, c]` | Which built-in tools the LLM sees | High — each tool has a schema (name, params, description) injected every turn. Fewer tools = fewer tokens. |
-| `extensions: false` | Disables all extension-provided tools | Medium — extensions can register many tools (linters, browsers, etc.). Each adds schema tokens. |
-| `extensions: ["my-ext"]` | Allowlist only specific extensions | Medium — pick only what the agent needs. |
-| `skills: false` | Prevents skill content from being injected into the system prompt | **Highest** — skill prompts are prose, not schemas. A verbose skill can be 10-50x the token cost of a tool schema. |
-| `skills: ["skill-a"]` | Inject only listed skills (preloaded inline) | Medium — you control exactly which skills appear. |
-| `isolated: true` | Shorthand for `extensions: false` + `skills: false` | High — zero extension tools, zero skill prompts. Useful for fast, focused agents. |
+| `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
 
-**Practical example:** An `Explore` agent that only reads files doesn't need write tools, browser extensions, or git skills. Setting `tools: [read, bash, grep, find, ls]` + `extensions: false` + `skills: false` saves thousands of tokens per turn compared to inheriting everything.
+# Read-only agent: blacklist approach (same result, easier to maintain)
+exclude_tools: [edit, write]
+
+# 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 dropdown — no registration required.
+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.
 
 ## Model Resolution
 
@@ -171,7 +272,7 @@ The extension picks the right model automatically. Precedence (highest first):
 5. **Agent frontmatter** — `model` in `.md` file
 6. **Parent model** — inherit from the calling agent
 
-The LLM never passes `model` — it's injected at call time. Set it once in config or frontmatter and forget about it.
+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.
 
 ## Commands
 

package/package.json

@@ -1,13 +1,16 @@
 {
   "name": "pi-subagents-lite",
-  "version": "0.4.0",
+  "version": "1.0.0",
   "description": "Lightweight sub-agents for pi — spawn specialized agents with isolated sessions, tools, and models.",
   "keywords": [
     "pi-package",
     "pi",
+    "pi-agent",
+    "pi-coding-agent",
     "pi-extension",
-    "subagent",
-    "agent"
+    "subagents",
+    "ai",
+    "agents"
   ],
   "author": "AlexParamonov",
   "license": "MIT",

package/src/agent-discovery.ts

@@ -1,8 +1,6 @@
 /**
  * agent-discovery.ts — Agent file discovery, parsing, and config merging.
  *
- * Extended from subagent-lazy/agent-discovery.ts with full frontmatter support.
- *
  * Scans:
  *   ~/.pi/agent/agents/*.md   (user agents)
  *   <project>/.pi/agents/*.md (project agents)
@@ -26,15 +24,15 @@ export interface AgentConfigFromMd {
   display_name?: string;
   description?: string;
   tools?: string[];
+  exclude_tools?: string[];
   extensions?: boolean | string[];
+  exclude_extensions?: string[];
   skills?: boolean | string[];
   preload_skills?: string[] | false;
   model?: string;
   thinking?: ThinkingLevel;
   max_turns?: number;
-  disallowed_tools?: string[];
-  enabled?: boolean;
-  isolated?: boolean;
+  hidden?: boolean;
   systemPrompt: string;
   source: "user" | "project";
 }
@@ -254,11 +252,6 @@ function compactDefined<T extends Record<string, unknown>>(obj: T): Partial<T> {
 
 /**
  * Parse a single agent .md file into AgentConfigFromMd.
- *
- * @param content - Raw file content
- * @param filename - Filename (for context, currently unused)
- * @param source - Source designation ("user" or "project")
- * @returns Parsed agent config with frontmatter and body
  */
 export function parseAgentFile(
   content: string,
@@ -272,15 +265,15 @@ export function parseAgentFile(
     display_name: parseString(frontmatter, "display_name"),
     description: parseString(frontmatter, "description"),
     tools: parseStringArray(frontmatter, "tools"),
+    exclude_tools: parseStringArray(frontmatter, "exclude_tools"),
     extensions: parseExtensions(frontmatter.extensions),
+    exclude_extensions: parseStringArray(frontmatter, "exclude_extensions"),
     skills: parseExtensions(frontmatter.skills),
     preload_skills: parsePreloadSkills(frontmatter.preload_skills),
     model: parseString(frontmatter, "model"),
     thinking: parseThinkingLevel(parseString(frontmatter, "thinking")),
     max_turns: parseNumber(frontmatter, "max_turns"),
-    disallowed_tools: parseStringArray(frontmatter, "disallowed_tools"),
-    enabled: parseBoolean(frontmatter, "enabled"),
-    isolated: parseBoolean(frontmatter, "isolated"),
+    hidden: parseBoolean(frontmatter, "hidden"),
     systemPrompt: body,
     source: source,
   };
@@ -396,16 +389,17 @@ function fromMd(md: AgentConfigFromMd): Partial<AgentConfig> {
     name: md.name,
     displayName: md.display_name,
     description: md.description,
-    builtinToolNames: md.tools,
+    registeredTools: md.tools,
+    tools: md.tools,
+    excludeTools: md.exclude_tools,
     extensions: md.extensions,
+    excludeExtensions: md.exclude_extensions,
     skills: md.skills,
     preloadSkills: md.preload_skills,
     model: md.model,
     thinking: md.thinking,
     maxTurns: md.max_turns,
-    disallowedTools: md.disallowed_tools,
-    enabled: md.enabled,
-    isolated: md.isolated,
+    hidden: md.hidden,
     systemPrompt: md.systemPrompt,
     source: md.source === "project" ? "project" : "global",
   };

package/src/agent-manager.ts

@@ -1,15 +1,7 @@
 /**
  * agent-manager.ts — Tracks agents, per-model concurrency, background execution.
  *
- * Forked from upstream pi-subagents. Key modifications:
- *   - Per-model concurrency (Map<string, { limit, running }>) replaces
- *     single maxConcurrent counter
- *   - No worktree isolation (all worktree imports and code paths removed)
- *   - Exposes steer(id, message) for /steer command
- *   - SpawnOptions.modelKey for concurrency pool lookup
- *   - ConcurrencyConfig with default + models map
- *   - No IsolationMode references
- *   - AgentRecord: removed worktree, worktreeResult, groupId, joinMode
+ * Supports per-model and per-provider concurrency limits with queuing.
  */
 
 import { randomUUID } from "node:crypto";
@@ -99,7 +91,6 @@ export interface SpawnOptions {
   description: string;
   model?: Model<any>;
   maxTurns?: number;
-  isolated?: boolean;
   thinkingLevel?: ThinkingLevel;
   isBackground?: boolean;
   /**
@@ -312,7 +303,6 @@ export class AgentManager {
       agentId: id,
       model: options.model,
       maxTurns: options.maxTurns,
-      isolated: options.isolated,
       thinkingLevel: options.thinkingLevel,
       signal: record.abortController!.signal,
       ...this.createRecordCallbacks(record, options),
@@ -498,13 +488,9 @@ export class AgentManager {
     return true;
   }
 
-  private disposeSession(session: AgentSession | undefined): void {
-    session?.dispose();
-  }
-
   /** Dispose a record's session and remove it from the map. */
   private removeRecord(id: string, record: AgentRecord): void {
-    this.disposeSession(record.session);
+    record.session?.dispose();
     record.session = undefined;
     this.agents.delete(id);
   }
@@ -522,7 +508,7 @@ export class AgentManager {
     clearInterval(this.cleanupInterval);
     this.queue = [];
     for (const record of this.agents.values()) {
-      this.disposeSession(record.session);
+      record.session?.dispose();
     }
     this.agents.clear();
   }