@swarmify/agents-mcp 0.2.3 → 0.2.5

package/README.md

@@ -1,21 +1,22 @@
 # @swarmify/agents-mcp
 
-Run subagents from any MCP client.
+Run Subagents, Swarm or Ralph Wiggums from any MCP client.
 
-Spawn CLI agents in parallel so your main agent stays focused. Each subagent runs
-in its own context and can be polled for progress.
+Spawn CLI agents in parallel so your main agent stays focused. Each subagent runs in its own context and can be polled for progress.
+
+Homepage: https://swarmify.co
+NPM: https://www.npmjs.com/package/@swarmify/agents-mcp
+VS Code Extension: https://marketplace.visualstudio.com/items?itemName=swarmify.swarm-ext
 
 ## Why This Exists
 
-MCP adoption is accelerating and the ecosystem is organizing around registries,
-gateways, and enterprise governance. At the same time, teams are pushing toward
-multi-agent workflows and running into orchestration reliability, tool overload,
-and security concerns. This server gives you a focused, practical building block
-for real-world swarm work.
+MCP adoption is accelerating and the ecosystem is organizing around registries, gateways, and enterprise governance. At the same time, teams are pushing toward multi-agent workflows and running into orchestration reliability, tool overload, and security concerns. This server gives you a focused, practical building block for real-world swarm work.
+
+The API surface is intentionally small, closer to iconic commands like `cd`, `ls`, and `git` than a framework. Fewer knobs means less room for an orchestrator to make mistakes.
 
 ## What You Get
 
-- MCP server with `spawn`, `status`, `stop`, and `tasks` tools
+- A dead simple MCP server with `Spawn`, `Status`, `Stop`, and `Tasks` tools
 - The `/swarm` command to teach an orchestrator how to distribute work
 - Plan vs edit modes that control file access per agent
 - Local logs and durable processes that survive IDE restarts
@@ -24,10 +25,13 @@ for real-world swarm work.
 
 ```bash
 # Claude Code
-claude mcp add swarmify-agents -- npx -y @swarmify/agents-mcp
+claude mcp add --scope user Swarm -- npx -y @swarmify/agents-mcp
+
+# Codex
+codex mcp add swarm -- npx -y @swarmify/agents-mcp@latest
 
 # Gemini CLI
-gemini mcp add swarmify-agents -- npx -y @swarmify/agents-mcp
+gemini mcp add Swarm -- npx -y @swarmify/agents-mcp
 
 # OpenCode (interactive)
 opencode mcp add
@@ -43,56 +47,54 @@ The server auto-discovers which agent CLIs you have installed.
 - Parallelize tasks across Claude, Codex, Gemini, and Cursor
 - Keep long-running loops responsive by offloading work to subagents
 - Integrate with MCP registries and gateways without changing your workflow
+- Run Ralph Wiggum loops inside spawned Claude Code agents when the plugin is installed
 
 ## Under the Hood
 
-Headless CLI agents run as background processes. Output streams to
-`~/.swarmify/agents/{id}/stdout.log`.
+Headless CLI agents run as background processes. Output streams to `~/.swarmify/agents/{id}/stdout.log`.
 
 Plan mode is read-only:
+
 - Claude: `--permission-mode plan`
 - Codex: sandboxed (no `--full-auto`)
 - Gemini and Cursor: no auto-approve flags
 
 Edit mode unlocks writes:
+
 - Codex: `--full-auto`
 - Claude: `acceptEdits`
 - Gemini: `--yolo`
 - Cursor: `-f`
 
-Agents are detached from the MCP server process. Close your IDE and reopen it,
-then reconnect with `status` and `tasks`.
+Agents are detached from the MCP server process. Close your IDE and reopen it, then reconnect with `Status` and `Tasks`.
 
 ## Common Questions
 
-**"Isn't this overkill for simple tasks?"**
-Yes. For typo fixes or small changes, one agent is fine. But for implementing a complex feature across 20 files, a single agent drowning in context is slower than a focused swarm working in parallel.
+**"Isn't this overkill for simple tasks?**"Yes. For typo fixes or small changes, one agent is fine. But for implementing a complex feature across 20 files, a single agent drowning in context is slower than a focused swarm working in parallel.
 
-**"What if agents conflict?"**
-They don't. The orchestrator (via `/swarm` command) assigns each agent specific files—no overlap. For shared files, it runs agents in sequential waves so there's no collision.
+**"What if agents conflict?**"They don't. The orchestrator (via `/swarm` command) assigns each agent specific files—no overlap. For shared files, it runs agents in sequential waves so there's no collision.
 
-**"How do I monitor what's happening?"**
-Use the Swarm `status` tool to see what each agent is doing: files changed, commands run, last messages. No black box—full visibility into the swarm.
+**"How do I monitor what's happening?**"Use the Swarm `Status` tool to see what each agent is doing: files changed, commands run, last messages. No black box—full visibility into the swarm.
 
 ## API Reference
 
 ### Tools
 
 | Tool | Description |
-|------|-------------|
-| `spawn` | Start an agent on a task. Returns immediately with agent ID. |
-| `status` | Get agent progress: files changed, commands run, last messages. |
-| `stop` | Stop one agent or all agents in a task. |
-| `tasks` | List all tasks with their agents and activity. |
+| --- | --- |
+| `Spawn` | Start an agent on a task. Returns immediately with agent ID. |
+| `Status` | Get agent progress: files changed, commands run, last messages. |
+| `Stop` | Stop one agent or all agents in a task. |
+| `Tasks` | List all tasks with their agents and activity. |
 
-### spawn
+### Spawn
 
 ```
-spawn(task_name, agent_type, prompt, mode?, cwd?, effort?)
+Spawn(task_name, agent_type, prompt, mode?, cwd?, effort?)
 ```
 
 | Parameter | Required | Description |
-|-----------|----------|-------------|
+| --- | --- | --- |
 | `task_name` | Yes | Groups related agents (e.g., "auth-feature") |
 | `agent_type` | Yes | `claude`, `codex`, `gemini`, or `cursor` |
 | `prompt` | Yes | The task for the agent |
@@ -100,54 +102,53 @@ spawn(task_name, agent_type, prompt, mode?, cwd?, effort?)
 | `cwd` | No | Working directory for the agent |
 | `effort` | No | `fast`, `default` (implicit), or `detailed` for max-capability models |
 
-### status
+### Status
 
 ```
-status(task_name, filter?)
+Status(task_name, filter?)
 ```
 
 | Parameter | Required | Description |
-|-----------|----------|-------------|
+| --- | --- | --- |
 | `task_name` | Yes | Task to check |
 | `filter` | No | `running` (default), `completed`, `failed`, `stopped`, or `all` |
 
-Returns files created/modified/read/deleted, bash commands executed, and last
-messages.
+Returns files created/modified/read/deleted, bash commands executed, and last messages.
 
-### stop
+### Stop
 
 ```
-stop(task_name, agent_id?)
+Stop(task_name, agent_id?)
 ```
 
 Stop all agents in a task, or a specific agent by ID.
 
-### tasks
+### Tasks
 
 ```
-tasks(limit?)
+Tasks(limit?)
 ```
 
-List all tasks sorted by most recent activity.
+List all tasks sorted by most recent activity. Defaults to 10 tasks when limit is omitted.
 
 ## Token Optimization
 
 This server is designed to minimize token usage for the calling agent:
 
 | Optimization | Benefit |
-|--------------|---------|
+| --- | --- |
 | Status defaults to `filter='running'` | Only shows active agents, not completed history |
 | Bash commands truncated to 120 chars | Heredocs collapsed to `cat <<EOF > path` |
 | Last 5 messages only | Not full conversation history |
 | File operations deduplicated | Sets of created/modified/read/deleted paths |
-| Spawn returns immediately | No blocking, poll with status later |
+| Spawn returns immediately | No blocking, poll with Status later |
 
 ## Supported Agents
 
 The server auto-discovers installed CLIs at startup:
 
 | Agent | CLI | Best For |
-|-------|-----|----------|
+| --- | --- | --- |
 | Claude | `claude` | Best for complex research and open-ended exploration |
 | Codex | `codex` | Fast, cheap. Self-contained features |
 | Gemini | `gemini` | Complex multi-system features, architectural changes |
@@ -156,7 +157,7 @@ The server auto-discovers installed CLIs at startup:
 ## Modes
 
 | Mode | File Access | Auto-loops? | Use Case |
-|------|-------------|-------------|----------|
+| --- | --- | --- | --- |
 | `plan` | Read-only | No | Research, exploration, code review |
 | `edit` | Read + Write | No | Implementation, refactoring, fixes |
 | `ralph` | Full yolo | Yes | Autonomous iteration through RALPH.md tasks |
@@ -196,16 +197,18 @@ Cover auth endpoints.
 ```
 
 **How it works:**
+
 1. Create a `RALPH.md` file in your project directory with tasks
-2. Call `spawn(mode='ralph', cwd='./my-project', prompt='Build the auth system')`
+2. Call `Spawn(mode='ralph', cwd='./my-project', prompt='Build the auth system')`
 3. MCP spawns ONE agent with full permissions
 4. Agent reads RALPH.md, understands the system, picks tasks logically
 5. For each task: completes work, marks checkbox `## [x]`, adds update
-6. Continues until all tasks checked (or you stop it with `stop` tool)
+6. Continues until all tasks checked (or you stop it with `Stop` tool)
 
 **Multiple ralph agents:** You can spawn multiple ralph agents in parallel for different directories or different RALPH.md files. The orchestrator controls this.
 
 **Safety:**
+
 - Scoped by `cwd` - orchestrator controls blast radius
 - RALPH.md must exist before spawn
 - Warns if used in home/system directories
@@ -214,18 +217,60 @@ Cover auth endpoints.
 ## Effort Levels
 
 | Level | Models Used |
-|-------|-------------|
+| --- | --- |
 | `fast` | codex: gpt-5.2-codex, claude: claude-haiku-4-5, gemini: gemini-3-flash, cursor: composer-1 |
 | `default` | codex: gpt-5.2-codex, claude: claude-sonnet-4-5, gemini: gemini-3-flash, cursor: composer-1 |
 | `detailed` | codex: gpt-5.1-codex-max, claude: claude-opus-4-5, gemini: gemini-3-pro, cursor: composer-1 |
 
+## Config
+
+Config lives at `~/.swarmify/config.json`.
+
+Example with per-agent swarm selection and effort model overrides:
+
+```json
+{
+  "agents": {
+    "claude": {
+      "swarm": true,
+      "effort": {
+        "models": {
+          "fast": "claude-haiku-4-5-20251001",
+          "default": "claude-sonnet-4-5",
+          "detailed": "claude-opus-4-5"
+        }
+      }
+    },
+    "codex": { "swarm": true },
+    "gemini": { "swarm": true },
+    "cursor": { "swarm": false }
+  }
+}
+```
+
+Shorthand for a single effort level override:
+
+```json
+{
+  "agents": {
+    "claude": {
+      "swarm": true,
+      "effort": {
+        "level": "fast",
+        "model": "claude-haiku-4-5-20251001"
+      }
+    }
+  }
+}
+```
+
 ## Environment Variables
 
 | Variable | Description |
-|----------|-------------|
-| `AGENT_SWARM_DEFAULT_MODE` | Set default mode (`plan` or `edit`) |
-| `AGENTS_SWARM_RALPH_FILE` | Task file name for ralph mode (default: `RALPH.md`) |
-| `AGENTS_SWARM_DISABLE_RALPH` | Set to `true` or `1` to disable ralph mode |
+| --- | --- |
+| `AGENTS_MCP_DEFAULT_MODE` | Set default mode (`plan` or `edit`) |
+| `AGENTS_MCP_RALPH_FILE` | Task file name for ralph mode (default: `RALPH.md`) |
+| `AGENTS_MCP_DISABLE_RALPH` | Set to `true` or `1` to disable ralph mode |
 
 ## Storage
 

package/dist/agents.d.ts

@@ -1,4 +1,11 @@
+import { type ModelOverrides } from './persistence.js';
 import { AgentType } from './parsers.js';
+/**
+ * Compute the Lowest Common Ancestor (LCA) of multiple file paths.
+ * Returns the deepest common directory shared by all paths.
+ * Returns null if paths is empty or paths have no common ancestor (different roots).
+ */
+export declare function computePathLCA(paths: string[]): string | null;
 export declare enum AgentStatus {
     RUNNING = "running",
     COMPLETED = "completed",
@@ -8,7 +15,9 @@ export declare enum AgentStatus {
 export type { AgentType } from './parsers.js';
 export declare const AGENT_COMMANDS: Record<AgentType, string[]>;
 export type EffortLevel = 'fast' | 'default' | 'detailed';
-export declare const EFFORT_MODEL_MAP: Record<EffortLevel, Record<AgentType, string>>;
+export type EffortModelMap = Record<EffortLevel, Record<AgentType, string>>;
+export declare const EFFORT_MODEL_MAP: EffortModelMap;
+export declare function resolveEffortModelMap(base: EffortModelMap, overrides: ModelOverrides | null | undefined): EffortModelMap;
 declare const VALID_MODES: readonly ["plan", "edit", "ralph"];
 type Mode = typeof VALID_MODES[number];
 export declare function resolveMode(requestedMode: string | null | undefined, defaultMode?: Mode): Mode;
@@ -25,15 +34,17 @@ export declare class AgentProcess {
     agentType: AgentType;
     prompt: string;
     cwd: string | null;
+    workspaceDir: string | null;
     mode: Mode;
     pid: number | null;
     status: AgentStatus;
     startedAt: Date;
     completedAt: Date | null;
+    parentSessionId: string | null;
     private eventsCache;
     private lastReadPos;
     private baseDir;
-    constructor(agentId: string, taskName: string, agentType: AgentType, prompt: string, cwd?: string | null, mode?: Mode, pid?: number | null, status?: AgentStatus, startedAt?: Date, completedAt?: Date | null, baseDir?: string | null);
+    constructor(agentId: string, taskName: string, agentType: AgentType, prompt: string, cwd?: string | null, mode?: Mode, pid?: number | null, status?: AgentStatus, startedAt?: Date, completedAt?: Date | null, baseDir?: string | null, parentSessionId?: string | null, workspaceDir?: string | null);
     get isEditMode(): boolean;
     getAgentDir(): Promise<string>;
     getStdoutPath(): Promise<string>;
@@ -61,12 +72,14 @@ export declare class AgentManager {
     private filterByCwd;
     private cleanupAgeDays;
     private defaultMode;
+    private effortModelMap;
     private constructorAgentsDir;
-    constructor(maxAgents?: number, maxConcurrent?: number, agentsDir?: string | null, defaultMode?: Mode | null, filterByCwd?: string | null, cleanupAgeDays?: number);
+    constructor(maxAgents?: number, maxConcurrent?: number, agentsDir?: string | null, defaultMode?: Mode | null, filterByCwd?: string | null, cleanupAgeDays?: number, modelOverrides?: ModelOverrides | null);
     private initialize;
     getDefaultMode(): Mode;
+    setModelOverrides(overrides: ModelOverrides | null | undefined): void;
     private loadExistingAgents;
-    spawn(taskName: string, agentType: AgentType, prompt: string, cwd?: string | null, mode?: Mode | null, effort?: EffortLevel): Promise<AgentProcess>;
+    spawn(taskName: string, agentType: AgentType, prompt: string, cwd?: string | null, mode?: Mode | null, effort?: EffortLevel, parentSessionId?: string | null, workspaceDir?: string | null): Promise<AgentProcess>;
     private buildCommand;
     private applyEditMode;
     private applyRalphMode;
@@ -75,6 +88,7 @@ export declare class AgentManager {
     listRunning(): Promise<AgentProcess[]>;
     listCompleted(): Promise<AgentProcess[]>;
     listByTask(taskName: string): Promise<AgentProcess[]>;
+    listByParentSession(parentSessionId: string): Promise<AgentProcess[]>;
     stopByTask(taskName: string): Promise<{
         stopped: string[];
         alreadyStopped: string[];

package/dist/agents.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../src/agents.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../src/agents.ts"],"names":[],"mappings":"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"}

package/dist/agents.js

@@ -5,6 +5,43 @@ import * as os from 'os';
 import { randomUUID } from 'crypto';
 import { resolveAgentsDir } from './persistence.js';
 import { normalizeEvents } from './parsers.js';
+/**
+ * Compute the Lowest Common Ancestor (LCA) of multiple file paths.
+ * Returns the deepest common directory shared by all paths.
+ * Returns null if paths is empty or paths have no common ancestor (different roots).
+ */
+export function computePathLCA(paths) {
+    const validPaths = paths.filter(p => p && p.trim());
+    if (validPaths.length === 0)
+        return null;
+    if (validPaths.length === 1)
+        return validPaths[0];
+    // Normalize and split all paths into segments
+    const splitPaths = validPaths.map(p => {
+        const normalized = path.resolve(p);
+        // Split by path separator, filter empty segments
+        return normalized.split(path.sep).filter(seg => seg);
+    });
+    // Find minimum length
+    const minLen = Math.min(...splitPaths.map(p => p.length));
+    // Find common prefix
+    const commonSegments = [];
+    for (let i = 0; i < minLen; i++) {
+        const segment = splitPaths[0][i];
+        const allMatch = splitPaths.every(p => p[i] === segment);
+        if (allMatch) {
+            commonSegments.push(segment);
+        }
+        else {
+            break;
+        }
+    }
+    if (commonSegments.length === 0)
+        return null;
+    // Reconstruct path (add leading separator for absolute paths)
+    const lca = path.sep + commonSegments.join(path.sep);
+    return lca;
+}
 export var AgentStatus;
 (function (AgentStatus) {
     AgentStatus["RUNNING"] = "running";
@@ -43,6 +80,32 @@ export const EFFORT_MODEL_MAP = {
         cursor: 'composer-1',
     },
 };
+export function resolveEffortModelMap(base, overrides) {
+    const resolved = {
+        fast: { ...base.fast },
+        default: { ...base.default },
+        detailed: { ...base.detailed },
+    };
+    if (!overrides)
+        return resolved;
+    for (const [agentType, effortOverrides] of Object.entries(overrides)) {
+        if (!effortOverrides)
+            continue;
+        if (!['codex', 'gemini', 'cursor', 'claude'].includes(agentType))
+            continue;
+        const typedAgent = agentType;
+        for (const level of ['fast', 'default', 'detailed']) {
+            const model = effortOverrides[level];
+            if (typeof model === 'string') {
+                const trimmed = model.trim();
+                if (trimmed) {
+                    resolved[level][typedAgent] = trimmed;
+                }
+            }
+        }
+    }
+    return resolved;
+}
 // Suffix appended to all prompts to ensure agents provide a summary
 const PROMPT_SUFFIX = `
 
@@ -65,7 +128,7 @@ function normalizeModeValue(modeValue) {
     return null;
 }
 function defaultModeFromEnv() {
-    for (const envVar of ['AGENT_SWARM_MODE', 'AGENT_SWARM_DEFAULT_MODE']) {
+    for (const envVar of ['AGENTS_MCP_MODE', 'AGENTS_MCP_DEFAULT_MODE']) {
         const rawValue = process.env[envVar];
         const parsed = normalizeModeValue(rawValue);
         if (parsed) {
@@ -77,6 +140,49 @@ function defaultModeFromEnv() {
     }
     return 'plan';
 }
+function coerceDate(value) {
+    if (value === null || value === undefined)
+        return null;
+    if (typeof value === 'number' && Number.isFinite(value)) {
+        const ms = value < 1e12 ? value * 1000 : value;
+        const date = new Date(ms);
+        return Number.isNaN(date.getTime()) ? null : date;
+    }
+    if (typeof value === 'string') {
+        const trimmed = value.trim();
+        if (!trimmed)
+            return null;
+        const numeric = Number(trimmed);
+        if (!Number.isNaN(numeric)) {
+            const ms = numeric < 1e12 ? numeric * 1000 : numeric;
+            const date = new Date(ms);
+            if (!Number.isNaN(date.getTime()))
+                return date;
+        }
+        const date = new Date(trimmed);
+        return Number.isNaN(date.getTime()) ? null : date;
+    }
+    return null;
+}
+function extractTimestamp(raw) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const candidates = [
+        raw.timestamp,
+        raw.time,
+        raw.created_at,
+        raw.createdAt,
+        raw.ts,
+        raw.started_at,
+        raw.startedAt,
+    ];
+    for (const candidate of candidates) {
+        const date = coerceDate(candidate);
+        if (date)
+            return date;
+    }
+    return null;
+}
 export function resolveMode(requestedMode, defaultMode = 'plan') {
     const normalizedDefault = normalizeModeValue(defaultMode);
     if (!normalizedDefault) {
@@ -131,26 +237,30 @@ export class AgentProcess {
     agentType;
     prompt;
     cwd;
+    workspaceDir;
     mode = 'plan';
     pid = null;
     status = AgentStatus.RUNNING;
     startedAt = new Date();
     completedAt = null;
+    parentSessionId = null;
     eventsCache = [];
     lastReadPos = 0;
     baseDir = null;
-    constructor(agentId, taskName, agentType, prompt, cwd = null, mode = 'plan', pid = null, status = AgentStatus.RUNNING, startedAt = new Date(), completedAt = null, baseDir = null) {
+    constructor(agentId, taskName, agentType, prompt, cwd = null, mode = 'plan', pid = null, status = AgentStatus.RUNNING, startedAt = new Date(), completedAt = null, baseDir = null, parentSessionId = null, workspaceDir = null) {
         this.agentId = agentId;
         this.taskName = taskName;
         this.agentType = agentType;
         this.prompt = prompt;
         this.cwd = cwd;
+        this.workspaceDir = workspaceDir;
         this.mode = mode;
         this.pid = pid;
         this.status = status;
         this.startedAt = startedAt;
         this.completedAt = completedAt;
         this.baseDir = baseDir;
+        this.parentSessionId = parentSessionId;
     }
     get isEditMode() {
         return this.mode === 'edit';
@@ -176,6 +286,8 @@ export class AgentProcess {
             event_count: this.events.length,
             duration: this.duration(),
             mode: this.mode,
+            parent_session_id: this.parentSessionId,
+            workspace_dir: this.workspaceDir,
         };
     }
     duration() {
@@ -225,6 +337,7 @@ export class AgentProcess {
             const stats = await fs.stat(stdoutPath).catch(() => null);
             if (!stats)
                 return;
+            const fallbackTimestamp = (stats.mtime || new Date()).toISOString();
             const fd = await fs.open(stdoutPath, 'r');
             const buffer = Buffer.alloc(1024 * 1024);
             const { bytesRead } = await fd.read(buffer, 0, buffer.length, this.lastReadPos);
@@ -238,7 +351,9 @@ export class AgentProcess {
                 try {
                     const rawEvent = JSON.parse(line);
                     const events = normalizeEvents(this.agentType, rawEvent);
+                    const resolvedTimestamp = extractTimestamp(rawEvent)?.toISOString() || fallbackTimestamp;
                     for (const event of events) {
+                        event.timestamp = resolvedTimestamp;
                         this.eventsCache.push(event);
                         if (event.type === 'result' || event.type === 'turn.completed' || event.type === 'thread.completed') {
                             if (event.status === 'success' || event.type === 'turn.completed') {
@@ -256,7 +371,7 @@ export class AgentProcess {
                     this.eventsCache.push({
                         type: 'raw',
                         content: line,
-                        timestamp: new Date().toISOString(),
+                        timestamp: fallbackTimestamp,
                     });
                 }
             }
@@ -274,11 +389,13 @@ export class AgentProcess {
             agent_type: this.agentType,
             prompt: this.prompt,
             cwd: this.cwd,
+            workspace_dir: this.workspaceDir,
             mode: this.mode,
             pid: this.pid,
             status: this.status,
             started_at: this.startedAt.toISOString(),
             completed_at: this.completedAt?.toISOString() || null,
+            parent_session_id: this.parentSessionId,
         };
         const metaPath = await this.getMetaPath();
         await fs.writeFile(metaPath, JSON.stringify(meta, null, 2));
@@ -296,7 +413,7 @@ export class AgentProcess {
         try {
             const metaContent = await fs.readFile(metaPath, 'utf-8');
             const meta = JSON.parse(metaContent);
-            const agent = new AgentProcess(meta.agent_id, meta.task_name || 'default', meta.agent_type, meta.prompt, meta.cwd || null, meta.mode === 'edit' ? 'edit' : 'plan', meta.pid || null, AgentStatus[meta.status] || AgentStatus.RUNNING, new Date(meta.started_at), meta.completed_at ? new Date(meta.completed_at) : null, baseDir);
+            const agent = new AgentProcess(meta.agent_id, meta.task_name || 'default', meta.agent_type, meta.prompt, meta.cwd || null, meta.mode === 'edit' ? 'edit' : 'plan', meta.pid || null, AgentStatus[meta.status] || AgentStatus.RUNNING, new Date(meta.started_at), meta.completed_at ? new Date(meta.completed_at) : null, baseDir, meta.parent_session_id || null, meta.workspace_dir || null);
             return agent;
         }
         catch {
@@ -321,11 +438,11 @@ export class AgentProcess {
             await this.readNewEvents();
             return;
         }
-        const fallbackCompletion = this.getLatestEventTime() || this.startedAt || new Date();
         if (this.status === AgentStatus.RUNNING) {
             const exitCode = await this.reapProcess();
             await this.readNewEvents();
             if (this.status === AgentStatus.RUNNING) {
+                const fallbackCompletion = this.getLatestEventTime() || this.startedAt || new Date();
                 if (exitCode !== null && exitCode !== 0) {
                     this.status = AgentStatus.FAILED;
                 }
@@ -336,6 +453,8 @@ export class AgentProcess {
             }
         }
         else if (!this.completedAt) {
+            await this.readNewEvents();
+            const fallbackCompletion = this.getLatestEventTime() || this.startedAt || new Date();
             this.completedAt = fallbackCompletion;
         }
         await this.saveMeta();
@@ -360,8 +479,9 @@ export class AgentManager {
     filterByCwd;
     cleanupAgeDays;
     defaultMode;
+    effortModelMap = EFFORT_MODEL_MAP;
     constructorAgentsDir = null;
-    constructor(maxAgents = 50, maxConcurrent = 10, agentsDir = null, defaultMode = null, filterByCwd = null, cleanupAgeDays = 7) {
+    constructor(maxAgents = 50, maxConcurrent = 10, agentsDir = null, defaultMode = null, filterByCwd = null, cleanupAgeDays = 7, modelOverrides = null) {
         this.maxAgents = maxAgents;
         this.maxConcurrent = maxConcurrent;
         this.constructorAgentsDir = agentsDir;
@@ -372,6 +492,7 @@ export class AgentManager {
             throw new Error(`Invalid default_mode '${defaultMode}'. Use 'plan' or 'edit'.`);
         }
         this.defaultMode = resolvedDefaultMode;
+        this.effortModelMap = resolveEffortModelMap(EFFORT_MODEL_MAP, modelOverrides);
         this.initialize();
     }
     async initialize() {
@@ -382,6 +503,9 @@ export class AgentManager {
     getDefaultMode() {
         return this.defaultMode;
     }
+    setModelOverrides(overrides) {
+        this.effortModelMap = resolveEffortModelMap(EFFORT_MODEL_MAP, overrides);
+    }
     async loadExistingAgents() {
         try {
             await fs.access(this.agentsDir);
@@ -432,11 +556,11 @@ export class AgentManager {
         }
         console.error(`Loaded ${loadedCount} agents from disk`);
     }
-    async spawn(taskName, agentType, prompt, cwd = null, mode = null, effort = 'default') {
+    async spawn(taskName, agentType, prompt, cwd = null, mode = null, effort = 'default', parentSessionId = null, workspaceDir = null) {
         await this.initialize();
         const resolvedMode = resolveMode(mode, this.defaultMode);
         // Resolve model from effort level
-        const resolvedModel = EFFORT_MODEL_MAP[effort][agentType];
+        const resolvedModel = this.effortModelMap[effort][agentType];
         const running = await this.listRunning();
         if (running.length >= this.maxConcurrent) {
             throw new Error(`Maximum concurrent agents (${this.maxConcurrent}) reached. Wait for an agent to complete or stop one first.`);
@@ -459,7 +583,7 @@ export class AgentManager {
         }
         const agentId = randomUUID().substring(0, 8);
         const cmd = this.buildCommand(agentType, prompt, resolvedMode, resolvedModel, resolvedCwd);
-        const agent = new AgentProcess(agentId, taskName, agentType, prompt, resolvedCwd, resolvedMode, null, AgentStatus.RUNNING, new Date(), null, this.agentsDir);
+        const agent = new AgentProcess(agentId, taskName, agentType, prompt, resolvedCwd, resolvedMode, null, AgentStatus.RUNNING, new Date(), null, this.agentsDir, parentSessionId, workspaceDir);
         const agentDir = await agent.getAgentDir();
         try {
             await fs.mkdir(agentDir, { recursive: true });
@@ -618,6 +742,10 @@ export class AgentManager {
         const all = await this.listAll();
         return all.filter(a => a.taskName === taskName);
     }
+    async listByParentSession(parentSessionId) {
+        const all = await this.listAll();
+        return all.filter(a => a.parentSessionId === parentSessionId);
+    }
     async stopByTask(taskName) {
         const agents = await this.listByTask(taskName);
         const stopped = [];