@bastani/atomic 0.9.16-alpha.1 → 0.9.16-alpha.3

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

@@ -1,378 +0,0 @@
-import { randomUUID } from "node:crypto";
-import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
-import type { McpExtensionState } from "./state.js";
-import {
-  extractUiPromptText,
-  UI_STREAM_HOST_CONTEXT_KEY,
-  UI_STREAM_REQUEST_META_KEY,
-  UI_STREAM_STRUCTURED_CONTENT_KEY,
-  type UiHostContext,
-  type UiMessageParams,
-  type UiModelContextParams,
-  type UiStreamMode,
-} from "./types.ts";
-import { logger } from "./logger.ts";
-import { startUiServer, type UiServerHandle } from "./ui-server.ts";
-import { isGlimpseAvailable, openGlimpseWindow } from "./glimpse-ui.js";
-import { escapeHtmlAttribute } from "./host-html-template.js";
-
-let activeGlimpseWindow: { close(): void } | null = null;
-
-export interface UiSessionRequest {
-  serverName: string;
-  toolName: string;
-  toolArgs: Record<string, unknown>;
-  uiResourceUri: string;
-  streamMode?: UiStreamMode;
-}
-
-export interface UiSessionRuntime {
-  serverName: string;
-  toolName: string;
-  reused: boolean;
-  streamId?: string;
-  streamToken?: string;
-  streamMode?: UiStreamMode;
-  requestMeta?: Record<string, unknown>;
-  url: string;
-  isActive: () => boolean;
-  sendToolResult: (result: CallToolResult) => void;
-  sendResultPatch: (result: CallToolResult) => void;
-  sendToolCancelled: (reason: string) => void | Promise<void>;
-  close: (reason?: string) => void;
-}
-
-const MAX_COMPLETED_SESSIONS = 10;
-
-function withStreamEnvelope(
-  result: CallToolResult,
-  streamId: string | undefined,
-  sequence: number,
-): CallToolResult {
-  if (!streamId) {
-    return result;
-  }
-
-  const structuredContent = result.structuredContent && typeof result.structuredContent === "object" && !Array.isArray(result.structuredContent)
-    ? { ...result.structuredContent }
-    : {};
-
-  const rawEnvelope = structuredContent[UI_STREAM_STRUCTURED_CONTENT_KEY];
-  const envelope = rawEnvelope && typeof rawEnvelope === "object" && !Array.isArray(rawEnvelope)
-    ? { ...rawEnvelope as Record<string, unknown> }
-    : {
-        frameType: "final",
-        phase: "settled",
-        status: result.isError ? "error" : "ok",
-      };
-
-  structuredContent[UI_STREAM_STRUCTURED_CONTENT_KEY] = {
-    ...envelope,
-    streamId,
-    sequence,
-  };
-
-  return {
-    ...result,
-    structuredContent,
-  };
-}
-
-async function openInBrowser(state: McpExtensionState, url: string): Promise<void> {
-  try {
-    await state.openBrowser(url);
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    state.ui?.notify(`MCP UI browser open failed: ${message}`, "warning");
-    state.ui?.notify(`Open manually: ${url}`, "info");
-  }
-}
-
-export async function maybeStartUiSession(
-  state: McpExtensionState,
-  request: UiSessionRequest,
-): Promise<UiSessionRuntime | null> {
-  const log = logger.child({
-    component: "UiSession",
-    server: request.serverName,
-    tool: request.toolName,
-  });
-
-  try {
-    if (
-      state.uiServer &&
-      state.uiServer.serverName === request.serverName &&
-      state.uiServer.toolName === request.toolName
-    ) {
-      const existingHandle = state.uiServer;
-      const streamMode = request.streamMode;
-      const streamId = streamMode ? randomUUID() : undefined;
-      const streamToken = streamMode ? randomUUID() : undefined;
-      let active = true;
-      let nextStreamSequence = 0;
-
-      const cleanupStreamListener = () => {
-        if (streamToken) {
-          state.manager.removeUiStreamListener(streamToken);
-        }
-      };
-
-      existingHandle.sendToolInput(request.toolArgs);
-
-      if (streamToken) {
-        state.manager.registerUiStreamListener(streamToken, (serverName, notification) => {
-          if (!active || state.uiServer !== existingHandle) return;
-          if (serverName !== request.serverName) return;
-          nextStreamSequence += 1;
-          existingHandle.sendResultPatch(
-            withStreamEnvelope(notification.result as CallToolResult, streamId, nextStreamSequence),
-          );
-        });
-      }
-
-      return {
-        serverName: request.serverName,
-        toolName: request.toolName,
-        reused: true,
-        streamId,
-        streamToken,
-        streamMode,
-        requestMeta: streamToken ? { [UI_STREAM_REQUEST_META_KEY]: streamToken } : undefined,
-        url: existingHandle.url,
-        isActive: () => active && state.uiServer === existingHandle,
-        sendToolResult: (result: CallToolResult) => {
-          if (!active || state.uiServer !== existingHandle) return;
-          nextStreamSequence += 1;
-          existingHandle.sendToolResult(withStreamEnvelope(result, streamId, nextStreamSequence));
-        },
-        sendResultPatch: (result: CallToolResult) => {
-          if (!active || state.uiServer !== existingHandle) return;
-          nextStreamSequence += 1;
-          existingHandle.sendResultPatch(withStreamEnvelope(result, streamId, nextStreamSequence));
-        },
-        sendToolCancelled: (reason: string) => {
-          if (!active || state.uiServer !== existingHandle) return;
-          nextStreamSequence += 1;
-          return existingHandle.sendToolCancelled(reason);
-        },
-        close: () => {
-          active = false;
-          cleanupStreamListener();
-        },
-      };
-    }
-
-    const resource = await state.uiResourceHandler.readUiResource(request.serverName, request.uiResourceUri);
-
-    if (state.uiServer) {
-      state.uiServer.close("replaced");
-      state.uiServer = null;
-    }
-    if (activeGlimpseWindow) {
-      activeGlimpseWindow.close();
-      activeGlimpseWindow = null;
-    }
-
-    const streamMode = request.streamMode;
-    const streamId = streamMode ? randomUUID() : undefined;
-    const streamToken = streamMode ? randomUUID() : undefined;
-    const hostContext: UiHostContext | undefined = streamMode && streamId
-      ? {
-          [UI_STREAM_HOST_CONTEXT_KEY]: {
-            mode: streamMode,
-            streamId,
-            intermediateResultPatches: streamMode === "stream-first",
-            partialInput: false,
-          },
-        }
-      : undefined;
-
-    let active = true;
-    let nextStreamSequence = 0;
-    let handle: UiServerHandle | null = null;
-
-    const cleanupStreamListener = () => {
-      if (streamToken) {
-        state.manager.removeUiStreamListener(streamToken);
-      }
-    };
-
-    handle = await startUiServer({
-      serverName: request.serverName,
-      toolName: request.toolName,
-      toolArgs: streamMode === "stream-first" ? {} : request.toolArgs,
-      resource,
-      manager: state.manager,
-      consentManager: state.consentManager,
-      hostContext,
-
-      onMessage: (params: UiMessageParams) => {
-        const prompt = extractUiPromptText(params);
-        if (prompt) {
-          if (state.sendMessage) {
-            state.sendMessage(
-              {
-                customType: "mcp-ui-prompt",
-                content: [{ type: "text", text: `User sent prompt from ${request.serverName} UI: "${prompt}"` }],
-                display: `💬 UI Prompt: ${prompt}`,
-                details: { server: request.serverName, tool: request.toolName, prompt },
-              },
-              { triggerTurn: true },
-            );
-            log.debug("Triggered agent turn for UI prompt", { prompt: prompt.slice(0, 50) });
-          }
-        } else if (params.type === "intent" || params.intent) {
-          const intent = params.intent ?? "";
-          const intentParams = params.params;
-          if (intent && state.sendMessage) {
-            const paramsStr = intentParams ? ` ${JSON.stringify(intentParams)}` : "";
-            state.sendMessage(
-              {
-                customType: "mcp-ui-intent",
-                content: [{ type: "text", text: `User triggered intent from ${request.serverName} UI: ${intent}${paramsStr}` }],
-                display: `🎯 UI Intent: ${intent}`,
-                details: { server: request.serverName, tool: request.toolName, intent, params: intentParams },
-              },
-              { triggerTurn: true },
-            );
-            log.debug("Triggered agent turn for UI intent", { intent });
-          }
-        } else if (params.type === "notify" || params.message) {
-          const text = params.message ?? "";
-          if (text && state.ui) {
-            state.ui.notify(`[${request.serverName}] ${text}`, "info");
-          }
-        }
-      },
-
-      onContextUpdate: (params: UiModelContextParams) => {
-        log.debug("Model context update from UI", {
-          hasContent: !!params.content,
-          hasStructured: !!params.structuredContent,
-        });
-      },
-
-      onComplete: (reason: string) => {
-        active = false;
-        cleanupStreamListener();
-
-        if (state.uiServer === handle && handle !== null) {
-          const completedHandle = handle;
-          const messages = completedHandle.getSessionMessages();
-          const stream = completedHandle.getStreamSummary();
-          const hasContent =
-            messages.prompts.length > 0 ||
-            messages.intents.length > 0 ||
-            messages.notifications.length > 0 ||
-            !!stream;
-
-          if (hasContent) {
-            state.completedUiSessions.push({
-              serverName: completedHandle.serverName,
-              toolName: completedHandle.toolName,
-              completedAt: new Date(),
-              reason,
-              messages,
-              stream,
-            });
-
-            while (state.completedUiSessions.length > MAX_COMPLETED_SESSIONS) {
-              state.completedUiSessions.shift();
-            }
-
-            log.debug("Session completed", {
-              reason,
-              prompts: messages.prompts.length,
-              intents: messages.intents.length,
-              notifications: messages.notifications.length,
-              streamFrames: stream?.frames ?? 0,
-            });
-          }
-
-          state.uiServer = null;
-          if (activeGlimpseWindow) {
-            activeGlimpseWindow.close();
-            activeGlimpseWindow = null;
-          }
-        }
-      },
-    });
-
-    if (streamToken) {
-      state.manager.registerUiStreamListener(streamToken, (serverName, notification) => {
-        if (!active || state.uiServer !== handle) return;
-        if (serverName !== request.serverName) return;
-        nextStreamSequence += 1;
-        handle.sendResultPatch(withStreamEnvelope(notification.result as CallToolResult, streamId, nextStreamSequence));
-      });
-    }
-
-    state.uiServer = handle;
-
-    const glimpseDetected = isGlimpseAvailable();
-    const viewerPref = process.env.MCP_UI_VIEWER?.toLowerCase();
-    const useGlimpse = viewerPref === "glimpse" ||
-      (viewerPref !== "browser" && glimpseDetected);
-
-    if (useGlimpse) {
-      try {
-        const iframeUrl = escapeHtmlAttribute(handle.url);
-        const glimpseHtml = `<!DOCTYPE html><html><head><meta charset="utf-8"><style>body{margin:0;padding:0;width:100vw;height:100vh;overflow:hidden}iframe{width:100%;height:100%;border:none}</style></head><body><iframe src="${iframeUrl}"></iframe></body></html>`;
-        activeGlimpseWindow = await openGlimpseWindow(glimpseHtml, {
-          title: `MCP · ${request.serverName} · ${request.toolName}`,
-          width: 1000,
-          height: 800,
-          onClosed: () => {
-            if (active) handle.close("glimpse-closed");
-          },
-        });
-      } catch (error) {
-        log.debug("Glimpse unavailable, using browser", {
-          error: error instanceof Error ? error.message : String(error),
-        });
-        await openInBrowser(state, handle.url);
-      }
-    } else {
-      await openInBrowser(state, handle.url);
-    }
-
-    return {
-      serverName: request.serverName,
-      toolName: request.toolName,
-      reused: false,
-      streamId,
-      streamToken,
-      streamMode,
-      requestMeta: streamToken ? { [UI_STREAM_REQUEST_META_KEY]: streamToken } : undefined,
-      url: handle.url,
-      isActive: () => active && state.uiServer === handle,
-      sendToolResult: (result: CallToolResult) => {
-        if (!active || state.uiServer !== handle) return;
-        nextStreamSequence += 1;
-        handle.sendToolResult(withStreamEnvelope(result, streamId, nextStreamSequence));
-      },
-      sendResultPatch: (result: CallToolResult) => {
-        if (!active || state.uiServer !== handle) return;
-        nextStreamSequence += 1;
-        handle.sendResultPatch(withStreamEnvelope(result, streamId, nextStreamSequence));
-      },
-      sendToolCancelled: (reason: string) => {
-        if (!active || state.uiServer !== handle) return;
-        return handle.sendToolCancelled(reason);
-      },
-      close: (reason?: string) => {
-        active = false;
-        cleanupStreamListener();
-        handle.close(reason);
-      },
-    };
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    log.error("Failed to start UI session", error instanceof Error ? error : undefined);
-    state.ui?.notify(
-      `MCP UI unavailable for ${request.toolName} (${request.serverName}): ${message}`,
-      "warning",
-    );
-    return null;
-  }
-}

package/dist/builtin/mcp/ui-stream-types.ts

@@ -1,89 +0,0 @@
-import { z } from "zod";
-
-export const UI_STREAM_HOST_CONTEXT_KEY = "pi-mcp-adapter/stream";
-export const UI_STREAM_REQUEST_META_KEY = "pi-mcp-adapter/stream-token";
-export const UI_STREAM_RESULT_PATCH_METHOD = "notifications/pi-mcp-adapter/ui-result-patch";
-export const SERVER_STREAM_RESULT_PATCH_METHOD = "notifications/pi-mcp-adapter/result-patch";
-export const UI_STREAM_STRUCTURED_CONTENT_KEY = "pi-mcp-adapter/stream";
-
-export const uiStreamModeSchema = z.enum(["eager", "stream-first"]);
-export type UiStreamMode = z.infer<typeof uiStreamModeSchema>;
-
-export const visualizationStreamPhaseSchema = z.enum(["shell", "narrative", "structure", "detail", "settled"]);
-export type VisualizationStreamPhase = z.infer<typeof visualizationStreamPhaseSchema>;
-
-export const visualizationStreamFrameTypeSchema = z.enum(["patch", "checkpoint", "final"]);
-export type VisualizationStreamFrameType = z.infer<typeof visualizationStreamFrameTypeSchema>;
-
-export const visualizationStreamStatusSchema = z.enum(["ok", "error"]);
-export type VisualizationStreamStatus = z.infer<typeof visualizationStreamStatusSchema>;
-
-const looseRecordSchema = z.record(z.string(), z.unknown());
-const looseArraySchema = z.array(z.unknown());
-
-export const uiStreamHostContextSchema = z.object({
-  mode: uiStreamModeSchema,
-  streamId: z.string().min(1),
-  intermediateResultPatches: z.boolean(),
-  partialInput: z.boolean(),
-});
-export type UiStreamHostContext = z.infer<typeof uiStreamHostContextSchema>;
-
-export const visualizationStreamEnvelopeSchema = z.object({
-  streamId: z.string().min(1),
-  sequence: z.number().int().nonnegative(),
-  frameType: visualizationStreamFrameTypeSchema,
-  phase: visualizationStreamPhaseSchema,
-  status: visualizationStreamStatusSchema,
-  message: z.string().optional(),
-  spec: looseRecordSchema.optional(),
-  checkpoint: looseRecordSchema.optional(),
-});
-export type VisualizationStreamEnvelope = z.infer<typeof visualizationStreamEnvelopeSchema>;
-
-export const uiStreamCallToolResultSchema = z.object({
-  content: looseArraySchema.optional(),
-  structuredContent: looseRecordSchema.optional(),
-  isError: z.boolean().optional(),
-  _meta: looseRecordSchema.optional(),
-}).passthrough();
-export type UiStreamCallToolResult = z.infer<typeof uiStreamCallToolResultSchema>;
-
-export const uiStreamResultPatchNotificationSchema = z.object({
-  method: z.literal(UI_STREAM_RESULT_PATCH_METHOD),
-  params: uiStreamCallToolResultSchema,
-});
-export type UiStreamResultPatchNotification = z.infer<typeof uiStreamResultPatchNotificationSchema>;
-
-export const serverStreamResultPatchNotificationSchema = z.object({
-  method: z.literal(SERVER_STREAM_RESULT_PATCH_METHOD),
-  params: z.object({
-    streamToken: z.string().min(1),
-    result: uiStreamCallToolResultSchema,
-  }),
-});
-export type ServerStreamResultPatchNotification = z.infer<typeof serverStreamResultPatchNotificationSchema>;
-
-export interface UiStreamSummary {
-  streamId: string;
-  mode: UiStreamMode;
-  frames: number;
-  phases: VisualizationStreamPhase[];
-  finalStatus?: VisualizationStreamStatus;
-  lastMessage?: string;
-}
-
-export function getUiStreamHostContext(hostContext: Record<string, unknown> | undefined): UiStreamHostContext | undefined {
-  const candidate = hostContext?.[UI_STREAM_HOST_CONTEXT_KEY];
-  const parsed = uiStreamHostContextSchema.safeParse(candidate);
-  return parsed.success ? parsed.data : undefined;
-}
-
-export function getVisualizationStreamEnvelope(structuredContent: unknown): VisualizationStreamEnvelope | undefined {
-  if (!structuredContent || typeof structuredContent !== "object" || Array.isArray(structuredContent)) {
-    return undefined;
-  }
-  const candidate = (structuredContent as Record<string, unknown>)[UI_STREAM_STRUCTURED_CONTENT_KEY];
-  const parsed = visualizationStreamEnvelopeSchema.safeParse(candidate);
-  return parsed.success ? parsed.data : undefined;
-}

package/dist/builtin/mcp/utils.ts

@@ -1,165 +0,0 @@
-import type { ExtensionAPI } from "@bastani/atomic";
-import { unflattenArgumentsWithSchema } from "@bastani/atomic";
-import { homedir, platform } from "node:os";
-import { join } from "node:path";
-import type { McpConfig, ServerEntry } from "./types.ts";
-
-async function execOpen(pi: ExtensionAPI, target: string, browser?: string) {
-  const os = platform();
-
-  if (os === "darwin") {
-    return browser ? pi.exec("open", ["-a", browser, target]) : pi.exec("open", [target]);
-  }
-  if (os === "win32") {
-    return browser
-      ? pi.exec("cmd", ["/c", "start", "", browser, target])
-      : pi.exec("cmd", ["/c", "start", "", target]);
-  }
-  return browser ? pi.exec(browser, [target]) : pi.exec("xdg-open", [target]);
-}
-
-export async function openUrl(pi: ExtensionAPI, url: string, browser?: string): Promise<void> {
-  const result = await execOpen(pi, url, browser);
-  if (result.code !== 0) {
-    throw new Error(result.stderr || `Failed to open browser (exit code ${result.code})`);
-  }
-}
-
-export async function openPath(pi: ExtensionAPI, targetPath: string): Promise<void> {
-  const result = await execOpen(pi, targetPath);
-  if (result.code !== 0) {
-    throw new Error(result.stderr || `Failed to open path (exit code ${result.code})`);
-  }
-}
-
-export async function parallelLimit<T, R>(
-  items: T[],
-  limit: number,
-  fn: (item: T) => Promise<R>
-): Promise<R[]> {
-  const results: R[] = [];
-  let index = 0;
-
-  async function worker() {
-    while (index < items.length) {
-      const i = index++;
-      results[i] = await fn(items[i]);
-    }
-  }
-
-  const workers = Array(Math.min(limit, items.length)).fill(null).map(() => worker());
-  await Promise.all(workers);
-  return results;
-}
-
-export function getConfigPathFromArgv(): string | undefined {
-  const idx = process.argv.indexOf("--mcp-config");
-  if (idx >= 0 && idx + 1 < process.argv.length) {
-    return process.argv[idx + 1];
-  }
-  return undefined;
-}
-
-export function interpolateEnvVars(value: string): string {
-  return value
-    .replace(/\$\{(\w+)\}/g, (_, name) => process.env[name] ?? "")
-    .replace(/\$env:(\w+)/g, (_, name) => process.env[name] ?? "");
-}
-
-export function interpolateEnvRecord(values: Record<string, string> | undefined): Record<string, string> | undefined {
-  if (!values) return undefined;
-
-  const resolved: Record<string, string> = {};
-  for (const [key, value] of Object.entries(values)) {
-    resolved[key] = interpolateEnvVars(value);
-  }
-  return resolved;
-}
-
-export function resolveConfigPath(value: string | undefined): string | undefined {
-  if (value === undefined) return undefined;
-
-  const resolved = interpolateEnvVars(value);
-  if (resolved === "~") return homedir();
-  if (resolved.startsWith("~/") || resolved.startsWith("~\\")) {
-    return join(homedir(), resolved.slice(2));
-  }
-  return resolved;
-}
-
-export function resolveBearerToken(definition: Pick<ServerEntry, "bearerToken" | "bearerTokenEnv">): string | undefined {
-  if (definition.bearerToken !== undefined) {
-    return interpolateEnvVars(definition.bearerToken);
-  }
-  return definition.bearerTokenEnv ? process.env[definition.bearerTokenEnv] : undefined;
-}
-
-export function truncateAtWord(text: string, target: number): string {
-  if (!text || text.length <= target) return text;
-
-  const truncated = text.slice(0, target);
-  const lastSpace = truncated.lastIndexOf(" ");
-
-  if (lastSpace > target * 0.6) {
-    return truncated.slice(0, lastSpace) + "...";
-  }
-
-  return truncated + "...";
-}
-
-export function formatAuthRequiredMessage(
-  config: Pick<McpConfig, "settings">,
-  serverName: string,
-  defaultMessage: string,
-): string {
-  const template = config.settings?.authRequiredMessage;
-  return template ? template.replaceAll("${server}", serverName) : defaultMessage;
-}
-
-/**
- * Extract the adapter-owned UI stream mode from tool metadata.
- */
-export function extractToolUiStreamMode(toolMeta: Record<string, unknown> | undefined): "eager" | "stream-first" | undefined {
-  const uiMeta = toolMeta?.ui;
-  if (!uiMeta || typeof uiMeta !== "object") return undefined;
-  const streamMode = (uiMeta as Record<string, unknown>)["pi-mcp-adapter.streamMode"];
-  if (streamMode === "eager" || streamMode === "stream-first") {
-    return streamMode;
-  }
-  return undefined;
-}
-
-/**
- * Reconstruct flattened tool-call arguments into proper nested arrays/objects.
- *
- * Some upstream providers — notably GitHub Copilot Gemini models proxied through
- * Google's GenAI API — serialize array/object function-call arguments as
- * flattened, indexed keys on the wire. For example a tool called with
- * `{ keywords: ["a", "b"] }` arrives as `{ "keywords[0]": "a", "keywords[1]": "b" }`,
- * which an MCP server then rejects as invalid arguments.
- *
- * This normalizer runs at the MCP `callTool` boundary so arguments are correct
- * regardless of how the model/provider serialized them. It is provider-agnostic
- * and schema-aware:
- *
- * - Bracket-indexed keys (`ids[0]`, `files[0].path`) are **always**
- *   reconstructed — they are unambiguous.
- * - Purely dotted keys (`parent.child`) are reconstructed only when the tool's
- *   `inputSchema` proves their head segment is an object/array container
- *   property. The presence of a bracket-indexed sibling does NOT force a pure
- *   dotted key to split, so a literal property name such as `filter.name`
- *   survives intact even when a sibling like `ids[0]` is present (issue #1496).
- * - Otherwise dotted keys are preserved verbatim — so a literal property name
- *   such as `filter.name` (a legitimate top-level schema property) is no longer
- *   silently split into `{ filter: { name } }`.
- *
- * When no schema is supplied (the legacy call shape), bracket-indexed payloads
- * are still reconstructed while pure dotted keys are preserved verbatim.
- */
-export function unflattenToolArguments(
-  args: Record<string, unknown> | null | undefined,
-  inputSchema?: unknown,
-): Record<string, unknown> {
-  if (args === null || args === undefined) return {};
-  return unflattenArgumentsWithSchema(args, inputSchema);
-}

package/dist/builtin/subagents/prompts/gather-context-and-clarify.md

@@ -1,27 +0,0 @@
----
-description: Use subagents to gather codebase context, then ask clarifying questions
----
-
-## Goal
-
-Build enough grounded codebase context to ask only the unresolved questions needed before planning or implementation. Use a small parallel fan-out, typically two or three specialists with distinct angles.
-
-Additional request context:
-
-$@
-
-## Constraints and tools
-
-Choose specialists according to what is unknown: `codebase-locator` for relevant files, directories, tests, and configs; `codebase-analyzer` for current behavior with `file:line` references; `codebase-pattern-finder` for implementations or patterns to model; `codebase-research-locator` for relevant prior docs, tickets, notes, or specs in `research/` and `specs/`; `codebase-research-analyzer` for applicable historical decisions, constraints, and trade-offs; and `codebase-online-researcher` for authoritative external evidence only when it could materially change the answer.
-
-Give each specialist a specific meta-prompt and keep every specialist read-only. Delegate only independent work too large for a handful of tool calls; do not delegate auditing your own work, and prefer one subagent over several. Parallelize independent reads; stay sequential when one result determines the next; synthesize after retrieval. Keep work within the requested scope.
-
-## Output
-
-Synthesize a concise, user-facing brief of roughly 300–600 words: established facts with evidence, remaining implementation-relevant uncertainties, and focused questions. Then use the `interview` tool to ask those unresolved questions so we reach shared understanding. Lead with the outcome; keep facts, decisions, caveats, and next steps; drop background and repetition; stay readable rather than compressed into fragments.
-
-Before reporting progress, audit each claim against a tool result from this session. Report only work you can point to evidence for; say so explicitly when something is unverified.
-
-## Stop rule
-
-Done means the specialists have returned concise findings and remaining clarification questions, their evidence has been synthesized, and the unresolved questions have been sent through `interview`. Do not plan or implement in this step.