@bastani/atomic 0.9.9 → 0.9.10-alpha.1

package/dist/builtin/mcp/README.md

@@ -114,7 +114,8 @@ Pi-specific files are the write targets for imported or shared global servers wh
       "command": "npx",
       "args": ["-y", "some-mcp-server"],
       "lifecycle": "lazy",
-      "idleTimeout": 10
+      "idleTimeout": 10,
+      "timeoutMs": 30000
     }
   }
 }
@@ -133,11 +134,14 @@ Pi-specific files are the write targets for imported or shared global servers wh
 | `bearerToken` / `bearerTokenEnv` | Token or env var name; `bearerToken` supports `${VAR}` and `$env:VAR` interpolation |
 | `lifecycle` | `"lazy"` (default), `"eager"`, or `"keep-alive"` |
 | `idleTimeout` | Minutes before idle disconnect (overrides global) |
+| `timeoutMs` | Per-tool-call inactivity timeout in milliseconds for local or remote servers; omit to use the MCP SDK default |
 | `exposeResources` | Expose MCP resources as tools (default: true) |
 | `directTools` | `true`, `string[]`, or `false` — register tools individually instead of through proxy |
 | `excludeTools` | `string[]` of tool names to hide (matches original names like `get_screenshot` and prefixed names like `figma_get_screenshot`) |
 | `debug` | Show server stderr (default: false) |
 
+`timeoutMs` is an **inactivity timeout**, not a total wall-clock limit. Each MCP progress notification resets the timer, so a tool that continues reporting progress can run indefinitely. The value must be a finite number greater than zero; invalid values produce a configuration error when the MCP config loads.
+
 ### Lifecycle Modes
 
 - **`lazy`** (default) — Don't connect at startup. Connect on first tool call or explicit cold-cache proxy metadata request (`search`, `describe`, or `server` list). Disconnect after idle timeout. Cached metadata keeps search/list working without connections.
@@ -336,7 +340,7 @@ Prefer `.mcp.json` for project-local shared MCP config. Use `.pi/mcp.json` only
 | Connect | `mcp({ connect: "server-name" })` |
 | UI messages | `mcp({ action: "ui-messages" })` |
 
-MCP proxy and direct-tool results render compactly by default: long text shows the first three lines plus a `Ctrl+o Expand` hint, while the full result remains available when expanded and is still returned unchanged to the model.
+MCP proxy and direct-tool results render compactly by default: long text shows the first three lines plus a `ctrl+o Expand` hint, while the full result remains available when expanded and is still returned unchanged to the model.
 
 Search includes both MCP tools and Pi tools (from extensions). Pi tools appear first with `[pi tool]` prefix. Space-separated words are OR'd.
 

package/dist/builtin/mcp/config.ts

@@ -6,8 +6,9 @@ import { CONFIG_DIR_NAME, getProjectConfigPaths } from "@bastani/atomic";
 import { getAgentPath, getAgentPaths } from "./agent-dir.ts";
 import type { McpConfig, ServerEntry, McpSettings, ImportKind, ServerProvenance } from "./types.ts";
 import { buildConfigWritePreview, getServersObject, readRawConfigObject, setServersObject, writeRawConfigObject, type ConfigWritePreview } from "./config-write-utils.ts";
+import { MCP_TIMEOUT_MS_CONFIG_ERROR, McpTimeoutConfigError, validateMcpServerTimeouts } from "./tool-call-timeout.js";
+export { MCP_TIMEOUT_MS_CONFIG_ERROR };
 export type { ConfigWritePreview } from "./config-write-utils.ts";
-
 const GENERIC_GLOBAL_CONFIG_PATH = join(homedir(), ".config", "mcp", "mcp.json");
 const PROJECT_CONFIG_NAME = ".mcp.json";
 const PROJECT_PI_CONFIG_NAME = `${CONFIG_DIR_NAME}/mcp.json`;
@@ -25,7 +26,6 @@ const IMPORT_PATHS: Record<ImportKind, string[]> = {
   windsurf: [join(homedir(), ".windsurf", "mcp.json")],
   vscode: [".vscode/mcp.json"],
 };
-
 interface ConfigSourceSpec {
   id: "shared-global" | "pi-global" | "shared-project" | "pi-project";
   label: string;
@@ -36,13 +36,11 @@ interface ConfigSourceSpec {
   shared: boolean;
   scope: "global" | "project";
 }
-
 export interface ConfigDiscoveryPath {
   label: string;
   path: string;
   exists: boolean;
 }
-
 export interface DiscoveredImportConfig {
   kind: ImportKind;
   path: string;
@@ -248,6 +246,7 @@ function expandImports(config: McpConfig, cwd = process.cwd()): McpConfig {
         }
       }
     } catch (error) {
+      if (error instanceof McpTimeoutConfigError) throw error;
       console.warn(`Failed to import MCP config from ${importKind}:`, error);
     }
   }
@@ -278,13 +277,14 @@ function getImportServerCount(importKind: ImportKind, path: string): number {
 function readValidatedConfig(path: string, label: string): McpConfig | null {
   if (!existsSync(path)) return null;
   try {
-    return validateConfig(JSON.parse(readFileSync(path, "utf-8")));
+    return validateMcpConfig(JSON.parse(readFileSync(path, "utf-8")));
   } catch (error) {
+    if (error instanceof McpTimeoutConfigError) throw error;
     console.warn(`Failed to load ${label}:`, error);
     return null;
   }
 }
-function validateConfig(raw: unknown): McpConfig {
+export function validateMcpConfig(raw: unknown): McpConfig {
   if (!raw || typeof raw !== "object") {
     return { mcpServers: {} };
   }
@@ -294,7 +294,7 @@ function validateConfig(raw: unknown): McpConfig {
     return { mcpServers: {} };
   }
   return {
-    mcpServers: servers as Record<string, ServerEntry>,
+    mcpServers: validateMcpServerTimeouts(servers as Record<string, unknown>),
     imports: Array.isArray(obj.imports) ? (obj.imports as ImportKind[]) : undefined,
     settings: obj.settings as McpSettings | undefined,
   };
@@ -320,7 +320,7 @@ function extractServers(config: unknown, kind: ImportKind): Record<string, Serve
   if (!servers || typeof servers !== "object" || Array.isArray(servers)) {
     return {};
   }
-  return servers as Record<string, ServerEntry>;
+  return validateMcpServerTimeouts(servers as Record<string, unknown>);
 }
 function isRepoPromptServer(name: string, entry: ServerEntry): boolean {
   const normalizedName = name.toLowerCase();

package/dist/builtin/mcp/direct-tool-executor.ts

@@ -1,5 +1,4 @@
 import type { AgentToolResult, AgentToolUpdateCallback, ExtensionContext } from "@bastani/atomic";
-import { CallToolResultSchema } from "@modelcontextprotocol/sdk/types.js";
 import type { McpExtensionState } from "./state.js";
 import type { DirectToolSpec, McpContent } from "./types.js";
 import { getFailureAgeSeconds, lazyConnect } from "./init.js";
@@ -11,6 +10,7 @@ import { formatAuthRequiredMessage, unflattenToolArguments } from "./utils.js";
 import { waitForCaller, waitForCallerWithLateCleanup } from "./caller-wait.js";
 import { notifyUiCancellation, rethrowHostAbortAfterUiCancellation } from "./apps-cancellation.js";
 import { asCallToolResult } from "./call-tool-result.js";
+import { callToolWithConfiguredTimeout, formatMcpToolCallFailure } from "./tool-call-timeout.js";
 
 interface DirectToolStateChangedDetails extends Record<string, unknown> {
   error: "state_changed";
@@ -166,6 +166,7 @@ export function createDirectToolExecutor(
         details: { error: "not_connected", server: spec.serverName },
       };
     }
+    const definition = state.config.mcpServers[spec.serverName] ?? connection.definition;
 
     let uiSession: UiSessionRuntime | null = null;
     let closeUiForStaleState = false;
@@ -221,11 +222,11 @@ export function createDirectToolExecutor(
       signal?.throwIfAborted();
       if (!isActiveStateOwner(state)) return cancelStaleUi();
 
-      const sdkResult = await connection.client.callTool({
+      const sdkResult = await callToolWithConfiguredTimeout(connection.client, {
         name: spec.originalName,
         arguments: unflattenToolArguments(params, spec.inputSchema),
         _meta: uiSession?.requestMeta,
-      }, CallToolResultSchema, { signal });
+      }, definition, spec.serverName, signal);
       signal?.throwIfAborted();
       if (!isActiveStateOwner(state)) return cancelStaleUi();
       const result = asCallToolResult(sdkResult);
@@ -258,11 +259,11 @@ export function createDirectToolExecutor(
       };
     } catch (error) {
       await rethrowHostAbortAfterUiCancellation(signal, uiSession);
-      const message = error instanceof Error ? error.message : String(error);
-      await notifyUiCancellation(uiSession, message);
+      const cancellationMessage = error instanceof Error ? error.message : String(error);
+      await notifyUiCancellation(uiSession, cancellationMessage);
       signal?.throwIfAborted();
       if (!isActiveStateOwner(state)) return staleStateResult();
-      let errorText = `Failed to call tool: ${message}`;
+      let errorText = formatMcpToolCallFailure(error, spec.serverName, definition.timeoutMs);
       if (spec.inputSchema) errorText += `\n\nExpected parameters:\n${formatSchema(spec.inputSchema)}`;
       return {
         content: [{ type: "text" as const, text: errorText }],

package/dist/builtin/mcp/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/mcp",
-  "version": "0.9.9",
+  "version": "0.9.10-alpha.1",
   "private": true,
   "description": "Atomic extension that adapts MCP (Model Context Protocol) servers into the coding agent. Fork of: https://github.com/nicobailon/pi-mcp-adapter",
   "contributors": [
@@ -32,8 +32,8 @@
   },
   "peerDependencies": {
     "@bastani/atomic": "*",
-    "@earendil-works/pi-ai": "^0.80.7",
-    "@earendil-works/pi-tui": "^0.80.7",
+    "@earendil-works/pi-ai": "^0.80.10",
+    "@earendil-works/pi-tui": "^0.80.10",
     "zod": "^3.25.0 || ^4.0.0"
   },
   "peerDependenciesMeta": {

package/dist/builtin/mcp/proxy-call.ts

@@ -9,11 +9,11 @@ import { maybeStartUiSession, type UiSessionRuntime } from "./ui-session.js";
 import { unflattenToolArguments } from "./utils.js";
 import { attemptAutoAuth, getAuthRequiredMessage, type AutoAuthResult } from "./proxy-auth.js";
 import type { ProxyToolResult } from "./proxy-types.js";
-import { CallToolResultSchema } from "@modelcontextprotocol/sdk/types.js";
 import { waitForCaller, waitForCallerWithLateCleanup } from "./caller-wait.js";
 import { notifyUiCancellation, rethrowHostAbortAfterUiCancellation } from "./apps-cancellation.js";
 import { asCallToolResult } from "./call-tool-result.js";
 import { assertMcpStateLease, McpStateChangedError, type AssertMcpStateLease } from "./state-lease.js";
+import { callToolWithConfiguredTimeout, formatMcpToolCallFailure } from "./tool-call-timeout.js";
 
 export async function executeCall(
   state: McpExtensionState,
@@ -297,6 +297,7 @@ export async function executeCall(
       };
     }
   }
+  const definition = state.config.mcpServers[serverName] ?? connection.definition;
 
   let uiSession: UiSessionRuntime | null = null;
 
@@ -339,7 +340,7 @@ export async function executeCall(
     assertMcpStateLease(assertActive);
 
     assertMcpStateLease(assertActive);
-    const resultPromise = connection.client.callTool({
+    const resultPromise = callToolWithConfiguredTimeout(connection.client, {
       name: toolMeta.originalName,
       // Normalize provider-flattened argument keys (e.g. Gemini's `keywords[0]`)
       // back into arrays/objects before the MCP server validates them.
@@ -347,7 +348,7 @@ export async function executeCall(
       // preserved unless the schema proves the head is a container.
       arguments: unflattenToolArguments(args, toolMeta.inputSchema),
       _meta: uiSession?.requestMeta,
-    }, CallToolResultSchema, { signal });
+    }, definition, serverName, signal);
 
     if (toolMeta.uiResourceUri) {
       const sdkResult = await resultPromise;
@@ -420,7 +421,7 @@ export async function executeCall(
     signal?.throwIfAborted();
     assertMcpStateLease(assertActive);
 
-    let errorWithSchema = `Failed to call tool: ${message}`;
+    let errorWithSchema = formatMcpToolCallFailure(error, serverName, definition.timeoutMs);
     if (toolMeta.inputSchema) {
       errorWithSchema += `\n\nExpected parameters:\n${formatSchema(toolMeta.inputSchema)}`;
     }

package/dist/builtin/mcp/sampling-handler.ts

@@ -1,3 +1,4 @@
+import type { ProviderHeaders } from "@earendil-works/pi-ai";
 import { complete, type Api, type AssistantMessage, type Message, type Model, type TextContent } from "@earendil-works/pi-ai/compat";
 import { truncateAtWord } from "./utils.ts";
 import type { ExtensionUIContext, ModelRegistry } from "@bastani/atomic";
@@ -121,7 +122,7 @@ async function resolveSamplingModel(
 ): Promise<{
   model: Model<Api>;
   apiKey?: string;
-  headers?: Record<string, string>;
+  headers?: ProviderHeaders;
 }> {
   const candidates: Model<Api>[] = [];
   const availableModels = options.modelRegistry.getAvailable();
@@ -151,7 +152,11 @@ async function resolveSamplingModel(
       errors.push(`${model.provider}/${model.id}: ${auth.error}`);
       continue;
     }
-    return { model, apiKey: auth.apiKey, headers: auth.headers };
+		return {
+			model: auth.baseUrl === undefined ? model : { ...model, baseUrl: auth.baseUrl },
+			apiKey: auth.apiKey,
+			headers: auth.headers,
+		};
   }
 
   if (errors.length > 0) {

package/dist/builtin/mcp/tool-call-timeout.ts

@@ -0,0 +1,101 @@
+import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import type { RequestOptions } from "@modelcontextprotocol/sdk/shared/protocol.js";
+import {
+  CallToolResultSchema,
+  ErrorCode,
+  McpError,
+  type CallToolRequest,
+} from "@modelcontextprotocol/sdk/types.js";
+import type { ServerEntry } from "./types.js";
+
+export const MCP_TIMEOUT_MS_CONFIG_ERROR =
+  "timeoutMs must be a finite number greater than 0 milliseconds";
+
+export class McpTimeoutConfigError extends Error {
+  constructor(serverName: string, value: unknown) {
+    const rendered = typeof value === "string" ? JSON.stringify(value) : String(value);
+    super(
+      `Invalid MCP configuration for server "${serverName}": ${MCP_TIMEOUT_MS_CONFIG_ERROR}; received ${rendered}.`,
+    );
+    this.name = "McpTimeoutConfigError";
+  }
+}
+
+export class McpToolCallTimeoutError extends Error {
+  constructor(serverName: string, timeoutMs: number, cause?: unknown) {
+    super(`MCP tool call to server "${serverName}" timed out after ${timeoutMs} ms of inactivity.`, {
+      cause,
+    });
+    this.name = "McpToolCallTimeoutError";
+  }
+}
+
+export function validateMcpServerTimeouts(
+  servers: Record<string, unknown>,
+): Record<string, ServerEntry> {
+  for (const [serverName, rawEntry] of Object.entries(servers)) {
+    if (!rawEntry || typeof rawEntry !== "object" || Array.isArray(rawEntry)) continue;
+    const timeoutMs = (rawEntry as Record<string, unknown>).timeoutMs;
+    if (timeoutMs === undefined) continue;
+    if (typeof timeoutMs !== "number" || !Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+      throw new McpTimeoutConfigError(serverName, timeoutMs);
+    }
+  }
+  return servers as Record<string, ServerEntry>;
+}
+
+export function createToolCallRequestOptions(
+  definition: Pick<ServerEntry, "timeoutMs">,
+  signal?: AbortSignal,
+): RequestOptions | undefined {
+  if (definition.timeoutMs === undefined) {
+    return signal ? { signal } : undefined;
+  }
+  return {
+    signal,
+    timeout: definition.timeoutMs,
+    resetTimeoutOnProgress: true,
+    // The SDK only issues a progress token (and therefore only delivers the progress
+    // notifications that reset this timeout) when an onprogress handler is registered,
+    // so an empty handler is required for resetTimeoutOnProgress to ever fire.
+    onprogress: () => {},
+  };
+}
+
+export async function callToolWithConfiguredTimeout(
+  client: Client,
+  params: CallToolRequest["params"],
+  definition: Pick<ServerEntry, "timeoutMs">,
+  serverName: string,
+  signal?: AbortSignal,
+) {
+  try {
+    return await client.callTool(
+      params,
+      CallToolResultSchema,
+      createToolCallRequestOptions(definition, signal),
+    );
+  } catch (error) {
+    if (definition.timeoutMs !== undefined && isMcpToolCallTimeout(error)) {
+      throw new McpToolCallTimeoutError(serverName, definition.timeoutMs, error);
+    }
+    throw error;
+  }
+}
+
+export function isMcpToolCallTimeout(error: unknown): error is McpError {
+  return error instanceof McpError && error.code === ErrorCode.RequestTimeout;
+}
+
+export function formatMcpToolCallFailure(
+  error: unknown,
+  serverName: string,
+  timeoutMs?: number,
+): string {
+  if (error instanceof McpToolCallTimeoutError) return error.message;
+  if (timeoutMs !== undefined && isMcpToolCallTimeout(error)) {
+    return new McpToolCallTimeoutError(serverName, timeoutMs).message;
+  }
+  const message = error instanceof Error ? error.message : String(error);
+  return `Failed to call tool: ${message}`;
+}

package/dist/builtin/mcp/tool-result-renderer.ts

@@ -57,8 +57,9 @@ export function renderMcpToolResult(
   const output = display.lines
     .map((line) => line === "…" ? theme.fg("muted", line) : theme.fg("toolOutput", line))
     .join("\n");
-  const hint = display.truncated && !options.expanded
-    ? `\n${theme.fg("muted", `(${keyText("app.tools.expand")} Expand)`)}`
+  const expandKey = keyText("app.tools.expand");
+  const hint = display.truncated && !options.expanded && expandKey
+    ? `\n${theme.fg("muted", `(${expandKey} Expand)`)}`
     : "";
 
   return new Text(`${output}${hint}`, 0, 0);

package/dist/builtin/mcp/types.ts

@@ -309,6 +309,11 @@ export interface ServerEntry {
   excludeTools?: string[];
   // Debug
   debug?: boolean;  // Show server stderr (default: false)
+  /**
+   * Per-tool-call inactivity timeout in milliseconds for local or remote servers.
+   * Omit to use the MCP SDK default.
+   */
+  timeoutMs?: number;
 }
 
 // Settings

package/dist/builtin/mcp/ui-server.ts

@@ -13,6 +13,7 @@ import { buildHostHtmlTemplate, buildCspMetaContent, applyCspMeta } from "./host
 import { logger } from "./logger.js";
 import { parseBody, sendJson, validateTokenBody, validateTokenQuery } from "./ui-server-http.js";
 import type { McpServerManager } from "./server-manager.js";
+import { callToolWithConfiguredTimeout } from "./tool-call-timeout.js";
 import {
   extractUiPromptText,
   getVisualizationStreamEnvelope,
@@ -312,13 +313,13 @@ export async function startUiServer(options: UiServerOptions): Promise<UiServerH
         try {
           options.manager.touch(options.serverName);
           options.manager.incrementInFlight(options.serverName);
-          const result = await connection.client.callTool({
+          const result = await callToolWithConfiguredTimeout(connection.client, {
             name: callParams.name,
             arguments:
               callParams.arguments && typeof callParams.arguments === "object" && !Array.isArray(callParams.arguments)
                 ? callParams.arguments
                 : {},
-          });
+          }, connection.definition, options.serverName);
           sendJson(res, 200, { ok: true, result });
         } finally {
           options.manager.decrementInFlight(options.serverName);

package/dist/builtin/subagents/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 ## [Unreleased]
 
+## [0.9.10-alpha.1] - 2026-07-19
+
+### Added
+
+- Added a `group` option on subagent tasks, parallel/chain items, and the top-level call that sets the intercom home group for spawned children so same-group subagents can intercom each other while staying isolated from other groups. A named string joins that group; `true` auto-generates one shared UUID group per parallel set (shared across all items in the set). Precedence is `explicit subagent group > inherited current-session (stage) group > env ATOMIC_INTERCOM_GROUP > config > "default"`. When a subagent does not specify a group it inherits its launching session's group — read race-safely from the session's `orchestrationContext.intercomGroup` rather than global env — so subagents spawned by a grouped workflow stage join that stage's group by default. The child group env (`ATOMIC_INTERCOM_GROUP`) is written only when the child actually has intercom access (the peer `intercom` tool or the `contact_supervisor` tool); a child without intercom is never placed into a group. `contact_supervisor` retains cross-group supervisor access through a broker-issued child capability rather than a client-authored channel marker.
+
+### Changed
+
+- Reworked isolated parallel worktrees to use the canonical main repository's `.atomic/worktrees/` directory, `worktree-*` branches, remote-default/`HEAD` base resolution, local-settings/hooks/`.worktreeinclude` post-creation setup, and force-remove plus branch-delete cleanup, including setup-failure cleanup from linked-worktree invocations.
+
+### Fixed
+
+- Fixed async subagent completion notices racing workflow-stage finalization. Completion notifications now carry stable admission identities, join already-claimed terminal preludes as one stage batch when received before close, and route externally without terminal transcript mutation when close wins. Successful-notification deduplication, retry acknowledgement, terminal ordering, and detached non-blocking execution remain intact.
+- Fixed asynchronous terminal dispatch to defer its acknowledgement and successful-notification dedupe until custom-message admission settles. Rejected batch routes now restore claimed Intercom preludes and return a failed acknowledgement so the durable result watcher can retry the same stable notification ID.
+- Fixed foreground subagent supervisor coordination deadlocking when launched inside a busy workflow stage, including parallel foreground groups where a long-running sibling kept the aggregate tool call active after the asking child detached. The workflow parent now honors the exact-owner probe/commit handshake before stage AgentSession admission; one accepted parallel commit releases foreground supervision for all active siblings while retaining their process lifecycle and eventual result recovery, and tasks still queued behind the concurrency limit are skipped without launching unsupervised. Run-owned direct and chain-parallel worktrees remain alive until all detached children close, when diffs are captured before cleanup instead of deleting active execution roots. Blocking decisions and interviews can receive replies while direct single execution, background execution, cancellation, and status/result recovery remain intact.
+- Secured foreground, background, parallel, chain, revived, and bounded dynamic-fanout supervisor communication by requesting broker-issued authorizations before child spawn and passing each grant through dedicated child environment metadata. Foreground/single-child paths use exact child scopes; asynchronous chains use bounded per-child slots so dynamic fanout index shifts cannot invalidate later children. Descendants without a fresh grant explicitly clear inherited capability metadata, parent-held grants are restored after reconnects, and the lightweight Intercom wrapper lazy-loads authorization on demand. Claimed provider failures abort launch; hosts without a provider suppress supervisor metadata instead of leaving `contact_supervisor` silently unusable.
+- Fixed subagent live-detail and full-notification hints to use the effective `app.tools.expand` binding and omit the shortcut affordance when it is unbound.
+- Fixed completion-notification header parsing to avoid polynomial regular-expression behavior on long malformed agent/task text while preserving accepted notification formats.
+- Fixed session startup stalling on background-job hydration when the subagents run directory has accumulated many historical runs. Active-job hydration is now deferred off the `session_start` hot path and only eagerly reconciles runs touched within the last 7 days (older runs are skipped with two `stat` calls instead of a full per-run status read and reconciliation), so the jobs widget populates moments after startup without blocking first input.
+- Fixed a host-process crash from the background-job tracker's timers using a stale extension context. Deferred hydration, poller ticks, and cleanup timers hold onto contexts that become invalid after `ctx.newSession()`, `ctx.fork()`, `ctx.switchSession()`, or `ctx.reload()`; every context read in those timer paths is now probed defensively and a stale retained UI context is dropped instead of throwing an unhandled "extension ctx is stale" error out of an unref'd timer.
+
 ## [0.9.9] - 2026-07-15
 
 ### Changed

package/dist/builtin/subagents/README.md

@@ -832,7 +832,7 @@ subagent({ action: "doctor" })
 
 ## Worktree isolation
 
-Parallel agents can clobber each other if they edit the same checkout. `worktree: true` gives each parallel child its own git worktree branched from `HEAD`.
+Parallel agents can clobber each other if they edit the same checkout. `worktree: true` gives each parallel child a branch-backed worktree under `<main-root>/.atomic/worktrees/<flattened-name>` on branch `worktree-<flattened-name>`. `/` is flattened to `+`, and creation remains anchored at the canonical main repository root even when Atomic is invoked inside another linked worktree. The base ref is `origin/<default-branch>` (fetched when needed), then `HEAD`.
 
 ```ts
 { tasks: [
@@ -854,11 +854,14 @@ Requirements:
 
 - run inside a git repo
 - working tree must be clean
-- `node_modules/` is symlinked into each worktree when present
+- `node_modules/` is symlinked from the main root into each worktree when present
 - task-level `cwd` overrides must be omitted or match the shared cwd
 - configured `worktreeSetupHook` must return valid JSON before timeout
+- `.atomic/settings.local.json` and untracked `.atomic/settings.json` are propagated without overwriting tracked content
+- the main repository's Husky or populated `.git/hooks` directory is shared through `core.hooksPath`
+- gitignored files matched by `.worktreeinclude` are copied into the worktree
 
-After a worktree parallel step completes, per-agent diff stats are appended to the output and full patch files are written to artifacts. Worktrees and temp branches are cleaned up in `finally` blocks.
+After a worktree parallel step completes, per-agent diff stats are appended to the output and full patch files are written to artifacts. Cleanup forcibly removes each worktree, waits briefly for Git's lock release, and deletes its `worktree-*` branch; the same cleanup runs after post-creation setup failures.
 
 ## Configuration
 

package/dist/builtin/subagents/agents/code-simplifier.md

@@ -9,7 +9,7 @@ description: |
   - Code that has gotten messy after several iterations.
 tools: read, edit, write, search, find, ls, bash, todo
 model: openai-codex/gpt-5.6-sol:medium
-fallbackModels: github-copilot/gpt-5.6-sol:medium, openai/gpt-5.6-sol:medium, openai-codex/gpt-5.5:medium, github-copilot/gpt-5.5:medium, openai/gpt-5.5:medium, anthropic/claude-fable-5:low, github-copilot/claude-opus-4.8 (1m):medium, anthropic/claude-opus-4-8:medium, cursor/gpt-5.6-sol:medium, cursor/gpt-5.5:medium, cursor/claude-fable-5:low, cursor/claude-opus-4-8-thinking:medium, cursor/grok-4.5, zai/glm-5.2:high, zai-coding-cn/glm-5.2:high, cursor/glm-5.2, openrouter/openai/gpt-5.6-sol:medium, openrouter/openai/gpt-5.5:medium, openrouter/anthropic/claude-fable-5:low, openrouter/anthropic/claude-opus-4-8:medium, openrouter/x-ai/grok-4.5, openrouter/z-ai/glm-5.2:xhigh
+fallbackModels: github-copilot/gpt-5.6-sol:medium, openai/gpt-5.6-sol:medium, openai-codex/gpt-5.5:medium, github-copilot/gpt-5.5:medium, openai/gpt-5.5:medium, anthropic/claude-fable-5:low, github-copilot/claude-opus-4.8 (1m):medium, anthropic/claude-opus-4-8:medium, cursor/gpt-5.6-sol:medium, cursor/gpt-5.5:medium, cursor/claude-fable-5:low, cursor/claude-opus-4-8-thinking:medium, xai/grok-4.5:high, cursor/grok-4.5:high, zai/glm-5.2:high, zai-coding-cn/glm-5.2:high, cursor/glm-5.2, openrouter/openai/gpt-5.6-sol:medium, openrouter/openai/gpt-5.5:medium, openrouter/anthropic/claude-fable-5:low, openrouter/anthropic/claude-opus-4-8:medium, openrouter/x-ai/grok-4.5, openrouter/z-ai/glm-5.2:xhigh
 skills: tdd, playwright-cli, tmux
 ---
 

package/dist/builtin/subagents/agents/codebase-analyzer.md

@@ -3,7 +3,7 @@ name: codebase-analyzer
 description: Analyzes codebase implementation details. Call the codebase-analyzer agent when you need to find detailed information about specific components.
 tools: read, search, find, ls, todo
 model: openai-codex/gpt-5.6-sol:medium
-fallbackModels: github-copilot/gpt-5.6-sol:medium, openai/gpt-5.6-sol:medium, openai-codex/gpt-5.5:medium, github-copilot/gpt-5.5:medium, openai/gpt-5.5:medium, anthropic/claude-fable-5:low, github-copilot/claude-opus-4.8 (1m):medium, anthropic/claude-opus-4-8:medium, cursor/gpt-5.6-sol:medium, cursor/gpt-5.5:medium, cursor/claude-fable-5:low, cursor/claude-opus-4-8-thinking:medium, cursor/grok-4.5, zai/glm-5.2:high, zai-coding-cn/glm-5.2:high, cursor/glm-5.2, openrouter/openai/gpt-5.6-sol:medium, openrouter/openai/gpt-5.5:medium, openrouter/anthropic/claude-fable-5:low, openrouter/anthropic/claude-opus-4-8:medium, openrouter/x-ai/grok-4.5, openrouter/z-ai/glm-5.2:xhigh
+fallbackModels: github-copilot/gpt-5.6-sol:medium, openai/gpt-5.6-sol:medium, openai-codex/gpt-5.5:medium, github-copilot/gpt-5.5:medium, openai/gpt-5.5:medium, anthropic/claude-fable-5:low, github-copilot/claude-opus-4.8 (1m):medium, anthropic/claude-opus-4-8:medium, cursor/gpt-5.6-sol:medium, cursor/gpt-5.5:medium, cursor/claude-fable-5:low, cursor/claude-opus-4-8-thinking:medium, xai/grok-4.5:high, cursor/grok-4.5:high, zai/glm-5.2:high, zai-coding-cn/glm-5.2:high, cursor/glm-5.2, openrouter/openai/gpt-5.6-sol:medium, openrouter/openai/gpt-5.5:medium, openrouter/anthropic/claude-fable-5:low, openrouter/anthropic/claude-opus-4-8:medium, openrouter/x-ai/grok-4.5, openrouter/z-ai/glm-5.2:xhigh
 skills: tdd, playwright-cli, tmux
 ---
 

package/dist/builtin/subagents/agents/codebase-locator.md

@@ -3,7 +3,7 @@ name: codebase-locator
 description: Locates files, directories, and components relevant to a feature or task. Basically a "super search/find/ls tool."
 tools: read, search, find, ls
 model: openai-codex/gpt-5.6-terra:high
-fallbackModels: github-copilot/gpt-5.6-terra:high, openai/gpt-5.6-terra:high, openai-codex/gpt-5.5:low, github-copilot/gpt-5.5:low, openai/gpt-5.5:low, github-copilot/claude-opus-4.8 (1m):low, anthropic/claude-opus-4-8:low, cursor/gpt-5.6-terra:high, cursor/gpt-5.5:low, cursor/claude-opus-4-8-thinking:low, cursor/grok-4.5, zai/glm-5.2:high, zai-coding-cn/glm-5.2:high, cursor/glm-5.2, openrouter/openai/gpt-5.6-terra:high, openrouter/openai/gpt-5.5:low, openrouter/anthropic/claude-opus-4-8:low, openrouter/x-ai/grok-4.5, openrouter/z-ai/glm-5.2:xhigh
+fallbackModels: github-copilot/gpt-5.6-terra:high, openai/gpt-5.6-terra:high, openai-codex/gpt-5.5:low, github-copilot/gpt-5.5:low, openai/gpt-5.5:low, github-copilot/claude-opus-4.8 (1m):low, anthropic/claude-opus-4-8:low, cursor/gpt-5.6-terra:high, cursor/gpt-5.5:low, cursor/claude-opus-4-8-thinking:low, xai/grok-4.5:high, cursor/grok-4.5:high, zai/glm-5.2:high, zai-coding-cn/glm-5.2:high, cursor/glm-5.2, openrouter/openai/gpt-5.6-terra:high, openrouter/openai/gpt-5.5:low, openrouter/anthropic/claude-opus-4-8:low, openrouter/x-ai/grok-4.5, openrouter/z-ai/glm-5.2:xhigh
 ---
 
 You are a specialist at finding WHERE code lives in a codebase. Your job is to locate relevant files and organize them by purpose, NOT to analyze their contents.

package/dist/builtin/subagents/agents/codebase-online-researcher.md

@@ -3,7 +3,7 @@ name: codebase-online-researcher
 description: Online research for up-to-date documentation and library-source knowledge. Use when you need authoritative external information — official docs, ecosystem context, version-specific behavior, GitHub permalinks into open-source libraries, or video tutorials.
 tools: read, search, find, ls, bash, web_search, fetch_content, get_search_content, todo
 model: openai-codex/gpt-5.6-sol:medium
-fallbackModels: github-copilot/gpt-5.6-sol:medium, openai/gpt-5.6-sol:medium, openai-codex/gpt-5.5:medium, github-copilot/gpt-5.5:medium, openai/gpt-5.5:medium, anthropic/claude-fable-5:low, github-copilot/claude-opus-4.8 (1m):medium, anthropic/claude-opus-4-8:medium, cursor/gpt-5.6-sol:medium, cursor/gpt-5.5:medium, cursor/claude-fable-5:low, cursor/claude-opus-4-8-thinking:medium, cursor/grok-4.5, zai/glm-5.2:high, zai-coding-cn/glm-5.2:high, cursor/glm-5.2, openrouter/openai/gpt-5.6-sol:medium, openrouter/openai/gpt-5.5:medium, openrouter/anthropic/claude-fable-5:low, openrouter/anthropic/claude-opus-4-8:medium, openrouter/x-ai/grok-4.5, openrouter/z-ai/glm-5.2:xhigh
+fallbackModels: github-copilot/gpt-5.6-sol:medium, openai/gpt-5.6-sol:medium, openai-codex/gpt-5.5:medium, github-copilot/gpt-5.5:medium, openai/gpt-5.5:medium, anthropic/claude-fable-5:low, github-copilot/claude-opus-4.8 (1m):medium, anthropic/claude-opus-4-8:medium, cursor/gpt-5.6-sol:medium, cursor/gpt-5.5:medium, cursor/claude-fable-5:low, cursor/claude-opus-4-8-thinking:medium, xai/grok-4.5:high, cursor/grok-4.5:high, zai/glm-5.2:high, zai-coding-cn/glm-5.2:high, cursor/glm-5.2, openrouter/openai/gpt-5.6-sol:medium, openrouter/openai/gpt-5.5:medium, openrouter/anthropic/claude-fable-5:low, openrouter/anthropic/claude-opus-4-8:medium, openrouter/x-ai/grok-4.5, openrouter/z-ai/glm-5.2:xhigh
 skills: playwright-cli
 ---
 

package/dist/builtin/subagents/agents/codebase-pattern-finder.md

@@ -3,7 +3,7 @@ name: codebase-pattern-finder
 description: Find similar implementations, usage examples, or existing patterns in the codebase that can be modeled after.
 tools: read, search, find, ls
 model: openai-codex/gpt-5.6-terra:high
-fallbackModels: github-copilot/gpt-5.6-terra:high, openai/gpt-5.6-terra:high, openai-codex/gpt-5.5:low, github-copilot/gpt-5.5:low, openai/gpt-5.5:low, github-copilot/claude-opus-4.8 (1m):low, anthropic/claude-opus-4-8:low, cursor/gpt-5.6-terra:high, cursor/gpt-5.5:low, cursor/claude-opus-4-8-thinking:low, cursor/grok-4.5, zai/glm-5.2:high, zai-coding-cn/glm-5.2:high, cursor/glm-5.2, openrouter/openai/gpt-5.6-terra:high, openrouter/openai/gpt-5.5:low, openrouter/anthropic/claude-opus-4-8:low, openrouter/x-ai/grok-4.5, openrouter/z-ai/glm-5.2:xhigh
+fallbackModels: github-copilot/gpt-5.6-terra:high, openai/gpt-5.6-terra:high, openai-codex/gpt-5.5:low, github-copilot/gpt-5.5:low, openai/gpt-5.5:low, github-copilot/claude-opus-4.8 (1m):low, anthropic/claude-opus-4-8:low, cursor/gpt-5.6-terra:high, cursor/gpt-5.5:low, cursor/claude-opus-4-8-thinking:low, xai/grok-4.5:high, cursor/grok-4.5:high, zai/glm-5.2:high, zai-coding-cn/glm-5.2:high, cursor/glm-5.2, openrouter/openai/gpt-5.6-terra:high, openrouter/openai/gpt-5.5:low, openrouter/anthropic/claude-opus-4-8:low, openrouter/x-ai/grok-4.5, openrouter/z-ai/glm-5.2:xhigh
 ---
 
 You are a specialist at finding code patterns and examples in the codebase. Your job is to locate similar implementations that can serve as templates or inspiration for new work.

package/dist/builtin/subagents/agents/codebase-research-analyzer.md

@@ -3,7 +3,7 @@ name: codebase-research-analyzer
 description: Analyzes local research documents to extract high-value insights, decisions, and technical details while filtering out noise. Use this when you want to deep dive on a research topic or understand the rationale behind decisions.
 tools: read, search, find, ls, todo
 model: openai-codex/gpt-5.6-sol:medium
-fallbackModels: github-copilot/gpt-5.6-sol:medium, openai/gpt-5.6-sol:medium, openai-codex/gpt-5.5:medium, github-copilot/gpt-5.5:medium, openai/gpt-5.5:medium, anthropic/claude-fable-5:low, github-copilot/claude-opus-4.8 (1m):medium, anthropic/claude-opus-4-8:medium, cursor/gpt-5.6-sol:medium, cursor/gpt-5.5:medium, cursor/claude-fable-5:low, cursor/claude-opus-4-8-thinking:medium, cursor/grok-4.5, zai/glm-5.2:high, zai-coding-cn/glm-5.2:high, cursor/glm-5.2, openrouter/openai/gpt-5.6-sol:medium, openrouter/openai/gpt-5.5:medium, openrouter/anthropic/claude-fable-5:low, openrouter/anthropic/claude-opus-4-8:medium, openrouter/x-ai/grok-4.5, openrouter/z-ai/glm-5.2:xhigh
+fallbackModels: github-copilot/gpt-5.6-sol:medium, openai/gpt-5.6-sol:medium, openai-codex/gpt-5.5:medium, github-copilot/gpt-5.5:medium, openai/gpt-5.5:medium, anthropic/claude-fable-5:low, github-copilot/claude-opus-4.8 (1m):medium, anthropic/claude-opus-4-8:medium, cursor/gpt-5.6-sol:medium, cursor/gpt-5.5:medium, cursor/claude-fable-5:low, cursor/claude-opus-4-8-thinking:medium, xai/grok-4.5:high, cursor/grok-4.5:high, zai/glm-5.2:high, zai-coding-cn/glm-5.2:high, cursor/glm-5.2, openrouter/openai/gpt-5.6-sol:medium, openrouter/openai/gpt-5.5:medium, openrouter/anthropic/claude-fable-5:low, openrouter/anthropic/claude-opus-4-8:medium, openrouter/x-ai/grok-4.5, openrouter/z-ai/glm-5.2:xhigh
 ---
 
 You are a specialist at extracting HIGH-VALUE insights from research documents. Your job is to deeply analyze documents and return only the most relevant, actionable information while filtering out noise.

package/dist/builtin/subagents/agents/codebase-research-locator.md

@@ -3,7 +3,7 @@ name: codebase-research-locator
 description: Discovers local research documents that are relevant to the current research task.
 tools: read, search, find, ls
 model: openai-codex/gpt-5.6-terra:high
-fallbackModels: github-copilot/gpt-5.6-terra:high, openai/gpt-5.6-terra:high, openai-codex/gpt-5.5:low, github-copilot/gpt-5.5:low, openai/gpt-5.5:low, github-copilot/claude-opus-4.8 (1m):low, anthropic/claude-opus-4-8:low, cursor/gpt-5.6-terra:high, cursor/gpt-5.5:low, cursor/claude-opus-4-8-thinking:low, cursor/grok-4.5, zai/glm-5.2:high, zai-coding-cn/glm-5.2:high, cursor/glm-5.2, openrouter/openai/gpt-5.6-terra:high, openrouter/openai/gpt-5.5:low, openrouter/anthropic/claude-opus-4-8:low, openrouter/x-ai/grok-4.5, openrouter/z-ai/glm-5.2:xhigh
+fallbackModels: github-copilot/gpt-5.6-terra:high, openai/gpt-5.6-terra:high, openai-codex/gpt-5.5:low, github-copilot/gpt-5.5:low, openai/gpt-5.5:low, github-copilot/claude-opus-4.8 (1m):low, anthropic/claude-opus-4-8:low, cursor/gpt-5.6-terra:high, cursor/gpt-5.5:low, cursor/claude-opus-4-8-thinking:low, xai/grok-4.5:high, cursor/grok-4.5:high, zai/glm-5.2:high, zai-coding-cn/glm-5.2:high, cursor/glm-5.2, openrouter/openai/gpt-5.6-terra:high, openrouter/openai/gpt-5.5:low, openrouter/anthropic/claude-opus-4-8:low, openrouter/x-ai/grok-4.5, openrouter/z-ai/glm-5.2:xhigh
 ---
 
 You are a specialist at finding documents in the `research/` directory. Your job is to locate relevant research documents and categorize them, NOT to analyze their contents in depth.

package/dist/builtin/subagents/agents/debugger.md

@@ -3,7 +3,7 @@ name: debugger
 description: Debug errors, test failures, and unexpected behavior. Use PROACTIVELY when encountering issues, analyzing stack traces, or investigating system problems.
 tools: read, search, find, ls, bash, web_search, fetch_content, get_search_content, intercom, contact_supervisor, todo
 model: openai-codex/gpt-5.6-sol:xhigh
-fallbackModels: github-copilot/gpt-5.6-sol:xhigh, openai/gpt-5.6-sol:xhigh, anthropic/claude-fable-5:high, openai-codex/gpt-5.5:xhigh, github-copilot/gpt-5.5:xhigh, openai/gpt-5.5:xhigh, github-copilot/claude-opus-4.8 (1m):high, anthropic/claude-opus-4-8:high, cursor/gpt-5.6-sol:xhigh, cursor/gpt-5.5:high, cursor/claude-opus-4-8-thinking:high, cursor/grok-4.5, zai/glm-5.2:xhigh, zai-coding-cn/glm-5.2:xhigh, cursor/glm-5.2, openrouter/openai/gpt-5.6-sol:xhigh, openrouter/anthropic/claude-fable-5:high, openrouter/sakana/fugu-ultra:high, openrouter/openai/gpt-5.5:xhigh, openrouter/anthropic/claude-opus-4-8:high, openrouter/x-ai/grok-4.5, openrouter/z-ai/glm-5.2:xhigh
+fallbackModels: github-copilot/gpt-5.6-sol:xhigh, openai/gpt-5.6-sol:xhigh, anthropic/claude-fable-5:high, kimi-coding/k3:max, moonshotai/kimi-k3:max, moonshotai-cn/kimi-k3:max, openai-codex/gpt-5.5:xhigh, github-copilot/gpt-5.5:xhigh, openai/gpt-5.5:xhigh, github-copilot/claude-opus-4.8 (1m):high, anthropic/claude-opus-4-8:high, cursor/gpt-5.6-sol:xhigh, cursor/gpt-5.5:high, cursor/claude-opus-4-8-thinking:high, xai/grok-4.5:high, cursor/grok-4.5:high, zai/glm-5.2:xhigh, zai-coding-cn/glm-5.2:xhigh, cursor/glm-5.2, openrouter/openai/gpt-5.6-sol:xhigh, openrouter/anthropic/claude-fable-5:high, openrouter/moonshotai/kimi-k3:max, openrouter/sakana/fugu-ultra:high, openrouter/openai/gpt-5.5:xhigh, openrouter/anthropic/claude-opus-4-8:high, openrouter/x-ai/grok-4.5, openrouter/z-ai/glm-5.2:xhigh
 skills: tdd, playwright-cli, tmux
 ---
 

package/dist/builtin/subagents/agents/worker.md

@@ -6,7 +6,7 @@ inheritProjectContext: true
 inheritSkills: false
 tools: read, edit, write, search, find, ls, bash, web_search, fetch_content, get_search_content, intercom, contact_supervisor, todo
 model: openai-codex/gpt-5.6-sol:medium
-fallbackModels: github-copilot/gpt-5.6-sol:medium, openai/gpt-5.6-sol:medium, openai-codex/gpt-5.5:medium, github-copilot/gpt-5.5:medium, openai/gpt-5.5:medium, anthropic/claude-fable-5:low, github-copilot/claude-opus-4.8 (1m):medium, anthropic/claude-opus-4-8:medium, cursor/gpt-5.6-sol:medium, cursor/gpt-5.5:medium, cursor/claude-fable-5:low, cursor/claude-opus-4-8-thinking:medium, cursor/grok-4.5, zai/glm-5.2:high, zai-coding-cn/glm-5.2:high, cursor/glm-5.2, openrouter/openai/gpt-5.6-sol:medium, openrouter/openai/gpt-5.5:medium, openrouter/anthropic/claude-fable-5:low, openrouter/anthropic/claude-opus-4-8:medium, openrouter/x-ai/grok-4.5, openrouter/z-ai/glm-5.2:xhigh
+fallbackModels: github-copilot/gpt-5.6-sol:medium, openai/gpt-5.6-sol:medium, openai-codex/gpt-5.5:medium, github-copilot/gpt-5.5:medium, openai/gpt-5.5:medium, anthropic/claude-fable-5:low, github-copilot/claude-opus-4.8 (1m):medium, anthropic/claude-opus-4-8:medium, cursor/gpt-5.6-sol:medium, cursor/gpt-5.5:medium, cursor/claude-fable-5:low, cursor/claude-opus-4-8-thinking:medium, xai/grok-4.5:high, cursor/grok-4.5:high, zai/glm-5.2:high, zai-coding-cn/glm-5.2:high, cursor/glm-5.2, openrouter/openai/gpt-5.6-sol:medium, openrouter/openai/gpt-5.5:medium, openrouter/anthropic/claude-fable-5:low, openrouter/anthropic/claude-opus-4-8:medium, openrouter/x-ai/grok-4.5, openrouter/z-ai/glm-5.2:xhigh
 skills: tdd, playwright-cli, tmux
 defaultContext: fork
 defaultProgress: true

package/dist/builtin/subagents/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/subagents",
-  "version": "0.9.9",
+  "version": "0.9.10-alpha.1",
   "private": true,
   "description": "Atomic extension for delegating tasks to subagents with chains, parallel execution, and background runs. Fork of: https://github.com/nicobailon/pi-subagents",
   "contributors": [
@@ -38,9 +38,9 @@
   },
   "peerDependencies": {
     "@bastani/atomic": "*",
-    "@earendil-works/pi-agent-core": "^0.80.7",
-    "@earendil-works/pi-ai": "^0.80.7",
-    "@earendil-works/pi-tui": "^0.80.7"
+    "@earendil-works/pi-agent-core": "^0.80.10",
+    "@earendil-works/pi-ai": "^0.80.10",
+    "@earendil-works/pi-tui": "^0.80.10"
   },
   "peerDependenciesMeta": {
     "@bastani/atomic": {

package/dist/builtin/subagents/skills/subagent/SKILL.md

@@ -419,7 +419,7 @@ subagent({
 })
 ```
 
-`worktree: true` gives each parallel task its own git worktree branched from HEAD. This requires a clean git state and is mainly for intentionally parallel writer workflows. If you want one writer thread and several advisory readers, prefer a single-writer pattern instead — only `debugger` and `code-simplifier` write, so co-locating them with read-only specialists in the same worktree is safe.
+`worktree: true` gives each parallel task its own `worktree-*` branch under the canonical main root's `.atomic/worktrees/`, using the remote default branch when available and `HEAD` otherwise. This requires a clean git state and is mainly for intentionally parallel writer workflows. If you want one writer thread and several advisory readers, prefer a single-writer pattern instead — only `debugger` and `code-simplifier` write, so co-locating them with read-only specialists in the same worktree is safe.
 
 ## Subagent + Intercom Coordination