Skip to content

Claude Code. Any Model. The most powerful AI coding agent now speaks every language.

123 KB
Raw Blame
/**
 * Claudish MCP Server
 *
 * Exposes all claudish models (OpenRouter, Kimi, GLM, Qwen, MiniMax, Gemini, OpenAI,
 * local models, etc.) and sessions as MCP tools for Claude Code.
 * Routes through the same proxy engine as the CLI — same auto-routing, fallback chains,
 * custom routing rules, and provider transports.
 *
 * Run with: claudish --mcp (stdio transport)
 */

import { existsSync, readFileSync, readdirSync } from "node:fs";
import { homedir } from "node:os";
import { dirname, join, resolve } from "node:path";
import { fileURLToPath } from "node:url";
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
import { EFFORT_LEVELS, type EffortLevel, isEffortLevel } from "./adapters/base-api-format.js";
import { searchCatalogModels } from "./adapters/model-catalog.js";
import { prehydrateCredentialsForSpawn } from "./auth/credentials/prehydrate.js";
import { setCredentialPromptRole } from "./auth/credentials/prompt-role.js";
import { writeFileAtomic } from "./fs-atomic.js";
import { loadHooksOnce } from "./hooks/index.js";
import { type ProtocolStdout, isolateProtocolStdout } from "./hooks/output-capture.js";
import { initLogger, log } from "./logger.js";
import { SessionManager } from "./mcp-session/index.js";
import { resolveSetupFrom } from "./mcp-session/inherited-settings.js";
import { parentSessionForCall } from "./mcp-session/parent-session.js";
import { NESTED_INSTRUCTIONS, NESTED_MCP_TOOL_NAMES } from "./mcp/nested-mode.js";
import {
  type HeartbeatHandle,
  NOOP_HEARTBEAT,
  resolveProgressIntervalMs,
  startHeartbeat,
} from "./mcp/progress-heartbeat.js";
import {
  type RunPromptResult,
  runPromptViaClaudeCode,
  stopAllClaudeCodePrintChildren,
} from "./mcp/run-prompt-claude-code.js";
import {
  type RecommendedModelsDoc,
  getRecommendedModels,
  readLastRecommendedModels,
} from "./model-loader.js";
// Imported for the predicate only. child-env's import-time bootstrap is a no-op here:
// a claudish MCP server is never the pane child (it carries no CLAUDISH_PANE_CWD).
import { inMcpSession } from "./pane/child-env.js";
import {
  ContractErrorException,
  type FailureReason,
  MIN_MAGMUX_VERSION,
  SLOT_STATES,
  type SlotState,
  TERMINAL_STATES,
  type TeamRunRow,
  assertMagmuxAvailable,
  checkChildFlags,
  contractMeta,
  ensureSwept,
  installPaneShutdownHooks,
  sockRootFor,
} from "./pane/index.js";
import { findAvailablePort } from "./port-manager.js";
import { readAllModelsCache } from "./providers/all-models-cache.js";
import { latestEffortRecommendations } from "./providers/effort-recommendations.js";
import { ensureEndpointsRegistered } from "./providers/endpoint-registration.js";
import { compareByReleaseDateDesc } from "./providers/model-ordering.js";
import { isLocalProviderName, parseModelChain, parseModelSpec } from "./providers/model-parser.js";
import { nativeRouteFor } from "./providers/native-route.js";
import { renderOpFailureBlock } from "./providers/onepassword.js";
import {
  type PreflightModelResult,
  preflightModel,
  renderPreflightReport,
} from "./providers/preflight-chain.js";
import { probeLink } from "./providers/probe-live.js";
import type { ProbeTarget } from "./providers/probe-runner.js";
import { BUILTIN_PROVIDERS } from "./providers/provider-definitions.js";
import { createProxyServer } from "./proxy-server.js";
import { renderEffortTableMarkdown, renderRecommendedMarkdown } from "./recommended-listing.js";
import { sanitizeForReport } from "./redact.js";
import {
  type ModelStatus,
  type TeamRunOutcome,
  type TeamStatus,
  cancelTeamRun,
  captureTeamSlot,
  getStatus,
  isSupersededRun,
  judgeResponses,
  listTeamRuns,
  preflightTeamRun,
  readTeamInputFile,
  readTeamStatus,
  resizeTeamSlot,
  setupSession,
  shutdownAllTeamRuns,
  startModels,
  summarise,
  teamLiveMaps,
  teamRunRow,
  teamRunRowFromDisk,
  validateSessionPath,
} from "./team-orchestrator.js";
import type { ProxyServer } from "./types.js";
import { VERSION } from "./version.js";

// No `.env` load here. `index.ts` loads the working directory's `.env` through the
// allowlist (dotenv-allowlist.ts) before it imports this module, and that is the only
// `.env` load claudish has. Claude Code starts this server in a checkout before its
// folder-trust dialog, so a second, unfiltered load here would hand the checkout every
// name the allowlist refused (`CLAUDE_PATH`, `NODE_OPTIONS`, base URLs, the pane markers).

// Get __dirname equivalent in ESM
const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);

// ─── Constants ───────────────────────────────────────────────────────────────

const CLAUDISH_CACHE_DIR = join(homedir(), ".claudish");
// OpenRouter's own model list, for `search_models`. Its OWN file: this once shared
// `all-models.json` with the cloud models catalog cache, and each writer erased the
// other's data, because the two hold different shapes.
const OPENROUTER_MODELS_CACHE_PATH = join(CLAUDISH_CACHE_DIR, "openrouter-models.json");
const CACHE_MAX_AGE_DAYS = 2;

/** The server's `instructions`, which the host adds to its system prompt. */
const INSTRUCTIONS = `Claudish MCP server gives you access to external AI models (OpenRouter, Ollama, LM Studio and every claudish provider), and to Claude models on the user's own Claude Code login.

## Which tool

- run_prompt: one quick prompt to one model's API. One request, one answer; no tools, no files, no session.
- create_session: one model doing a task as a full Claude Code session (tools, files, several turns).
- team: several models on the same task, each a full Claude Code session, with optional blind judging.

## Sessions

Each session is an interactive Claude Code running the model in its own headless terminal pane. Nothing is pushed to you while it runs: poll.

1. create_session returns {session_id, state: "STARTING"} at once while Claude Code boots.
2. Poll list_sessions (include_completed: true), about once every 10 seconds. Each row has state, activity, idle_seconds and accounting.
   - STARTING: booting, or the first prompt is not yet accepted.
   - RUNNING: a turn is in progress (activity names the tool in use).
   - AWAITING_INPUT: waiting for send_input — an interactive session between turns, or a turn stopped on a question (activity "AskUserQuestion"). A send declines a question and becomes the next prompt.
   - AWAITING_PERMISSION: a permission or plan-approval dialog is open. A send declines it and becomes the next prompt.
   - COMPLETED, FAILED, TIMEOUT, CANCELLED, EMPTY: finished.
3. send_input may be called at any time; it is queued until the session is idle.
4. COMPLETED: call get_output for the answer.
5. FAILED or TIMEOUT — or COMPLETED with an empty or surprising answer — call get_diagnostics. It returns the child's final screen, the upstream error bodies, the recent state records, the resolved model chain and the paths to the full records. It needs no re-run and no debug flag.
6. capture_session reads a session's current screen; resize_session sets its terminal size (any time, mid-turn included); cancel_session stops it. Nothing stops a session for being idle: a child inside a long build is silent and working.

The session_id from create_session is the key for every session tool.`;

// ─── Types ───────────────────────────────────────────────────────────────────

type ToolGroup = "low-level" | "agentic" | "session" | "debug";

/**
 * Per-call context handed to every tool handler. Built fresh in the CallTool
 * dispatch, so nothing here is shared between concurrent calls.
 *
 * It is an explicit parameter rather than AsyncLocalStorage on purpose: ambient
 * state is exactly what would let a long-lived closure (`SessionManager.onStateChange`,
 * a `runModels` progress callback) read a `progressToken` from whatever call happens
 * to be on the stack later, which is the one bug class this design makes unreachable.
 */
interface ToolCallContext {
  /**
   * Emit ONE keepalive frame right now, in addition to the periodic ones.
   * Safe to call from anywhere inside the handler; a no-op when the client sent
   * no `progressToken`, when the tool did not opt into `heartbeat`, or after the
   * heartbeat has been stopped. Never throws.
   */
  reportProgress: (message?: string) => void;
  /**
   * Fires when the host cancels the call (`notifications/cancelled`) or gives up on it
   * (its own request timeout). From the SDK's `RequestHandlerExtra.signal`. A tool that
   * starts a child process stops it on this signal.
   */
  signal: AbortSignal;
}

interface ToolDefinition {
  name: string;
  description: string;
  inputSchema: {
    type: "object";
    properties?: Record<string, unknown>;
    required?: string[];
  };
  group: ToolGroup;
  /**
   * Opt in to the periodic `notifications/progress` keepalive. Set ONLY on tools
   * that can block past the client's MCP idle window (30 min by default on stdio).
   * The dispatch owns start and stop; the handler cannot leak a timer.
   *
   * The type is the literal `true`, not `boolean`: `heartbeat: false` has no
   * meaning distinct from omitting the flag, and spelling it that way keeps the
   * only legal state an opt-in.
   */
  heartbeat?: true;
  /**
   * Widening this to two parameters costs NOTHING at the existing call sites:
   * TypeScript function types are bivariant in parameter count, so every
   * `async (args) => …` / `async () => …` handler already in this file stays
   * assignable verbatim. A handler that ignores `ctx` also pays nothing at
   * runtime — its heartbeat is `NOOP_HEARTBEAT` unless it opted in above.
   */
  handler: (
    args: Record<string, unknown>,
    ctx: ToolCallContext
  ) => Promise<{
    content: Array<{ type: "text"; text: string }>;
    isError?: boolean;
  }>;
}

// ─── Helper Functions ────────────────────────────────────────────────────────

async function loadAllModels(forceRefresh = false): Promise<any[]> {
  if (!forceRefresh && existsSync(OPENROUTER_MODELS_CACHE_PATH)) {
    try {
      const cacheData = JSON.parse(readFileSync(OPENROUTER_MODELS_CACHE_PATH, "utf-8"));
      const lastUpdated = new Date(cacheData.lastUpdated);
      const ageInDays = (Date.now() - lastUpdated.getTime()) / (1000 * 60 * 60 * 24);
      if (ageInDays <= CACHE_MAX_AGE_DAYS) {
        return cacheData.models || [];
      }
    } catch {
      // Cache invalid
    }
  }

  try {
    const response = await fetch("https://openrouter.ai/api/v1/models");
    if (!response.ok) throw new Error(`API returned ${response.status}`);
    const data = await response.json();
    const models = data.data || [];
    try {
      writeFileAtomic(
        OPENROUTER_MODELS_CACHE_PATH,
        JSON.stringify({ lastUpdated: new Date().toISOString(), models })
      );
    } catch (err) {
      // The fetched list is still the answer; only the cache is lost.
      log(
        `[mcp] OpenRouter models cache write failed: ${err instanceof Error ? err.message : String(err)}`
      );
    }
    return models;
  } catch (err) {
    log(
      `[mcp] OpenRouter models fetch failed: ${err instanceof Error ? err.message : String(err)}`
    );
    try {
      if (existsSync(OPENROUTER_MODELS_CACHE_PATH)) {
        const cacheData = JSON.parse(readFileSync(OPENROUTER_MODELS_CACHE_PATH, "utf-8"));
        return cacheData.models || [];
      }
    } catch (cacheErr) {
      log(
        `[mcp] OpenRouter models cache unreadable: ${cacheErr instanceof Error ? cacheErr.message : String(cacheErr)}`
      );
    }
    return [];
  }
}

// ─── Lazy Proxy Singleton ────────────────────────────────────────────────────
// The proxy runs the same routing engine as the CLI: auto-route, fallback chains,
// custom routing rules, catalog resolution, and all direct provider transports.
// It's started once on first use and reused for all subsequent MCP tool calls.

let proxyInstance: ProxyServer | null = null;
let proxyStarting: Promise<ProxyServer> | null = null;

async function getProxy(): Promise<ProxyServer> {
  if (proxyInstance) return proxyInstance;
  if (proxyStarting) return proxyStarting;

  proxyStarting = (async () => {
    const port = await findAvailablePort(10000, 19999);
    const proxy = await createProxyServer(
      port,
      process.env.OPENROUTER_API_KEY,
      undefined, // no default model — each call specifies its own
      false, // not monitor mode
      process.env.ANTHROPIC_API_KEY,
      undefined, // no model map
      { quiet: true, hostMode: "mcp" }
    );
    proxyInstance = proxy;
    return proxy;
  })();

  return proxyStarting;
}

/** Parse Anthropic SSE stream and extract text content + usage */
export function parseAnthropicSse(raw: string): {
  text: string;
  usage?: { input: number; output: number };
} {
  let text = "";
  let inputTokens = 0;
  let outputTokens = 0;
  let hasUsage = false;

  for (const block of raw.split("\n\n")) {
    const lines = block.split("\n").filter((l) => l.trim());
    let dataStr = "";
    for (const line of lines) {
      if (line.startsWith("data: ")) dataStr += line.slice(6);
    }
    if (!dataStr || dataStr === "[DONE]") continue;

    try {
      const data = JSON.parse(dataStr);
      if (data.type === "message_start" && data.message?.usage) {
        inputTokens = data.message.usage.input_tokens || 0;
        outputTokens = data.message.usage.output_tokens || 0;
        hasUsage = true;
      } else if (data.type === "content_block_delta" && data.delta?.type === "text_delta") {
        text += data.delta.text;
      } else if (data.type === "message_delta" && data.usage) {
        outputTokens = data.usage.output_tokens || outputTokens;
        hasUsage = true;
      }
    } catch {
      // Skip unparseable events
    }
  }

  return { text, usage: hasUsage ? { input: inputTokens, output: outputTokens } : undefined };
}

/**
 * One request through the in-process proxy, for every model that is not a bare
 * Claude name. The body carries NO `max_tokens`: step 5w strips every output-limit
 * field the adapters write and adds the wire's own only when the request has one,
 * except on the Messages API, which requires one and gets the catalog's
 * `maxOutputTokens`. No model limit is pinned here
 * (ai-docs/architecture/wire.md "Output limit").
 *
 * `effort` goes out as `output_config.effort`, the field Claude Code itself sends,
 * so step 5w maps it onto the connection's published levels as it does for Claude
 * Code's own request.
 */
export async function runPromptViaProxy(
  model: string,
  prompt: string,
  systemPrompt?: string,
  effort?: EffortLevel
): Promise<RunPromptResult> {
  const proxy = await getProxy();

  // Build Anthropic Messages API request
  const body: Record<string, unknown> = {
    model,
    messages: [{ role: "user", content: prompt }],
    stream: true,
  };
  if (systemPrompt) {
    body.system = systemPrompt;
  }
  if (effort) {
    body.output_config = { effort };
  }

  const response = await fetch(`${proxy.url}/v1/messages`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(body),
  });

  if (!response.ok) {
    const error = await response.text();
    throw new Error(`Proxy error: ${response.status} - ${error}`);
  }

  const raw = await response.text();
  const parsed = parseAnthropicSse(raw);

  if (!parsed.text) {
    throw new Error("Model returned empty response");
  }

  return { content: parsed.text, usage: parsed.usage };
}

/**
 * One `run_prompt` request, on the path its model needs. `nativeRouteFor` FIRST, as
 * the proxy does (CLAUDE.md invariant): a bare Claude name (`claude-*`, `opus`,
 * `sonnet`, `haiku`, `internal`, ...) runs as one Claude Code print-mode call on the
 * user's own Claude Code login, because the proxy's native route forwards the
 * caller's credential and an MCP call has none. Every other model, including the
 * explicit `anthropic@claude-*` (metered), goes through the in-process proxy. The
 * ORIGINAL model string is passed on; claudish's CLI owns alias normalisation.
 *
 * `effort` reaches only the proxy path: on the print path Claude Code sets the
 * effort of its own Claude model.
 */
export async function runPrompt(
  model: string,
  prompt: string,
  systemPrompt?: string,
  signal?: AbortSignal,
  effort?: EffortLevel
): Promise<RunPromptResult> {
  if (nativeRouteFor(model) !== null) {
    return runPromptViaClaudeCode(model, prompt, systemPrompt, { signal });
  }
  return runPromptViaProxy(model, prompt, systemPrompt, effort);
}

/** `run_prompt`'s success text: the answer, then a footer of token and auth lines. */
function formatRunPromptResult(result: RunPromptResult): string {
  const footer: string[] = [];
  if (result.usage) {
    footer.push(`Tokens: ${result.usage.input} input, ${result.usage.output} output`);
  }
  if (result.auth !== undefined) {
    footer.push(
      result.auth === "subscription"
        ? "Auth: Claude Code login (subscription)"
        : `Auth: ${result.auth}`
    );
  }
  return footer.length > 0 ? `${result.content}\n\n---\n${footer.join("\n")}` : result.content;
}

function fuzzyScore(text: string, query: string): number {
  const lowerText = text.toLowerCase();
  const lowerQuery = query.toLowerCase();
  if (lowerText === lowerQuery) return 1;
  if (lowerText.includes(lowerQuery)) return 0.8;
  let score = 0;
  let queryIndex = 0;
  for (const char of lowerText) {
    if (queryIndex < lowerQuery.length && char === lowerQuery[queryIndex]) {
      score++;
      queryIndex++;
    }
  }
  return queryIndex === lowerQuery.length ? score / lowerText.length : 0;
}

/**
 * Two `fuzzyScore` results this close count as EQUAL relevance, and the
 * freshness tiebreak decides. Chosen well below the smallest meaningful gap
 * fuzzyScore can produce (its subsequence branch is `matched / text.length`,
 * so distinct scores differ by at least ~1e-3 for realistic id lengths) and
 * well above float noise.
 */
const SCORE_TIE_EPSILON = 1e-6;

/**
 * Project a raw model record onto the shape `compareByReleaseDateDesc` reads.
 * `loadAllModels` returns the OpenRouter `/api/v1/models` shape, which dates a
 * model with a unix-seconds `created` rather than an ISO `releaseDate`; the
 * Firebase-derived cache rows use `releaseDate`. Accept either.
 */
function orderingKey(model: any): { releaseDate?: string; id?: string } {
  const releaseDate =
    typeof model?.releaseDate === "string"
      ? model.releaseDate
      : typeof model?.created === "number" && Number.isFinite(model.created)
        ? new Date(model.created * 1000).toISOString()
        : undefined;
  return { releaseDate, id: typeof model?.id === "string" ? model.id : "" };
}

/**
 * The action a caller should take for each failure class. Deterministic strings
 * so the agent branches on a known value instead of parsing prose.
 */
export const NEXT_STEP: Record<FailureReason, string> = {
  cancelled:
    "you stopped this slot; nothing is wrong with it. Re-run it if you still want its vote",
  timeout: "grid mode only — magmux ended the pane. The orchestrator has no deadline",
  boot_timeout:
    "the child never reached its prompt and its screen kept changing — read the evidence " +
    "screen; usually a slow catalog fetch or MCP server start",
  boot_blocked:
    "a screen claudish does not know stopped boot — its text is in `what`; answer it once " +
    "interactively in that directory",
  first_run_dialog:
    "run claude (or claudish --model X) once interactively in that directory and answer the " +
    "dialog named in `what`; claudish never accepts it for you",
  agent_rejected: "fix the agent name; the available agents are listed in `what`",
  prompt_not_accepted: "the REPL never took the prompt — read the evidence screen; retry",
  prompt_not_read:
    "the child never read all of its task file — check that its agent or tool flags allow " +
    "Read and that the model can call tools; `what` says which lines were read",
  child_exited: "read the evidence screen, then retry or drop the model",
  pane_lost: `magmux died — check \`magmux --version\` ≥ ${MIN_MAGMUX_VERSION} and retry`,
  blocked:
    "the child asked a question team cannot answer — make the prompt self-contained or use " +
    "create_session",
  api_error: "retry once, or route via a different provider (or@<model>)",
  refused: "the model refused — rephrase or drop the model",
  empty_output: "retry once; if it repeats, drop the model",
  shape_mismatch:
    "the answer (assistant text after the task was read) did not match. Every assistant " +
    "message of the turn was read from the transcript, so nothing was lost in transit — " +
    "the model did not produce it. Re-prompt with the required format restated; do NOT " +
    "count this slot as a vote",
};

// The preflight "no route" cell moved to `providers/preflight-chain.ts` with the
// rest of the preflight report; re-exported for existing importers.
export { noRouteCell } from "./providers/preflight-chain.js";

/** `18864` → `18.4KB`. */
function fmtSize(n: number): string {
  if (n <= 0) return "0B";
  if (n < 1024) return `${n}B`;
  if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)}KB`;
  return `${(n / (1024 * 1024)).toFixed(1)}MB`;
}

/**
 * Render a team run as a compact, self-delimiting card.
 *
 * Deliberately does NOT emit `JSON.stringify(status)` and does NOT inline raw
 * stderr/stdout. The previous implementation did both, which billed every
 * snippet TWICE — once JSON-escaped in the dump, once raw in the markdown block.
 * Measured worst case (6 models, 3 failures, both snippets at their 2000-char
 * cap): 28,403 B delivered, 12,000 B of it pure duplication (42%).
 *
 * Nothing is lost. Machine-readable status stays one `mode: "status"` call away
 * and on disk at `<session>/status.json`; full stderr/stdout stay in
 * `<session>/errors/<id>.log`, which the card names per failure. The card itself
 * carries reason + one-line detail + next step, which is what a caller needs to
 * decide, without paying for evidence it may never read.
 *
 * Self-delimiting because MCP `resource_link` blocks arrive flattened into the
 * text stream with no separator — a consumer must be able to see where this ends.
 */
/**
 * The MCP `effort` argument: undefined when absent, else a canonical level.
 * Throws a message naming the levels on anything else.
 */
export function effortArg(value: unknown): EffortLevel | undefined {
  if (value === undefined || value === null || value === "" || value === KEEP_EFFORT) {
    return undefined;
  }
  if (isEffortLevel(value)) return value;
  throw new Error(
    `Invalid 'effort': ${JSON.stringify(value)}. Expected one of ${EFFORT_LEVELS.join(", ")} ` +
      `or "${KEEP_EFFORT}" (list_models shows the recommended level per model and task type).`
  );
}

/** The `effort` value that keeps Claude Code's own level, answering the clarification. */
export const KEEP_EFFORT = "default";

/**
 * When a caller sent no effort, the recommended levels of the models that have
 * any, by task type: `{model: {taskType: level}}`, keyed as the caller wrote the
 * model. Undefined when none has a row, so a call with nothing to recommend is
 * never stopped. A native Claude name is skipped: it ignores the effort.
 */
export function effortClarification(
  specs: readonly string[],
  efforts:
    | Readonly<Record<string, Readonly<Record<string, { effort: string }>>>>
    | undefined = latestEffortRecommendations()?.efforts
): Record<string, Record<string, string>> | undefined {
  if (!efforts) return undefined;
  const out: Record<string, Record<string, string>> = {};
  for (const spec of specs) {
    if (nativeRouteFor(spec) !== null) continue;
    const row = efforts[parseModelSpec(spec).model];
    if (!row) continue;
    out[spec] = Object.fromEntries(Object.entries(row).map(([task, rec]) => [task, rec.effort]));
  }
  return Object.keys(out).length > 0 ? out : undefined;
}

/**
 * The answer that stops a call made with no effort: the caller knows its task,
 * so it picks the column and calls again. Starts nothing.
 */
function needsEffortResult(
  recommended: Record<string, Record<string, string>>,
  how: string
): { content: Array<{ type: "text"; text: string }>; isError: true } {
  return {
    content: [
      {
        type: "text" as const,
        text:
          `needs_effort: nothing was started. Map your task to one task type and call again ${how}.\n` +
          `Recommended levels: ${JSON.stringify(recommended, null, 2)}`,
      },
    ],
    isError: true,
  };
}

/**
 * The MCP `team` `efforts` argument: one canonical level per model, keyed by a
 * string of `models` exactly. Undefined when absent; throws on a key that is
 * not in `models` or a value that is not a level, so a typo never runs a slot
 * at an effort the caller did not choose.
 */
export function modelEffortsArg(
  value: unknown,
  models: readonly string[]
): Record<string, EffortLevel> | undefined {
  if (value === undefined || value === null) return undefined;
  if (typeof value !== "object" || Array.isArray(value)) {
    throw new Error(`Invalid 'efforts': expected an object like {"<model>": "<level>"}.`);
  }
  const out: Record<string, EffortLevel> = {};
  for (const [model, level] of Object.entries(value)) {
    if (!models.includes(model)) {
      throw new Error(
        `Invalid 'efforts': ${JSON.stringify(model)} is not one of 'models' ` +
          `(${models.join(", ")}). Keys must match a 'models' entry exactly.`
      );
    }
    if (!isEffortLevel(level)) {
      throw new Error(
        `Invalid 'efforts' for ${model}: ${JSON.stringify(level)}. ` +
          `Expected one of ${EFFORT_LEVELS.join(", ")}.`
      );
    }
    out[model] = level;
  }
  return Object.keys(out).length > 0 ? out : undefined;
}

/** True when `id` is exactly a canonical model id of the cached cloud models catalog. */
function isCanonicalCatalogModel(id: string): boolean {
  return readAllModelsCache()?.entries.some((e) => e.modelId === id) ?? false;
}

/**
 * A model spec as claudish routing must see it. The calling agent often writes a
 * `provider@` the user never asked for (copied from a listing, or guessed), and
 * that bypasses the user's routing: their providers, preferences and overrides.
 * So the provider is removed unless the user required it (`required`), and only
 * where the bare name routes: a single `provider@model` whose model part is a
 * canonical model id of the cloud models catalog. Markers (`+pro`, `#fast`) stay.
 * A chain, a local or custom-URL provider, legacy syntax or a wire id the catalog
 * does not know as a model id (`kc@k3`) is returned unchanged.
 */
export function stripUnrequestedProvider(
  spec: string,
  required: boolean,
  isCatalogModel: (id: string) => boolean = isCanonicalCatalogModel
): string {
  if (required || parseModelChain(spec).length !== 1) return spec;
  const parsed = parseModelSpec(spec);
  if (!parsed.isExplicitProvider || parsed.isLegacySyntax) return spec;
  // Only a built-in claudish provider: a user's custom endpoint (`corp-proxy@gpt-4o`)
  // or an explicit metered `anthropic@claude-*` names a vendor and a bill the
  // bare name would not reach.
  const builtin = BUILTIN_PROVIDERS.find((p) => p.name === parsed.provider);
  if (!builtin || builtin.isLocal || isLocalProviderName(parsed.provider)) return spec;
  if (!isCatalogModel(parsed.model)) return spec;
  return spec.slice(spec.indexOf("@") + 1);
}

/**
 * The MCP `team` `user_required_provider` argument: the specs, exactly as in
 * `models` or `judges`, whose provider the user named. Throws on anything else.
 */
export function userRequiredProvidersArg(
  value: unknown,
  specs: readonly string[]
): ReadonlySet<string> {
  if (value === undefined || value === null) return new Set();
  if (!Array.isArray(value) || value.some((v) => typeof v !== "string")) {
    throw new Error(`Invalid 'user_required_provider': expected an array of model specs.`);
  }
  for (const spec of value as string[]) {
    if (!specs.includes(spec)) {
      throw new Error(
        `Invalid 'user_required_provider': ${JSON.stringify(spec)} is not one of the ` +
          `models (${specs.join(", ")}). Entries must match a 'models' or 'judges' entry exactly.`
      );
    }
  }
  return new Set(value as string[]);
}

/** One `{from, to}` per spec whose provider was removed, for the tool's answer and the log. */
export function strippedProviders(
  specs: readonly string[],
  required: ReadonlySet<string>,
  isCatalogModel?: (id: string) => boolean
): { specs: string[]; stripped: Array<{ from: string; to: string }> } {
  const proposed = specs.map((from) =>
    stripUnrequestedProvider(from, required.has(from), isCatalogModel)
  );
  // Two different specs that would strip to one name (`or@kimi-k3`, `kc@kimi-k3`)
  // are a provider comparison: both keep their provider, so neither slot loses
  // its route or its effort to the other.
  const stripped: Array<{ from: string; to: string }> = [];
  const out = specs.map((from, i) => {
    const to = proposed[i];
    if (to === from) return from;
    const collides = proposed.some((other, j) => j !== i && other === to && specs[j] !== from);
    if (collides) return from;
    stripped.push({ from, to });
    return to;
  });
  if (stripped.length > 0) {
    log(`[mcp] provider removed: ${stripped.map((x) => `${x.from} -> ${x.to}`).join(", ")}`);
  }
  return { specs: out, stripped };
}

/** The note a tool answer carries when it removed a provider. */
function strippedNote(stripped: ReadonlyArray<{ from: string; to: string }>): string | undefined {
  if (stripped.length === 0) return undefined;
  return (
    `Provider removed so claudish routing decides: ${stripped.map((x) => `${x.from} -> ${x.to}`).join(", ")}. ` +
    "Pass 'user_required_provider' only when the user named the provider."
  );
}

/**
 * Build the flag list handed to every child Claude Code process.
 *
 * Two inputs, deliberately: `agent` is first-class because selecting a
 * subagent is the common case and a caller should not have to know the flag
 * spelling, and `claude_flags` stays open because claudish forwards ANY
 * unrecognised flag to Claude Code (cli.ts catch-all) — so `--effort`,
 * `--permission-mode`, `--allowedTools` and anything added later work without
 * a claudish release.
 *
 * The dedicated parameter WINS: if `claude_flags` also carries an `--agent`,
 * that pair is dropped rather than emitted twice, so the effective agent is
 * always the one the caller named explicitly.
 */
export function buildChildClaudeFlags(agent: unknown, claudeFlags: unknown): string[] | undefined {
  const extra = typeof claudeFlags === "string" ? claudeFlags.split(/\s+/).filter(Boolean) : [];
  const named = typeof agent === "string" ? agent.trim() : "";

  if (named.startsWith("-")) {
    throw new Error(
      `Invalid 'agent': ${named}. Expected a subagent name (e.g. "dev:reviewer"), not a flag.`
    );
  }

  const cleaned: string[] = [];
  for (let i = 0; i < extra.length; i++) {
    const tok = extra[i];
    // ONLY `--agent`. NOT `--agents`, which is an unrelated Claude Code flag
    // ("--agents <json>: JSON object defining custom agents") — stripping it
    // would silently discard the caller's custom agent DEFINITIONS while they
    // believe they were passed.
    if (named && (tok === "--agent" || tok.startsWith("--agent="))) {
      // Skip the flag and, for the space-separated form, its value. A dangling
      // `--agent` with no value drops just the flag.
      if (tok === "--agent" && extra[i + 1] && !extra[i + 1].startsWith("-")) i++;
      continue;
    }
    cleaned.push(tok);
  }

  const flags = [...(named ? ["--agent", named] : []), ...cleaned];
  return flags.length > 0 ? flags : undefined;
}

/**
 * The prose that stops a caller reading `outputSize` as progress.
 *
 * A slot's `outputSize` is written once, when it finishes, so a working slot
 * always reports 0. Real orchestrators have read that 0 next to a 20-minute-old
 * `startedAt` and concluded the slot produced nothing; one then had to reason its
 * way back out in front of the user. The note leads with that, because a caller
 * skimming a JSON blob reads the first clause and stops.
 *
 * Returned only while some slot is not terminal — on a settled run the states are
 * final, `outputSize` means exactly what it says, and this would be noise.
 */
export function teamStatusNote(opts: {
  anyActive: boolean;
  live: boolean;
  /** slots whose turn sits in `finishing` with no end-of-turn record (R3-M4) */
  endRecordMissing?: string[];
}): string | undefined {
  if (!opts.anyActive) return undefined;
  const trap =
    "outputSize is the size of the FINAL answer and is written once, when a slot " +
    "finishes. Every slot still working therefore reports 0 however much work it has " +
    "done: it is NOT a progress signal, and 0 there does not mean the slot produced nothing.";
  // No live handles means this server did not spawn the run, or was restarted
  // under it. Promising fields that are null would send the reader after
  // evidence that is not there.
  if (!opts.live) {
    return (
      `${trap} This run is not live in this process — it was started elsewhere, or this ` +
      "server restarted — so there are no liveness fields for it and the states above are " +
      "whatever was last written to status.json."
    );
  }
  const missing = opts.endRecordMissing ?? [];
  const missingNote = missing.length
    ? ` Slot(s) ${missing.join(", ")}: the model's message ended long ago with a static ` +
      "screen and no Stop hook running, but Claude Code never wrote its end-of-turn record " +
      "(turn_end_record_missing). Nothing ends such a slot on a timer — cancel it if it " +
      "stays this way."
    : "";
  return (
    `${trap} Judge a working slot on three fields read TOGETHER: ` +
    "live_output_bytes_by_slot (answer bytes so far, the number outputSize will become), " +
    "idle_seconds_by_slot (seconds of silence) and activity_by_slot (what it is doing: a " +
    'tool name, "thinking", "background" or "finishing"). Silence while a tool runs is a ' +
    "build or test suite, and is not a failure signal. Nothing cancels on your behalf — " +
    `use mode:"cancel" if you decide to.${missingNote}`
  );
}

/** A persisted state outside the closed set reads FAILED (terminal), as §8 B says. */
function slotStateOf(m: ModelStatus): string {
  return (SLOT_STATES as readonly string[]).includes(m.state) ? m.state : "FAILED";
}

/**
 * Assemble the `status` response: the legacy path-based payload, the contract's
 * `contract_version`/`capabilities`, and `run` (§8 B). Pure and exported so the payload
 * can be tested without spawning a run: every liveness input is a parameter.
 */
export function buildTeamStatusPayload(opts: {
  status: TeamStatus;
  sessionPath: string;
  idle: Record<string, number> | null;
  activity: Record<string, string> | null;
  liveBytes: Record<string, number> | null;
  run: TeamRunRow;
  endRecordMissing?: string[];
}): Record<string, unknown> {
  const { status, sessionPath, idle, activity, liveBytes } = opts;
  // Keyed on the states, not on liveness. A run this server never spawned can still
  // show working slots from a stale status.json, and that is precisely a reader who
  // is about to misjudge an `outputSize` of 0.
  const anyActive = Object.values(status.models).some(
    (m) => !TERMINAL_STATES.includes(slotStateOf(m) as SlotState)
  );
  const note = teamStatusNote({
    anyActive,
    live: idle !== null,
    endRecordMissing: opts.endRecordMissing,
  });
  return {
    ...status,
    // §8 B: the legacy `models[slot].state` uses the same closed SlotState set as `run`
    // (a pre-contract status.json can still say PENDING; it reads as FAILED, like `run`)
    models: Object.fromEntries(
      Object.entries(status.models ?? {}).map(([id, m]) => [id, { ...m, state: slotStateOf(m) }])
    ),
    // Bytes of answer produced SO FAR, per slot still working. `outputSize` cannot
    // answer this.
    live_output_bytes_by_slot: liveBytes,
    idle_seconds_by_slot: idle,
    // What each slot is DOING, which is what makes the idle number readable. Silence
    // while a tool runs is a build; the same silence in "thinking" is a stalled answer.
    activity_by_slot: activity,
    ...(note ? { note } : {}),
    // The rendered result card, once there is a result to render.
    ...(anyActive ? {} : { summary: formatTeamResult(status, sessionPath) }),
    ...contractMeta(),
    run: opts.run,
  };
}

/** One failed slot on the result card: reason, what happened, next step, evidence. */
function failureLines(id: string, m: ModelStatus): string[] {
  const reason = m.error?.reason;
  const out = [`  ${id}  ${slotStateOf(m)}  reason=${reason ?? "unknown"}`];
  // A blocked slot's detail is the question it stopped on.
  if (m.error?.detail)
    out.push(`      ${reason === "blocked" ? "question" : "what"}: ${m.error.detail}`);
  out.push(`      next: ${(reason && NEXT_STEP[reason]) || "read the evidence log"}`);
  out.push(
    m.error?.errorLogPath
      ? `      evidence: ${m.error.errorLogPath}`
      : "      evidence: NONE CAPTURED — orchestrator bug, report via report_error"
  );
  return out;
}

export function formatTeamResult(status: TeamStatus, sessionPath: string): string {
  const entries = Object.entries(status.models).sort(([a], [b]) => a.localeCompare(b));
  // Everything that is not COMPLETED belongs with the failures: EMPTY (the turn settled
  // but its answer is unusable), CANCELLED (the caller stopped it), FAILED and TIMEOUT.
  // Filing EMPTY under "succeeded" is what forced callers to infer failure from
  // outputSize by hand.
  const succeeded = entries.filter(([, m]) => m.state === "COMPLETED");
  const failed = entries.filter(([, m]) => m.state !== "COMPLETED");

  const lines: string[] = [];
  lines.push(`<<<TEAM_RESULT path="${sessionPath}">>>`);
  lines.push(
    `status: ${failed.length === 0 ? "ok" : succeeded.length === 0 ? "all-failed" : "partial"}` +
      ` — ${succeeded.length}/${entries.length} succeeded`
  );

  if (succeeded.length > 0) {
    lines.push("succeeded:");
    for (const [id, m] of succeeded) {
      lines.push(`  ${id}  ${fmtSize(m.outputSize)}  response-${id}.md`);
      // R3-M5: an open background shell (or a truncated turn) is worth a line.
      for (const a of m.anomalies ?? []) lines.push(`      note: ${a}`);
    }
  }

  if (failed.length > 0) {
    lines.push("failures:");
    for (const [id, m] of failed) lines.push(...failureLines(id, m));
    lines.push("actions:");
    lines.push("  final screen and answer for one failure → Read the evidence path above");
    lines.push(
      `  machine-readable status                → team(mode="status", path="${sessionPath}")`
    );
    lines.push(
      `  report a provider bug                  → report_error(session_path="${sessionPath}")`
    );
  }

  lines.push("<<<END_TEAM_RESULT>>>");
  return lines.join("\n");
}

// ─── team: the mod-contract verbs (§8 A–D) ───────────────────────────────────

type ToolAnswer = { content: Array<{ type: "text"; text: string }>; isError?: boolean };

function contractAnswer(value: unknown): ToolAnswer {
  return { content: [{ type: "text", text: JSON.stringify(value, null, 2) }] };
}

/** Every §8 verb answers its errors as the `ContractError` JSON with `isError: true`. */
function contractErrorAnswer(e: unknown): ToolAnswer {
  const err =
    e instanceof ContractErrorException
      ? e
      : new ContractErrorException("invalid_args", e instanceof Error ? e.message : String(e));
  return {
    content: [{ type: "text", text: JSON.stringify(err.toContractError()) }],
    isError: true,
  };
}

function contractPath(raw: unknown, mode: string): string {
  if (typeof raw !== "string" || !raw)
    throw new ContractErrorException("invalid_args", `'path' is required for mode '${mode}'`);
  try {
    return validateSessionPath(raw);
  } catch (e) {
    throw new ContractErrorException("invalid_args", e instanceof Error ? e.message : String(e));
  }
}

function optionalString(raw: unknown, name: string): string | undefined {
  if (raw === undefined || raw === null) return undefined;
  if (typeof raw !== "string" || !raw)
    throw new ContractErrorException("invalid_args", `'${name}' must be a non-empty string`);
  return raw;
}

/** A boolean argument: absent → false; anything but a JSON boolean is the caller's error. */
function optionalBoolean(raw: unknown, name: string): boolean {
  if (raw === undefined || raw === null) return false;
  if (typeof raw !== "boolean")
    throw new ContractErrorException("invalid_args", `'${name}' must be a boolean`);
  return raw;
}

/** An integer argument such as `since_seq`; absent → undefined. */
function optionalInteger(raw: unknown, name: string): number | undefined {
  if (raw === undefined || raw === null) return undefined;
  if (typeof raw !== "number" || !Number.isInteger(raw))
    throw new ContractErrorException("invalid_args", `'${name}' must be an integer`);
  return raw;
}

/** A required integer argument such as `cols`; absent or not an integer → `invalid_args`. */
function requiredInteger(raw: unknown, name: string, mode?: string): number {
  const n = optionalInteger(raw, name);
  if (n === undefined)
    throw new ContractErrorException(
      "invalid_args",
      `'${name}' is required${mode ? ` for mode '${mode}'` : ""}`
    );
  return n;
}

/**
 * `team(mode="status")` (§8 B): the legacy payload of the newest run at `path` plus
 * `contract_version`, `capabilities` and `run`. Given a `run_id` that a newer run at the
 * same path superseded, only `run` and the contract keys: `status.json` there now
 * belongs to the newer run.
 */
export function teamStatusAnswer(path: string, runId?: string): Record<string, unknown> {
  let row: TeamRunRow | null = null;
  if (runId) {
    row = teamRunRow(path, runId);
    if (!row)
      throw new ContractErrorException(
        "unknown_run",
        `no team run with run_id ${runId} at ${path} is retained by this server`
      );
    if (isSupersededRun(runId)) return { ...contractMeta(), run: row };
  } else {
    row = teamRunRow(path);
  }
  let status: TeamStatus;
  try {
    status = getStatus(path);
  } catch (err) {
    // An absent status.json is normal before a run starts; a corrupt one is not.
    if ((err as NodeJS.ErrnoException)?.code !== "ENOENT") {
      log(
        `[team] unreadable status.json at ${path}: ${err instanceof Error ? err.message : String(err)}`
      );
    }
    if (row) return { ...contractMeta(), run: row };
    throw new ContractErrorException(
      "unknown_run",
      `no team run at ${path}: no status.json there and no run held by this server`
    );
  }
  const live = teamLiveMaps(path, runId);
  return buildTeamStatusPayload({
    status,
    sessionPath: path,
    idle: live?.idle ?? null,
    activity: live?.activity ?? null,
    liveBytes: live?.liveBytes ?? null,
    run: row ?? teamRunRowFromDisk(path, status),
    endRecordMissing: live?.endRecordMissing,
  });
}

/**
 * `list` / `status` / `cancel` / `capture` / `resize`: memory reads and the two pane verbs,
 * JSON answers, ContractError errors.
 */
export async function teamContractVerb(
  mode: "list" | "status" | "cancel" | "capture" | "resize",
  args: Record<string, unknown>
): Promise<ToolAnswer> {
  try {
    if (mode === "list") return contractAnswer(listTeamRuns());
    // Every argument's TYPE is checked before the run is looked up: a wrongly typed argument
    // is the caller's error whether or not the run exists (§8 E).
    const path = contractPath(args.path, mode);
    const runId = optionalString(args.run_id, "run_id");
    const slot = optionalString(args.slot, "slot");
    const since = optionalInteger(args.since_seq, "since_seq");
    const spans = optionalBoolean(args.spans, "spans");
    const cols = mode === "resize" ? requiredInteger(args.cols, "cols", mode) : undefined;
    const rows = mode === "resize" ? requiredInteger(args.rows, "rows", mode) : undefined;
    switch (mode) {
      case "status":
        return contractAnswer(teamStatusAnswer(path, runId));
      case "cancel":
        return contractAnswer(await cancelTeamRun(path, slot, runId));
      case "capture": {
        if (slot === undefined)
          throw new ContractErrorException("invalid_args", "'slot' is required for mode 'capture'");
        return contractAnswer(captureTeamSlot(path, slot, since, spans, runId));
      }
      case "resize": {
        if (slot === undefined)
          throw new ContractErrorException("invalid_args", "'slot' is required for mode 'resize'");
        return contractAnswer(
          await resizeTeamSlot(path, slot, cols as number, rows as number, runId)
        );
      }
    }
  } catch (e) {
    return contractErrorAnswer(e);
  }
}

/**
 * `report_error` sends data OFF this machine, so it gets the full treatment:
 * credentials AND the personal details that identify the user.
 *
 * Replaces a local implementation that knew only `sk-` keys — it missed Google
 * (`AIza…`), xAI, JWTs, GitHub tokens, and every `_TOKEN` / `_SECRET` / `_KEY`
 * variable that wasn't literally named `*_API_KEY`.
 */
const sanitize = sanitizeForReport;

// ─── Tool Definitions ────────────────────────────────────────────────────────

function defineTools(sessionManager: SessionManager, nested: boolean): ToolDefinition[] {
  const tools: ToolDefinition[] = [];

  // A nested server does not register `report_error` (mcp/nested-mode.ts), so an
  // error text must not point at it.
  const reportHint = (text: string): string => (nested ? "" : text);

  // ── Low-Level Tools ──────────────────────────────────────────────────

  /**
   * Append the 1Password failure block to an error a tool is about to return.
   *
   * Every op-source failure is deliberately non-fatal — a broken import must never
   * lock the user out — so the only report was `warnOnce` on STDERR. An MCP host
   * captures that stream and shows the user nothing, which is exactly why a
   * 1Password problem here reads as silence rather than an error: claudish was
   * explaining itself into a pipe nobody reads. Splicing the block into the tool
   * RESULT puts the explanation where the agent and the user will actually see it.
   *
   * Returns the message unchanged when 1Password played no part this run, so
   * non-op users and unrelated failures see byte-identical output.
   */
  function withOpFailureContext(message: string, subject: string): string {
    const block = renderOpFailureBlock(subject);
    return block.length === 0 ? message : `${message}\n\n${block.join("\n")}`;
  }

  tools.push({
    name: "run_prompt",
    description:
      "One quick prompt, straight to one model's API: a single request and its answer. No " +
      "Claude Code session, no tools, no files, no conversation state — this is not subagent " +
      "work. For a task that needs tools, files or more than one turn, use create_session " +
      "(one model) or team (several models). Non-Claude models (Kimi, GLM, Qwen, MiniMax, " +
      "Gemini, GPT, Grok, …) go through claudish's routing straight to the provider's API. " +
      "A Claude model name (claude-*, opus, sonnet, haiku) runs as one Claude Code " +
      "print-mode call on the user's own Claude Code login, with tools, MCP servers and " +
      "settings off.",
    inputSchema: {
      type: "object",
      properties: {
        model: {
          type: "string",
          description:
            "Model name. Pass the bare name (e.g. 'gemini-4-argon'): claudish routing picks " +
            "the provider from the user's setup. A 'provider@' on a catalog model is removed " +
            "unless 'user_required_provider' is true. A bare Claude name (claude-*, opus, " +
            "sonnet, haiku) runs on Claude Code's own login.",
        },
        user_required_provider: {
          type: "boolean",
          description:
            "True only when the USER named the provider ('use OpenRouter for it'): the " +
            "'provider@model' spec is then sent as given.",
        },
        prompt: { type: "string", description: "The prompt to send to the model" },
        system_prompt: { type: "string", description: "Optional system prompt" },
        effort: {
          type: "string",
          enum: [...EFFORT_LEVELS, KEEP_EFFORT],
          description:
            "Reasoning effort for this request. Take it from list_models' " +
            "'Recommended effort by task type' table: your task's column, this model's row. " +
            "Omitted for a model that has a row, the call starts nothing and answers " +
            `'needs_effort' with that row; "${KEEP_EFFORT}" keeps Claude Code's own level. ` +
            "Mapped onto the levels the model's connection publishes. Ignored for a bare " +
            "Claude name.",
        },
      },
      required: ["model", "prompt"],
    },
    group: "low-level",
    // A single reasoning model can block for many minutes with nothing on the
    // wire. Handler body unchanged — the dispatch owns the keepalive.
    heartbeat: true,
    handler: async (args, ctx) => {
      try {
        const { specs, stripped } = strippedProviders(
          [args.model as string],
          new Set(args.user_required_provider === true ? [args.model as string] : [])
        );
        // Keyed as the caller wrote the model, like team's 'efforts' keys.
        const recommended =
          args.effort === undefined ? effortClarification([args.model as string]) : undefined;
        if (recommended) {
          return needsEffortResult(
            recommended,
            `with effort: "<level>" (effort: "${KEEP_EFFORT}" keeps Claude Code's own)`
          );
        }
        const result = await runPrompt(
          specs[0],
          args.prompt as string,
          args.system_prompt as string | undefined,
          ctx.signal,
          effortArg(args.effort)
        );
        const text = [strippedNote(stripped), formatRunPromptResult(result)]
          .filter(Boolean)
          .join("\n\n");
        return { content: [{ type: "text" as const, text }] };
      } catch (error) {
        const errMsg = error instanceof Error ? error.message : String(error);
        return {
          content: [
            {
              type: "text" as const,
              text: withOpFailureContext(
                `Error: ${errMsg}${reportHint(`\n\n---\n**To report this error**, use the \`report_error\` tool with \`error_type: "provider_failure"\` and \`model: "${args.model}"\`.`)}`,
                `while routing ${args.model}`
              ),
            },
          ],
          isError: true,
        };
      }
    },
  });

  tools.push({
    name: "list_models",
    description:
      "List recommended models for coding tasks, and the catalog's recommended reasoning " +
      "effort per model and task type (pass it as team 'efforts' or create_session / " +
      "run_prompt 'effort')",
    inputSchema: { type: "object" },
    group: "low-level",
    handler: async () => {
      // A failed fetch falls back to the list last written to disk, of any
      // generation, and says so; the reason goes to the log, never to stdout.
      let doc: RecommendedModelsDoc | null = null;
      let note = "";
      try {
        doc = await getRecommendedModels();
        if (!doc.models || doc.models.length === 0) {
          log("[mcp] list_models: the recommended list is empty");
          doc = null;
        }
      } catch (err) {
        log(`[mcp] list_models: ${err instanceof Error ? err.message : String(err)}`);
      }
      if (!doc) {
        doc = readLastRecommendedModels();
        if (doc) {
          note =
            "_The live catalog could not be read; this list is from generation " +
            `${doc.generationId ?? "unknown"}, the last one this machine stored._`;
          log(
            `[mcp] list_models: answered from stored generation ${doc.generationId ?? "unknown"}`
          );
        }
      }

      // getRecommendedModels wrote the sidecar on a fetch; an older one still
      // shows the last generation this machine read.
      const efforts = latestEffortRecommendations();
      const effortTable = efforts ? renderEffortTableMarkdown(efforts.efforts) : "";
      const listing = doc
        ? renderRecommendedMarkdown(doc)
        : "No recommended models found. Try search_models instead.";
      const text = [note, listing, effortTable].filter(Boolean).join("\n\n");
      return { content: [{ type: "text" as const, text }] };
    },
  });

  tools.push({
    name: "search_models",
    description:
      "Search OpenRouter's listing by name, provider, or capability, and cross-reference " +
      "claudish's own catalog. SCOPE: the listing covers OpenRouter only, so a name's " +
      "absence from it is NOT evidence the name is unroutable — subscription wire ids " +
      "(`k3`) and catalog aliases live outside that namespace and are reported separately " +
      "here.",
    inputSchema: {
      type: "object",
      properties: {
        query: { type: "string", description: "Search query (e.g., 'grok', 'vision', 'free')" },
        limit: { type: "number", description: "Maximum results to return (default: 10)" },
      },
      required: ["query"],
    },
    group: "low-level",
    handler: async (args) => {
      const query = args.query as string;
      const maxResults = (args.limit as number) || 10;
      const allModels = await loadAllModels();
      if (allModels.length === 0) {
        return {
          content: [
            {
              type: "text" as const,
              text: "Failed to load models. Check your internet connection.",
            },
          ],
          isError: true,
        };
      }
      const results = allModels
        .map((model: any) => {
          const nameScore = fuzzyScore(model.name || "", query);
          const idScore = fuzzyScore(model.id || "", query);
          const descScore = fuzzyScore(model.description || "", query) * 0.5;
          return { model, score: Math.max(nameScore, idScore, descScore) };
        })
        .filter((item: any) => item.score > 0.2)
        // RELEVANCE stays primary — a search must never rank a stale exact
        // match below a fresh fuzzy one. Freshness is the TIEBREAK, which is
        // what decides the many exact ties fuzzyScore produces (1 for an exact
        // match, 0.8 for any substring hit). Scores are floats, so compare them
        // with an epsilon rather than `===`; otherwise a 1e-17 difference
        // between two "equal" subsequence scores would silently keep the old
        // arbitrary insertion order.
        .sort((a: any, b: any) => {
          if (Math.abs(a.score - b.score) > SCORE_TIE_EPSILON) return b.score - a.score;
          return compareByReleaseDateDesc(orderingKey(a.model), orderingKey(b.model));
        })
        .slice(0, maxResults);
      // The listing above is ONE namespace. Subscription wire ids (`k3`) and
      // catalog identities live outside it, so a miss here is not evidence a
      // name is unroutable — and that inference is exactly what sends callers
      // to a metered route. Always report what the catalog knows alongside it.
      const catalogMatches = searchCatalogModels(query, Math.max(maxResults, 5));
      const renderCatalogSection = (): string => {
        if (catalogMatches.length === 0) return "";
        let s = "\n## Catalog names (what claudish routes)\n\n";
        s += "| Bare name | Matched alias | Subscription plan |\n";
        s += "|-----------|---------------|-------------------|\n";
        for (const m of catalogMatches) {
          const plans = m.subscriptionPlanIds.length > 0 ? m.subscriptionPlanIds.join(", ") : "-";
          s += `| ${m.modelId} | ${m.matchedAlias ?? "-"} | ${plans} |\n`;
        }
        s +=
          "\nPass the **bare name**. Routing puts a subscription ahead of the metered API and " +
          "rewrites the model to that plan's wire id for you. An aggregator-qualified id " +
          "(`moonshotai/...`, `accounts/fireworks/...`) pins that aggregator and bills per token.\n";
        return s;
      };

      if (results.length === 0) {
        const catalog = renderCatalogSection();
        const text = catalog
          ? `No OpenRouter listing matches "${query}", but claudish's catalog knows these:\n${catalog}`
          : `No models found matching "${query}".\n\n` +
            "This searched OpenRouter's listing only. Subscription wire ids and catalog " +
            "aliases are not in it, so this is not proof the name is unroutable. Call " +
            "`list_models` for the recommended set.";
        return { content: [{ type: "text" as const, text }] };
      }
      let output = `# Search Results for "${query}"\n\n`;
      output += "## OpenRouter listing\n\n";
      output += "| Model | Provider | Pricing | Context |\n";
      output += "|-------|----------|---------|----------|\n";
      for (const { model } of results) {
        const provider = model.id.split("/")[0];
        const promptPrice = Number.parseFloat(model.pricing?.prompt || "0") * 1000000;
        const completionPrice = Number.parseFloat(model.pricing?.completion || "0") * 1000000;
        const avgPrice = (promptPrice + completionPrice) / 2;
        const pricing =
          avgPrice > 0 ? `$${avgPrice.toFixed(2)}/1M` : avgPrice < 0 ? "varies" : "FREE";
        const context = model.context_length
          ? `${Math.round(model.context_length / 1000)}K`
          : "N/A";
        output += `| ${model.id} | ${provider} | ${pricing} | ${context} |\n`;
      }
      output += renderCatalogSection();
      // Suggest the BARE catalog name, never the top aggregator id. The old
      // footer recommended whatever the listing ranked first — for "kimi" that
      // was `accounts/fireworks/routers/kimi-k3-fast`, a metered address, so
      // the tool's own advice routed users off their subscription.
      const suggested = catalogMatches[0]?.modelId ?? results[0].model.id;
      output += `\nUse with: run_prompt(model="${suggested}", prompt="your prompt")`;
      return { content: [{ type: "text" as const, text: output }] };
    },
  });

  tools.push({
    name: "compare_models",
    description:
      "DEBUG. Send the same single prompt to several models, one after another, and show " +
      "their answers side by side — to check that routes answer or to eyeball raw answers. " +
      "Each model gets exactly what run_prompt sends: one request, no tools, no Claude Code " +
      "session. Not for real work: use team for a blind-judged multi-model run, or " +
      "create_session for one model doing a task.",
    inputSchema: {
      type: "object",
      properties: {
        models: {
          type: "array",
          items: { type: "string" },
          description: "List of model names or model specs to compare, in the order to run them",
        },
        prompt: { type: "string", description: "The prompt to send to all models" },
        system_prompt: { type: "string", description: "Optional system prompt" },
      },
      required: ["models", "prompt"],
    },
    group: "debug",
    // N models run SEQUENTIALLY below, so the total blocking time is the sum of
    // every model's latency — the easiest of the three tools to push past the
    // client's idle window.
    heartbeat: true,
    handler: async (args, ctx) => {
      const modelIds = args.models as string[];
      const prompt = args.prompt as string;
      const systemPrompt = args.system_prompt as string | undefined;

      // Ordering: ARGUMENT order, deliberately. The caller chose this sequence
      // and reads the comparison against it, so the repo-wide newest-first
      // display rule does NOT apply here.
      const results: Array<{
        model: string;
        response: string;
        error?: string;
        tokens?: { input: number; output: number };
      }> = [];
      for (const model of modelIds) {
        try {
          const result = await runPrompt(model, prompt, systemPrompt, ctx.signal);
          results.push({ model, response: result.content, tokens: result.usage });
        } catch (error) {
          results.push({
            model,
            response: "",
            error: error instanceof Error ? error.message : String(error),
          });
        }
        // Belt-and-braces: the periodic timer alone already suffices, but a
        // completed model is real news, so refresh the idle timer at that moment
        // too. Counts only — no model output, no prompt text.
        ctx.reportProgress(`compare_models: ${results.length}/${modelIds.length} models done`);
      }

      let output = "# Model Comparison\n\n";
      output += `**Prompt:** ${prompt.slice(0, 100)}${prompt.length > 100 ? "..." : ""}\n\n`;
      for (const result of results) {
        output += `## ${result.model}\n\n`;
        if (result.error) {
          output += `**Error:** ${result.error}\n\n`;
        } else {
          output += `${result.response}\n\n`;
          if (result.tokens) {
            output += `*Tokens: ${result.tokens.input} in, ${result.tokens.output} out*\n\n`;
          }
        }
        output += "---\n\n";
      }
      const failed = results.filter((r) => r.error);
      if (failed.length > 0) {
        output += reportHint(
          '---\n**To report failed model(s)**, use the `report_error` tool with `error_type: "provider_failure"` and the model ID(s) above.\n'
        );
      }
      return { content: [{ type: "text" as const, text: output }] };
    },
  });

  // ── Agentic Tools ────────────────────────────────────────────────────

  tools.push({
    name: "preflight",
    description:
      "DIAGNOSTIC. For a list of models, report which provider would serve each, " +
      "whether that hop is subscription or metered, and whether it is reachable right " +
      "now. This is for a human investigating a model list. It is NOT a step before " +
      "`team`, `create_session` or `run_prompt` — those resolve their own routing, and " +
      "a caller that hands them a bare model name never needs to know the route.",
    inputSchema: {
      type: "object",
      properties: {
        models: {
          type: "array",
          items: { type: "string" },
          description:
            "Model ids to check — bare (`glm-5.2`) or explicit (`[email protected]`). Bare names go " +
            "through the SAME routing rules and credential filter a real run would use, so " +
            "the provider reported here is the provider that would serve it.",
        },
        probe: {
          type: "boolean",
          description:
            "Send a real short request to each resolved route (default true). Set false for " +
            "a routing/billing answer only — far faster, but it cannot tell you the provider " +
            "is actually reachable, which is the failure this tool exists to catch.",
        },
        timeout_ms: {
          type: "number",
          description:
            "Probe timeout in ms PER HOP (default 20000). A model whose first hop fails is " +
            "probed down its routing chain until a hop serves, so it can take hops × this.",
        },
      },
      required: ["models"],
    },
    group: "agentic",
    // N models each waiting on a live provider can sit well past the client's MCP
    // idle window, and this tool is specifically meant to be called with a big
    // model list — exactly the shape that gets aborted without a keepalive.
    heartbeat: true,
    handler: async (args, ctx) => {
      const models = Array.isArray(args.models) ? (args.models as string[]) : [];
      if (models.length === 0) {
        return {
          content: [{ type: "text" as const, text: "preflight: no models given." }],
          isError: true,
        };
      }

      const doProbe = args.probe !== false;
      const timeoutMs = typeof args.timeout_ms === "number" ? args.timeout_ms : 20_000;
      // Start the proxy only if something will actually be probed. Native names
      // never are (see the loop), so an all-native model list must neither wait on
      // proxy startup nor throw from it.
      const needsProxy = doProbe && models.some((m) => nativeRouteFor(m) === null);
      const proxy = needsProxy ? await getProxy() : null;

      // Register runtime providers before ANY `route()` call below.
      //
      // `preflight` exists to answer "which provider would serve this, and can it
      // right now" before a caller commits slots to a `team` run. Asking that
      // against a registry that has never been populated makes every bundled
      // catalog row and every user `customEndpoints` entry invisible, so a model
      // that works reports "no credentialed provider" — the exact failure mode
      // preflight exists to prevent, produced by preflight itself. Eighth surface
      // of #192; `--probe`, the picker and `providers --json` were the others.
      //
      // Sync, latched, config-only. Free after the first call.
      ensureEndpointsRegistered();

      // Each model is judged by its ROUTING CHAIN (`preflight-chain.ts`): kept hops
      // in chain order, each probed until one serves, a failed hop followed by the
      // runtime's own advance/stop rule. A native Claude name is never probed (the
      // native handler forwards the inbound Claude Code header, which this process
      // does not have), and counts as neither ready nor failed. `timeout_ms` is per
      // hop. Metered hops are probed too: the runtime would use them.
      const probe = proxy
        ? (target: ProbeTarget) =>
            probeLink(
              proxy.url,
              // A kept hop passed the credential filter, so a miss here would be a
              // routing bug, not a missing key.
              { provider: target.provider, modelSpec: target.probeSpec, hasCredentials: true },
              timeoutMs
            )
        : null;

      const results: PreflightModelResult[] = [];
      for (const model of models) {
        ctx.reportProgress(`preflight: ${model}`);
        results.push(
          await preflightModel(model, {
            probe,
            // The heartbeat names what it is waiting on.
            onHop: (hop, total) =>
              ctx.reportProgress(`preflight: ${model} · hop ${hop.index}/${total}`),
          })
        );
      }

      const text = renderPreflightReport(results, { probed: doProbe });
      return { content: [{ type: "text" as const, text }] };
    },
  });

  tools.push({
    name: "team",
    description:
      "Run AI models on a task with anonymized outputs and optional blind judging. Every " +
      "slot is an interactive Claude Code session in its own headless magmux pane. " +
      "Modes: 'run' (START the models and return once each has taken its prompt — it does " +
      "NOT wait for answers), 'status' (per-slot state; read `run.slots`), 'list' (every " +
      "run this server holds), 'capture' (one slot's screen), 'resize' (set one slot's " +
      "terminal size), 'cancel' (stop one slot or the whole run), 'judge'(blind-vote on existing outputs), 'run-and-judge' (the " +
      "blocking pipeline). Poll 'status' (read run.slots) or 'list'. " +
      "NO SLOT IS EVER KILLED ON A TIMER once its prompt is accepted. A team slot is a full " +
      "Claude Code session and may work for a long time; a slot inside a build or test " +
      "suite emits nothing for minutes and is working, not stuck. Judge the silence " +
      "against the task you set, and use 'cancel' if you decide a slot is wedged. A slot " +
      "that stops on a question it cannot answer is FAILED 'blocked' (team has no way to " +
      "answer it). JUDGING A WORKING SLOT: read live_output_bytes_by_slot, " +
      "idle_seconds_by_slot and activity_by_slot (or each row's idle_seconds and " +
      "activity). Do NOT use 'outputSize' — it is the size of the final answer, written " +
      "only when a slot finishes, so it is 0 for every working slot no matter how much " +
      "that slot has produced.",
    inputSchema: {
      type: "object",
      properties: {
        mode: {
          type: "string",
          enum: ["run", "judge", "run-and-judge", "status", "cancel", "list", "capture", "resize"],
          description:
            "Operation mode. 'run' STARTS the models and returns once every slot has taken " +
            "its prompt (or failed to) — it does not wait for answers. Poll 'status' (read " +
            "`run.slots`) or 'list' for progress, then 'judge' once the slots have " +
            "finished. 'capture' returns one slot's screen; 'resize' sets its terminal size. " +
            "'run-and-judge' is the blocking pipeline and holds the call open for the whole run. 'cancel' stops one slot or " +
            "the whole run.",
        },
        slot: {
          type: "string",
          description:
            "For 'cancel', 'capture' and 'resize': the anonymised slot id (e.g. '02') from the " +
            "slot map 'run' returned. 'capture' and 'resize' require it; for 'cancel', omit it " +
            "to stop every slot in the run.",
        },
        path: {
          type: "string",
          description:
            "Session directory path (must be within current working directory). Required " +
            "by every mode except 'list'.",
        },
        run_id: {
          type: "string",
          description:
            "For 'status', 'cancel', 'capture' and 'resize': the run_id a 'run' answer " +
            "returned. It " +
            "addresses THAT run while this server retains it, even after a newer run reused " +
            "the path. Omit it to address the newest run at 'path'.",
        },
        since_seq: {
          type: "number",
          description:
            "For 'capture': the `seq` of the screen you already hold. When it is still " +
            "current the answer is `{unchanged:true}`; any other value returns the full screen.",
        },
        spans: {
          type: "boolean",
          description: "For 'capture': also return the colour/attribute spans of each line.",
        },
        cols: {
          type: "integer",
          description:
            "For 'resize' (required): the terminal width in columns, clamped to 40–9999. The " +
            "answer {run_id, path, slot, cols, rows, changed, seq} reports the size set.",
        },
        rows: {
          type: "integer",
          description:
            "For 'resize' (required): the terminal height in rows, clamped to 24–9999 and to " +
            "at most 4 000 000 cells (cols × rows).",
        },
        models: {
          type: "array",
          items: { type: "string" },
          description:
            "Model IDs to run (required for 'run' and 'run-and-judge' modes). " +
            "Native Claude names ARE runnable slots and belong in this array alongside " +
            "external models: 'internal'/'default' select the default tier, and " +
            "'opus'/'sonnet'/'haiku'/'claude-*' select a specific one. They run on the " +
            "user's Claude subscription through the native passthrough (no API key, no " +
            "translation), and — unlike a Task agent — they are covered by require_pattern, " +
            "so a native reviewer that never produced the required shape is reported " +
            "EMPTY 'shape_mismatch' instead of silently succeeding.",
        },
        efforts: {
          type: "object",
          additionalProperties: { type: "string", enum: [...EFFORT_LEVELS] },
          description:
            "Reasoning effort per model for 'run' and 'run-and-judge', e.g. " +
            '{"gpt-6-luna": "high", "kimi-k3": "max"}. Keys must match a \'models\' ' +
            "entry exactly. Take each level from list_models' 'Recommended effort by task " +
            "type' table: your task's column, the model's row. The slot pins that level on " +
            "every request (claudish --effort-override); a model without an entry keeps " +
            "Claude Code's own effort. Omitted while a model has a row, nothing starts and " +
            "the answer is 'needs_effort' with the rows; {} keeps Claude Code's own for all.",
        },
        judges: {
          type: "array",
          items: { type: "string" },
          description: "Model IDs to use as judges (default: same as runners)",
        },
        user_required_provider: {
          type: "array",
          items: { type: "string" },
          description:
            "The 'models' or 'judges' entries whose provider the USER named ('run Kimi on " +
            "OpenRouter'), exactly as written there. Every other 'provider@' on a catalog " +
            "model is removed so claudish routing picks the provider from the user's setup; " +
            "pass bare names unless the user asked for a provider.",
        },
        input_file: {
          type: "string",
          description:
            "PREFERRED. Path to a file holding the task prompt, relative to the working " +
            "directory. Use this rather than `input` for anything longer than a sentence: " +
            "a prompt passed inline is echoed verbatim in the caller's terminal, where a " +
            "200-line review brief buries every other argument and makes the call " +
            "unreadable. Write the brief to the session directory first (input.md is the " +
            "conventional name) and point here.",
        },
        input: {
          type: "string",
          description:
            "Task prompt as inline text. Prefer `input_file` — inline text is rendered in " +
            "full in the caller's terminal. Passing both is an error. If neither is given, " +
            "an input.md already present in the session directory is used.",
        },
        require_pattern: {
          type: "string",
          description:
            "Regex (no flags) the slot's answer MUST match, or the slot is reported EMPTY " +
            "with reason 'shape_mismatch' instead of succeeded. The answer is the turn's " +
            "assistant text, read from the transcript; for a prompt delivered as a file it " +
            "starts after the child read that file, so `^` anchors to the answer's start. " +
            "Strongly recommended whenever your prompt mandates an output shape — e.g. " +
            "'```vote' for a voting panel.",
        },
        min_output_bytes: {
          type: "number",
          description:
            "Report a slot EMPTY if its answer is shorter than this many bytes (default 0 = " +
            "off). A blunter instrument than require_pattern — short answers can be " +
            "legitimate — so prefer require_pattern when you know the expected shape.",
        },
        agent: {
          type: "string",
          description:
            "Claude Code subagent every child runs as, e.g. 'dev:reviewer', 'dev:architect'. " +
            "Each child is a full Claude Code session, so this loads that agent's system " +
            "prompt and tool allowlist — the same specialisation a Task agent gets, but " +
            "inside the team run, where require_pattern still applies. Applies to EVERY " +
            "model in the run (native and external alike); there is no per-model form. An " +
            "unknown agent fails the slot 'agent_rejected', listing the available agents.",
        },
        claude_flags: {
          type: "string",
          description:
            "Any other Claude Code flags, space-separated (e.g. '--effort high " +
            "--permission-mode plan'): flags and their values only, never positional text. " +
            "One value per flag (write '--allowedTools Read,Bash'). Flags that would break " +
            "the interactive pane (-p, --output-format, --resume, …) and print-mode-only " +
            "flags (--max-turns, --max-budget-usd, …) are refused. Prefer the dedicated " +
            "'agent' parameter for the subagent; an --agent given here is ignored when " +
            "'agent' is also set. NOTE: split on whitespace, so a flag VALUE containing " +
            'spaces (e.g. --append-system-prompt "two words") cannot be expressed here.',
        },
      },
      required: ["mode"],
    },
    group: "agentic",
    // The tool the whole keepalive exists for: a real run was aborted at exactly
    // 1800s with no `notifications/progress` on the wire. A progress frame is the
    // only notification measured to reset the client's MCP idle timer.
    //
    // Still needed even though `run` no longer blocks on answers: `run-and-judge` is
    // the pipeline mode and holds the call open for the whole run, and `run` itself
    // waits up to boot + admission (≤ 120 s) for every slot to take its prompt.
    //
    // The background run keeps calling `ctx.reportProgress` after `run` has
    // returned. That is safe by contract — see ToolCallContext: a no-op once the
    // heartbeat is stopped, and it never throws.
    heartbeat: true,
    handler: async (args, ctx) => {
      const mode = args.mode as string;
      if (
        mode === "list" ||
        mode === "status" ||
        mode === "cancel" ||
        mode === "capture" ||
        mode === "resize"
      ) {
        return teamContractVerb(mode, args);
      }
      try {
        if (mode !== "run" && mode !== "judge" && mode !== "run-and-judge")
          throw new Error(`Unknown mode: ${mode}`);
        const path = args.path;
        if (typeof path !== "string" || !path) throw new Error(`'path' is required for '${mode}'`);
        const givenModels = args.models as string[] | undefined;
        const givenJudges = args.judges as string[] | undefined;
        const requiredProviders = userRequiredProvidersArg(args.user_required_provider, [
          ...(givenModels ?? []),
          ...(givenJudges ?? []),
        ]);
        const modelStrip = givenModels
          ? strippedProviders(givenModels, requiredProviders)
          : undefined;
        const judgeStrip = givenJudges
          ? strippedProviders(givenJudges, requiredProviders)
          : undefined;
        const models = modelStrip?.specs;
        const judges = judgeStrip?.specs;
        const providerNote = strippedNote([
          ...(modelStrip?.stripped ?? []),
          ...(judgeStrip?.stripped ?? []),
        ]);
        // `input_file` is the preferred form: a team prompt is usually a long
        // brief, and inline text is echoed in full in the caller's terminal.
        // Accepting both would silently pick one and discard the other, which is
        // the kind of thing a caller only discovers from the models' answers.
        const inlineInput = args.input as string | undefined;
        const inputFile = args.input_file as string | undefined;
        if (inlineInput !== undefined && inputFile !== undefined) {
          throw new Error(
            "Pass `input_file` or `input`, not both. Prefer `input_file` — inline text is " +
              "rendered verbatim in the caller's terminal."
          );
        }
        const input = inputFile !== undefined ? readTeamInputFile(inputFile) : inlineInput;
        const requirePattern = args.require_pattern as string | undefined;
        const minOutputBytes = args.min_output_bytes as number | undefined;
        const childFlags = buildChildClaudeFlags(args.agent, args.claude_flags) ?? [];
        // No agent probe here: the interactive child refuses an unknown --agent itself,
        // before any model request, and that slot is FAILED agent_rejected (D11).

        const resolved = validateSessionPath(path);

        // Keys name the models as the caller wrote them; the slots run the stripped specs.
        const givenEfforts = givenModels ? modelEffortsArg(args.efforts, givenModels) : undefined;
        const efforts = givenEfforts
          ? Object.fromEntries(
              Object.entries(givenEfforts).map(([m, level]) => [
                models?.[givenModels?.indexOf(m) ?? -1] ?? m,
                level,
              ])
            )
          : undefined;

        const runOpts = {
          requirePattern,
          minOutputBytes,
          claudeFlags: childFlags,
          efforts,
          onProgress: (u: { phase: "running" | "settled" }) => {
            // A state change is real news, so refresh the client's idle timer at
            // that moment as well as on the periodic tick. Short phase string only:
            // the run's progress is read with `team(mode:"status")`, never pushed.
            ctx.reportProgress(`team: ${u.phase}`);
          },
        };

        /** The prompt the slots will get: `input`, else an input.md already in the dir. */
        const promptText = (): string | undefined => {
          if (input !== undefined) return input;
          const existing = join(resolved, "input.md");
          return existsSync(existing) ? readFileSync(existing, "utf-8") : undefined;
        };

        if (
          (mode === "run" || mode === "run-and-judge") &&
          givenModels &&
          args.efforts === undefined
        ) {
          // Keyed as the caller wrote the models: that is how 'efforts' keys must read.
          const recommended = effortClarification(givenModels);
          if (recommended) {
            return needsEffortResult(
              recommended,
              `with efforts: {"<model>": "<level>"} (efforts: {} keeps Claude Code's own for every model)`
            );
          }
        }

        switch (mode) {
          case "run": {
            if (!models?.length) throw new Error("'models' is required for 'run' mode");
            // Every refusal BEFORE anything is written: a refused run leaves no
            // session directory, no record and no pane (§4.1).
            await preflightTeamRun({
              path: resolved,
              slots: models.length,
              claudeFlags: childFlags,
              input: promptText(),
              requirePattern,
            });
            setupSession(resolved, models, input);

            // The run's record in the sessions directory, for observers outside
            // this process (the magus claudish plugin monitor): the run's own
            // status.json lives wherever the caller pointed `path`, and the record
            // is how an observer outside this process learns the run ended.
            // Written BEFORE any pane exists; a throw here fails the call with
            // nothing started.
            const parentClaudeSessionId = await parentSessionForCall({
              hostPid: sessionManager.hostPid,
            });
            const monitorRecord = sessionManager.recordTeamRun({
              teamPath: resolved,
              slots: models.length,
              parentClaudeSessionId,
            });
            const settleRecord = (outcome: TeamRunOutcome): void =>
              sessionManager.finishTeamRun(monitorRecord, outcome);

            // Returns once every slot has LEFT STARTING (D9): its prompt was
            // accepted, or it failed to boot or to take it. Never once the answers
            // exist: a team slot can legitimately work for a long time, and holding
            // the call open for that made the run's duration the client's problem.
            //
            // The record's end is passed IN as `onSettled`, so it exists before
            // the first pane and fires however fast the run settles. If
            // `startModels` throws, it has already reaped whatever it started;
            // the record ends `failed`, `reason: start-failed`, and the ORIGINAL
            // error reaches the caller (`finishTeamRun` never throws).
            let handle: Awaited<ReturnType<typeof startModels>>;
            try {
              handle = await startModels(resolved, {
                ...runOpts,
                onSettled: (status) => settleRecord(summarise(status)),
              });
            } catch (err) {
              const counts = summarise(readTeamStatus(resolved));
              settleRecord({
                ...counts,
                slots: Math.max(counts.slots, models.length),
                failed: models.length - counts.ok - counts.cancelled,
                status: "failed",
                reason: "start-failed",
              });
              throw err;
            }
            const run = teamRunRow(resolved, handle.runId);
            const p = handle.sessionPath;
            return {
              content: [
                {
                  type: "text" as const,
                  text: JSON.stringify(
                    {
                      started: true,
                      run_id: handle.runId,
                      team_session_id: handle.teamSessionId,
                      session_path: p,
                      monitor_record: monitorRecord,
                      slots: handle.slots,
                      run,
                      next: {
                        status: `team(mode:"status", path:"${p}", run_id:"${handle.runId}") — read run.slots`,
                        list: `team(mode:"list")`,
                        capture: `team(mode:"capture", path:"${p}", slot:"<id>")`,
                        cancel: `team(mode:"cancel", path:"${p}", slot:"<id>")`,
                        judge: `team(mode:"judge", path:"${p}") once every slot has finished`,
                      },
                      ...(providerNote ? { provider_note: providerNote } : {}),
                      note:
                        "Every slot has taken its prompt or failed to. Nothing terminates a " +
                        "working slot on a timer: `status` reports each slot's state, " +
                        "activity and seconds of silence; a slot inside a long build is " +
                        "quiet and working. You decide whether to cancel.",
                    },
                    null,
                    2
                  ),
                },
              ],
            };
          }
          case "judge": {
            const verdict = await judgeResponses(resolved, { judges, claudeFlags: childFlags });
            const out = providerNote ? { ...verdict, provider_note: providerNote } : verdict;
            return { content: [{ type: "text" as const, text: JSON.stringify(out, null, 2) }] };
          }
          case "run-and-judge": {
            if (!models?.length) throw new Error("'models' is required for 'run-and-judge' mode");
            await preflightTeamRun({
              path: resolved,
              slots: models.length,
              claudeFlags: childFlags,
              input: promptText(),
              requirePattern,
            });
            setupSession(resolved, models, input);
            const handle = await startModels(resolved, runOpts);
            await handle.done;
            const run = teamRunRow(resolved, handle.runId);
            const verdict = await judgeResponses(resolved, { judges, claudeFlags: childFlags });
            return {
              content: [
                {
                  type: "text" as const,
                  text: JSON.stringify(
                    {
                      ...verdict,
                      run_id: handle.runId,
                      run,
                      ...(providerNote ? { provider_note: providerNote } : {}),
                    },
                    null,
                    2
                  ),
                },
              ],
            };
          }
          default:
            throw new Error(`Unknown mode: ${mode}`);
        }
      } catch (error) {
        return {
          content: [
            {
              type: "text" as const,
              text: withOpFailureContext(
                `Error: ${error instanceof Error ? error.message : String(error)}`,
                "while running the team"
              ),
            },
          ],
          isError: true,
        };
      }
    },
  });

  tools.push({
    name: "report_error",
    description:
      "Report a claudish error to developers. IMPORTANT: Ask the user for consent BEFORE calling this tool. Show them what data will be sent (sanitized). All data is anonymized: API keys, user paths, and emails are stripped. Set auto_send=true to suggest the user enables automatic future reporting.",
    inputSchema: {
      type: "object",
      properties: {
        error_type: {
          type: "string",
          enum: ["provider_failure", "team_failure", "stream_error", "adapter_error", "other"],
          description: "Category of the error",
        },
        model: { type: "string", description: "Model ID that failed (anonymized in report)" },
        command: { type: "string", description: "Command that was run" },
        stderr_snippet: { type: "string", description: "First 500 chars of stderr output" },
        exit_code: { type: "number", description: "Process exit code" },
        error_log_path: { type: "string", description: "Path to full error log file" },
        session_path: { type: "string", description: "Path to team session directory" },
        additional_context: { type: "string", description: "Any extra context about the error" },
        auto_send: {
          type: "boolean",
          description: "If true, suggest the user enable automatic error reporting",
        },
      },
      required: ["error_type"],
    },
    group: "agentic",
    handler: async (args) => {
      const error_type = args.error_type as string;
      const model = args.model as string | undefined;
      const command = args.command as string | undefined;
      const stderr_snippet = args.stderr_snippet as string | undefined;
      const exit_code = args.exit_code as number | undefined;
      const error_log_path = args.error_log_path as string | undefined;
      const session_path = args.session_path as string | undefined;
      const additional_context = args.additional_context as string | undefined;
      const auto_send = args.auto_send as boolean | undefined;

      let stderrFull = stderr_snippet || "";
      if (error_log_path) {
        try {
          stderrFull = readFileSync(error_log_path, "utf-8");
        } catch {}
      }

      const sessionData: Record<string, string> = {};
      if (session_path) {
        const sp = session_path;
        for (const file of ["status.json", "manifest.json", "input.md"]) {
          try {
            sessionData[file] = readFileSync(join(sp, file), "utf-8");
          } catch {}
        }
        try {
          const errorDir = join(sp, "errors");
          if (existsSync(errorDir)) {
            for (const f of readdirSync(errorDir)) {
              if (f.endsWith(".log")) {
                try {
                  sessionData[`errors/${f}`] = readFileSync(join(errorDir, f), "utf-8");
                } catch {}
              }
            }
          }
        } catch {}
        try {
          for (const f of readdirSync(sp)) {
            if (f.startsWith("response-") && f.endsWith(".md")) {
              try {
                const content = readFileSync(join(sp, f), "utf-8");
                sessionData[f] =
                  content.slice(0, 200) + (content.length > 200 ? "... (truncated)" : "");
              } catch {}
            }
          }
        } catch {}
      }

      let version = "unknown";
      try {
        const pkgPath = join(__dirname, "../package.json");
        if (existsSync(pkgPath)) {
          version = JSON.parse(readFileSync(pkgPath, "utf-8")).version;
        }
      } catch {}

      const report = {
        version,
        timestamp: new Date().toISOString(),
        error_type,
        model: model || "unknown",
        command: sanitize(command),
        stderr: sanitize(stderrFull),
        exit_code: exit_code ?? null,
        platform: process.platform,
        arch: process.arch,
        runtime: `bun ${process.version}`,
        context: sanitize(additional_context),
        session: Object.fromEntries(Object.entries(sessionData).map(([k, v]) => [k, sanitize(v)])),
      };

      const reportSummary = JSON.stringify(report, null, 2);
      const autoSendHint = auto_send
        ? "\n\n**Suggestion:** Enable automatic error reporting so future errors are sent without asking. Run `claudish config` → Privacy → toggle Telemetry, or set `CLAUDISH_TELEMETRY=1`."
        : "";

      const REPORT_URL = "https://us-central1-claudish-6da10.cloudfunctions.net/errorReportIngest";

      try {
        const response = await fetch(REPORT_URL, {
          method: "POST",
          headers: { "Content-Type": "application/json" },
          body: JSON.stringify(report),
          signal: AbortSignal.timeout(5000),
        });

        if (response.ok) {
          return {
            content: [
              {
                type: "text" as const,
                text: `Error report sent successfully.\n\n**Sanitized data sent:**\n\`\`\`json\n${reportSummary}\n\`\`\`${autoSendHint}`,
              },
            ],
          };
        }
        return {
          content: [
            {
              type: "text" as const,
              text: `Error report endpoint returned ${response.status}. Report was NOT sent.\n\n**Data that would have been sent (all sanitized):**\n\`\`\`json\n${reportSummary}\n\`\`\`\n\nYou can manually report this at https://github.com/anthropics/claudish/issues${autoSendHint}`,
            },
          ],
        };
      } catch (err) {
        return {
          content: [
            {
              type: "text" as const,
              text: `Could not reach error reporting endpoint (${err instanceof Error ? err.message : "network error"}).\n\n**Sanitized error data (for manual reporting):**\n\`\`\`json\n${reportSummary}\n\`\`\`\n\nReport manually at https://github.com/anthropics/claudish/issues${autoSendHint}`,
            },
          ],
        };
      }
    },
  });

  // ── Session Tools ────────────────────────────────────────────────────

  tools.push({
    name: "create_session",
    description:
      "Create a new claudish proxy session for an external model: an interactive Claude Code running " +
      "it in its own headless magmux pane. Returns at once with state STARTING; nothing is " +
      "pushed while it runs: poll list_sessions (about once every 10 s) for its state, then " +
      "call get_output once it is COMPLETED. With a prompt it is one-shot (it ends when that turn " +
      `settles); without one it is interactive and waits for send_input. Needs magmux >= ${MIN_MAGMUX_VERSION} ` +
      "(darwin and linux).",
    inputSchema: {
      type: "object",
      properties: {
        model: {
          type: "string",
          description:
            "Model name. Pass the bare name (e.g. 'gpt-6.1-sol'): claudish routing picks the " +
            "provider from the user's setup. A 'provider@' on a catalog model is removed " +
            "unless 'user_required_provider' is true.",
        },
        user_required_provider: {
          type: "boolean",
          description:
            "True only when the USER named the provider: the 'provider@model' spec is then " +
            "used as given.",
        },
        prompt: {
          type: "string",
          description: "Initial prompt to send. If omitted, send later via send_input.",
        },
        timeout_seconds: {
          type: "integer",
          minimum: 1,
          maximum: 3600,
          description:
            "Session timeout in whole seconds, 1-3600 (default: 600). Out-of-range values are clamped.",
        },
        agent: {
          type: "string",
          description:
            "Claude Code subagent the session runs as, e.g. 'dev:reviewer'. Equivalent to " +
            "putting '--agent <name>' in claude_flags, and wins over one given there.",
        },
        claude_flags: {
          type: "string",
          description:
            "Any other Claude Code / claudish flags and their values, space-separated — no " +
            "positional text. Unrecognised flags pass through to the child Claude Code. " +
            "Flags the pane owns or that only work in print mode are refused. NOTE: split on " +
            "whitespace, so a flag VALUE containing spaces cannot be expressed here.",
        },
        effort: {
          type: "string",
          enum: [...EFFORT_LEVELS, KEEP_EFFORT],
          description:
            "Reasoning effort for the whole session. Take it from list_models' " +
            "'Recommended effort by task type' table: your task's column, this model's row. " +
            "Pinned on every request (claudish --effort-override), over one in claude_flags. " +
            "Omitted for a model that has a row, nothing starts and the answer is " +
            `'needs_effort' with that row; "${KEEP_EFFORT}" keeps Claude Code's own level.`,
        },
        work_dir: {
          type: "string",
          description: "Working directory for the session (default: current directory)",
        },
        setup_from: {
          type: ["string", "null"],
          description:
            "Directory whose .claude/settings.json and settings.local.json the session " +
            "inherits (enabled plugins, permissions, env), so a session in another work_dir " +
            "keeps the caller's plugins and agents; an explicit path must be an existing " +
            "directory. Default: the caller's project directory, " +
            "when work_dir differs from it. null keeps the session on work_dir's own settings only.",
        },
      },
      required: ["model"],
    },
    group: "session",
    handler: async (args) => {
      try {
        const claudishFlags = buildChildClaudeFlags(args.agent, args.claude_flags) ?? [];
        const effort = effortArg(args.effort);
        if (effort) claudishFlags.push("--effort-override", effort);
        // Refusals first, before any credential work: reserved or positional flags, then
        // a missing magmux (its message starts with the code word). An unknown --agent is
        // refused by the child itself, before any model request (D11).
        const flagCheck = checkChildFlags(claudishFlags);
        if (!flagCheck.ok) throw new Error(`invalid_args: ${flagCheck.message}`);
        await assertMagmuxAvailable();

        // Resolve the model's credential AND its route in THIS process before
        // spawning the child. Several create_session calls in flight at once
        // would otherwise each open their own 1Password SDK client, and the
        // desktop app denies all but one ("Denied authorization for SDK
        // client"). Resolving here write-throughs the key into process.env,
        // which the child inherits; the returned plan pins the bare name to an
        // explicit "provider@model" spec so the child never re-walks the chain
        // and asks 1Password about candidates the parent short-circuited past.
        //
        // Pinning is SKIPPED for a work_dir outside this process's cwd: route()
        // reads project-local config relative to process.cwd(), so the parent
        // would decide with the wrong project's rules. process.chdir() is not
        // an option — it is process-global and races concurrent calls.
        const { specs, stripped } = strippedProviders(
          [args.model as string],
          new Set(args.user_required_provider === true ? [args.model as string] : [])
        );
        const requestedModel = specs[0];
        const recommended =
          args.effort === undefined ? effortClarification([args.model as string]) : undefined;
        if (recommended) {
          return needsEffortResult(
            recommended,
            `with effort: "<level>" (effort: "${KEEP_EFFORT}" keeps Claude Code's own)`
          );
        }
        const workDir = args.work_dir as string | undefined;

        const plan = await prehydrateCredentialsForSpawn([requestedModel], {
          pin: workDir === undefined || resolve(workDir) === process.cwd(),
        });

        // The conversation live in the calling window, from the host's session
        // record: one read at call time, no wait. See mcp-session/parent-session.ts.
        const parentClaudeSessionId = await parentSessionForCall({
          hostPid: sessionManager.hostPid,
        });

        // Reserves the pane, writes prompt.md and spawn.json, then starts the pane; no
        // boot wait.
        const sessionId = await sessionManager.createSession({
          model: requestedModel,
          spawnModel: plan.pinned.get(requestedModel),
          prompt: args.prompt as string | undefined,
          timeoutSeconds: args.timeout_seconds as number | undefined,
          claudishFlags,
          cwd: workDir,
          // Claude Code reads project settings only from the child's own cwd.
          setupFrom: resolveSetupFrom(args.setup_from, workDir, process.cwd()),
          parentClaudeSessionId,
        });

        return {
          content: [
            {
              type: "text" as const,
              text: JSON.stringify({
                session_id: sessionId,
                state: sessionManager.getSession(sessionId).state,
                ...(stripped.length > 0
                  ? { model: requestedModel, note: strippedNote(stripped) }
                  : {}),
              }),
            },
          ],
        };
      } catch (error) {
        const errMsg = error instanceof Error ? error.message : String(error);
        // A missing magmux or a full pane limit is the environment, not the provider:
        // `Error: <code>: …` with the code first (§4.3), and no report_error hint.
        // A refused argument is the CALLER's error: same bare form, never a provider_failure hint.
        const code = (error as { code?: unknown } | null)?.code;
        if (
          code === "magmux_unavailable" ||
          code === "pane_limit" ||
          errMsg.startsWith("invalid_args:")
        ) {
          return { content: [{ type: "text" as const, text: `Error: ${errMsg}` }], isError: true };
        }
        return {
          content: [
            {
              type: "text" as const,
              text: withOpFailureContext(
                `Error creating session: ${errMsg}\n\n---\n**To report this error**, use the \`report_error\` tool with \`error_type: "provider_failure"\` and \`model: "${args.model}"\`.`,
                `while routing ${args.model}`
              ),
            },
          ],
          isError: true,
        };
      }
    },
  });

  tools.push({
    name: "send_input",
    description:
      "Send a prompt to a session. Accepted in every non-terminal state and queued until the " +
      "session is idle: STARTING and RUNNING queue it; AWAITING_INPUT delivers it at once; during " +
      "a question or a permission dialog the dialog is declined (Esc) and the text becomes the next " +
      "prompt. Any accepted send makes a one-shot session interactive. Returns {success, queued} or " +
      "{success:false, reason, state}.",
    inputSchema: {
      type: "object",
      properties: {
        session_id: { type: "string", description: "Session ID from create_session" },
        text: { type: "string", description: "Text to send to the session" },
      },
      required: ["session_id", "text"],
    },
    group: "session",
    handler: async (args) => {
      const result = sessionManager.sendInput(args.session_id as string, args.text as string);
      return {
        content: [{ type: "text" as const, text: JSON.stringify(result) }],
      };
    },
  });

  tools.push({
    name: "get_output",
    description:
      "Get a session's answer prose (each settled turn's assistant text, from its transcript). " +
      "Call once list_sessions shows the session COMPLETED (or between turns of an " +
      "interactive session).",
    inputSchema: {
      type: "object",
      properties: {
        session_id: { type: "string", description: "Session ID from create_session" },
        tail_lines: {
          type: "number",
          description: "Number of lines to return from the end (default: all)",
        },
      },
      required: ["session_id"],
    },
    group: "session",
    handler: async (args) => {
      try {
        const output = sessionManager.getOutput(
          args.session_id as string,
          args.tail_lines as number | undefined
        );
        return {
          content: [{ type: "text" as const, text: JSON.stringify(output) }],
        };
      } catch (error) {
        return {
          content: [
            {
              type: "text" as const,
              text: `Error: ${error instanceof Error ? error.message : String(error)}`,
            },
          ],
          isError: true,
        };
      }
    },
  });

  tools.push({
    name: "cancel_session",
    description:
      "Cancel a session. Returns once its state is CANCELLED ({session_id, state, changed}); the " +
      "pane close and process-group reap finish in the background. Idempotent: a second call " +
      "returns the same state with changed:false. Errors are a JSON ContractError.",
    inputSchema: {
      type: "object",
      properties: {
        session_id: { type: "string", description: "Session ID to cancel" },
      },
      required: ["session_id"],
    },
    group: "session",
    handler: async (args) => {
      try {
        const sessionId = optionalString(args.session_id, "session_id");
        if (sessionId === undefined)
          throw new ContractErrorException("invalid_args", "'session_id' is required");
        return contractAnswer(sessionManager.cancelSession(sessionId));
      } catch (e) {
        return contractErrorAnswer(e);
      }
    },
  });

  tools.push({
    name: "list_sessions",
    description:
      "List sessions: {contract_version, capabilities, sessions}. Optionally include " +
      "finished ones. Each row reports `state`, `activity` and `idle_seconds`: how long since " +
      "the session's screen or transcript last changed. Nothing kills a session for being " +
      "idle — a child inside a long Bash call is silent and working — so this is yours to " +
      "judge against the task you set, and `cancel_session` is yours to call if the answer is no. " +
      "A failed row's `reason_detail` is one line saying why (for api_error, the provider's " +
      "own error message); it is null while the session is live and on COMPLETED.",
    inputSchema: {
      type: "object",
      properties: {
        include_completed: {
          type: "boolean",
          description: "Include completed/failed/cancelled sessions (default: false)",
        },
      },
    },
    group: "session",
    handler: async (args) => {
      try {
        const includeCompleted = optionalBoolean(args.include_completed, "include_completed");
        return contractAnswer({
          ...contractMeta(),
          sessions: sessionManager.listSessionRows(includeCompleted),
        });
      } catch (e) {
        return contractErrorAnswer(e);
      }
    },
  });

  // Diagnostics as API.
  //
  // Two sessions once ran 900 seconds of genuine billed work — 241
  // assistant messages, ~94k output tokens, 150 tool calls — and reported
  // success with an empty output log. The cause was one line, written to
  // `~/.claudish/sessions/<id>/stderr.log` and left there:
  //   [claude-code:unrecognized_model] {"model":"[email protected]"}
  // No MCP tool returned it. Diagnosis meant reading the filesystem by hand,
  // which an agent consuming this interface has no reason to know about — and a
  // failure that has already happened cannot be reproduced with `--debug`.
  //
  // Everything this returns is captured unconditionally while the session runs.
  tools.push({
    name: "get_diagnostics",
    description:
      "Explain what a session actually did — its final screen, upstream error bodies, " +
      "the recent state records, anomalies, the resolved model chain, accounting, and the paths " +
      "to the full records (transcript included). Call this FIRST whenever a session fails, times " +
      "out, or completes with empty or surprising output; it needs no re-run and no debug flag. " +
      "`idleSeconds` reports how long since the screen or transcript last changed, and is null " +
      "once the session is no longer live. It is information, never a verdict: claudish does " +
      "not terminate a session for silence.",
    inputSchema: {
      type: "object",
      properties: {
        session_id: { type: "string", description: "Session ID from create_session" },
        event_limit: {
          type: "number",
          description:
            "How many of the most recent state records to include (default: 40, max: 200). " +
            "0 omits them; `event_log_path` always has the full record.",
        },
      },
      required: ["session_id"],
    },
    group: "session",
    handler: async (args) => {
      try {
        const diagnostics = sessionManager.getDiagnostics(
          args.session_id as string,
          args.event_limit as number | undefined
        );
        return {
          content: [{ type: "text" as const, text: JSON.stringify(diagnostics) }],
        };
      } catch (error) {
        return {
          content: [
            {
              type: "text" as const,
              text: `Error: ${error instanceof Error ? error.message : String(error)}`,
            },
          ],
          isError: true,
        };
      }
    },
  });

  tools.push({
    name: "capture_session",
    description:
      "Read a session's current terminal screen: {seq, cols, rows, cursor, lines, final, " +
      "spans?}. A memory read, meant for polling about once per second. Pass the last `seq` as " +
      "since_seq to get {unchanged:true, seq, final} while nothing changed. `final:true` is the " +
      "last screen of a closed pane. Errors are a JSON ContractError.",
    inputSchema: {
      type: "object",
      properties: {
        session_id: { type: "string", description: "Session ID from create_session" },
        since_seq: {
          type: "number",
          description: "The seq of your previous capture; an equal seq answers {unchanged:true}",
        },
        spans: {
          type: "boolean",
          description: "Include per-row colour and attribute runs (default: false)",
        },
      },
      required: ["session_id"],
    },
    group: "session",
    handler: async (args) => {
      try {
        const sessionId = optionalString(args.session_id, "session_id");
        if (sessionId === undefined)
          throw new ContractErrorException("invalid_args", "'session_id' is required");
        const since = optionalInteger(args.since_seq, "since_seq");
        const spans = optionalBoolean(args.spans, "spans");
        return contractAnswer(sessionManager.captureSession(sessionId, since, spans));
      } catch (e) {
        return contractErrorAnswer(e);
      }
    },
  });

  tools.push({
    name: "resize_session",
    description:
      "Set a session's terminal size: the child gets a real SIGWINCH and Claude Code reflows. " +
      "Allowed at any time, mid-turn included; the last call wins. The size is clamped to " +
      "cols 40–9999, rows 24–9999 and at most 4 000 000 cells (claudish's floor, magmux's " +
      "ceiling); the answer " +
      "{session_id, cols, rows, changed, seq, pending?} reports the size set. `seq` is the screen's seq after the resize: the next capture_session " +
      "shows the new cols/rows. `changed:false` = already that size. `pending:true` = the pane " +
      "is starting or its socket is reconnecting; the size is applied then. A finished session " +
      "answers its last size with changed:false. Errors are a JSON ContractError " +
      "(`resize_unsupported` when the installed magmux has no resize op).",
    inputSchema: {
      type: "object",
      properties: {
        session_id: { type: "string", description: "Session ID from create_session" },
        cols: { type: "integer", description: "Terminal width in columns (clamped to 40–9999)" },
        rows: {
          type: "integer",
          description: "Terminal height in rows (clamped to 24–9999 and 4 000 000 cells)",
        },
      },
      required: ["session_id", "cols", "rows"],
    },
    group: "session",
    handler: async (args) => {
      try {
        const sessionId = optionalString(args.session_id, "session_id");
        if (sessionId === undefined)
          throw new ContractErrorException("invalid_args", "'session_id' is required");
        const cols = requiredInteger(args.cols, "cols");
        const rows = requiredInteger(args.rows, "rows");
        return contractAnswer(await sessionManager.resizeSession(sessionId, cols, rows));
      } catch (e) {
        return contractErrorAnswer(e);
      }
    },
  });

  return tools;
}

// ─── Tool Group Resolution ───────────────────────────────────────────────────

function resolveToolGroups(mode: string): Set<ToolGroup> {
  switch (mode) {
    case "low-level":
      return new Set(["low-level"]);
    case "agentic":
      return new Set(["agentic"]);
    case "session":
      return new Set(["session"]);
    case "debug":
      return new Set(["debug"]);
    default:
      // Every other value — `all`, unset, a typo, or the removed `channel` — is
      // everything. `channel` gets no alias: a rename removes the old name.
      return new Set(["low-level", "agentic", "session", "debug"]);
  }
}

/** Every value `CLAUDISH_MCP_TOOLS` recognises, in the order the docs list them. */
const TOOL_MODES = ["all", "low-level", "agentic", "session", "debug"] as const;

/**
 * The stderr line for a `CLAUDISH_MCP_TOOLS` value that names no tool mode, or
 * undefined for a recognised one. The value still selects every tool; the line
 * exists so a typo, or the removed `channel`, is not silently read as `all`.
 */
function unknownToolModeWarning(mode: string): string | undefined {
  if ((TOOL_MODES as readonly string[]).includes(mode)) return undefined;
  const renamed = mode === "channel" ? " (`channel` was renamed to `session`)" : "";
  return `[claudish] CLAUDISH_MCP_TOOLS=${JSON.stringify(mode)} is not a tool mode${renamed}; selecting all tools. Valid values: ${TOOL_MODES.join(", ")}`;
}

// ─── Server Setup ────────────────────────────────────────────────────────────

/**
 * Whether `claudish --mcp` writes the debug log (`logs/` in the working directory):
 * the same switches as every other claudish run. `--debug-claudish` / `-d` turn it
 * on and `--no-debug-claudish` off, the last one on the command line winning; without
 * a flag, `CLAUDISH_DEBUG` decides (1/true on, 0/false or unset off). The MCP server
 * runs no `parseArgs`, so it reads these itself.
 */
export function mcpDebugLogEnabled(
  argv: readonly string[],
  env: Record<string, string | undefined>
): boolean {
  let flag: boolean | undefined;
  for (const arg of argv) {
    if (arg === "--debug-claudish" || arg === "-d") flag = true;
    else if (arg === "--no-debug-claudish") flag = false;
  }
  if (flag !== undefined) return flag;
  const fromEnv = env.CLAUDISH_DEBUG?.toLowerCase();
  return fromEnv === "1" || fromEnv === "true";
}

async function main() {
  // FIRST, before anything can start loadHooksOnce(): descriptor 1 belongs to
  // the JSON-RPC writer alone. Every other stdout route — Bun's native
  // console.log, process.stdout.write, fs.writeSync(1), Bun.write(Bun.stdout),
  // an inheriting child — lands on stderr or in the debug log, so no hook
  // output (and no stray write of claudish's own) can corrupt the protocol.
  // Where libc cannot be bound, `active` is false, stdout is untouched, and the
  // loader loads no user hook module in this process.
  const iso: ProtocolStdout = isolateProtocolStdout();

  // The always-on structural log (~/.claudish/logs/claudish-mcp_*.log, never
  // stdout) records why a tool answered from a fallback; `--log-off` disables it,
  // as for every other claudish run. The debug log is also where hook output and
  // diverted stdout writes go.
  const argv = process.argv.slice(2);
  initLogger(
    mcpDebugLogEnabled(argv, process.env),
    "debug",
    argv.includes("--log-off"),
    "claudish-mcp",
    500
  );
  if (!iso.active) log(`[mcp] protocol stdout not isolated: ${iso.reason ?? "unknown"}`);

  // Session hooks need the engine without a proxy, so loading starts now, in the
  // background. The MCP server's own proxy (run_prompt, preflight) awaits the
  // same memoised promise before it builds a handler.
  void loadHooksOnce({ hostMode: "mcp" });

  const toolMode = (process.env.CLAUDISH_MCP_TOOLS || "all").toLowerCase();
  // Inside a session a claudish owner started, one level of nesting is the limit:
  // only the one-shot tools of NESTED_MCP_TOOL_NAMES, intersected with the groups
  // CLAUDISH_MCP_TOOLS enables (never widened), no channel capability, and the
  // nested instructions. See pane-session.md § One level of nesting.
  const nested = inMcpSession();
  const enabledGroups = resolveToolGroups(toolMode);
  const toolModeWarning = unknownToolModeWarning(toolMode);
  if (toolModeWarning) console.error(toolModeWarning);

  // Tools only, for every tool mode. No `experimental: {"claude/channel": {}}`: the
  // server pushes nothing; a host polls `list_sessions` and reads the records.
  const server = new Server(
    // `version.ts` is generated from packages/cli/package.json, so serverInfo names
    // the release the host is actually talking to.
    { name: "claudish", version: VERSION },
    {
      capabilities: { tools: {} },
      instructions: nested ? NESTED_INSTRUCTIONS : INSTRUCTIONS,
    }
  );

  // Sessions are observed by polling (`list_sessions`, `get_output`) and through
  // their records on disk; nothing is pushed to the host.
  const sessionManager = new SessionManager();

  // Keepalive cadence for `heartbeat: true` tools. Resolved ONCE per server rather
  // than per call, so a long-lived session cannot change its behaviour mid-flight.
  const progressIntervalMs = resolveProgressIntervalMs();

  // Build tool registry
  const allTools = defineTools(sessionManager, nested);
  const nestedNames: readonly string[] = NESTED_MCP_TOOL_NAMES;
  const enabledTools = allTools.filter(
    (t) => enabledGroups.has(t.group) && (!nested || nestedNames.includes(t.name))
  );
  const toolMap = new Map(enabledTools.map((t) => [t.name, t]));

  console.error(
    `[claudish] MCP server started (tools: ${nested ? "nested" : toolMode}, ${enabledTools.length} tools)`
  );

  // Register ListTools handler
  server.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools: enabledTools.map((t) => ({
      name: t.name,
      description: t.description,
      inputSchema: t.inputSchema,
    })),
  }));

  // Register CallTool handler
  //
  // `extra._meta` is the caller's request `_meta` (SDK protocol.ts sets it from
  // `request.params?._meta`), which is where Claude Code puts `progressToken`. A
  // tool marked `heartbeat: true` gets a periodic `notifications/progress`
  // keepalive for as long as it runs: the client aborts a call that emits nothing
  // for its idle window (30 min on stdio by default — the exact 1800s a real
  // `team` run died at), and a progress frame is the ONLY notification measured to
  // reset that timer.
  //
  // `extra.sendNotification` is preferred over `server.notification` because it is
  // the request-scoped sender; on non-stdio transports it is what correlates the
  // frame with its request. `notifications/progress` needs no capability
  // declaration — the SDK always allows it.
  //
  // The dispatch owns start AND stop. `finally` runs after the result value is
  // computed but before it reaches the SDK, so a frame can never be emitted after
  // the response it belongs to — the GLips/Figma-Context-MCP#362 teardown pattern
  // is structurally unreachable, and a handler cannot forget to stop a timer it
  // never started.
  server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
    const { name, arguments: args } = request.params;
    const tool = toolMap.get(name);
    if (!tool) {
      return {
        content: [{ type: "text" as const, text: `Error: Unknown tool "${name}"` }],
        isError: true,
      };
    }

    const heartbeat: HeartbeatHandle = tool.heartbeat
      ? startHeartbeat({
          token: extra._meta?.progressToken,
          label: name,
          intervalMs: progressIntervalMs,
          send: (frame) =>
            extra.sendNotification({ method: "notifications/progress", params: frame }),
        })
      : NOOP_HEARTBEAT;
    const ctx: ToolCallContext = {
      reportProgress: (message) => heartbeat.tick(message),
      signal: extra.signal,
    };

    try {
      return await tool.handler(args ?? {}, ctx);
    } catch (error) {
      return {
        content: [
          {
            type: "text" as const,
            text: `Error: ${error instanceof Error ? error.message : String(error)}`,
          },
        ],
        isError: true,
      };
    } finally {
      heartbeat.stop();
    }
  });

  // Connect via stdio transport, writing through the protocol writer (the real
  // stdout's private descriptor when isolation is active).
  const transport = new StdioServerTransport(process.stdin, iso.protocolOut);
  await server.connect(transport);
  installMcpShutdown(sessionManager);
  // The startup sweep: panes whose owner died (and whose watcher died too) are reaped
  // after an identity check. Asynchronous, and once per root per process — the first
  // pane's own sweep (ensureSwept in startPaneSession) is this one, not a second `ps`.
  // A nested server registers no session tools and never spawns a pane, so it has
  // nothing to sweep.
  if (!nested)
    void ensureSwept(sockRootFor()).catch((err: unknown) =>
      log(`[mcp] stale pane sweep failed: ${err instanceof Error ? err.message : String(err)}`)
    );
}

/**
 * Shutdown (D15 layer 3, §20.3 item 8): stdin EOF, transport close, SIGINT, SIGTERM and
 * SIGHUP settle every team run and session CANCELLED — so their records end
 * (`meta.json`, the closing wait line) — then reap every pane in parallel and exit.
 * Installed before any pane exists, so `startPaneSession`'s own default hooks never
 * replace these options. A SIGKILL of this process ends no record; the per-pane
 * watchers still remove the panes.
 */
function installMcpShutdown(sessionManager: SessionManager): void {
  const before = async (): Promise<void> => {
    // `run_prompt`'s Claude Code print children are plain processes, not panes: stop
    // their process groups here, or they outlive the server.
    stopAllClaudeCodePrintChildren();
    await Promise.allSettled([shutdownAllTeamRuns(), sessionManager.shutdownAll()]);
  };
  // The stdio transport closes when stdin does, so stdin's `end`/`close` is the
  // transport-close hook too.
  installPaneShutdownHooks({ stdin: true, before });
}

// ─── Entry Point ─────────────────────────────────────────────────────────────

/**
 * Entry point for MCP server mode.
 * Called from index.ts when --mcp flag is used.
 */
export function startMcpServer() {
  // An MCP server never opens a credential dialog: its host is a program, and
  // its panes are pane children (`auth/credentials/prompt-role.ts`).
  setCredentialPromptRole("never");
  main().catch((error) => {
    console.error("[claudish] MCP fatal error:", error);
    process.exit(1);
  });
}