pi-subagents-lite 0.4.1 → 1.0.1

package/src/agent-runner.ts

@@ -1,16 +1,10 @@
 /**
- * agent-runner.ts — Core execution engine: creates sessions, runs agents, collects results.
+ * Core execution engine: creates sessions, runs agents, collects results.
  *
- * Forked from upstream pi-subagents. Key modifications:
- *   - Removed buildParentContext import and inheritContext code path
- *   - Removed buildMemoryBlock/buildReadOnlyMemoryBlock imports and memory code paths
- *   - Replaced import { detectEnv } from env.ts with inline git detection via pi.exec()
- *   - Handles `isolated` parameter internally (sets extensions=false, skills=false)
- *   - RunOptions: keeps pi: ExtensionAPI, isolated?: boolean. Removes inheritContext, isolation
- *   - PromptExtras: removed memoryBlock — keeps skillBlocks[] only
- *   - EXCLUDED_TOOL_NAMES prevents sub-subagent spawning
+ * EXCLUDED_TOOL_NAMES prevents sub-subagent spawning.
  */
 
+import path from "node:path";
 import type { Model } from "@earendil-works/pi-ai";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import {
@@ -23,20 +17,20 @@ import {
   SessionManager,
   SettingsManager,
 } from "@earendil-works/pi-coding-agent";
-import { getAgentConfig, getConfig, getToolNamesForType } from "./agent-types.js";
+import { getAgentConfig, getConfig, getToolNamesForType, BUILTIN_TOOL_NAMES } from "./agent-types.js";
 import { extractText } from "./context.js";
 import type { LifetimeUsage } from "./usage.js";
 import { findModelInRegistry } from "./utils.js";
 import { DEFAULT_AGENTS } from "./default-agents.js";
-import { buildAgentPrompt, type PromptExtras, type SkillMeta } from "./prompts.js";
-import { preloadSkills, loadSkillMeta } from "./skill-loader.js";
+import { buildAgentPrompt, type PromptExtras } from "./prompts.js";
+import { preloadSkills, loadSkillMeta, type SkillMeta } from "./skill-loader.js";
 import { type CompactionInfo, type EnvInfo, SHORT_ID_LENGTH, type SubagentType, type ThinkingLevel } from "./types.js";
 
 /** Names of tools registered by this extension that subagents must NOT inherit. */
-export const EXCLUDED_TOOL_NAMES = ["Agent"];
+const EXCLUDED_TOOL_NAMES = ["Agent"];
 
-/** Additional turns allowed after the soft limit steer message. */
-const GRACE_TURNS = 5;
+/** Default grace turns when not specified in config. */
+const DEFAULT_GRACE_TURNS = 6;
 
 /** Timeout for quick git commands (branch detection, repo check). */
 const GIT_EXEC_TIMEOUT_MS = 5000;
@@ -61,8 +55,6 @@ interface RunOptions {
   model?: Model<any>;
   maxTurns?: number;
   signal?: AbortSignal;
-  /** When true, agent gets only built-in tools (no extensions, no skills). */
-  isolated?: boolean;
   thinkingLevel?: ThinkingLevel;
   /** Override working directory. */
   cwd?: string;
@@ -84,6 +76,8 @@ interface RunOptions {
    * pre-compaction context size estimate. Aborted compactions don't fire.
    */
   onCompaction?: (info: CompactionInfo) => void;
+  /** Grace turns: extra turns allowed after hitting maxTurns. Defaults to 6. */
+  graceTurns?: number;
 }
 
 interface RunResult {
@@ -187,36 +181,166 @@ export function subscribeToSessionEvents(
 }
 
 /**
- * Filter active tools: remove extension tools to prevent nesting,
- * apply extension allowlist if specified, and apply disallowedTools denylist.
- * Returns null when no filtering is needed (isolated mode with no denylist).
+ * Extract the extension name from an extension's file path.
+ *
+ * Handles all distribution methods:
+ *  - git packages: `.../git/github.com/<user>/<pkg>/...` → "<pkg>"
+ *  - npm packages: `.../node_modules/[...]pkg/...` → "pkg"
+ *  - local extensions: `~/.pi/agent/extensions/<name>/...` → "<name>"
+ *  - direct files: `extensions/<name>.ts` → "<name>"
+ *
+ * Does NOT depend on internal directory structure (dist/, lib/, src/, etc).
+ * Only cares about the package root, which is determined by distribution method.
+ */
+function extractExtensionName(extPath: string): string {
+  const parts = extPath.split(path.sep);
+
+  // 1. Git package: .../git/github.com/<user>/<pkg>/...
+  //    Package name is 3 dirs after 'git' (github.com/user/pkg)
+  const gitIdx = parts.indexOf("git");
+  if (gitIdx !== -1 && gitIdx + 3 < parts.length) {
+    return parts[gitIdx + 3];
+  }
+
+  // 2. npm package: .../node_modules/[...]pkg/...
+  const nmIdx = parts.lastIndexOf("node_modules");
+  if (nmIdx !== -1 && nmIdx + 1 < parts.length) {
+    const next = parts[nmIdx + 1];
+    if (next.startsWith("@") && nmIdx + 2 < parts.length) {
+      return parts[nmIdx + 2]; // @scope/pkg → pkg
+    }
+    return next;
+  }
+
+  // 3. Local extension: .../extensions/<name>/... or .../extensions/<name>.ts
+  const extIdx = parts.lastIndexOf("extensions");
+  if (extIdx !== -1 && extIdx + 1 < parts.length) {
+    const afterExt = parts[extIdx + 1];
+    // Subdirectory: extensions/tavily/index.ts → tavily
+    if (afterExt && !afterExt.includes(".")) {
+      return afterExt;
+    }
+    // Direct file: extensions/review.ts → review
+    const file = parts[parts.length - 1];
+    return path.basename(file, path.extname(file));
+  }
+
+  // Fallback: parent dir name
+  return path.basename(path.dirname(extPath));
+}
+
+/**
+ * Resolve tool entries (with ext/* syntax) into concrete tool names.
+ * Returns a set of resolved tool names.
+ */
+function resolveToolEntries(
+  entries: string[],
+  extToolMap: Map<string, string[]> | undefined,
+  notify?: (msg: string) => void,
+): Set<string> {
+  const resolved = new Set<string>();
+
+  for (const entry of entries) {
+    const slashIdx = entry.indexOf("/");
+    if (slashIdx !== -1) {
+      // ext/* or ext/tool syntax
+      const extName = entry.slice(0, slashIdx);
+      const toolPart = entry.slice(slashIdx + 1);
+      if (toolPart === "*") {
+        const extTools = extToolMap?.get(extName);
+        if (extTools && extTools.length > 0) {
+          for (const t of extTools) resolved.add(t);
+        } else {
+          notify?.(`extension "${extName}" is not loaded, "${entry}" will have no effect`);
+        }
+      } else {
+        // ext/tool syntax: e.g. "tavily/web_search"
+        resolved.add(toolPart);
+      }
+    } else {
+      // Bare tool name
+      resolved.add(entry);
+    }
+  }
+
+  return resolved;
+}
+
+/**
+ * Filter active tools: apply tools allowlist/denylist and EXCLUDED_TOOL_NAMES.
+ *
+ * The `tools` config controls which tool schemas the LLM sees (built-in + extension).
+ * The `extensions` config controls which extensions are loaded (hooks + commands).
+ * `extensions` does NOT affect tool visibility — that's `tools`'s job.
+ *
+ * Supports ext/* syntax for both whitelist and blacklist modes.
+ *
+ * `tools` and `excludeTools` are mutually exclusive. If both set, `tools` wins.
+ *
+ * Returns null when no filtering is needed, otherwise the filtered tool list.
  */
 function filterActiveTools(
   activeTools: string[],
-  builtinToolNames: string[],
-  extensions: true | string[] | false,
-  disallowedTools?: string[],
+  extToolMap: Map<string, string[]> | undefined,
+  tools: true | string[] | false | undefined,
+  excludeTools: string[] | undefined,
+  notify?: (msg: string) => void,
 ): string[] | null {
-  const disallowedSet = disallowedTools ? new Set(disallowedTools) : undefined;
-
-  if (extensions === false) {
-    // Isolated mode — only apply denylist to built-in tools
-    if (!disallowedSet) return null;
-    const filtered = activeTools.filter(t => !disallowedSet.has(t));
+  // Blacklist mode: excludeTools set and tools not set as whitelist
+  if (excludeTools && !Array.isArray(tools)) {
+    const excludeSet = resolveToolEntries(excludeTools, extToolMap, notify);
+    const filtered = activeTools.filter(t =>
+      !EXCLUDED_TOOL_NAMES.includes(t) && !excludeSet.has(t)
+    );
     return filtered.length !== activeTools.length ? filtered : null;
   }
 
-  const builtinToolNameSet = new Set(builtinToolNames);
-  const filtered = activeTools.filter((t) => {
-    if (EXCLUDED_TOOL_NAMES.includes(t)) return false;
-    if (disallowedSet?.has(t)) return false;
-    if (builtinToolNameSet.has(t)) return true;
-    if (Array.isArray(extensions)) {
-      return extensions.some(ext => t.startsWith(ext) || t.includes(ext));
+  if (Array.isArray(tools)) {
+    // Whitelist mode: resolve entries with ext/* expansion
+    const allBuiltinSet = new Set(BUILTIN_TOOL_NAMES);
+    const allowedTools = resolveToolEntries(tools, extToolMap, notify);
+
+    // Warn about unknown entries
+    for (const entry of tools) {
+      const slashIdx = entry.indexOf("/");
+      if (slashIdx === -1 && !allBuiltinSet.has(entry)) {
+        // Bare name, not a known built-in — check if it's an extension tool
+        const toolExts = extToolMap ? [...extToolMap.entries()].filter(([, tools]) => tools.includes(entry)) : [];
+        if (toolExts.length === 0) {
+          notify?.(`tool "${entry}" not found in any loaded extension`);
+        }
+      }
     }
-    return true;
-  });
-  return filtered.length !== activeTools.length ? filtered : null;
+
+    const visibleSet = new Set<string>();
+    for (const t of activeTools) {
+      if (EXCLUDED_TOOL_NAMES.includes(t)) continue;
+      if (allowedTools.has(t)) {
+        visibleSet.add(t);
+      }
+    }
+
+    // Warn if a loaded extension has none of its tools in `tools`
+    if (extToolMap) {
+      for (const [extName, extTools] of extToolMap) {
+        const hasAny = extTools.some(t => allowedTools.has(t));
+        if (!hasAny) {
+          notify?.(`extension "${extName}" is loaded but none of its tools are in tools: [${tools.join(", ")}]`);
+        }
+      }
+    }
+
+    return [...visibleSet];
+  }
+
+  if (tools === false) {
+    return [];
+  }
+
+  // tools: true or undefined — all tools visible (except excluded)
+  const hasExcluded = activeTools.some(t => EXCLUDED_TOOL_NAMES.includes(t));
+  if (!hasExcluded) return null;
+  return activeTools.filter(t => !EXCLUDED_TOOL_NAMES.includes(t));
 }
 
 /** Run a git command via pi.exec, returning stdout on success or null on failure. */
@@ -254,21 +378,32 @@ export async function runAgent(
   const config = getConfig(type);
   const agentConfig = getAgentConfig(type);
 
+  // Warn on mutual exclusion violations
+  const notify = (msg: string) => {
+    if (ctx.ui?.notify) {
+      ctx.ui.notify(`[pi-subagents] ${msg}`, "warning");
+    } else {
+      console.warn(`[pi-subagents] ${msg}`);
+    }
+  };
+  if (agentConfig?.excludeTools && Array.isArray(agentConfig.tools)) {
+    notify(`agent "${type}": both tools and exclude_tools set — tools (whitelist) wins`);
+  }
+  if (agentConfig?.excludeExtensions && Array.isArray(agentConfig.extensions)) {
+    notify(`agent "${type}": both extensions and exclude_extensions set — extensions (whitelist) wins`);
+  }
+
   // Resolve working directory
   const effectiveCwd = options.cwd ?? ctx.cwd;
 
   const env = await detectEnv(options.pi, effectiveCwd);
 
-  // Resolve extensions/skills: isolated overrides to false
-  // Falls back to agent config (frontmatter) when not set via options (tool injection)
-  const effectiveIsolated = options.isolated ?? agentConfig?.isolated;
-  const extensions = effectiveIsolated ? false : config.extensions;
-  const skills = effectiveIsolated ? false : config.skills;
-  const preloadSkillsList = effectiveIsolated ? false : agentConfig?.preloadSkills;
+  // Resolve extensions/skills from agent config (frontmatter)
+  const extensions = config.extensions;
+  const skills = config.skills;
+  const preloadSkillsList = agentConfig?.preloadSkills;
 
-  // Build prompt extras (no memoryBlock — skills only).
-  // - preloadSkills: force full content into system prompt
-  // - skills: metadata only (whitelist), agent reads on-demand
+  // Build prompt extras (skills only).
   const extras: PromptExtras = {};
   if (Array.isArray(preloadSkillsList)) {
     extras.skillBlocks = preloadSkills(preloadSkillsList, effectiveCwd);
@@ -299,7 +434,10 @@ export async function runAgent(
   const agentDir = getAgentDir();
 
   // Load extensions/skills: true or string[] → load; false → don't.
-  const loader = new DefaultResourceLoader({
+  // When extensions is an array, use extensionsOverride to selectively load
+  // only the listed extensions (hooks/commands of excluded ones never fire).
+  // When excludeExtensions is set (and extensions is not string[]), filter out those extensions.
+  const loaderOpts: ConstructorParameters<typeof DefaultResourceLoader>[0] = {
     cwd: effectiveCwd,
     agentDir,
     noExtensions: extensions === false,
@@ -309,9 +447,44 @@ export async function runAgent(
     noContextFiles: true,
     systemPromptOverride: () => systemPrompt,
     appendSystemPromptOverride: () => [],
-  });
+  };
+  const excludeExtSet = agentConfig?.excludeExtensions
+    ? new Set(agentConfig.excludeExtensions)
+    : undefined;
+  if (Array.isArray(extensions)) {
+    // Whitelist mode: only load listed extensions
+    const allowedNames = new Set(extensions.map(ext => {
+      const slashIdx = ext.indexOf("/");
+      return slashIdx !== -1 ? ext.slice(0, slashIdx) : ext;
+    }));
+    loaderOpts.extensionsOverride = (result) => ({
+      ...result,
+      extensions: result.extensions.filter(ext =>
+        allowedNames.has(extractExtensionName(ext.path)),
+      ),
+    });
+  } else if (excludeExtSet) {
+    // Blacklist mode: load all except excluded extensions
+    loaderOpts.extensionsOverride = (result) => ({
+      ...result,
+      extensions: result.extensions.filter(ext =>
+        !excludeExtSet.has(extractExtensionName(ext.path)),
+      ),
+    });
+  }
+  const loader = new DefaultResourceLoader(loaderOpts);
   await loader.reload();
 
+  // Build extension name → tool names map from loaded extensions.
+  // Used by filterActiveTools to resolve extension names in the extensions frontmatter field.
+  const extResult = loader.getExtensions();
+  const extToolMap = new Map<string, string[]>();
+  for (const ext of extResult.extensions) {
+    const name = extractExtensionName(ext.path);
+    const tools = [...ext.tools.keys()];
+    if (tools.length > 0) extToolMap.set(name, tools);
+  }
+
   // Resolve model: explicit option > config.model > parent model
   const model = options.model ?? findModelInRegistry(
     agentConfig?.model, ctx.modelRegistry, ctx.model,
@@ -341,19 +514,9 @@ export async function runAgent(
     options.agentId ? `${baseSessionName}#${options.agentId.slice(0, SHORT_ID_LENGTH)}` : baseSessionName,
   );
 
-  // Filter active tools: remove our own tools to prevent nesting,
-  // apply extension allowlist if specified, and apply disallowedTools denylist
-  const filteredTools = filterActiveTools(
-    session.getActiveToolNames(),
-    toolNames,
-    extensions,
-    agentConfig?.disallowedTools,
-  );
-  if (filteredTools) {
-    session.setActiveToolsByName(filteredTools);
-  }
-
   // Bind extensions so that session_start fires and extensions can initialize
+  // This must happen BEFORE tool filtering — extensions like pi-mcp-adapter
+  // register tools lazily during session_start, not at extension load time.
   await session.bindExtensions({
     onError: (err) => {
       options.onToolActivity?.({
@@ -363,6 +526,33 @@ export async function runAgent(
     },
   });
 
+  // Rebuild extToolMap after session_start — extensions may have registered
+  // new tools (e.g., pi-mcp-adapter registers 'mcp' tool at session_start).
+  const postBindExtToolMap = new Map<string, string[]>();
+  for (const ext of extResult.extensions) {
+    const name = extractExtensionName(ext.path);
+    const tools = [...ext.tools.keys()];
+    if (tools.length > 0) postBindExtToolMap.set(name, tools);
+  }
+
+  // Filter active tools: apply tools allowlist/denylist and EXCLUDED_TOOL_NAMES
+  const filteredTools = filterActiveTools(
+    session.getActiveToolNames(),
+    postBindExtToolMap,
+    agentConfig?.tools,
+    agentConfig?.excludeTools,
+    (msg) => {
+      if (ctx.ui?.notify) {
+        ctx.ui.notify(`[pi-subagents] ${msg}`, "warning");
+      } else {
+        console.warn(`[pi-subagents] ${msg}`);
+      }
+    },
+  );
+  if (filteredTools) {
+    session.setActiveToolsByName(filteredTools);
+  }
+
   options.onSessionCreated?.(session);
 
   // Track turns for graceful max_turns enforcement
@@ -370,6 +560,7 @@ export async function runAgent(
   const maxTurns = normalizeMaxTurns(options.maxTurns ?? agentConfig?.maxTurns);
   let softLimitReached = false;
   let aborted = false;
+  const graceTurns = options.graceTurns ?? DEFAULT_GRACE_TURNS;
 
   const unsubEvents = subscribeToSessionEvents(session, options);
 
@@ -381,7 +572,7 @@ export async function runAgent(
       if (!softLimitReached && turnCount >= maxTurns) {
         softLimitReached = true;
         session.steer("You have reached your turn limit. Wrap up immediately — provide your final answer now.");
-      } else if (softLimitReached && turnCount >= maxTurns + GRACE_TURNS) {
+      } else if (softLimitReached && turnCount >= maxTurns + graceTurns) {
         aborted = true;
         session.abort();
       }

package/src/agent-types.ts

@@ -3,24 +3,36 @@
  *
  * Merges embedded default agents with user-defined agents from .pi/agents/*.md.
  * User agents override defaults with the same name. Disabled agents are kept but excluded from spawning.
- *
- * Trimmed from upstream: removed getMemoryToolNames(), getReadOnlyMemoryToolNames(),
- * MEMORY_TOOL_NAMES, READONLY_MEMORY_TOOL_NAMES (memory feature cut).
  */
 
+import { scanAgentFilesInDir, mergeAgents } from "./agent-discovery.js";
 import { DEFAULT_AGENTS } from "./default-agents.js";
 import type { AgentConfig } from "./types.js";
 
-/** All known built-in tool names. */
-const BUILTIN_TOOL_NAMES: string[] = ["read", "bash", "edit", "write", "grep", "find", "ls"];
+/**
+ * All tool names that Pi can provide to a session.
+ *
+ * Note: only `read`, `bash`, `edit`, `write` are active by default.
+ * `grep` must be explicitly activated via setActiveToolsByName().
+ * `find` and `ls` were removed — they're thin wrappers over bash commands
+ * that add ~180 tokens/turn with no real benefit.
+ */
+export const BUILTIN_TOOL_NAMES: string[] = ["read", "bash", "edit", "write", "grep"];
 
 /** Unified runtime registry of all agents (defaults + user-defined). */
 const agents = new Map<string, AgentConfig>();
 
+/**
+ * Directories to scan for agent .md files at startup and on-demand.
+ * Set by setAgentScanDirs() during session_start.
+ */
+let userAgentDir = "";
+let projectAgentDir = "";
+
 /**
  * Register agents into the unified registry.
  * Starts with DEFAULT_AGENTS, then overlays user agents (overrides defaults with same name).
- * Disabled agents (enabled === false) are kept in the registry but excluded from spawning.
+ * Hidden agents (hidden === true) are kept in the registry but excluded from spawning.
  */
 export function registerAgents(userAgents: Map<string, AgentConfig>): void {
   agents.clear();
@@ -36,6 +48,37 @@ export function registerAgents(userAgents: Map<string, AgentConfig>): void {
   }
 }
 
+/**
+ * Set the agent scan directories for on-demand discovery.
+ * Called during session_start alongside scanAndRegisterAgents.
+ */
+export function setAgentScanDirs(userDir: string, projectDir: string): void {
+  userAgentDir = userDir;
+  projectAgentDir = projectDir;
+}
+
+/**
+ * Scan the known agent directories and register any newly discovered agents
+ * that aren't already in the registry. Returns the number of new agents added.
+ */
+export async function discoverNewAgents(): Promise<number> {
+  const [userAgents, projectAgents] = await Promise.all([
+    scanAgentFilesInDir(userAgentDir, "user"),
+    scanAgentFilesInDir(projectAgentDir, "project"),
+  ]);
+
+  const merged = mergeAgents(DEFAULT_AGENTS, userAgents, projectAgents);
+
+  let count = 0;
+  for (const [name, config] of merged) {
+    if (!agents.has(name)) {
+      agents.set(name, config);
+      count++;
+    }
+  }
+  return count;
+}
+
 /** Resolve a type name case-insensitively. Also matches displayName. Returns the canonical key or undefined. */
 export function resolveType(name: string): string | undefined {
   if (!name) return undefined;
@@ -54,14 +97,14 @@ export function getAgentConfig(name: string): AgentConfig | undefined {
   return key ? agents.get(key) : undefined;
 }
 
-/** Get all enabled type names (for spawning and tool descriptions). */
+/** Get all visible type names (for spawning and tool descriptions). */
 export function getAvailableTypes(): string[] {
   return [...agents.entries()]
-    .filter(([_, config]) => config.enabled !== false)
+    .filter(([_, config]) => config.hidden !== true)
     .map(([name]) => name);
 }
 
-/** Get all type names including disabled (for UI listing). */
+/** Get all type names including hidden (for UI listing). */
 export function getAllTypes(): string[] {
   return [...agents.keys()];
 }
@@ -69,16 +112,18 @@ export function getAllTypes(): string[] {
 /** Get built-in tool names for a type (case-insensitive). */
 export function getToolNamesForType(type: string): string[] {
   const config = getAgentConfig(type);
-  return config?.builtinToolNames?.length
-    ? config.builtinToolNames
+  return config?.registeredTools?.length
+    ? config.registeredTools
     : [...BUILTIN_TOOL_NAMES];
 }
 
 /** Resolved config shape returned by getConfig. */
-interface ResolvedAgentConfig {
+export interface ResolvedAgentConfig {
   displayName: string;
   description: string;
-  builtinToolNames: string[];
+  registeredTools: string[];
+  /** Controls tool schema visibility. true = all, string[] = listed, false = none. */
+  tools?: true | string[] | false;
   extensions: true | string[] | false;
   skills: true | string[] | false;
 }
@@ -87,7 +132,8 @@ function toResolved(config: AgentConfig): ResolvedAgentConfig {
   return {
     displayName: config.displayName ?? config.name,
     description: config.description,
-    builtinToolNames: config.builtinToolNames ?? BUILTIN_TOOL_NAMES,
+    registeredTools: config.registeredTools ?? BUILTIN_TOOL_NAMES,
+    tools: config.tools,
     extensions: config.extensions,
     skills: config.skills,
   };
@@ -98,20 +144,20 @@ export function getConfig(type: string): ResolvedAgentConfig {
   const resolvedKey = resolveType(type);
   const config = resolvedKey ? agents.get(resolvedKey) : undefined;
 
-  // If config exists and is enabled, use it; otherwise fall back to general-purpose
-  const activeConfig = config?.enabled !== false
+  // If config exists and is not hidden, use it; otherwise fall back to general-purpose
+  const activeConfig = config?.hidden !== true
     ? config
     : agents.get("general-purpose");
 
-  if (activeConfig && activeConfig.enabled !== false) {
+  if (activeConfig && activeConfig.hidden !== true) {
     return toResolved(activeConfig);
   }
 
-  // Absolute fallback — general-purpose was disabled or missing
+  // Absolute fallback — general-purpose was hidden or missing
   return {
     displayName: "Agent",
     description: "General-purpose agent for complex, multi-step tasks",
-    builtinToolNames: BUILTIN_TOOL_NAMES,
+    registeredTools: BUILTIN_TOOL_NAMES,
     extensions: true,
     skills: true,
   };

package/src/config-io.ts

@@ -14,7 +14,7 @@ const CONFIG_PATH = path.join(CONFIG_DIR, "subagents-lite.json");
 
 /** Default configuration — used when config file doesn't exist or is invalid. */
 export const DEFAULT_CONFIG: SubagentsConfig = {
-  agent: { default: null, forceBackground: false },
+  agent: { default: null, forceBackground: false, graceTurns: 6 },
   concurrency: { default: 4 },
 };
 
@@ -24,10 +24,8 @@ export function loadConfig(): SubagentsConfig {
     const raw = fs.readFileSync(CONFIG_PATH, "utf-8");
     return JSON.parse(raw) as SubagentsConfig;
   } catch {
-    // File doesn't exist or is invalid — return defaults
+    return { ...DEFAULT_CONFIG, agent: { ...DEFAULT_CONFIG.agent }, concurrency: { ...DEFAULT_CONFIG.concurrency } };
   }
-
-  return { ...DEFAULT_CONFIG, agent: { ...DEFAULT_CONFIG.agent }, concurrency: { ...DEFAULT_CONFIG.concurrency } };
 }
 
 /** Write config to disk with atomic rename. */

package/src/context.ts

@@ -1,18 +1,21 @@
 /**
- * context.ts — Extract parent conversation context for subagent inheritance.
+ * context.ts — Message content extraction and conversation snapshot formatting.
  *
- * Contains extractText (for message content) and buildSnapshotMarkdown
- * (for agent session snapshot viewer). buildParentContext was removed
- * when inherit_context was cut.
+ * extractText: pull text from message content blocks.
+ * buildSnapshotMarkdown: format agent conversation as markdown for snapshot viewer.
  */
 
 import { summarizeToolArgs } from "./output-file.js";
 
+function isTextBlock(c: unknown): c is { type: "text"; text: string } {
+  return typeof c === "object" && c !== null && (c as Record<string, unknown>).type === "text";
+}
+
 /** Extract text from a message content block array. */
 export function extractText(content: unknown[]): string {
   return content
-    .filter((c: any) => c.type === "text")
-    .map((c: any) => c.text ?? "")
+    .filter(isTextBlock)
+    .map((c) => c.text)
     .join("\n");
 }
 

package/src/default-agents.ts

@@ -7,7 +7,7 @@
 
 import type { AgentConfig } from "./types.js";
 
-const READ_ONLY_TOOLS = ["read", "bash", "grep", "find", "ls"];
+const READ_ONLY_TOOLS = ["read", "bash", "grep"];
 
 export const DEFAULT_AGENTS: Map<string, AgentConfig> = new Map([
   [
@@ -16,7 +16,7 @@ export const DEFAULT_AGENTS: Map<string, AgentConfig> = new Map([
       name: "general-purpose",
       displayName: "Agent",
       description: "General-purpose agent for complex, multi-step tasks",
-      // builtinToolNames omitted — means "all available tools" (resolved at lookup time)
+      // registeredTools omitted — means "all available tools" (resolved at lookup time)
       extensions: true,
       skills: true,
       systemPrompt: "",
@@ -29,7 +29,7 @@ export const DEFAULT_AGENTS: Map<string, AgentConfig> = new Map([
       name: "Explore",
       displayName: "Explore",
       description: "Fast codebase exploration agent (read-only)",
-      builtinToolNames: READ_ONLY_TOOLS,
+      registeredTools: READ_ONLY_TOOLS,
       extensions: true,
       skills: true,
       model: "anthropic/claude-haiku-4-5-20251001",