pi-fast-subagent 0.5.1 → 0.6.0

package/README.md

@@ -61,6 +61,56 @@ 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.

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.1",
+  "version": "0.6.0",
   "description": "In-process subagent delegation for pi with single, parallel, and background modes",
   "type": "module",
   "keywords": [