@pi-archimedes/subagent 1.8.2 → 1.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-archimedes/subagent",
-  "version": "1.8.2",
+  "version": "1.9.0",
   "type": "module",
   "keywords": [
     "pi-package"
@@ -11,7 +11,7 @@
   ],
   "main": "./src/index.ts",
   "dependencies": {
-    "@pi-archimedes/core": "1.8.2"
+    "@pi-archimedes/core": "1.9.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": ">=0.1.0",

package/src/agent-manager.ts

@@ -14,6 +14,13 @@ import {
 import type { AgentConfig } from "./agents.js";
 import { discoverAgentsAll } from "./agents.js";
 import { serializeAgent, validateAgentName } from "./frontmatter-io.js";
+import {
+  writeLocalModel,
+  deleteLocalModel,
+  readLocalConfig,
+  setLocalConfig,
+  type LocalConfig,
+} from "./local-config.js";
 
 // ── Screen constants ────────────────────────────────────────────────────────
 
@@ -1204,7 +1211,7 @@ function setFieldValue(agent: AgentConfig, field: EditField, value: string): voi
 
 // ── Save logic ──────────────────────────────────────────────────────────────
 
-function saveAgent(state: ManagerState, requestRender: () => void): void {
+export function saveAgent(state: ManagerState, requestRender: () => void): void {
   if (!state.editAgent) return;
 
   const agent = state.editAgent;
@@ -1241,18 +1248,77 @@ function saveAgent(state: ManagerState, requestRender: () => void): void {
   const newName = agent.name.endsWith(".md") ? agent.name : `${agent.name}.md`;
   const newPath = path.join(dir, newName);
 
+  // Capture model before entering the try block so it is available in the
+  // catch block for .md rollback if a later step (JSON write, etc.) fails.
+  const model = agent.model;
+
+  // Track whether the .md write succeeded so the catch block knows whether
+  // to restore or clean up the on-disk file.
+  const isRename = oldPath && oldPath !== newPath;
+  let originalContent: string | undefined;
+  if (!isRename && fs.existsSync(newPath)) {
+    // Read existing .md content so we can restore it verbatim if a later
+    // step (JSON write, re-discovery, etc.) fails.
+    originalContent = fs.readFileSync(newPath, "utf-8");
+  }
+  let mdWritten = false;
+  // Track whether the old .md file was already removed during a rename so
+  // the catch block knows whether newPath is the sole surviving copy.
+  let oldPathDeleted = false;
+  // Track whether the JSON config write succeeded so the catch block can
+  // roll it back if a later step (re-discovery, etc.) fails.
+  let jsonWritten = false;
+  // Snapshot of the JSON config captured before the write so the catch
+  // block can restore it. Declared here (not inside try) so it is
+  // accessible in the catch block.
+  let jsonConfigBefore: LocalConfig = {};
+
   try {
     // Ensure directory exists
     fs.mkdirSync(dir, { recursive: true });
 
-    // Serialize and write
-    const content = serializeAgent(agent);
+    // Build a shallow copy without the model for .md serialization so the
+    // live edit object is NOT mutated during serialization. If the .md
+    // write fails below, the live object stays intact for a retry.
+    const mdAgent = { ...agent };
+    delete mdAgent.model;
+
+    // Serialize and write the .md file FIRST. If this fails, no JSON state
+    // is persisted and the live edit object is untouched.
+    const content = serializeAgent(mdAgent);
     fs.writeFileSync(newPath, content, "utf-8");
+    mdWritten = true;
+
+    // Only after the .md write succeeds, perform JSON store mutations.
+    // Capture a backup of the current JSON config so we can roll it back
+    // if a later step (re-discovery, etc.) fails after this write succeeds.
+    jsonConfigBefore = readLocalConfig();
+    // Write/remove the NEW name entry first, then clean up the OLD name.
+    if (model !== undefined) {
+      writeLocalModel(agent.name, model);
+    } else {
+      deleteLocalModel(agent.name);
+    }
+    jsonWritten = true;
+
+    // Handle rename: delete old JSON entry keyed by original name (after
+    // the new entry is safely written). Wrapped in try-catch so a failure
+    // here does not leave the .md written but the live object un-stripped.
+    const originalName = state.editOriginal?.name;
+    if (originalName && originalName !== agent.name) {
+      try {
+        deleteLocalModel(originalName);
+      } catch {
+        // Best-effort: stale entry is harmless and will be cleaned up on
+        // a subsequent save/rename
+      }
+    }
 
-    // Handle rename if name changed
+    // Handle rename: delete old .md file if name changed
     if (oldPath && oldPath !== newPath) {
       try {
         fs.unlinkSync(oldPath);
+        oldPathDeleted = true;
       } catch {
         // Old file may not exist (e.g., new agent)
       }
@@ -1281,7 +1347,52 @@ function saveAgent(state: ManagerState, requestRender: () => void): void {
     state.editDirty = false;
     state.editError = null;
     requestRender();
+
+    // Only strip model from the live edit object AFTER all operations
+    // (including re-discovery) have succeeded. This ensures that if any
+    // step fails, the catch block can restore the model to .md and the
+    // live object retains it for a safe retry.
+    delete agent.model;
   } catch (err) {
+    // Restore prior .md state if the write succeeded but a later step
+    // (JSON write, re-discovery, etc.) failed:
+    //   - rename (old file not yet unlinked): check whether the old file
+    //     still exists. If so, delete newPath so only the original remains.
+    //     If the old file is gone (deleted externally or by a prior attempt),
+    //     newPath may be the sole copy — keep it with a model fallback, or
+    //     delete it when there is no model to fall back on.
+    //   - existing file: write the original content back verbatim.
+    //   - new file with a model: keep a frontmatter fallback so the model
+    //     override survives for the next retry.
+    // If the old .md was already unlinked during rename (oldPathDeleted),
+    // newPath is the sole surviving copy — leave it in place.
+    // If the .md write itself failed (mdWritten is false) there is nothing
+    // to restore on disk.
+    if (mdWritten) {
+      if (isRename && !oldPathDeleted) {
+        if (oldPath && fs.existsSync(oldPath)) {
+          // Old file still exists — safe to delete newPath and restore prior state
+          try { fs.unlinkSync(newPath); } catch { /* best-effort */ }
+        } else if (model !== undefined) {
+          // Old file is gone — keep newPath with model as fallback
+          try { fs.writeFileSync(newPath, serializeAgent({ ...agent, model }), "utf-8"); } catch { /* best-effort */ }
+        } else {
+          // Old file is gone and no model — delete newPath (no prior state to restore)
+          try { fs.unlinkSync(newPath); } catch { /* best-effort */ }
+        }
+      } else if (originalContent !== undefined) {
+        try { fs.writeFileSync(newPath, originalContent, "utf-8"); } catch { /* best-effort */ }
+      } else if (model !== undefined) {
+        try { fs.writeFileSync(newPath, serializeAgent({ ...agent, model }), "utf-8"); } catch { /* best-effort */ }
+      } else {
+        // New file without model — delete it (no prior state to restore)
+        try { fs.unlinkSync(newPath); } catch { /* best-effort */ }
+      }
+    }
+    // Roll back JSON if it was written but a later step failed
+    if (jsonWritten) {
+      try { setLocalConfig(jsonConfigBefore); } catch { /* best-effort */ }
+    }
     state.editError = err instanceof Error ? err.message : "Failed to save agent";
     requestRender();
   }

package/src/agents.test.ts

@@ -0,0 +1,109 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import type { AgentConfig } from "./agents.js";
+import { applyLocalOverrides, formatAgentList } from "./agents.js";
+
+// Redirect getAgentDir() to a temp directory via PI_CODING_AGENT_DIR.
+// This must happen before any function calls so readLocalConfig()
+// resolves agents.local.json to our sandbox directory.
+const testDir = join(tmpdir(), "pi-test-local-config-agents");
+process.env.PI_CODING_AGENT_DIR = testDir;
+
+function makeAgent(
+  name: string,
+  model?: string,
+): AgentConfig {
+  return {
+    name,
+    description: `Agent ${name}`,
+    systemPrompt: "hello",
+    source: "global" as const,
+    filePath: join(testDir, `${name}.md`),
+    ...(model !== undefined ? { model } : {}),
+  };
+}
+
+describe("applyLocalOverrides", () => {
+  beforeEach(() => {
+    mkdirSync(testDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    rmSync(testDir, { recursive: true, force: true });
+  });
+
+  it("sets model from JSON override", () => {
+    const path = join(testDir, "agents.local.json");
+    writeFileSync(path, JSON.stringify({ codex: { model: "o1" } }), "utf-8");
+
+    const agent = makeAgent("codex");
+    applyLocalOverrides([agent]);
+    expect(agent.model).toBe("o1");
+  });
+
+  it("leaves model unchanged when no JSON entry exists", () => {
+    const agent = makeAgent("codex", "M1");
+    applyLocalOverrides([agent]);
+    expect(agent.model).toBe("M1");
+  });
+
+  it("leaves model unchanged when JSON entry has no model field", () => {
+    const path = join(testDir, "agents.local.json");
+    writeFileSync(path, JSON.stringify({ codex: {} }), "utf-8");
+
+    const agent = makeAgent("codex", "M1");
+    applyLocalOverrides([agent]);
+    expect(agent.model).toBe("M1");
+  });
+
+  it("handles empty agent list", () => {
+    expect(() => applyLocalOverrides([])).not.toThrow();
+  });
+
+  it("works with corrupt JSON file (agent model stays unchanged)", () => {
+    const path = join(testDir, "agents.local.json");
+    writeFileSync(path, "{ broken json", "utf-8");
+
+    const agent = makeAgent("codex", "M1");
+    applyLocalOverrides([agent]);
+    expect(agent.model).toBe("M1");
+  });
+});
+
+function mkAgent(overrides: Partial<AgentConfig> & Pick<AgentConfig, "name">): AgentConfig {
+  return {
+    name: overrides.name,
+    description: overrides.description ?? "desc",
+    systemPrompt: overrides.systemPrompt ?? "prompt",
+    source: overrides.source ?? "user",
+    filePath: overrides.filePath ?? "/x.md",
+    ...(overrides.model !== undefined ? { model: overrides.model } : {}),
+    ...(overrides.tools !== undefined ? { tools: overrides.tools } : {}),
+  };
+}
+
+describe("formatAgentList", () => {
+  it("reports no agents when empty", () => {
+    expect(formatAgentList([])).toContain("No agents configured");
+  });
+
+  it("formats a single agent (singular)", () => {
+    const out = formatAgentList([mkAgent({ name: "general" })]);
+    expect(out).toContain("1 agent:");
+    expect(out).toContain("• general [user] — desc");
+  });
+
+  it("formats multiple agents (plural)", () => {
+    const out = formatAgentList([mkAgent({ name: "general" }), mkAgent({ name: "explore" })]);
+    expect(out).toContain("2 agents:");
+  });
+
+  it("includes model and tools overrides only when set", () => {
+    const withExtras = formatAgentList([mkAgent({ name: "reviewer", model: "anthropic/claude-sonnet-4-5", tools: ["read", "bash"] })]);
+    expect(withExtras).toContain("(model: anthropic/claude-sonnet-4-5, 2 tools)");
+    const withoutExtras = formatAgentList([mkAgent({ name: "general" })]);
+    expect(withoutExtras).not.toMatch(/\(model:|tools\)/);
+  });
+});

package/src/agents.ts

@@ -7,6 +7,7 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
+import { readLocalConfig } from "./local-config.js";
 
 export interface AgentConfig {
   name: string;
@@ -136,6 +137,20 @@ export interface AgentsDiscoveryResult {
   projectDir: string | null; // e.g., .pi/agents or null if not found
 }
 
+/**
+ * Apply local model overrides from agents.local.json to a list of agents.
+ * Reads the config once and mutates matching agents in place.
+ */
+export function applyLocalOverrides(agents: AgentConfig[]): void {
+  const config = readLocalConfig();
+  for (const agent of agents) {
+    const local = config[agent.name];
+    if (local?.model !== undefined) {
+      agent.model = local.model;
+    }
+  }
+}
+
 /**
  * Discover all available agents from global, user and/or project directories.
  * Precedence (highest last): global < user < project
@@ -155,7 +170,9 @@ export function discoverAgents(cwd: string): AgentConfig[] {
   for (const agent of userAgents) agentMap.set(agent.name, agent);
   for (const agent of projectAgents) agentMap.set(agent.name, agent);
 
-  return Array.from(agentMap.values());
+  const all = Array.from(agentMap.values());
+  applyLocalOverrides(all);
+  return all;
 }
 
 /**
@@ -170,6 +187,10 @@ export function discoverAgentsAll(cwd: string): AgentsDiscoveryResult {
   const userAgents = loadAgentsFromDir(userDir, "user");
   const projectAgents = projectDir ? loadAgentsFromDir(projectDir, "project") : [];
 
+  applyLocalOverrides(globalAgents);
+  applyLocalOverrides(userAgents);
+  applyLocalOverrides(projectAgents);
+
   return {
     global: globalAgents,
     user: userAgents,
@@ -186,3 +207,23 @@ export function discoverAgentsAll(cwd: string): AgentsDiscoveryResult {
 export function findAgent(agents: AgentConfig[], name: string): AgentConfig | undefined {
   return agents.find((a) => a.name === name);
 }
+
+/**
+ * Format discovered agents as a compact, readable listing for the `list_agents`
+ * tool. Standard detail: name, source, description, and model/tools overrides
+ * only when set.
+ */
+export function formatAgentList(agents: AgentConfig[]): string {
+  if (agents.length === 0) {
+    return "No agents configured. Create one in ~/.pi/agent/agents/ or .agents/agents/.";
+  }
+  const lines = agents.map((a) => {
+    let line = `• ${a.name} [${a.source}] — ${a.description}`;
+    const extras: string[] = [];
+    if (a.model) extras.push(`model: ${a.model}`);
+    if (a.tools && a.tools.length > 0) extras.push(`${a.tools.length} tools`);
+    if (extras.length > 0) line += ` (${extras.join(", ")})`;
+    return line;
+  });
+  return `${agents.length} agent${agents.length === 1 ? "" : "s"}:\n${lines.join("\n")}`;
+}

package/src/compact.ts

@@ -1,5 +1,5 @@
 import { Text } from "@earendil-works/pi-tui";
-import type { SubagentDetails, SubagentProgress, SubagentResult, SubagentToolResult } from "./types.js";
+import type { SubagentDetails, SubagentProgress, SubagentResult, SubagentToolCall, SubagentToolResult } from "./types.js";
 import { formatTokens, formatDuration, formatCost, truncLine, buildStatsLine, buildAgentLabel } from "./format.js";
 
 type Theme = { fg: (token: string, text: string) => string; bold: (text: string) => string };
@@ -14,7 +14,7 @@ interface ActivityData {
   finalOutput: string | undefined;
   status: "running" | "completed" | "failed" | undefined;
   error: string | undefined;
-  toolCalls?: string[] | undefined;
+  toolCalls?: (SubagentToolCall | string)[] | undefined;
 }
 
 export function buildActivityLine(
@@ -35,7 +35,7 @@ export function buildActivityLine(
     return theme.fg("error", "✗ Failed");
   }
 
-  // Running: show the current tool with live duration
+  // Running: show the current tool with live duration (grey while running)
   if (data.currentTool) {
     const arrow = theme.fg("muted", "↳ ");
     const argsPreview = data.currentToolArgs
@@ -44,7 +44,7 @@ export function buildActivityLine(
     const durationPart = data.currentToolStartedAt
       ? " | " + formatDuration(Date.now() - data.currentToolStartedAt)
       : "";
-    let line = theme.fg("syntaxFunction", data.currentTool);
+    let line = theme.fg("muted", data.currentTool);
     if (argsPreview) {
       line += theme.fg("dim", ": " + argsPreview);
     }
@@ -55,9 +55,21 @@ export function buildActivityLine(
   }
 
   // Running, no active tool: show the most recently completed tool call
+  // Color only the tool name green (success) or red (error)
   if (data.toolCalls && data.toolCalls.length > 0) {
     const lastCall = data.toolCalls[data.toolCalls.length - 1];
-    if (lastCall) return theme.fg("muted", "↳ " + lastCall);
+    if (lastCall) {
+      if (typeof lastCall === "string") {
+        return theme.fg("dim", "↳ " + truncLine(lastCall, 60));
+      }
+      const color = lastCall.error ? "error" : "success";
+      const arrow = theme.fg("muted", "↳ ");
+      const name = theme.fg(color, lastCall.name);
+      const argsPart = lastCall.argsPreview
+        ? theme.fg("dim", ": " + truncLine(lastCall.argsPreview, 60))
+        : "";
+      return arrow + name + argsPart;
+    }
   }
 
   // Running, no tool history: show first line of streamed output if any

package/src/expanded.ts

@@ -1,9 +1,25 @@
 import { Text } from "@earendil-works/pi-tui";
-import type { SubagentDetails, SubagentProgress, SubagentResult } from "./types.js";
+import type { SubagentDetails, SubagentProgress, SubagentResult, SubagentToolCall } from "./types.js";
 import { formatTokens, formatDuration, truncLine, buildStatsLine, buildAgentLabel } from "./format.js";
 
 type Theme = { fg: (token: string, text: string) => string; bold: (text: string) => string };
 
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+function formatToolCall(call: SubagentToolCall | string, theme: Theme): string {
+  // Backward compat: old persisted sessions may have toolCalls as string[]
+  if (typeof call === "string") {
+    return theme.fg("dim", "↳ " + call);
+  }
+  const arrow = theme.fg("muted", "↳ ");
+  const color = call.error ? "error" : "success";
+  const name = theme.fg(color, call.name);
+  const argsPart = call.argsPreview
+    ? theme.fg("dim", ": " + call.argsPreview)
+    : "";
+  return arrow + name + argsPart;
+}
+
 // ── Expanded completed result ───────────────────────────────────────────────
 
 export function buildExpandedText(
@@ -43,7 +59,7 @@ export function buildExpandedText(
   if (toolCalls && toolCalls.length > 0) {
     lines.push("");
     for (const call of toolCalls) {
-      lines.push(theme.fg("dim", "↳ " + call));
+      lines.push(formatToolCall(call, theme));
     }
   }
 
@@ -116,7 +132,7 @@ export function renderProgressExpanded(
   if (progress.toolCalls && progress.toolCalls.length > 0) {
     lines.push("");
     for (const call of progress.toolCalls) {
-      lines.push(theme.fg("dim", "↳ " + call));
+      lines.push(formatToolCall(call, theme));
     }
   }
 
@@ -129,7 +145,7 @@ export function renderProgressExpanded(
     const durationPart = progress.currentToolStartedAt
       ? " | " + formatDuration(Date.now() - progress.currentToolStartedAt)
       : "";
-    let line = theme.fg("syntaxFunction", progress.currentTool);
+    let line = theme.fg("muted", progress.currentTool);
     if (argsPreview) {
       line += theme.fg("dim", ": " + argsPreview);
     }
@@ -192,7 +208,7 @@ export function buildProgressExpandedText(
   if (progress.toolCalls && progress.toolCalls.length > 0) {
     lines.push("");
     for (const call of progress.toolCalls) {
-      lines.push(theme.fg("dim", "↳ " + call));
+      lines.push(formatToolCall(call, theme));
     }
   }
 
@@ -204,7 +220,7 @@ export function buildProgressExpandedText(
     const durationPart = progress.currentToolStartedAt
       ? " | " + formatDuration(Date.now() - progress.currentToolStartedAt)
       : "";
-    let line = theme.fg("syntaxFunction", progress.currentTool);
+    let line = theme.fg("muted", progress.currentTool);
     if (argsPreview) {
       line += theme.fg("dim", ": " + argsPreview);
     }

package/src/handlers.ts

@@ -50,11 +50,16 @@ export function extractArgsPreview(args: unknown): string {
 export function handleToolStart(state: StreamState, event: JsonEvent): void {
   state.toolCount++;
   state.currentTool = event.toolName as string;
-  state.currentToolArgs = JSON.stringify(event.args);
+  // Use extractArgsPreview instead of JSON.stringify for readable display
+  const argsPreview = extractArgsPreview(event.args);
+  state.currentToolArgs = argsPreview;
   state.currentToolStartedAt = Date.now();
   // Record tool call with args preview
-  const argsPreview = extractArgsPreview(event.args);
-  state.toolCalls.push(`${state.currentTool}: ${argsPreview}`);
+  state.toolCalls.push({
+    name: state.currentTool,
+    argsPreview,
+    error: false,
+  });
   if (state.toolCalls.length > TOOL_CALLS_MAX) {
     state.toolCalls.splice(0, state.toolCalls.length - TOOL_CALLS_MAX);
   }
@@ -75,6 +80,14 @@ export function handleToolEnd(state: StreamState): void {
  */
 export function handleToolResult(state: StreamState, event: JsonEvent): void {
   const result = event.result as Record<string, unknown> | undefined;
+
+  // Mark the last tool call as errored if the result indicates an error
+  const lastCall = state.toolCalls[state.toolCalls.length - 1];
+  const isError = event.isError === true || result?.isError === true;
+  if (lastCall && lastCall.name === (event.toolName as string) && isError) {
+    lastCall.error = true;
+  }
+
   if (!result) return;
 
   const toolName = (event.toolName as string) ?? "tool";

package/src/index.ts

@@ -3,7 +3,8 @@ import { Text, TUI } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 // execute.js + agent-manager.js lazy-loaded below to keep subagent tool registration fast
 import { renderSubagentResult } from "./render.js";
-import { discoverAgents, discoverAgentsAll, findAgent } from "./agents.js";
+import { discoverAgents, discoverAgentsAll, findAgent, formatAgentList } from "./agents.js";
+import { validateModel, firstError } from "./model-validation.js";
 import type {
   SubagentDetails,
   SubagentProgress,
@@ -14,7 +15,9 @@ import type {
 // ── JSON Schema for tool parameters (TypeBox) ──────────────────────────────
 
 const TaskItem = Type.Object({
-  agent: Type.Optional(Type.String()),
+  agent: Type.Optional(Type.String({
+    description: "Agent name for this task (optional). If omitted, runs config-less.",
+  })),
   task: Type.String(),
   model: Type.Optional(Type.String()),
   cwd: Type.Optional(Type.String()),
@@ -22,7 +25,7 @@ const TaskItem = Type.Object({
 
 const SUBAGENT_PARAMS_SCHEMA = Type.Object({
   agent: Type.Optional(Type.String({
-    description: "Agent name/identifier (optional, defaults to 'general')",
+    description: "Agent name (optional). If omitted, the subagent runs config-less — parent's current model, all tools, no system-prompt override. Call list_agents to see available agents.",
   })),
   task: Type.Optional(Type.String({
     description: "Task description for the subagent. Required when not using 'tasks' array.",
@@ -55,7 +58,7 @@ export function registerSubagent(pi: ExtensionAPI): void {
     name: "subagent",
     label: "Subagent",
     description:
-      "Delegate tasks to subagents. Provide either 'task' (single) or 'tasks' (parallel). Never omit both. Options: agent, model, cwd.",
+      "Delegate tasks to subagents. Provide either 'task' (single) or 'tasks' (parallel). Agent is optional — omit for a config-less run with the parent's model and all tools. Model override is rarely needed; the agent config or parent model is used by default.",
     parameters: SUBAGENT_PARAMS_SCHEMA,
 
     async execute(
@@ -78,12 +81,34 @@ export function registerSubagent(pi: ExtensionAPI): void {
 
       // Parallel mode
       if (params.tasks && params.tasks.length > 0) {
-        const missingAgents = params.tasks.filter((t) => t.agent && !findAgent(agents, t.agent));
-        if (missingAgents.length > 0) {
+        // Combined pre-spawn checks for parallel mode: unknown agents + invalid
+        // models. If ANY task is invalid, abort the whole batch with a single
+        // tool result listing all errors (no tasks spawn).
+        const errors: string[] = [];
+        const unknownAgents = params.tasks
+          .filter((t) => t.agent && !findAgent(agents, t.agent!))
+          .map((t) => `"${t.agent}"`);
+        if (unknownAgents.length > 0) {
           const available = agents.map((a) => a.name).join(", ") || "none";
-          const unknown = missingAgents.map((t) => `"${t.agent}"`).join(", ");
+          errors.push(`Unknown agent(s): ${unknownAgents.join(", ")}. Available: ${available}. Call list_agents for details.`);
+        }
+        const unknownAgentSet = new Set(unknownAgents.map((n) => n.replace(/"/g, '')));
+        for (const t of params.tasks) {
+          // Skip model validation for tasks already caught by unknown-agent check
+          if (t.agent && unknownAgentSet.has(t.agent)) continue;
+          const taskAgentConfig = t.agent ? findAgent(agents, t.agent) : undefined;
+          const me = firstError(
+            validateModel(t.model, ctx.modelRegistry, { agentName: t.agent }),
+            validateModel(taskAgentConfig?.model, ctx.modelRegistry, {
+              agentName: t.agent,
+              agentFilePath: taskAgentConfig?.filePath,
+            }),
+          );
+          if (me) errors.push(me);
+        }
+        if (errors.length > 0) {
           return {
-            content: [{ type: "text", text: `Unknown agent(s): ${unknown}. Available: ${available}` }],
+            content: [{ type: "text", text: errors.join("\n") }],
             details: {
               mode: "parallel",
               results: [],
@@ -134,7 +159,7 @@ export function registerSubagent(pi: ExtensionAPI): void {
         if (params.agent && !agentConfig) {
           const available = agents.map((a) => a.name).join(", ") || "none";
           return {
-            content: [{ type: "text", text: `Unknown agent: "${params.agent}". Available: ${available}` }],
+            content: [{ type: "text", text: `Unknown agent: "${params.agent}". Available: ${available}. Call list_agents for details.` }],
             details: {
               mode: "single",
               results: [],
@@ -143,6 +168,22 @@ export function registerSubagent(pi: ExtensionAPI): void {
             isError: true,
           };
         }
+        // Pre-spawn model validation (P2): fail fast with a friendly error
+        // instead of spawning a child that will crash on a bogus --model.
+        const modelError = firstError(
+          validateModel(params.model, ctx.modelRegistry, { agentName: params.agent }),
+          validateModel(agentConfig?.model, ctx.modelRegistry, {
+            agentName: params.agent,
+            agentFilePath: agentConfig?.filePath,
+          }),
+        );
+        if (modelError) {
+          return {
+            content: [{ type: "text", text: modelError }],
+            details: { mode: "single", results: [], progress: undefined },
+            isError: true,
+          };
+        }
         const result: SubagentResult = await executeSubagent({
           agent: params.agent ?? undefined,
           agentConfig,
@@ -234,10 +275,29 @@ export function registerSubagent(pi: ExtensionAPI): void {
       }
     },
   });
+
+  registerListAgentsTool(pi);
 }
 
 // ── Helpers ─────────────────────────────────────────────────────────────────
 
+export function registerListAgentsTool(pi: ExtensionAPI): void {
+  pi.registerTool({
+    name: "list_agents",
+    label: "Agents",
+    description:
+      "List available subagent configurations (name, description, source, model/tools overrides). Call before dispatching if unsure which agents exist or which fits the task.",
+    parameters: Type.Object({}),
+    async execute(_id, _params, _signal, _onUpdate, ctx) {
+      const agents = discoverAgents(ctx.cwd);
+      return {
+        content: [{ type: "text" as const, text: formatAgentList(agents) }],
+        details: { count: agents.length },
+      };
+    },
+  });
+}
+
 function formatProgressSummary(progress: SubagentProgress[]): string {
   if (progress.length === 0) return "";
   const lines = progress.map((p) => {