pi-fast-subagent 0.5.0 → 0.6.0

package/README.md

@@ -61,6 +61,101 @@ model: anthropic/claude-haiku-4-5
 You are code exploration specialist. Read relevant files, trace data flow, summarize findings clearly.
 ```
 
+### Agent frontmatter
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | yes | Unique agent identifier used in `subagent({ agent: "..." })` |
+| `description` | yes | One-line description shown in `/fast-subagent:agent` |
+| `model` | no | Model override, format `provider/model-id` (e.g. `anthropic/claude-haiku-4-5`) |
+| `tools` | no | Tool allowlist (see below) |
+
+### `tools:` field
+
+Controls which tools the subagent has access to. Subagents inherit parent extensions (web_search, fetch_content, mcp, …) by default.
+
+| Value | Behavior |
+|-------|----------|
+| *(omitted)* | Inherit everything — all builtins + all parent extensions (**default**) |
+| `all` | Same as omitted — explicit "everything" |
+| `none` | No tools at all — pure reasoning agent |
+| comma list | Allowlist; extensions auto-load only if any listed tool is non-builtin |
+
+Built-in tools: `read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`.
+
+Examples:
+
+```md
+---
+name: writer
+description: Pure-reasoning writing assistant
+tools: none
+---
+```
+
+```md
+---
+name: coder
+description: Lean code-editing agent, no extensions
+tools: read, bash, edit, write, grep, find, ls
+---
+```
+
+```md
+---
+name: researcher
+description: Web research agent
+tools: read, write, web_search, fetch_content
+---
+```
+
+> **Performance note:** inheriting all extensions adds startup cost (extension init) and token cost (larger system prompt). For tight, focused agents, list tools explicitly — extensions are only loaded when the allowlist actually needs them.
+
+## Background Agents
+
+Every foreground subagent can be moved to background at any time. Background jobs run concurrently while you continue chatting. When a job finishes, pi automatically posts the result as a follow-up message.
+
+### Status bar
+
+While a foreground subagent is running, the pi status bar shows:
+```
+{agent-name} running · Ctrl+Shift+B to move to background
+```
+
+While background jobs are running:
+```
+⧗ N bg agents
+```
+
+### Moving to background
+
+**Keyboard shortcut (while subagent is running):**
+```
+Ctrl+Shift+B
+```
+
+**Slash command:**
+```
+/fast-subagent:bg fg_ab12cd34
+```
+
+**Via tool call:**
+```js
+subagent({ action: "detach", jobId: "fg_ab12cd34" })
+```
+
+### Auto-completion announcement
+
+When a background job finishes, pi injects a follow-up message automatically:
+```
+Background subagent ✓: sa_ab12cd34 (scout, 4.2s)
+> Explore src and summarize architecture
+
+<result output>
+```
+
+Failed jobs are announced the same way with ✗ and the error message.
+
 ## Slash Commands
 
 ### `/fast-subagent:agent`
@@ -81,13 +176,13 @@ Tab-completion is supported for agent names.
 
 ### `/fast-subagent:bg`
 
-Detach running foreground subagent to background:
+Detach a running foreground subagent to background. Each foreground job has a `fg_` prefixed ID shown in the status bar.
 
 ```
 /fast-subagent:bg fg_ab12cd34
 ```
 
-Omit job id to list active foreground jobs:
+Omit ID to list all active foreground jobs:
 
 ```
 /fast-subagent:bg
@@ -95,13 +190,13 @@ Omit job id to list active foreground jobs:
 
 ### `/fast-subagent:bg-status`
 
-Show active background subagents in selector UI. Arrow keys move selection. Enter shows full details for selected job.
+Open selector UI showing all active background jobs. Arrow keys to navigate, Enter to view full details.
 
 ```
 /fast-subagent:bg-status
 ```
 
-Show details for specific background job:
+Skip the selector — show details for a specific job directly:
 
 ```
 /fast-subagent:bg-status sa_ab12cd34
@@ -109,52 +204,58 @@ Show details for specific background job:
 
 ### `/fast-subagent:bg-cancel`
 
-Cancel running background subagent. Omit job id to open selector UI, then choose job with arrow keys.
+Open selector UI to choose a running job to cancel:
 
 ```
 /fast-subagent:bg-cancel
 ```
 
-Cancel specific background job directly:
+Cancel a specific job directly:
 
 ```
 /fast-subagent:bg-cancel sa_ab12cd34
 ```
 
-## Usage
+## Keyboard Shortcuts
 
-### List agents
+| Shortcut | Action |
+|---|---|
+| `Ctrl+Shift+B` | Move active foreground subagent to background |
 
-```js
-subagent({ action: "list" })
-```
+## Roadmap
 
-### Single
+Goal: keep this extension **small and focused** — aligned with pi's philosophy of minimal, composable tooling. No feature creep. Every addition must earn its place.
 
-```js
-subagent({
-  agent: "scout",
-  task: "Explore src and summarize architecture"
-})
-```
+- **UI/UX polish** — improve visibility of running subagents: clearer status lines, better progress feedback, agent name + task always visible during execution
+- ~~**Background subagents**~~ ✔ shipped in v0.4.0 — fire-and-forget with `background: true`, poll/cancel/detach support
+
+## Notes
+
+- Async/background isolation not supported in-process
+- Git worktree isolation not supported
+- Nested subagent depth limited to 2 by default
+
+## Tool Reference
 
-### General-purpose built-in agent
+> These are `subagent` tool call examples used by the LLM internally. Not typically invoked directly by users.
+
+### List / discover agents
 
 ```js
-subagent({
-  agent: "general",
-  task: "Summarize open TODOs and propose next step"
-})
+// List all agents
+subagent({ action: "list" })
+
+// Get details for a specific agent
+subagent({ action: "get", agent: "scout" })
+
+// Scope filter: "user" | "project" | "both" (default)
+subagent({ action: "list", agentScope: "project" })
 ```
 
-### Override model
+### Single
 
 ```js
-subagent({
-  agent: "scout",
-  task: "Explore src and summarize architecture",
-  model: "anthropic/claude-haiku-4-5"
-})
+subagent({ agent: "scout", task: "Explore src and summarize architecture" })
 ```
 
 ### Parallel
@@ -165,42 +266,32 @@ subagent({
     { agent: "scout", task: "Map auth flow" },
     { agent: "scout", task: "Map navigation" }
   ],
-  concurrency: 2
+  concurrency: 2  // default: 4
 })
+
+// Repeat one task N times
+subagent({ tasks: [{ agent: "scout", task: "Explore src", count: 3 }] })
 ```
 
-### Background (fire-and-forget)
+### Background
 
 ```js
-// Dispatch — returns job ID immediately
+// Fire-and-forget — returns job ID immediately
 subagent({ agent: "scout", task: "Explore src", background: true })
 // → { jobId: "sa_ab12cd34", status: "running" }
 
-// Poll — check result / progress
-subagent({ action: "poll", jobId: "sa_ab12cd34" })
-
-// Cancel
-subagent({ action: "cancel", jobId: "sa_ab12cd34" })
-
-// List all background jobs
-subagent({ action: "status" })
-
-// Detach a running foreground job to background
-subagent({ action: "detach", jobId: "fg_ab12cd34" })
+subagent({ action: "poll",   jobId: "sa_ab12cd34" })  // check progress
+subagent({ action: "cancel", jobId: "sa_ab12cd34" })  // abort
+subagent({ action: "status" })                        // list all bg jobs
+subagent({ action: "detach", jobId: "fg_ab12cd34" })  // move fg → bg
 ```
 
-## Roadmap
+### Options
 
-Goal: keep this extension **small and focused** — aligned with pi's philosophy of minimal, composable tooling. No feature creep. Every addition must earn its place.
-
-- **UI/UX polish** — improve visibility of running subagents: clearer status lines, better progress feedback, agent name + task always visible during execution
-- **Background agents** — ala claude code
-
-## Notes
-
-- Async/background isolation not supported in-process
-- Git worktree isolation not supported
-- Nested subagent depth limited to 2 by default
+```js
+subagent({ agent: "scout", task: "...", model: "anthropic/claude-haiku-4-5" })
+subagent({ agent: "scout", task: "...", cwd: "/path/to/project" })
+```
 
 ## Publish
 

package/agents/scout.md

@@ -2,6 +2,7 @@
 name: scout
 description: Explores codebases, maps structure, traces data flow, answers how things work across many files
 model: anthropic/claude-haiku-4-5
+tools: read, bash, edit, write, grep, find, ls
 ---
 
 You are code exploration specialist.

package/agents.ts

@@ -8,16 +8,54 @@ import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import { getAgentDir, parseFrontmatter } from "@mariozechner/pi-coding-agent";
 
+/**
+ * tools frontmatter semantics:
+ *   unset        → inherit everything (builtins + extensions) — same as `all`
+ *   `all`        → all builtins + all extension tools (web_search, fetch_content, mcp, …)
+ *   `none`       → no tools at all
+ *   comma list   → allowlist; extensions auto-loaded if any listed tool is non-builtin
+ *                  for lean "builtins-only" mode, list them explicitly:
+ *                    tools: read, bash, edit, write, grep, find, ls
+ *
+ * Represented as:
+ *   "all"        → everything (default when frontmatter omits `tools`)
+ *   "none"       → no tools
+ *   string[]     → allowlist
+ */
+export type AgentTools = "all" | "none" | string[];
+
+export const BUILTIN_TOOL_NAMES = ["read", "bash", "edit", "write", "grep", "find", "ls"] as const;
+
 export interface AgentConfig {
   name: string;
   description: string;
   model?: string;
-  tools?: string[];
+  tools: AgentTools;
   systemPrompt: string;
   source: "user" | "project";
   filePath: string;
 }
 
+const BUILTIN_TOOLS = new Set<string>(BUILTIN_TOOL_NAMES);
+
+export function agentNeedsExtensions(tools: AgentTools): boolean {
+  if (tools === "all") return true;
+  if (tools === "none") return false;
+  return tools.some((t) => !BUILTIN_TOOLS.has(t));
+}
+
+// Default: everything. Agents list specific tools for lean / restricted mode.
+function parseToolsField(raw: unknown): AgentTools {
+  if (raw === undefined || raw === null) return "all";
+  const str = String(raw).trim();
+  if (!str) return "all";
+  const lower = str.toLowerCase();
+  if (lower === "all") return "all";
+  if (lower === "none") return "none";
+  const list = str.split(",").map((t) => t.trim()).filter(Boolean);
+  return list.length ? list : "all";
+}
+
 function loadAgentsFromDir(dir: string, source: "user" | "project"): AgentConfig[] {
   if (!fs.existsSync(dir)) return [];
   let entries: fs.Dirent[];
@@ -36,13 +74,12 @@ function loadAgentsFromDir(dir: string, source: "user" | "project"): AgentConfig
       const content = fs.readFileSync(filePath, "utf-8");
       const { frontmatter, body } = parseFrontmatter<Record<string, string>>(content);
       if (!frontmatter?.name || !frontmatter?.description) continue;
-      const rawTools = frontmatter.tools;
-      const tools = rawTools?.split(",").map((t: string) => t.trim()).filter(Boolean);
+      const tools = parseToolsField(frontmatter.tools);
       agents.push({
         name: frontmatter.name,
         description: frontmatter.description,
         model: frontmatter.model,
-        tools: tools?.length ? tools : undefined,
+        tools,
         systemPrompt: body.trim(),
         source,
         filePath,

package/index.ts

@@ -32,7 +32,13 @@ import {
 
 type DefaultResourceLoaderOptions = ConstructorParameters<typeof DefaultResourceLoader>[0];
 import { Type } from "@sinclair/typebox";
-import { type AgentConfig, discoverAgents } from "./agents.js";
+import { type AgentConfig, agentNeedsExtensions, discoverAgents } from "./agents.js";
+
+function formatTools(tools: AgentConfig["tools"]): string {
+  if (tools === "all") return "all";
+  if (tools === "none") return "none";
+  return tools.join(", ");
+}
 
 // ─── Tool arg summarizer (compact one-liner per tool call) ─────────────────────
 
@@ -228,11 +234,14 @@ async function runAgent(
   const { authStorage, modelRegistry } = getAuth();
   const agentDir = getAgentDir();
 
-  // Build resource loader — no extensions/context files to keep subagent lean
+  // Build resource loader — no extensions/context files to keep subagent lean.
+  // Agents can opt in to extensions via `extensions: true` in frontmatter, which
+  // makes tools like web_search / fetch_content / mcp / etc. available to the
+  // subagent (subject to the optional `tools:` allowlist below).
   const loaderOptions: DefaultResourceLoaderOptions = {
     cwd,
     agentDir,
-    noExtensions: true,
+    noExtensions: !agentNeedsExtensions(agent.tools),
     noContextFiles: true,
     noSkills: true,
   };
@@ -264,8 +273,13 @@ async function runAgent(
     }
   }
 
-  // Restrict tools if agent specifies them
-  if (agent.tools && agent.tools.length > 0) {
+  // Apply tools allowlist.
+  //   "all"    → no restriction (everything registered stays active)
+  //   "none"   → disable every tool
+  //   string[] → explicit allowlist
+  if (agent.tools === "none") {
+    session.setActiveToolsByName([]);
+  } else if (Array.isArray(agent.tools) && agent.tools.length > 0) {
     session.setActiveToolsByName(agent.tools);
   }
 
@@ -598,7 +612,7 @@ export default function (pi: ExtensionAPI) {
           `File: ${agent.filePath}`,
           `Description: ${agent.description}`,
           agent.model ? `Model: ${agent.model}` : "",
-          agent.tools ? `Tools: ${agent.tools.join(", ")}` : "",
+          `Tools: ${formatTools(agent.tools)}`,
           agent.systemPrompt ? `\nSystem prompt:\n${agent.systemPrompt}` : "",
         ].filter(Boolean).join("\n");
         ctx.ui.notify(lines, "info");
@@ -984,7 +998,7 @@ export default function (pi: ExtensionAPI) {
           `## ${agent.name} [${agent.source}]`,
           `**Description:** ${agent.description}`,
           agent.model ? `**Model:** ${agent.model}` : null,
-          agent.tools ? `**Tools:** ${agent.tools.join(", ")}` : null,
+          `**Tools:** ${formatTools(agent.tools)}`,
           agent.systemPrompt ? `\n**System prompt:**\n${agent.systemPrompt}` : null,
         ].filter(Boolean).join("\n");
         return { content: [{ type: "text", text: info }] };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-fast-subagent",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "In-process subagent delegation for pi with single, parallel, and background modes",
   "type": "module",
   "keywords": [