agency-lang 0.8.1 → 0.9.0

package/dist/lib/agents/agency-agent/agent.agency

@@ -1,9 +1,4 @@
-import { getVersion } from "std::agency"
-import {
-  printLocalCatalog,
-  localModelsSupported,
-  listModelNames,
- } from "std::agency/local"
+import { localModelsSupported, listModelNames } from "std::agency/local"
 import { parseArgs } from "std::args"
 import { map } from "std::array"
 import { today } from "std::date"
@@ -11,7 +6,6 @@ import { generateImage } from "std::image"
 import { applyAgentCwd, setAgentCwd } from "std::index"
 import { listHostedModels, hostedModelInfo, setLlmOptions } from "std::llm"
 import { setMemoryId, disableMemory } from "std::memory"
-import { keys } from "std::object"
 import { basename, dirname } from "std::path"
 import {
   ScopedRuleFields,
@@ -24,7 +18,6 @@ import {
   builtinPolicyNames,
   BUILTIN_POLICIES,
  } from "std::policy"
-import { loadMcpToolsWithStatus, mergeMcpServers, isMcpAvailable, readProjectMcpConfig } from "std::mcp"
 import { exists } from "std::shell"
 import { commandsDir, expandSlash } from "std::skills"
 import { highlight } from "std::syntax"
@@ -45,19 +38,33 @@ import {
   clearScreen,
   clearHistory,
  } from "std::ui/cli"
-import { box, render } from "std::ui/layout"
 
-import { figs, title } from "./images/images.agency"
+import { parseAgentArgs } from "./lib/args.agency"
 import { detectAttachments, modalityFilter } from "./lib/attachments.agency"
+import { showCapabilities, editCapabilities } from "./lib/capabilitiesUi.agency"
+import { mergedPalette, projectCommands } from "./lib/commandPalette.agency"
 import {
   POLICY_PATH,
   SESSION_POLICY_PATH,
   HISTORY_PATH,
   ALWAYS_FIELDS,
  } from "./lib/config.agency"
+import { getHeader } from "./lib/header.agency"
+import { generateImageFile } from "./lib/images.agency"
+import { getMcpTools, maybeLoadMcp, mcpSlashCommand } from "./lib/mcp.agency"
 import { filterHostedModels, ModelFilters } from "./lib/modelFilters.agency"
-import { parseModelFlag, parseModelSpec, knownProviders, embeddingSpecHasProvider, missingProviderEnvVar, Resolved } from "./lib/models.agency"
-import { SLOTS } from "./lib/slots.agency"
+import {
+  parseModelFlag,
+  parseModelSpec,
+  knownProviders,
+  missingProviderEnvVar,
+  Resolved,
+ } from "./lib/models.agency"
+import {
+  givePolicyChoice,
+  printPolicyHelp,
+  getPolicyForAgent,
+ } from "./lib/policy.agency"
 import {
   buildLayers,
   resolveAll,
@@ -72,21 +79,29 @@ import {
   availableBackendItems,
  } from "./lib/search.agency"
 import {
-  CAPABILITY_FIELDS,
-  CapabilityPatch,
-  mergeCapabilityOverride,
-  removeCapabilityField,
-  providerLacksEmbeddings,
- } from "./lib/capabilities.agency"
+  Session,
+  switchModel,
+  reactToSlotChange,
+  modelChoiceItems,
+  parseModelsFilters,
+  markMemoryEmbeddingsPinned,
+  pickModelsForAgent,
+ } from "./lib/session.agency"
 import {
-  Settings,
   getCapabilitySettings,
   getModelSettings,
-  getMcpServers,
   loadSettings,
   saveSettings,
  } from "./lib/settings.agency"
-import { truncate, formatArgs, formatToolResponse } from "./lib/utils.agency"
+import { SLOTS } from "./lib/slots.agency"
+import {
+  truncate,
+  formatArgs,
+  formatToolResponse,
+  retryReasonLabel,
+  formatTurnFailure,
+ } from "./lib/utils.agency"
+import { renderLLMCallResponse } from "./lib/utils/renderLLMCallResponse.agency"
 import {
   configureModels,
   configureLocalModel,
@@ -106,7 +121,6 @@ import {
   overrideFromResolved,
   embeddingsOverride,
   providerEnvMissing,
-  demoteProvider,
  } from "./shared.agency"
 import { codeAgent, setCodeOneShot } from "./subagents/code.agency"
 import { explorerAgent } from "./subagents/explorer.agency"
@@ -126,14 +140,18 @@ import { reviewAgent } from "./subagents/review.agency"
 /*
  * Agency Agent — helps users create and modify Agency code.
  *
- * Multi-thread architecture: the agent splits work across two
- * specialists, each with its own thread / system prompt / tool set:
+ * Multi-thread architecture: the coordinator (`mainAgent`) runs the
+ * user's message with the specialists registered as tools. Each
+ * specialist has its own thread / system prompt / tool set, and the
+ * coordinator's LLM delegates by calling one as a tool and getting its
+ * reply back (call/return — not a flat hop/handoff loop):
  *   - `code.agency`     — writes, edits, typechecks, runs code
  *   - `research.agency` — looks up docs, fetches URLs, browses web
+ *   - `review.agency`   — parse/typecheck feedback on Agency code
+ *   - `oracle.agency`   — read-only critique on a stronger model
+ *   - `explorer.agency` — read-only broad codebase/docs synthesis
  *
  * The standard library does the heavy lifting:
- *   - `std::agent.route` runs the per-turn hop loop, owns the
- *     handoff signal, and force-answers when the hop limit is hit.
  *   - `std::policy.cliPolicyHandler` provides the interactive
  *     approve/reject/always menu and persists "always" decisions to
  *     `~/.agency-agent/policy.json`.
@@ -146,7 +164,7 @@ import { reviewAgent } from "./subagents/review.agency"
  *      `mainAgent` and printing the reply into the scroll output.
  *   2. Per-effect ALWAYS_FIELDS map for the policy handler's
  *      "approve-always-here" option.
- *   3. Wire the two specialists into one `RouterConfig`.
+ *   3. Wire the specialists into `mainAgentTools`.
  *
  * Other features:
  * - Doc-as-skills: bundles `docs/site/guide` etc. (copied to
@@ -159,28 +177,29 @@ import { reviewAgent } from "./subagents/review.agency"
  *   editing `.agency` files.
  */
 
-// Verbose tool-call tracing. Enabled either by `AGENT_DEBUG=1` (legacy)
-// or by passing `--debug` / `--verbose` on the command line (set in main()).
 let AGENT_DEBUG: boolean = env("AGENT_DEBUG") == "1"
 let VERBOSE: boolean = false
 
-// Whether the agent is running in interactive (TTY) mode. Set in main()
-// before any tool calls happen, so the callbacks below can suppress
-// scroll-output writes when stdout is destined for a Unix pipe.
+// Whether the agent is running in interactive (TTY) mode.
 let _isInteractive: boolean = true
 
-// The `--policy` argument (a built-in name or a policy-file path), or ""
-// when the flag is absent. Set in main() before `setupSession` runs;
-// consumed there to override the saved policy for this run only.
+// The `--policy` argument (a built-in name or a policy-file path),
+// or "" when absent
 let _policyArg: string = ""
 
-// Live tool-call tracing. Always shown in the interactive REPL; in
-// one-shot mode it's suppressed so piped output is just the reply,
-// unless the user opts in with `--verbose` / `--debug` (AGENT_DEBUG).
+// Live tool-call tracing. Always shown in the interactive REPL, but in
+// one-shot mode it's suppressed unless the user opts in
+// with `--verbose` / `--debug` (AGENT_DEBUG). A function, not a static
+// const: it reads globals that `main()` sets after module init, so the
+// value must be computed per call.
 def _showTraces(): boolean {
   return _isInteractive || VERBOSE || AGENT_DEBUG
 }
 
+/**************************
+**** CALLBACKS / HOOKS ****
+***************************/
+
 callback("onToolCallStart") as data {
   if (_showTraces()) {
     pushMessage(color.yellow("⏺ ${data.toolName}(${formatArgs(data.args)})"))
@@ -206,6 +225,21 @@ callback("onLLMCallStart") as data {
 }
 
 callback("onLLMCallEnd") as data {
+  if (data.result.hostedToolResults) {
+    for (result in data.result.hostedToolResults) {
+      match(result.tool) {
+        "web_search" => {
+          const queries = map(result.queries, \q -> "\"${q}\"").join(", ")
+          // there's also result.sources and result.citations
+          pushMessage(
+            color.yellow(
+            "⏺ web_search(provider: '${result.provider}', queries: [${queries}])",
+          ),
+          )
+        }
+      }
+    }
+  }
   if (AGENT_DEBUG || VERBOSE) {
     pushMessage(
       color.green.dim("💬 [${data.model}] ${renderLLMCallResponse(data.result)}"),
@@ -213,42 +247,6 @@ callback("onLLMCallEnd") as data {
   }
 }
 
-// Map a transient LLM retry reason (an `LLMRetryReason` from the runtime
-// retry layer) to a short, human-facing label. `connectionLost` is the
-// lost-internet / closed-the-laptop case; the rest cover provider hiccups
-// and our own per-call timeout.
-export def retryReasonLabel(reason: string): string {
-  if (reason == "connectionLost") {
-    return "Connection lost"
-  }
-  if (reason == "timeout") {
-    return "Request timed out"
-  }
-  if (reason == "streamInterrupted") {
-    return "Connection interrupted"
-  }
-  if (reason == "rateLimit") {
-    return "Rate limited"
-  }
-  if (reason == "overloaded") {
-    return "Model overloaded"
-  }
-  if (reason == "serverError") {
-    return "Server error"
-  }
-  if (reason == "invalidStructuredOutput") {
-    return "Output failed validation"
-  }
-  return reason
-}
-
-// A transient LLM failure (lost connection, timeout, server hiccup) the
-// runtime is about to retry. Surface a dim, one-line heads-up so the user
-// understands the pause instead of staring at a frozen prompt — this is the
-// "lost internet / closed the laptop" experience the abort taxonomy made
-// distinguishable. Gated like the other traces so piped one-shot output
-// stays clean. `attempt` is the 1-based retry number; `maxRetries` is the
-// configured retry budget.
 callback("onLLMRetry") as data {
   if (_showTraces()) {
     pushMessage(
@@ -259,58 +257,11 @@ callback("onLLMRetry") as data {
   }
 }
 
-// Turn a terminal (retries-exhausted) LLM failure into a short, actionable
-// message. The runtime's exhausted-retry error text embeds the reason in
-// parens, e.g. "LLM call failed after 3 attempts (connectionLost): ...". We
-// recognize the transport reasons that mean "the network or model dropped"
-// and give concrete advice; anything else echoes the raw error so nothing
-// is hidden.
-export def formatTurnFailure(errText: string): string {
-  if (errText.includes("(connectionLost)") || errText.includes("(streamInterrupted)")) {
-    return "⚠ Lost the connection to the model and couldn't recover after retrying.\nCheck your internet connection and try again."
-  }
-  if (errText.includes("(timeout)")) {
-    return "⚠ The model took too long to respond — the request timed out after retrying.\nTry again, perhaps with a smaller request."
-  }
-  if (errText.includes("(rateLimit)") || errText.includes("(overloaded)") || errText.includes("(serverError)")) {
-    return "⚠ The model provider is busy and the request failed after retrying.\nWait a moment and try again."
-  }
-  return "⚠ The request failed: ${errText}"
-}
-
-type ToolCallData = {
-  name: string;
-  arguments: any
-}
-
-type LLMResponse = {
-  output?: string;
-  toolCalls: ToolCallData[];
-  usage: { inputTokens: number; outputTokens: number; totalTokens: number; cachedInputTokens: number };
-  cost: { inputCost: number; outputCost: number; cachedInputCost: number; totalCost: number; currency: string };
-  model: string
-}
-
-def renderLLMCallResponse(data: LLMResponse): string {
-  let response = []
-  if (data.output != "" && data.output != null && data.output != undefined) {
-    response.push(data.output)
-  }
-  if (data.toolCalls.length > 0) {
-    for (toolCall in data.toolCalls) {
-      response.push(`${toolCall.name}(${formatArgs(toolCall.arguments)})`)
-    }
-  }
-  return response.join("\n")
-}
-
 def loadAgentsMd(dir: string): string {
   """
   Read `AGENTS.md` from `dir` if it exists and return it wrapped in a
   <project_context> block ready to splice into a system prompt. Returns
-  an empty string if there is no AGENTS.md or it cannot be read. The
-  read is auto-approved — the user implicitly opted in to scanning the
-  project directory by running the agent there.
+  an empty string if there is no AGENTS.md or it cannot be read.
   """
   if (!exists("AGENTS.md", dir)) {
     return ""
@@ -319,518 +270,166 @@ def loadAgentsMd(dir: string): string {
   if (isFailure(result)) {
     return ""
   }
-  return "\n\n<project_context>\n${result.value}\n</project_context>"
+  return """
+
+  <project_context>
+  ${result.value}
+  </project_context>
+  """
 }
 
 // Per-turn grounding context. Captured at startup and re-used so the
-// LLM doesn't have to re-ground each turn. Initialized in `main()`.
+// LLM doesn't have to re-ground each turn.
 let _context: string = ""
 
-// Project-local slash commands. `cwd()` works at module-init time so
-// we anchor at the user's project root (not the agent's source dir).
-// `with approve` auto-approves the `glob`/`read` during init — the
-// user implicitly opted in by running the agent in this directory.
-static const projectCommands = commandsDir("${cwd()}/.claude/commands") with approve
-
-def builtinPalette(): Record<string, string> {
-  return {
-    "/exit": "Exit the agent",
-    "/clear": "Clear the conversation transcript",
-    "/clear-history": "Clear the input history (recall + saved file)",
-    "/cost": "Show cumulative LLM cost and tokens",
-    "/model": "Switch the model (bare to pick, or slot=model)",
-    "/models": "List / filter the hosted model catalog",
-    "/local": "Switch to a local model",
-    "/search": "Choose the web search backend (hosted / Tavily / Brave / off)",
-    "/settings": "View and change capability settings for the current model",
-    "/mcp": "List configured MCP servers and their tools",
-    "/paste": "Multi-line paste mode (Ctrl+D submits, Ctrl+C cancels)",
-    "/help": "Show available slash commands"
-  }
-}
-
-// Built-ins win over file commands so a user `/clear.md` can't shadow
-// the built-in `/clear`. Build file entries first, then overlay builtins.
-def mergedPalette(): Record<string, string> {
-  let out: Record<string, string> = {}
-  for (cmd in projectCommands) {
-    let label = cmd.description
-    if (cmd.argHint != "") {
-      label = "${cmd.description} ${cmd.argHint}"
-    }
-    out["/${cmd.name}"] = label
-  }
-  const builtins = builtinPalette()
-  for (key in builtins) {
-    out[key] = builtins[key]
-  }
-  return out
-}
-
-// In-session model selection state. One mutable cell holding the current
-// Session (the pin + per-slot overrides chosen via /model this run). switchModel
-// is pure over this value — it copies, never mutates — so it stays testable.
-export type Session = {
-  pin: string;
-  slots: Record<string, string>
-}
-
+// In-session model selection state (the pin + per-slot overrides chosen via
+// `/model` this run). `switchModel` is pure over this value — it copies,
+// never mutates — so the REPL folds its return back in here.
 let _session: Session = {
   pin: "",
   slots: {}
 }
 
-/** Apply an in-session model selection. Copies `prior` (never mutates), folds in
-  the new spec (bare → pin; slot=model → per-slot), resolves, applies, and returns
-  the new session + assignment + the slots that changed (so the caller can react,
-  e.g. the cross-provider recall notice). Turn-boundary semantics: takes effect on
-  the NEXT turn; no in-flight call is mutated. */
-export def switchModel(
-  prior: Session,
-  spec: string,
-  ctx: Ctx,
-  before: Record<string, Resolved>,
-): { session: Session; resolved: Record<string, Resolved>; changes: SlotChange[] } {
-  // The caller builds ctx from currentProvider(), which returns the
-  // PROMOTED name on openai sessions. priceDefault and the built-in
-  // tables key by public provider names, so demote before resolving —
-  // otherwise a switch that lets any slot fall through to the built-in
-  // defaults fails with "openai-responses has no built-in defaults".
-  const ctx2: Ctx = {
-    provider: demoteProvider(ctx.provider),
-    price: ctx.price
-  }
-  let nextSlots: Record<string, string> = {}
-  for (key in Object.keys(prior.slots)) {
-    nextSlots[key] = prior.slots[key]
-  }
-  let next: Session = {
-    pin: prior.pin,
-    slots: nextSlots
-  }
-  const parsed = parseModelFlag(spec)
-  if (parsed.slot != "" && !SLOTS.includes(parsed.slot)) {
-    pushMessage(
-      color.red("Unknown model slot '${parsed.slot}'. Valid slots: ${SLOTS.join(", ")}."),
-    )
-    return {
-      session: prior,
-      resolved: before,
-      changes: []
-    }
-  }
-  if (parsed.slot == "embedding" && !embeddingSpecHasProvider(parsed.model)) {
-    // The embedding slot exists to point AWAY from the chat provider, so
-    // the provider can never be inferred. Require the explicit form.
-    pushMessage(
-      color.red(
-      "Embedding models need the provider/model form, e.g. embedding=openai/text-embedding-3-small.",
-    ),
-    )
-    return {
-      session: prior,
-      resolved: before,
-      changes: []
-    }
-  }
-  if (parsed.slot == "") {
-    next.pin = parsed.model
-  } else {
-    next.slots[parsed.slot] = parsed.model
-  }
-
-  // A saved provider (settings.model.provider) means a provider is established,
-  // so a unified provider/model spec should not be split during resolution.
-  const settings = getModelSettings(loadSettings())
-  const providerEstablished = settings.provider != null && settings.provider != ""
-  const layers = buildLayers(
-    next.pin,
-    next.slots,
-    "",
-    {},
-    settings,
-    knownProviders(),
-    providerEstablished,
+def searchSlashCommand(): boolean {
+  const opts = availableBackendItems()
+  const choice = chooseOption(
+    "Web search backend",
+    "Pick how this agent searches the web. Current: ${getSearchBackend()}",
+    opts,
+    false,
+    true,
   )
-  const all = resolveAll(layers, ctx2)
-  if (isFailure(all)) {
-    pushMessage(color.red("Could not switch model: ${all.error}"))
-    return {
-      session: prior,
-      resolved: before,
-      changes: []
-    }
-  }
-  const resolved = promoteAll(all.value)
-  applyResolved(resolved)
-  return {
-    session: next,
-    resolved: resolved,
-    changes: diffResolved(before, resolved)
+  if (choice != "" && choice != null && choice != undefined) {
+    setSearchBackend(choice)
+    pushMessage("Web search backend set to: ${choice}")
   }
+  return true
 }
 
-/** React to one resolved-slot change. Phase 1: a `main`-slot provider change
-  means the embedding space behind memory changed, so pause memory and warn.
-  (std::memory has no tier-2-only toggle yet -- full pause; structured recall
-  returns when a selective toggle lands.) Returns true if it emitted the notice. */
-export def reactToSlotChange(change: SlotChange): boolean {
-  if (change.slot == "main" && change.before.provider != change.after.provider) {
-    // Skip the pause only when startup actually enabled memory WITH the
-    // override. A set-but-keyless slot took the fallback path, so memory
-    // runs on derived embeddings and the provider change still shifts
-    // the embedding space behind recall.
-    if (_memoryEmbeddingsPinned) {
-      return false
-    }
-    pushMessage(
-      color.dim(
-      "Warning: provider changed - memory is paused until restart (recall would be unreliable).",
-    ),
-    )
-    // `with approve`: the agent is deliberately auto-pausing memory on a
-    // provider switch, not asking the user — so don't surface an approval prompt.
-    disableMemory() with approve
-    return true
-  }
-  if (change.slot == "embedding") {
-    const override = overrideFromResolved(change.after)
-    if (override != null) {
-      const missing = missingProviderEnvVar(override.provider)
-      if (missing != "") {
-        pushMessage(
-          color.yellow(
-          "Warning: the embedding slot needs ${missing}, which is not set. The assignment takes effect at next agent start, and memory falls back to the default embedding behavior until it is exported.",
-        ),
-        )
-        return true
-      }
-      // The healthy path must not be silent: enableMemory already ran,
-      // so the user would otherwise believe embeddings switched now.
+def costSlashCommand(): boolean {
+  // Derive BOTH the header total and the per-model breakdown from the
+  // same process-wide accumulator (getModelCosts), so the `Cost:` /
+  // `Tokens:` lines and the rows below them can never visibly disagree.
+  // (getCost()/getTokens() read the per-branch accumulator, a different
+  // scope — adjacent in the output, they could in principle diverge.)
+  // Rows are sorted by cost descending by getModelCosts(); a subagent
+  // on a pricier model (e.g. the oracle on opus-4.8) shows up here.
+  const byModel = getModelCosts()
+  let totalCost = 0.0
+  let totalTokens = 0
+  for (m in byModel) {
+    totalCost = totalCost + m.cost
+    totalTokens = totalTokens + m.inputTokens + m.outputTokens
+  }
+  pushMessage("Cost:   $${totalCost.toFixed(4)}")
+  pushMessage("Tokens: ${totalTokens}")
+  if (byModel.length > 0) {
+    pushMessage("")
+    pushMessage("By model:")
+    for (m in byModel) {
       pushMessage(
-        color.dim(
-        "Embedding slot set: memory embeddings use ${override.provider}/${override.model} at next agent start.",
-      ),
+        "  ${m.model}  ↑${m.inputTokens} ↓${m.outputTokens}  $${m.cost.toFixed(4)}",
       )
-      return true
     }
   }
-  return false
-}
-
-// ChoiceItem list for the model pickers: the hosted catalog, filtered, each
-// labeled with provider + input price for an informed pick.
-export def modelChoiceItems(filters: ModelFilters): ChoiceItem[] {
-  let items: ChoiceItem[] = []
-  for (model in filterHostedModels(listHostedModels(), filters)) {
-    const label = "${model.name}  (${model.provider}, $${model.inputCost}/1M in)"
-    items.push({
-      key: model.name,
-      label: label
-    })
-  }
-  return items
-}
-
-// Parse a `/models [provider]` command line into filters. Bare `/models` (or a
-// trailing-space-only arg) yields no filters; `/models <provider>` narrows to
-// one provider. Extracted from the handler so it is unit-testable.
-export def parseModelsFilters(cmd: string): ModelFilters {
-  const prefix = "/models "
-  if (!cmd.startsWith(prefix)) {
-    return {}
-  }
-  const arg = cmd.substring(prefix.length).trim()
-  if (arg == "") {
-    return {}
-  }
-  return {
-    provider: arg
-  }
-}
-
-/** Human label for a capability source layer. Interprets the source
-  strings resolveCapabilities emits (capabilities.agency). */
-def capabilitySourceLabel(source: string): string {
-  if (source == "default") {
-    return "built-in default"
-  }
-  if (source == "provider") {
-    return "provider default: ${getCapabilityProvider()}"
-  }
-  if (source == "model") {
-    return "built-in for ${getCapabilityModelKey()}"
-  }
-  if (source == "user-global") {
-    return "your global override"
-  }
-  if (source == "user-provider") {
-    return "your override for ${getCapabilityProvider()}"
-  }
-  return "your override for ${getCapabilityModelKey()}"
+  return true
 }
 
-/** One "value (source)" cell. The typed Capabilities shape cannot be
-  indexed by a dynamic key, so this is the renderer's per-field switch. */
-def capabilityRow(fieldKey: string): string {
-  const resolved = getCapabilitiesResolved()
-  const values = resolved.values
-  const sources = resolved.sources
-  if (fieldKey == "prompt") {
-    return "${values.prompt}   (${capabilitySourceLabel(sources.prompt)})"
-  }
-  if (fieldKey == "summarize") {
-    return "${values.summarize}   (${capabilitySourceLabel(sources.summarize)})"
+def modelSlashCommand(): boolean {
+  let spec = ""
+  if (trimmed != "/model") {
+    spec = trimmed.substring(7).trim()
   }
-  if (fieldKey == "memory") {
-    return "${values.memory}   (${capabilitySourceLabel(sources.memory)})"
+  if (spec == "") {
+    pushMessage("Current models:")
+    const current = getResolvedSlots()
+    for (slot in Object.keys(current)) {
+      const resolved = current[slot]
+      if (resolved != null) {
+        pushMessage("  ${slot}: ${resolved.model} (${resolved.via})")
+      }
+    }
+    const items = modelChoiceItems({})
+    const choice = chooseOption(
+      "Model",
+      "Pick a model, or type one (or slot=model, e.g. reasoning=claude-opus-4-8). Empty to cancel.",
+      items,
+      allowFreeText: true,
+      allowCancel: true,
+    )
+    if (choice == "" || choice == null) {
+      return true
+    }
+    spec = choice
   }
-  let cap = "none"
-  if (values.maxTokens != null) {
-    cap = "${values.maxTokens}"
+  const ctx: Ctx = {
+    provider: currentProvider(),
+    price: "standard"
   }
-  return "${cap}   (${capabilitySourceLabel(sources.maxTokens)})"
-}
-
-/** Render the current profile with per-field provenance. */
-def showCapabilities() {
-  pushMessage("Capabilities for ${getCapabilityModelKey()} (${getCapabilityProvider()}):")
-  for (field in CAPABILITY_FIELDS) {
-    pushMessage("  ${field.label}   ${capabilityRow(field.key)}")
+  const out = switchModel(_session, spec, ctx, getResolvedSlots())
+  _session = out.session
+  for (change in out.changes) {
+    reactToSlotChange(change)
   }
-}
-
-/** The settings.json key a scope writes under. Global's key is unused. */
-def scopeTargetName(scopeKey: string): string {
-  if (scopeKey == "provider") {
-    return getCapabilityProvider()
+  pushMessage("Model set:")
+  for (slot in Object.keys(out.resolved)) {
+    const resolved = out.resolved[slot]
+    if (resolved != null) {
+      pushMessage(color.dim("  ${slot}: ${resolved.model} (${resolved.via})"))
+    }
   }
-  return getCapabilityModelKey()
-}
-
-/** Persist one override patch at a scope, then re-resolve. */
-def saveCapabilityOverride(scopeKey: string, patch: CapabilityPatch) {
-  let settings = loadSettings()
-  settings.capabilities = mergeCapabilityOverride(
-    getCapabilitySettings(settings),
-    scopeKey,
-    scopeTargetName(scopeKey),
-    patch,
-  )
-  saveSettings(settings)
-  refreshCapabilities(getCapabilityModelKey(), getCapabilityProvider())
-}
-
-/** Remove one field override at a scope, then re-resolve. */
-def removeCapabilityOverride(scopeKey: string, fieldKey: string) {
-  let settings = loadSettings()
-  settings.capabilities = removeCapabilityField(
-    getCapabilitySettings(settings),
-    scopeKey,
-    scopeTargetName(scopeKey),
-    fieldKey,
-  )
-  saveSettings(settings)
-  refreshCapabilities(getCapabilityModelKey(), getCapabilityProvider())
+  return true
 }
 
-/** Ask which scope an override applies to. Returns "" on cancel. */
-def pickOverrideScope(): string {
-  let scopeItems: ChoiceItem[] = []
-  scopeItems.push({
-    key: "model",
-    label: "this model (${getCapabilityModelKey()})"
-  })
-  scopeItems.push({
-    key: "provider",
-    label: "this provider (${getCapabilityProvider()})"
-  })
-  scopeItems.push({
-    key: "global",
-    label: "all models"
-  })
-  const scopeKey = chooseOption("Scope", "Where should this apply?", scopeItems, allowCancel: true)
-  if (scopeKey == null) {
-    return ""
+def modelsSlashCommand(trimmed: string): boolean {
+  const filters = parseModelsFilters(trimmed)
+  const models = filterHostedModels(listHostedModels(), filters)
+  if (models.length == 0) {
+    pushMessage("No models match.")
+    return true
   }
-  return scopeKey
-}
-
-/** Re-apply the resolved cap as the branch default. After a reset the
-  resolved value falls back to a built-in layer, which is always numeric
-  for known providers, so live-apply covers removal too. */
-def applyLiveMaxTokens() {
-  const capValue = getCapabilities().maxTokens
-  if (capValue != null) {
-    setLlmOptions({ maxTokens: capValue })
+  for (model in models) {
+    pushMessage(
+      "  ${model.name}  (${model.provider}, $${model.inputCost}/1M in, ${model.contextWindow} ctx)",
+    )
   }
+  return true
 }
 
-/** Positive-integer parse. parseInt and isNaN appear nowhere in the
-  repo's .agency code, so this uses a digits check instead. Returns -1
-  for anything that is not all digits. */
-def parsePositiveInt(text: string): number {
-  // Bound to a const because the parser rejects method calls on string
-  // LITERALS ("0123456789".includes(...) does not parse; a variable does).
-  const digits = "0123456789"
-  const trimmed = text.trim()
-  if (trimmed == "") {
-    return -1
-  }
-  for (ch in trimmed.split("")) {
-    if (!digits.includes(ch)) {
-      return -1
-    }
+def localSlashCommand(): boolean {
+  if (!localModelsSupported()) {
+    pushMessage(
+      color.yellow(
+      "Local models need smoltalk-llama-cpp. Install:  ! npm i -g smoltalk-llama-cpp",
+    ),
+    )
+    return true
   }
-  return Number(trimmed)
-}
-
-/** Interactive edit: field → value → scope → save → live-apply. */
-def editCapabilities() {
-  let fieldItems: ChoiceItem[] = []
-  for (field in CAPABILITY_FIELDS) {
-    fieldItems.push({
-      key: field.key,
-      label: "${field.label} — ${field.description}"
+  let items: ChoiceItem[] = []
+  for (modelName in listModelNames()) {
+    items.push({
+      key: modelName.name,
+      label: modelName.name
     })
   }
-  const fieldKey = chooseOption(
-    "Settings",
-    "Pick a setting to change (empty to exit).",
-    fieldItems,
+  const choice = chooseOption(
+    "Local model",
+    "Pick a local model, or type an hf: URI / .gguf path (downloads on first use):",
+    items,
+    allowFreeText: true,
     allowCancel: true,
   )
-  if (fieldKey == "" || fieldKey == null) {
-    return
-  }
-
-  let patch: CapabilityPatch = {}
-  if (fieldKey == "prompt") {
-    let promptItems: ChoiceItem[] = []
-    promptItems.push({
-      key: "large",
-      label: "large — full coordinator prompt"
-    })
-    promptItems.push({
-      key: "small",
-      label: "small — compact prompt for small-context models"
-    })
-    const picked = chooseOption("prompt", "System prompt size.", promptItems, allowCancel: true)
-    if (picked == "" || picked == null) {
-      return
-    }
-    patch = {
-      prompt: picked
-    }
-  }
-  if (fieldKey == "summarize" || fieldKey == "memory") {
-    let onOffItems: ChoiceItem[] = []
-    onOffItems.push({
-      key: "on",
-      label: "on"
-    })
-    onOffItems.push({
-      key: "off",
-      label: "off"
-    })
-    const picked = chooseOption(fieldKey, "Enable ${fieldKey}?", onOffItems, allowCancel: true)
-    if (picked == "" || picked == null) {
-      return
-    }
-    if (fieldKey == "summarize") {
-      patch = {
-        summarize: picked == "on"
-      }
-    } else {
-      patch = {
-        memory: picked == "on"
-      }
-      if (picked == "on") {
-        const status = embeddingKeyStatus(getResolvedSlots())
-        if (status.state == "key-missing") {
-          pushMessage(
-            color.red(
-            "Cannot enable memory: the embedding slot needs ${status.varName}, which is not set. Export it, or point the embedding slot elsewhere via /model.",
-          ),
-          )
-          return
-        }
-        if (status.state == "no-override" && providerLacksEmbeddings(getCapabilityProvider())) {
-          pushMessage(
-            color.dim(
-            "Note: ${getCapabilityProvider()} has no embeddings endpoint, so Tier-2 semantic recall stays off. Point the embedding slot at a provider that has one, e.g. /model embedding=openai/text-embedding-3-small.",
-          ),
-          )
-        }
-      }
-    }
-  }
-  if (fieldKey == "maxTokens") {
-    let capItems: ChoiceItem[] = []
-    capItems.push({
-      key: "reset",
-      label: "reset — remove my override, use the default"
-    })
-    const picked = chooseOption(
-      "maxTokens",
-      "Default output-token cap. Type a number, or pick reset.",
-      capItems,
-      allowFreeText: true,
-      allowCancel: true,
-    )
-    if (picked == "" || picked == null) {
-      return
-    }
-    if (picked == "reset") {
-      const scopeKey = pickOverrideScope()
-      if (scopeKey == "") {
-        return
-      }
-      removeCapabilityOverride(scopeKey, "maxTokens")
-      applyLiveMaxTokens()
-      pushMessage("Override removed.")
-      showCapabilities()
-      return
-    }
-    const parsed = parsePositiveInt(picked)
-    if (parsed <= 0) {
-      pushMessage(color.red("Not a positive number: ${picked}"))
-      return
-    }
-    patch = {
-      maxTokens: parsed
-    }
-  }
-
-  const scopeKey = pickOverrideScope()
-  if (scopeKey == "") {
-    return
-  }
-  saveCapabilityOverride(scopeKey, patch)
-
-  // Live-apply what can apply now; explain what can't.
-  if (fieldKey == "memory") {
-    if (getCapabilities().memory) {
-      // The ON direction cannot live-apply. enableAgentMemory's
-      // `with approve` cannot override the outer policy handler that
-      // startInteractive installed, so the memory-dir fs interrupts
-      // would surface as policy prompts mid-flow, or get denied and
-      // half-apply the toggle. The OFF direction stays live below:
-      // disableMemory raises no fs interrupts and already runs in-REPL
-      // from reactToSlotChange.
-      pushMessage(color.dim("Memory turns on at next agent start (enabling mid-session would raise policy prompts)."))
-    } else {
-      disableMemory() with approve
-    }
-  }
-  if (fieldKey == "maxTokens") {
-    applyLiveMaxTokens()
+  if (choice == "" || choice == null) {
+    return true
   }
-  if (fieldKey == "prompt") {
-    pushMessage(color.dim("Prompt change applies on next agent start (this session's system message is already sent)."))
+  const before = getResolvedSlots()
+  configureLocalModel(choice)
+  configureSearch(true)
+  for (change in diffResolved(before, getResolvedSlots())) {
+    reactToSlotChange(change)
   }
-  pushMessage("Saved.")
-  showCapabilities()
+  pushMessage("Switched to local model: ${choice}")
+  return true
 }
 
 // Slash-command + user-message dispatcher invoked by `repl()` for
@@ -842,618 +441,121 @@ def _runTurn(msg: string): boolean {
   // raw `msg` so the LLM sees the exact text the user typed when
   // nothing matches.
   const trimmed = msg.trim()
-  if (trimmed == "") {
-    return true
-  }
-  if (trimmed == "/exit" || trimmed == "/quit") {
-    return false
-  }
-  if (trimmed == "/clear") {
-    clearMessages()
-    return true
-  }
-  if (trimmed == "/clear-history") {
-    clearHistory()
-    pushMessage("Input history cleared.")
-    return true
-  }
-  if (trimmed == "/help") {
-    pushMessage(
-      "Commands: /exit, /clear, /clear-history, /cost, /model, /models, /local, /search, /settings, /mcp, /paste, /help",
-    )
-    return true
-  }
-  if (trimmed == "/settings") {
-    showCapabilities()
-    editCapabilities()
-    return true
-  }
-  if (trimmed == "/mcp") {
-    if (!isMcpAvailable()) {
-      pushMessage(color.yellow("MCP is not installed. Run: npm install @agency-lang/mcp"))
-      return true
-    }
-    const merged = mergeMcpServers(getMcpServers(loadSettings()), readProjectMcpConfig(cwd()))
-    if (keys(merged).length == 0) {
-      pushMessage(color.dim("No MCP servers configured. Add an mcpServers block to agency.json or settings.json."))
+  return match(trimmed) {
+    "" => true
+    "/exit" => false
+    "/quit" => false
+    "/clear" => {
+      clearMessages()
       return true
     }
-    pushMessage(color.bold("MCP servers:"))
-    for (name in keys(merged)) {
-      // mcpServerStatus is populated at session start. A server present in the
-      // config but absent from the status map was never loaded (e.g. /mcp run
-      // before startup finished) — show it as unknown rather than connected.
-      let status = mcpServerStatus[name]
-      if (status == null) {
-        status = "not loaded"
-      }
-      pushMessage("  ${name} — ${status}")
-    }
-    pushMessage(color.dim("Loaded ${mcpTools.length} MCP tool(s) this session."))
-    return true
-  }
-  if (trimmed == "/search") {
-    const opts = availableBackendItems()
-    const choice = chooseOption(
-      "Web search backend",
-      "Pick how this agent searches the web. Current: ${getSearchBackend()}",
-      opts,
-      false,
-      true,
-    )
-    if (choice != "" && choice != null && choice != undefined) {
-      setSearchBackend(choice)
-      pushMessage("Web search backend set to: ${choice}")
-    }
-    return true
-  }
-  if (trimmed == "/cost") {
-    // Derive BOTH the header total and the per-model breakdown from the
-    // same process-wide accumulator (getModelCosts), so the `Cost:` /
-    // `Tokens:` lines and the rows below them can never visibly disagree.
-    // (getCost()/getTokens() read the per-branch accumulator, a different
-    // scope — adjacent in the output, they could in principle diverge.)
-    // Rows are sorted by cost descending by getModelCosts(); a subagent
-    // on a pricier model (e.g. the oracle on opus-4.8) shows up here.
-    const byModel = getModelCosts()
-    let totalCost = 0.0
-    let totalTokens = 0
-    for (m in byModel) {
-      totalCost = totalCost + m.cost
-      totalTokens = totalTokens + m.inputTokens + m.outputTokens
-    }
-    pushMessage("Cost:   $${totalCost.toFixed(4)}")
-    pushMessage("Tokens: ${totalTokens}")
-    if (byModel.length > 0) {
-      pushMessage("")
-      pushMessage("By model:")
-      for (m in byModel) {
-        pushMessage(
-          "  ${m.model}  ↑${m.inputTokens} ↓${m.outputTokens}  $${m.cost.toFixed(4)}",
-        )
-      }
-    }
-    return true
-  }
-  if (trimmed == "/model" || trimmed.startsWith("/model ")) {
-    let spec = ""
-    if (trimmed != "/model") {
-      spec = trimmed.substring(7).trim()
-    }
-    if (spec == "") {
-      pushMessage("Current models:")
-      const current = getResolvedSlots()
-      for (slot in Object.keys(current)) {
-        const resolved = current[slot]
-        if (resolved != null) {
-          pushMessage("  ${slot}: ${resolved.model} (${resolved.via})")
-        }
-      }
-      const items = modelChoiceItems({})
-      const choice = chooseOption(
-        "Model",
-        "Pick a model, or type one (or slot=model, e.g. reasoning=claude-opus-4-8). Empty to cancel.",
-        items,
-        allowFreeText: true,
-        allowCancel: true,
-      )
-      if (choice == "" || choice == null) {
-        return true
-      }
-      spec = choice
-    }
-    const ctx: Ctx = {
-      provider: currentProvider(),
-      price: "standard"
-    }
-    const out = switchModel(_session, spec, ctx, getResolvedSlots())
-    _session = out.session
-    for (change in out.changes) {
-      reactToSlotChange(change)
-    }
-    pushMessage("Model set:")
-    for (slot in Object.keys(out.resolved)) {
-      const resolved = out.resolved[slot]
-      if (resolved != null) {
-        pushMessage(color.dim("  ${slot}: ${resolved.model} (${resolved.via})"))
-      }
-    }
-    return true
-  }
-  if (trimmed == "/models" || trimmed.startsWith("/models ")) {
-    const filters = parseModelsFilters(trimmed)
-    const models = filterHostedModels(listHostedModels(), filters)
-    if (models.length == 0) {
-      pushMessage("No models match.")
+    "/clear-history" => {
+      clearHistory()
+      pushMessage("Input history cleared.")
       return true
     }
-    for (model in models) {
+    "/help" => {
       pushMessage(
-        "  ${model.name}  (${model.provider}, $${model.inputCost}/1M in, ${model.contextWindow} ctx)",
-      )
-    }
-    return true
-  }
-  if (trimmed == "/local") {
-    if (!localModelsSupported()) {
-      pushMessage(
-        color.yellow(
-        "Local models need smoltalk-llama-cpp. Install:  ! npm i -g smoltalk-llama-cpp",
-      ),
+        "Commands: /exit, /clear, /clear-history, /cost, /model, /models, /local, /search, /settings, /mcp, /paste, /help",
       )
       return true
     }
-    let items: ChoiceItem[] = []
-    for (modelName in listModelNames()) {
-      items.push({
-        key: modelName.name,
-        label: modelName.name
-      })
-    }
-    const choice = chooseOption(
-      "Local model",
-      "Pick a local model, or type an hf: URI / .gguf path (downloads on first use):",
-      items,
-      allowFreeText: true,
-      allowCancel: true,
-    )
-    if (choice == "" || choice == null) {
+    "/settings" => {
+      showCapabilities()
+      editCapabilities()
       return true
     }
-    const before = getResolvedSlots()
-    configureLocalModel(choice)
-    configureSearch(true)
-    for (change in diffResolved(before, getResolvedSlots())) {
-      reactToSlotChange(change)
-    }
-    pushMessage("Switched to local model: ${choice}")
-    return true
-  }
-
-  // Hand the message to the agent. `agentReply` does the slash-command
-  // expansion and the actual agent work; the REPL just renders the reply.
-  // Wrap in `try` so a terminal LLM failure (e.g. the connection dropped and
-  // retries were exhausted) renders a friendly heads-up instead of a raw
-  // Failure object. Aborts/interrupts are NOT caught here — `try` re-throws
-  // them so an Esc-cancel still reaches the policy handler.
-  const result = try agentReply(msg)
-  if (result is success(reply)) {
-    if (reply != "" && reply != null && reply != undefined) {
-      pushMessage(highlight("${reply}\n", language: "markdown"))
-    } else {
-      pushMessage(color.red("No reply generated."))
+    "/mcp" => mcpSlashCommand()
+    "/search" => searchSlashCommand()
+    "/cost" => costSlashCommand()
+    "/model" => modelSlashCommand()
+    "/models" => modelsSlashCommand(trimmed)
+    "/local" => localSlashCommand()
+    _ => {
+      if (trimmed.startsWith("/model ")) {
+        return modelSlashCommand()
+      }
+      if (trimmed.startsWith("/models ")) {
+        return modelsSlashCommand(trimmed)
+      }
+      return renderUserTurn(trimmed, msg)
     }
-  } else if (result is failure(f)) {
-    pushMessage(color.red(formatTurnFailure("${f.error}")))
   }
-  return true
 }
 
 let first = true
 
-// Valid `--agent` targets. Empty / "main" routes through the coordinator;
-// the rest route the starting prompt's first turn directly to that
-// subagent. Used to validate the flag and to dispatch in `agentReplyVia`.
+// Valid `--agent` targets. Empty / "main" routes through the coordinator.
 static const START_AGENTS = ["main", "code", "research", "oracle", "explorer", "review"]
-
-static const MAIN_PROMPT_LARGE = """
-You are the top-level coordinator of an Agency-language assistant. You
-receive every user message and decide how to respond.
-
-You have five subagent tools (each running in its own isolated
-context) and one direct tool:
-
-- `codeAgent(userMsg)` — anything that touches code or the filesystem:
-  reading, writing, editing, typechecking, running shell commands,
-  and answering Agency syntax / CLI questions. Use this for any task
-  that involves inspecting or modifying source code.
-- `researchAgent(userMsg)` — web search, URL fetches, Wikipedia,
-  external API lookups, summarizing external content.
-- `reviewAgent(userMsg)` — reviews Agency code for syntax and type
-  errors. Call this after `codeAgent` produces non-trivial new or
-  modified Agency code, passing the code to be reviewed.
-- `oracleAgent(userMsg)` — a read-only senior reviewer on a stronger
-  reasoning model. Read the **Oracle** section below — you are
-  expected to use this tool **frequently**.
-- `explorerAgent(userMsg)` — a read-only researcher that produces
-  broad, synthesizing answers about the codebase or bundled docs.
-  Read the **Explorer** section below.
-- `generateImageFile(prompt, path, size, images)` — generate an image
-  from a text prompt (or modify existing images by passing their paths
-  in `images`) and save it to `path`. Call it directly whenever the
-  user asks you to create, draw, edit, or restyle an image — do NOT
-  route image generation to `codeAgent`.
-
-**Answer directly (no tool call) when** the message is conversational,
-a clarifying question, or something you can answer from context alone.
-
-**Delegate when** the message clearly needs one of the subagents'
-capabilities. Pick one based on what the message actually needs —
-don't pre-emptively call multiple subagents.
-
-## Picking between oracle, explorer, and code agent
-
-These three overlap on "reads the codebase," but they're for
-different jobs. Pick by **the shape of the answer the user wants**:
-
-- **oracle** → sharp verdict on a specific plan, diff, or bug.
-  Output: short, decisive ("this plan won't work because X").
-- **explorer** → broad synthesis from reading many files.
-  Output: structured overview ("Agency's five main features
-  are..."). Use for "summarize", "tour", "what are the main",
-  "how does X work across...".
-- **codeAgent** → targeted action: edit, run, typecheck, or
-  answer a focused Agency-syntax question. Output: the edit
-  itself, or a concise factual reply.
-
-Default: if the user asks a broad/synthesizing question,
-`explorerAgent` beats `codeAgent` every time. The code agent is
-optimized for terse action and will under-read on broad asks.
-
-Subagents return summary text. Surface that result to the user (in
-your own words if you're combining multiple results), formatted as
-Markdown.
-
-## Oracle
-
-The oracle is the most powerful tool you have. Use it **FREQUENTLY**.
-It is a read-only senior reviewer running on a stronger reasoning
-model than you. It can read the codebase and the Agency docs but
-cannot write, edit, or run anything. Its job is to **think hard so
-you don't have to guess**.
-
-Call the oracle:
-
-- **Before** dispatching `codeAgent` for any non-trivial task — ask
-  the oracle to sanity-check the plan, find existing code that
-  already solves the problem, or suggest a simpler approach.
-- **After** `codeAgent` produces a non-trivial diff — ask the oracle
-  to review the work for correctness, missed edge cases, and
-  better alternatives.
-- When `codeAgent` reports it's stuck on a bug after one or two
-  attempts — ask the oracle what's actually going on.
-- When the user proposes a plan or approach — ask the oracle
-  whether the plan is sound, **before** you act on it. If the
-  oracle finds a flaw, surface that to the user *before* taking
-  any action.
-- Whenever you're tempted to guess about the codebase ("I think
-  there's probably already a helper for X") — ask the oracle to
-  look.
-
-**Tell the user when you're consulting the oracle.** Say something
-like "Let me ask the oracle to review this plan before we start"
-or "I'll have the oracle look for an existing implementation." The
-visibility is half the value — the user benefits from knowing a
-second opinion is being sought.
-
-Pass the oracle a self-contained question with full context. It
-does not see your conversation. Include the user's request, the
-plan or diff under review, relevant file paths, and the specific
-question you want answered.
-
-Default bias: when in doubt, **consult the oracle**. The cost of
-asking is small; the cost of executing a flawed plan is large.
-
-## Explorer
-
-The explorer is your go-to for **broad, synthesizing questions**
-about the codebase or the bundled Agency docs. It is read-only and
-runs on a stronger reasoning model with extended thinking. Its job
-is **coverage** — it reads widely and returns a structured synthesis.
-
-Call the explorer when the user asks:
-
-- "Summarize the Agency docs" / "What are the main features?"
-- "Give me a tour of `lib/X/`" / "What's in this module?"
-- "How does X work across the codebase?"
-- "Walk me through the compilation pipeline"
-- Anything where a good answer requires reading 5+ files and
-  organizing the findings by theme.
-
-Do NOT use the explorer for:
-- Specific factual lookups ("what does function X return?") — use
-  `codeAgent`.
-- Plan critique or bug diagnosis — use `oracleAgent`.
-- External / web research — use `researchAgent`.
-
-**Tell the user when you're consulting the explorer.** "Let me have
-the explorer go through the docs and put together an overview." Like
-with the oracle, the visibility is part of the value — the user
-benefits from knowing breadth is being applied.
-
-Pass the explorer a self-contained question with explicit scope
-("all of `docs/site/guide/`", "the `lib/parsers/` module"). It does
-not see your conversation. Be clear about the level of detail
-expected.
-
-## Style
-
-Never start a response by calling the user's question or idea good,
-great, fascinating, profound, excellent, or perfect. Skip flattery
-and respond directly. Don't pad replies with "happy to help",
-"certainly", or trailing summaries the user can read in the diff.
-
-**Use ASCII diagrams when they clarify.** For control flow, state
-machines, pipelines, module relationships, or any "how do the parts
-fit together" answer, draw a small ASCII diagram in a fenced
-```text block. Boxes, arrows, and trees beat paragraphs for
-structural explanations:
-
-```text
-parse → SymbolTable.build → preprocess → TypeScriptBuilder → printTs
-```
-
-Keep diagrams small. Skip them where prose or code is clearer —
-diagrams earn their space by showing **relationships** or **flow**.
-
-## Be proactive
-
-When the user asks you to look at, debug, or change a file or some code,
-**delegate to `codeAgent` to do it** — don't ask the user to paste a file
-or describe code a subagent could read. The code agent has `read`, `glob`,
-and `ls` and resolves relative paths against the user's working directory
-automatically, so a bare filename like `foo.agency` is enough. Only ask
-the user for information you genuinely cannot obtain through a subagent.
-
-## Answer before action
-
-When the user asks a question, asks for an opinion, or asks how to
-plan or approach something, **answer the question first**. Don't
-jump straight into delegating to a subagent or making tool calls
-unless the user has clearly asked for an action ("do X", "fix Y",
-"build Z"). If the user is exploring or thinking out loud, think
-with them — don't sprint to implementation.
-"""
-
-// Compact coordinator prompt for small-context models, ~350 tokens
-// instead of ~3,400. Selected when the capability profile says
-// prompt: "small". An 8K-context model loses 40% of its window to the
-// large prompt before the user types anything. The phrase "compact
-// coordinator" is a deliberate marker that verification greps for in
-// statelogs.
-static const MAIN_PROMPT_SMALL = """
-You are the compact coordinator of an Agency-language assistant. Decide
-how to answer each user message.
-
-Tools (each runs in its own context; pass a self-contained message):
-- `codeAgent(userMsg)` — anything touching code or files: read, write,
-  edit, run, typecheck. Also Agency syntax and CLI questions.
-- `researchAgent(userMsg)` — web search, URL fetches, external facts.
-- `reviewAgent(userMsg)` — check non-trivial new Agency code for
-  syntax and type errors; pass the code to review.
-- `oracleAgent(userMsg)` — deep reasoning on a hard question; include
-  all needed context in the message.
-- `explorerAgent(userMsg)` — broad read-only codebase/docs questions.
-- `generateImageFile(prompt, path, size, images)` — create or edit an
-  image; do not route image work to codeAgent.
-
-Routing rules:
-- Simple chat, greetings, quick factual answers: reply directly, no
-  tools.
-- Anything code- or file-related: codeAgent. Current/external info:
-  researchAgent. Broad "summarize/tour/how does X work" questions:
-  explorerAgent.
-- Surface tool results to the user concisely; do not re-run a tool the
-  user did not ask to re-run.
-
-Style: plain, direct answers in Markdown. No preamble. Keep replies
-short unless the task demands detail.
-"""
-
-// Exported for tests: agent-cwd resolution of edit inputs is a spec
-// invariant with no other observable (the deterministic image client
-// ignores its images argument). generateImage accepts path / URL /
-// data-URI strings, so only local paths get agent-cwd resolution —
-// running a URL through applyAgentCwd would mangle it into
-// "<agentCwd>/https:/…".
-export def resolveEditInputs(images: string[]): string[] {
-  return map(images) as inputPath {
-    if (inputPath.startsWith("http://") || inputPath.startsWith("https://") || inputPath.startsWith("data:")) {
-      return inputPath
-    }
-    return applyAgentCwd(inputPath)
-  }
-}
-
-// Direct image generation for the coordinator. Saves to disk and
-// returns the path — never base64, which would flood the LLM context.
-// The write rides the std::writeBinary interrupt gate (writes are not
-// auto-approved by policy) and generation cost accrues to the agent's
-// cost tracking like any llm() call.
-export def generateImageFile(
-  prompt: string,
-  path: string,
-  size: string = "",
-  images: string[] = [],
-): string {
-  """
-  Generate an image from a text prompt and save it to `path`. To MODIFY
-  existing images (edit / variation), pass their paths in `images`.
-  Returns the saved path on success. Use this when the user asks to
-  create, draw, edit, or restyle an image.
-
-  @param prompt - What to generate, or how to modify the input images.
-  @param path - Where to save the resulting image (e.g. "diagram.png").
-  @param size - Optional size like "1024x1024".
-  @param images - Optional input image paths to edit / vary.
-  """
-  // LLM-supplied paths resolve against the agent cwd, like every other
-  // agent file tool.
-  const inputs = resolveEditInputs(images)
-  const generated = generateImage(prompt, size: size, images: inputs)
-  if (isFailure(generated)) {
-    return "Image generation failed: ${generated.error}"
-  }
-  // writeBinary rejects an absolute filename when dir is set, so split
-  // path into (dir, name); useAgentCwd resolves a relative dir against
-  // the agent cwd (absolute dirs pass through untouched).
-  const written = writeBinary(
-    basename(path),
-    generated.value.base64,
-    dirname(path),
-    useAgentCwd: true,
-  )
-  if (isFailure(written)) {
-    return "Generated the image, but saving to ${path} failed: ${written.error}"
-  }
-  // Show the model what it made (generate -> view -> refine). The loop
-  // inlines the bytes when it builds the injected user message; the
-  // path resolves the same way the write did.
-  attachToReply(image(applyAgentCwd(path)))
-  return "Saved image to ${path}"
-}
+static const MAIN_PROMPT_LARGE = read("prompts/main-large.md") with approve
+static const MAIN_PROMPT_SMALL = read("prompts/main-small.md") with approve
 
 static const mainAgentTools = [
-  researchAgent.partial(allowHandoff: false),
-  codeAgent.partial(allowHandoff: false),
-  reviewAgent.partial(allowHandoff: false),
-  oracleAgent.partial(allowHandoff: false),
-  explorerAgent.partial(allowHandoff: false),
+  researchAgent,
+  codeAgent,
+  reviewAgent,
+  oracleAgent,
+  explorerAgent,
   generateImageFile,
 ]
 
-// MCP tools are appended to the coordinator's tools. ORDERING CONTRACT:
-// maybeLoadMcp (session start, in main()) must run before mainAgent's first
-// turn, or MCP tools silently vanish.
-let mcpTools: any[] = []
-// Per-server load outcome ("connected" / "unavailable"), for /mcp.
-let mcpServerStatus: Record<string, string> = {}
-
-export def setMcpTools(tools: any[]) {
-  mcpTools = tools
-}
-
-def setMcpServerStatus(status: Record<string, string>) {
-  mcpServerStatus = status
-}
-
-// MCP OAuth notification. The @agency-lang/mcp package opens the browser itself
-// (macOS-only today); we only print the URL so the user can complete auth.
-def onMcpOAuth(data: any) {
-  print(color.yellow("MCP authorization needed — opening browser. If it does not open, visit:\n${data.authUrl}"))
-}
-
-/** Load MCP tools from the project agency.json merged with the global settings
-  and hand them to the coordinator. No-op when @agency-lang/mcp is not installed
-  or no servers are configured. loadMcpTools warns-and-skips internally on any
-  per-server failure, so it always returns an array. */
-def maybeLoadMcp(settings: Settings) {
-  if (!isMcpAvailable()) {
-    return
-  }
-  const merged = mergeMcpServers(getMcpServers(settings), readProjectMcpConfig(cwd()))
-  if (keys(merged).length == 0) {
-    return
-  }
-  // Always returns a result (per-server failures warn-and-skip internally), so
-  // there is no Failure branch. The status map drives /mcp.
-  const loaded = loadMcpToolsWithStatus(merged, onMcpOAuth)
-  setMcpTools(loaded.tools)
-  setMcpServerStatus(loaded.status)
-}
-
 /** Enable memory when the capability profile allows it. When the user
   pointed the embedding slot at a provider, embeddings run there. A
   missing API key degrades to the default embedding behavior with one
-  notice. It never blocks startup. */
-// Whether startup actually enabled memory WITH the embedding override.
-// The pause guard in reactToSlotChange consults this instead of
-// re-deriving from the slots: a keyless override took the fallback path,
-// so memory runs on DERIVED embeddings and a main-provider change still
-// shifts the embedding space. Exported mutator so tests can drive the
-// guard directly.
-let _memoryEmbeddingsPinned = false
-
-export def markMemoryEmbeddingsPinned(pinned: boolean) {
-  _memoryEmbeddingsPinned = pinned
-}
-
+  notice. It never blocks startup. The `_memoryEmbeddingsPinned` guard that
+  `reactToSlotChange` consults lives in `./lib/session.agency`; we set it
+  here via `markMemoryEmbeddingsPinned`. */
 def maybeEnableMemory() {
   const status = embeddingKeyStatus(getResolvedSlots())
   const plan = memoryEnablePlan(getCapabilities().memory, status)
   markMemoryEmbeddingsPinned(plan == "enable-override")
-  if (plan == "skip") {
-    return
-  }
-  if (plan == "enable-override") {
-    enableAgentMemory(status.override)
-    return
-  }
-  if (plan == "enable-fallback") {
-    print(
-      color.dim(
-      "Memory: the embedding slot needs ${status.varName}, which is not set. Falling back to the default embedding behavior.",
-    ),
-    )
+  return match(plan) {
+    "skip" => null
+    "enable-override" => {
+      enableAgentMemory(status.override)
+      return null
+    }
+    "enable-fallback" => {
+      print(
+        color.dim(
+        "Memory: the embedding slot needs ${status.varName}, which is not set. Falling back to the default embedding behavior.",
+      ),
+      )
+      enableAgentMemory()
+      return null
+    }
+    _ => {
+      enableAgentMemory()
+      return null
+    }
   }
-  enableAgentMemory()
 }
 
 def mainAgent(prompt: string | (string | Attachment)[]): string {
-  const doSummarize = getCapabilities().summarize
-  thread(label: "main", summarize: doSummarize, session: "main") {
+  // const doSummarize = getCapabilities().summarize
+  thread(label: "main", session: "main") {
     setMemoryId("main")
     if (first) {
-      // `_context` carries the per-run grounding (date, cwd, AGENTS.md),
-      // set by `setupSession`. Appending it to the system prompt is what
-      // actually gets that context to the LLM.
-      let sysPrompt = MAIN_PROMPT_LARGE
-      if (getCapabilities().prompt == "small") {
-        sysPrompt = MAIN_PROMPT_SMALL
+      const promptSize = getCapabilities().prompt
+      const sysPrompt = match(promptSize) {
+        "small" => MAIN_PROMPT_SMALL catch ""
+        _ => MAIN_PROMPT_LARGE catch ""
       }
       systemMessage("${sysPrompt}${_context}")
       first = false
     }
-    const result = llm(prompt, {
+    const result = llm(
+      prompt,
+      {
       memory: true,
-      tools: [...mainAgentTools, ...mcpTools]
-    })
+      tools: [...mainAgentTools, ...getMcpTools()]
+    },
+    )
   }
   return result
 }
 
-// Dispatch one turn. `target` empty (or "main") runs the coordinator
-// `mainAgent`, which routes as usual; any subagent name routes the turn
-// directly to that subagent. All subagents share `(userMsg, allowHandoff)`
-// and the seed turn never hands off (allowHandoff: false). Used by both
-// the one-shot path and the interactive seed turn.
-export def agentReplyVia(target: string, userMsg: string): string {
-  const expanded = expandSlash(userMsg, projectCommands)
-  if (target == "code") {
-    return codeAgent(expanded, false)
-  }
-  if (target == "research") {
-    return researchAgent(expanded, false)
-  }
-  if (target == "oracle") {
-    return oracleAgent(expanded, false)
-  }
-  if (target == "explorer") {
-    return explorerAgent(expanded, false)
-  }
-  if (target == "review") {
-    return reviewAgent(expanded, false)
-  }
+def checkForAttachments(expanded: string): Attachment[] {
   // Auto-attach image/PDF files the user referenced (drag-drop or typed
   // path), filtered to what the resolved model accepts. Never silent:
   // every attach and every skip prints a visible line.
@@ -1464,11 +566,7 @@ export def agentReplyVia(target: string, userMsg: string): string {
     )
   }
   if (detected.attached.length == 0) {
-    // Deliberate special case: a text-only turn stays a bare string. A
-    // one-element array is API-equivalent, but the stored thread message
-    // shape (string vs parts array) — and with it every serialized
-    // session and message fixture — would change for EVERY turn.
-    return mainAgent(expanded)
+    return []
   }
   for (item in detected.attached) {
     pushMessage(color.dim("📎 attached ${item.label}"))
@@ -1476,174 +574,66 @@ export def agentReplyVia(target: string, userMsg: string): string {
   const attachments = map(detected.attached) as item {
     return item.attachment
   }
-  const parts: (string | Attachment)[] = [expanded, ...attachments]
-  return mainAgent(parts)
+  return attachments
 }
 
-// The agent's core turn, decoupled from the terminal: expand any project
-// slash command, then run the prompt through `mainAgent` and return the
-// reply. The REPL (`main` / `_runTurn`) owns input, output, and built-in
-// commands; everything the *agent* does for a user message lives here, so
-// it can be driven and tested without a terminal or user input. See
-// `tests/agentTurn.agency`.
-export def agentReply(userMsg: string): string {
-  return agentReplyVia("", userMsg)
+type AgentTarget =
+  | "code"
+  | "explorer"
+  | "main"
+  | "oracle"
+  | "research"
+  | "review"
+  | "coordinator"
+
+export def dispatchAgent(agentName: AgentTarget, userMsg: string): string {
+  const expanded = expandSlash(userMsg, projectCommands)
+  return match(agentName) {
+    "code" => codeAgent(expanded)
+    "research" => researchAgent(expanded)
+    "oracle" => oracleAgent(expanded)
+    "explorer" => explorerAgent(expanded)
+    "review" => reviewAgent(expanded)
+    _ => {
+      const attachments = checkForAttachments(expanded)
+      return mainAgent([expanded, ...attachments])
+    }
+  }
 }
 
-def roundedCost(): string {
-  return "$${getCost().toFixed(4)}"
+def renderUserTurn(trimmed: string, msg: string): boolean {
+  const result = try dispatchAgent("coordinator", msg)
+  renderAgentResponse(result)
+  return true
 }
 
 def _buildStatus(): { left: string; right: string; context: string } {
+  const roundedCost = "$${getCost().toFixed(4)}"
   return {
     left: "",
-    right: roundedCost(),
+    right: roundedCost,
     context: ""
   }
 }
 
-def sample(arr: any[]): any {
-  return arr[Math.floor(Math.random() * arr.length)]
-}
-
-def printHeader() {
-  const fig = sample(figs)
-  const data = box(
-    title: "Agency",
-    padding: 1,
-    borderColor: "cyan",
-    titleColor: "cyan",
-    width: "full",
-  ) as b {
-    b.row(gap: 1) as r {
-      r.column(width: "66%") as left {
-        left.text("Welcome to the Agency Agent!", bold: true)
-        left.text("Ask me to write code, look up docs, or just chat.")
-        left.text("All costs are estimates. Actual costs may be higher.", dim: true)
-        left.hline()
-        left.text("Getting Started", bold: true, fgColor: "cyan")
-        left.text("/help for commands · /exit to quit", dim: true)
-      }
-      r.vline()
-      r.column(width: "30%", align: "center") as right {
-        right.raw(fig, align: "center")
-      }
-    }
-  }
-  print(render(data, color: true))
-}
-
-// Print `--policy` usage and list the built-in policies (name + one-line
-// description). Shown when `--policy` is passed with no value.
-def printPolicyHelp() {
-  print(color.bold("Usage: agency agent --policy <name | path>"))
-  print(
-    "Select the approval policy for this run: a built-in name below, or a path to a policy JSON file.",
-  )
-  print("")
-  print(color.bold("Built-in policies:"))
-  for (p in BUILTIN_POLICIES) {
-    print("  ${color.cyan(p.name)}")
-    print("      ${p.description}")
-  }
-}
-
-def givePolicyChoice() {
-  const title = "Welcome to the agency agent. Please pick a policy to start."
-  const body = "Don't worry, you can change this later. The policy just controls how the agent asks for your approval when it wants to do something. You can also create your own custom policy file at ${POLICY_PATH} and the agent will use it automatically."
-  let items: ChoiceItem[] = [
-    {
-    key: "minimal",
-    label: "minimal default policy, you do most approvals manually"
-  },
-    {
-    key: "recommended",
-    label: "recommended default policy, allow reading files and browsing the web, no writes"
-  },
-  ]
-
-  const answer = chooseOption(title, body, items, allowFreeText: true)
-  return match(answer) {
-    "minimal" => minimalAutoApprovePolicy
-    "recommended" => recommendedAutoApprovePolicy
-  }
-}
-
 // Shared session setup for both interactive and one-shot modes. Builds
-// the per-run grounding context, loads (or initializes) the policy, and
-// returns the installed CLI policy handler. `interactive` gates the
-// first-run policy-choice prompt: one-shot has no user to answer it, so
-// it falls back to the recommended default (reads/web auto-approved;
-// writes still require approval, which a non-interactive run can't
-// grant — those tasks block, which is the safe behavior).
+// the grounding context, loads (or initializes) the policy, and
+// returns the installed CLI policy handler.
 def setupSession(interactive: boolean): any {
-  // Point every path-taking tool at the user's working directory so the
-  // agent's relative file/shell commands resolve against where the user
-  // launched it. The user (via the agent) can change this later with
-  // setAgentCwd.
   setAgentCwd(cwd())
 
   // Grounding: the LLM shouldn't have to ask where it is or what day it
-  // is. Project context: inline an AGENTS.md from the workspace root if
-  // present so the LLM follows the project's conventions.
+  // is. Also load `AGENTS.md` if present.
   const projectContext = loadAgentsMd(cwd()) with approve
-  _context = "\n\nCurrent date: ${today()}\nCurrent working directory: ${cwd()}${projectContext}"
+  _context = """
 
-  // Which file the handler persists against, and an optional in-memory
-  // policy to start from. Normally the user's saved policy loaded from
-  // POLICY_PATH; a `--policy` override redirects this (see below) so the
-  // saved policy is never read or written.
-  let policyFile = POLICY_PATH
-  let sessionPolicy: any = null
+  Current date: ${today()}
+  Current working directory: ${cwd()}
+  ${projectContext}
+  """
+
+  const { policyFile, sessionPolicy } = getPolicyForAgent(_policyArg, interactive)
 
-  if (_policyArg != "") {
-    // `--policy` override: a built-in name or a path to a policy file.
-    // The cwd-scoped built-ins pin the launch directory, so we resolve
-    // them against `cwd()` (what `setAgentCwd` just stored, and what the
-    // write/git/bash interrupts resolve their default paths back to).
-    const builtin = builtinPolicy(_policyArg, cwd())
-    if (builtin != null) {
-      // Hand the policy to the handler in memory (no disk write): a
-      // one-off, cwd-scoped override must not clobber the saved policy
-      // or leak into a later run from a different directory. Any new
-      // interactive "always" decision persists to the session file.
-      policyFile = SESSION_POLICY_PATH
-      sessionPolicy = builtin
-    } else {
-      // Not a built-in name — treat it as a policy file path and use it
-      // directly (the handler loads/persists it). Validate up front so a
-      // typo fails fast instead of silently starting from empty.
-      const loaded = parsePolicyFile(_policyArg)
-      if (loaded is failure(f)) {
-        print(
-          color.red(
-          "--policy '${_policyArg}' is neither a built-in policy (${builtinPolicyNames().join(", ")}) nor a readable policy file (${f.status}).",
-        ),
-        )
-        process.exit(1)
-      }
-      policyFile = _policyArg
-    }
-  } else {
-    const policy = parsePolicyFile(POLICY_PATH)
-    if (policy is failure(f)) {
-      if (f.status == "doesnt-exist") {
-        if (interactive) {
-          print(color.yellow("No existing policy found at ${POLICY_PATH}."))
-          setPolicy(POLICY_PATH, givePolicyChoice())
-        } else {
-          setPolicy(POLICY_PATH, recommendedAutoApprovePolicy)
-        }
-      } else {
-        print(color.red("Failed to load policy: ${JSON.stringify(f.error)}"))
-        process.exit(1)
-      }
-    } else {
-      setPolicy(POLICY_PATH, policy.value)
-    }
-  }
-  // Bind the handler to a local var so `with handler` parses (the
-  // `with` clause only accepts an identifier, not a call expression).
   return cliPolicyHandler(
     file: policyFile,
     fields: ALWAYS_FIELDS,
@@ -1651,59 +641,45 @@ def setupSession(interactive: boolean): any {
   )
 }
 
-// One-shot entry: run a single turn through the same `mainAgent` the
-// REPL uses, with the same session setup and policy handler, and return
-// the reply. Used for `agency agent -p "..."`, a positional query, or
-// piped stdin. Slash commands are expanded so `-p /foo bar` works like
-// typing it in the REPL; the loop-only built-ins (`/exit` etc.) are
-// meaningless here and aren't checked.
 def oneShotAgent(target: string, prompt: string): string {
   _isInteractive = false
-  const handler = setupSession(false)
-  let reply: string = ""
+  const handler = setupSession(interactive: false)
   handle {
-    // `try` converts a terminal LLM failure (retries exhausted on a dropped
-    // connection / timeout) into a friendly message; aborts/interrupts still
-    // propagate to the handler below.
-    const result = try agentReplyVia(target, prompt)
-    if (result is success(r)) {
-      reply = r
-    } else if (result is failure(f)) {
-      reply = formatTurnFailure("${f.error}")
+    const result = try dispatchAgent(target, prompt)
+    return match(result) {
+      success(r) => r
+      failure(f) => formatTurnFailure("${f.error}")
     }
-  } with (data) {
-    return handler(data)
-  }
-  return reply
+  } with handler
 }
 
-// Render one seeded turn into the REPL scroll area: echo the auto-run
-// prompt so the user sees what was asked, then push the agent's reply.
-// Mirrors the reply-rendering half of `_runTurn`.
-def _runSeedTurn(target: string, msg: string) {
+/* A seeded turn is if the user invokes the Agency agent with
+an initial prompt – by using the agency doctor command, for example.
+It means that agent starts with an initial prompt already there to respond to. */
+def runSeedTurn(target: string, msg: string) {
   pushMessage(color.dim("> ${msg}"))
-  const result = try agentReplyVia(target, msg)
-  if (result is success(reply)) {
-    if (reply != "" && reply != null && reply != undefined) {
+  const response = try dispatchAgent(target, msg)
+  renderAgentResponse(response)
+}
+
+def renderAgentResponse(
+  response: Result<string | null, { error: string }>,
+): void {
+  if (response is success(reply)) {
+    if (reply != "" && reply != null) {
       pushMessage(highlight("${reply}\n", language: "markdown"))
     } else {
       pushMessage(color.red("No reply generated."))
     }
-  } else if (result is failure(f)) {
+  } else if (response is failure(f)) {
     pushMessage(color.red(formatTurnFailure("${f.error}")))
   }
 }
 
-// Start the interactive REPL. When `seedPrompt` is non-empty it is run as
-// the first turn (routed via `seedTarget`) *inside* the handle block so
-// its interrupts reach the policy `handler`; the user is then left at the
-// prompt. `seedPrompt == ""` is the plain REPL with no seed. Subsequent
-// turns always go through `_runTurn` (the coordinator) regardless of
-// `seedTarget` — the target only kicks off the first turn.
 def startInteractive(handler: any, seedTarget: string, seedPrompt: string) {
   handle {
     if (seedPrompt != "") {
-      _runSeedTurn(seedTarget, seedPrompt)
+      runSeedTurn(seedTarget, seedPrompt)
     }
     repl(
       status: _buildStatus,
@@ -1713,107 +689,20 @@ def startInteractive(handler: any, seedTarget: string, seedPrompt: string) {
       historyMax: 1000,
       paletteCommands: mergedPalette(),
     )
-  } with (data) {
-    return handler(data)
-  }
+  } with handler
   print(color.cyan("\nGoodbye!"))
 }
 
 node main() {
   // Parse CLI flags first — `parseArgs` exits on --help / --version /
   // usage errors, before any handlers or the TUI are installed.
-  const args = parseArgs(
-    {
-    programName: "agency agent",
-    description: "Agency language assistant — interactive REPL by default; one-shot when piped or passed a query / --print.",
-    version: getVersion(),
-    flags: {
-      print: {
-        type: "boolean",
-        short: "p",
-        description: "Run one-shot: print the reply to stdout and exit (no REPL)"
-      },
-      debug: {
-        type: "boolean",
-        description: "Log tool returns (toolName, result, timing). Same as AGENT_DEBUG=1"
-      },
-      verbose: {
-        type: "boolean",
-        description: "Echo tool-call starts to stdout in non-interactive mode"
-      },
-      model: {
-        type: "string",
-        description: "Model for all LLM calls (overrides provider auto-detection)"
-      },
-      fastmodel: {
-        type: "string",
-        description: "Model for ordinary work (default: per detected provider)"
-      },
-      slowmodel: {
-        type: "string",
-        description: "Model for deep reasoning, e.g. the oracle/explorer subagents"
-      },
-      provider: {
-        type: "string",
-        description: "Force the LLM provider. Given alone (openai/anthropic/google/openrouter) it selects that provider's default models and skips env auto-detection; pair it with --model for any other provider (e.g. litellm, openai-compat, or a custom/local model)"
-      },
-      interactive: {
-        type: "boolean",
-        short: "i",
-        description: "Run the given prompt as the first turn of an interactive session, then hand over the REPL (instead of one-shot)"
-      },
-      agent: {
-        type: "string",
-        description: "Route the starting prompt to a named subagent: code, research, oracle, explorer, review (default: coordinator)"
-      },
-      policy: {
-        type: "string",
-        optional: true,
-        description: "Approval policy for this run: a built-in name (minimal, recommended, with-writes, approve-all) or a path to a policy JSON file. with-writes auto-approves file writes and git changes scoped to the current directory and its children; approve-all approves EVERY interrupt with no scoping (sandbox use only). Overrides the saved policy without persisting it. Pass --policy with no value to list the built-in policies."
-      },
-      "agent-home": {
-        type: "string",
-        description: "Directory to use instead of ~/.agency-agent for settings, policy, and history (equivalent to the AGENCY_AGENT_HOME env var; the flag wins when both are set)"
-      },
-      local: {
-        type: "string",
-        optional: true,
-        description: "Run a local model (downloads if needed): a curated short name, an hf: URI, or a .gguf path. Run without a value for guided setup. Pins all slots to the local model; mutually exclusive with --model/--fastmodel/--slowmodel. Requires: npm i -g smoltalk-llama-cpp"
-      },
-      "local-model": {
-        type: "string",
-        optional: true,
-        description: "Deprecated alias for --local."
-      },
-      trace: {
-        type: "string",
-        optional: true,
-        description: "Write an execution trace to this file for debugging (bare --trace writes <runId>.agencytrace in the current directory)"
-      },
-      "log-file": {
-        type: "string",
-        description: "Append structured statelog events (one JSON object per line) to this file for debugging"
-      },
-      "max-tool-call-rounds": {
-        type: "number",
-        description: "Max LLM tool-call rounds before a tool loop halts (default 10 interactive, 50 in one-shot/-p mode)"
-      },
-      "max-tool-result-chars": {
-        type: "number",
-        description: "Max chars of a single tool result fed back to the model (0 disables; default 100000)"
-      }
-    }
-  },
-  )
+  const args = parseAgentArgs()
 
-  // NOTE: --trace / --log-file / --agent-home are declared here only for
+  // NOTE: --trace / --log / --agent-home are declared here only for
   // --help and so parseArgs accepts them. runBundledAgent extracts them from
   // the forwarded args and passes them to this process via env vars
   // (AGENCY_CONFIG_OVERRIDES for the first two, AGENCY_AGENT_HOME for the
-  // last), read before this main() runs — the RuntimeContext consumes the
-  // config overrides at construction, and lib/config.agency derives the
-  // settings/policy/history paths from the agent home in its static-const
-  // initializers. Do not re-handle them here.
+  // last).
 
   if (args.flags.debug) {
     AGENT_DEBUG = true
@@ -1821,6 +710,21 @@ node main() {
   if (args.flags.verbose) {
     VERBOSE = true
   }
+
+  if (isFailure(MAIN_PROMPT_LARGE)) {
+    print(
+      color.red("Failed to read prompts/main-large.md: ${MAIN_PROMPT_LARGE.error}"),
+    )
+    process.exit(1)
+  }
+
+  if (isFailure(MAIN_PROMPT_SMALL)) {
+    print(
+      color.red("Failed to read prompts/main-small.md: ${MAIN_PROMPT_SMALL.error}"),
+    )
+    process.exit(1)
+  }
+
   // `--policy` is an optional-value flag: a bare `--policy` (no name or
   // path) prints the usage + the built-in policies and exits, rather than
   // silently doing nothing.
@@ -1830,100 +734,7 @@ node main() {
   }
   _policyArg = args.flags.policy ?? ""
 
-  // Model setup. `--local` (deprecated alias: `--local-model`) is an optional-
-  // value flag with three states: absent (null); bare empty-string for guided
-  // setup; a value for that local model. `--local` and the hosted flags
-  // (--model / --fastmodel / --slowmodel) are mutually exclusive -- local and
-  // hosted are different in kind (provider llama-cpp, no embedding endpoint).
-  const localVal = args.flags["local"] ?? args.flags["local-model"]
-  const modelArg = args.flags.model ?? ""
-  const hasModelFlags = modelArg != "" || (args.flags.fastmodel ?? "") != "" || (args.flags.slowmodel ?? "") != ""
-  if (localVal != null && hasModelFlags) {
-    print(
-      color.red("Pass either --model (hosted) or --local (local), not both."),
-    )
-    process.exit(1)
-  }
-  if (localVal == "") {
-    // Bare --local: guided setup. Non-interactive can't prompt, so keep the
-    // print-catalog-and-exit behavior there.
-    if (!isTTY()) {
-      printLocalCatalog()
-      process.exit(0)
-    }
-    if (!localModelsSupported()) {
-      print(color.yellow("Local models need the smoltalk-llama-cpp package."))
-      print("Install it, then re-run:  ! npm i -g smoltalk-llama-cpp")
-      process.exit(1)
-    }
-    let items: ChoiceItem[] = []
-    for (modelName in listModelNames()) {
-      items.push({
-        key: modelName.name,
-        label: modelName.name
-      })
-    }
-    const choice = chooseOption(
-      "Local model",
-      "Pick a model, or type an hf: URI / .gguf path (downloads on first use):",
-      items,
-      allowFreeText: true,
-      allowCancel: true,
-    )
-    if (choice == "" || choice == null) {
-      process.exit(0)
-    }
-    configureLocalModel(choice)
-    configureSearch(true)
-    // fall through into the session on the chosen local model
-  } else if (localVal != null) {
-    configureLocalModel(localVal)
-    configureSearch(true)
-  } else {
-    // Hosted path. --model accepts `slot=model` (per-slot) or a bare model
-    // (global pin); explicit --fastmodel/--slowmodel win over a --model slot=.
-    const parsed = parseModelFlag(modelArg)
-    let modelGlobal = ""
-    let fastFlag = ""
-    let slowFlag = ""
-    let embeddingFlag = ""
-    if (modelArg != "") {
-      if (parsed.slot == "") {
-        modelGlobal = parsed.model
-      } else if (parsed.slot == "main") {
-        fastFlag = parsed.model
-      } else if (parsed.slot == "reasoning") {
-        slowFlag = parsed.model
-      } else if (parsed.slot == "embedding") {
-        if (!embeddingSpecHasProvider(parsed.model)) {
-          print(
-            color.red(
-            "Embedding models need the provider/model form, e.g. --model embedding=openai/text-embedding-3-small.",
-          ),
-          )
-          process.exit(1)
-        }
-        embeddingFlag = parsed.model
-      } else {
-        print(
-          color.red(
-          "Unknown model slot '${parsed.slot}' in --model. Valid slots: ${SLOTS.join(", ")}.",
-        ),
-        )
-        process.exit(1)
-      }
-    }
-    const fm = args.flags.fastmodel ?? ""
-    const sm = args.flags.slowmodel ?? ""
-    if (fm != "") {
-      fastFlag = fm
-    }
-    if (sm != "") {
-      slowFlag = sm
-    }
-    configureModels(modelGlobal, fastFlag, slowFlag, embeddingFlag, args.flags.provider ?? "")
-    configureSearch(false)
-  }
+  pickModelsForAgent(args)
 
   // Persistent knowledge graph, gated on the capability profile. Must run
   // before any handler/REPL is installed.
@@ -1939,83 +750,53 @@ node main() {
   const positionalQuery = args.positionals.join(" ")
   const hasQuery = positionalQuery != ""
   const startAgent = args.flags.agent ?? ""
+  // Validate the target subagent name up front (empty = coordinator).
+  if (startAgent != "" && !START_AGENTS.includes(startAgent)) {
+    print(
+      color.red(
+      "Unknown --agent value: ${startAgent}. Valid: ${START_AGENTS.join(", ")}",
+    ),
+    )
+    process.exit(1)
+  }
+
   const wantInteractive = args.flags.interactive
 
   // Seeded interactive: run the prompt as the first turn, then hand over the
   // REPL (needs a TTY + query, and not --print). Everything else is one-shot.
   const seededInteractive = wantInteractive && hasQuery && isTTY() && !args.flags.print
-  const runningOneShot = !seededInteractive && (args.flags.print || hasQuery || !isTTY())
+  const isOneShot = !seededInteractive && (args.flags.print || hasQuery || !isTTY())
 
-  // Tool-loop caps. One-shot runs (--print / piped / a positional query) have
-  // no REPL to continue an autonomous task, so maxToolCallRounds defaults
-  // higher (resolveMaxToolCallRounds); an explicit --max-tool-call-rounds always
-  // wins. Set as branch-scoped defaults on the root branch BEFORE any subagent
-  // is dispatched, so every (fork-seeded) subagent inherits them. setLlmOptions
-  // merges only present keys, so this never clobbers the model defaults above.
-  // Separate calls, each gated on its own value: setLlmOptions only skips
-  // `undefined`, not `null`, so passing an absent key would clobber the bag.
-  const maxRounds = resolveMaxToolCallRounds(args.flags["max-tool-call-rounds"] ?? null, runningOneShot)
+  const maxRounds = resolveMaxToolCallRounds(
+    args.flags["max-tool-call-rounds"] ?? null,
+    isOneShot,
+  )
   if (maxRounds != null) {
-    setLlmOptions({ maxToolCallRounds: maxRounds })
+    setLlmOptions({
+      maxToolCallRounds: maxRounds
+    })
   }
   const maxResultChars = args.flags["max-tool-result-chars"]
   if (maxResultChars != null) {
-    setLlmOptions({ maxToolResultChars: maxResultChars })
+    setLlmOptions({
+      maxToolResultChars: maxResultChars
+    })
   }
 
-  // Per-model default output cap from the capability profile. The hosted
-  // default of 20000 carries the adaptive-thinking empty-reply fix that
-  // used to live here as a TEMPORARY block. Local profiles cap lower.
-  // Branch-scoped, so every subagent inherits it. A per-call
-  // llm(..., { maxTokens }) still wins, e.g. the summarizer's 256.
   const capsMaxTokens = getCapabilities().maxTokens
   if (capsMaxTokens != null) {
-    setLlmOptions({ maxTokens: capsMaxTokens })
+    setLlmOptions({
+      maxTokens: capsMaxTokens
+    })
   }
 
   // One-shot autonomy: tell the code subagent there is no human to answer
   // questions and no next turn, so it must drive to a finished artifact.
   // Set before any dispatch so both the pinned `--agent code` path and the
   // coordinator (which calls codeAgent as a tool) pick it up.
-  setCodeOneShot(runningOneShot)
+  setCodeOneShot(isOneShot)
 
-  // Validate the target subagent name up front (empty = coordinator).
-  if (startAgent != "" && !START_AGENTS.includes(startAgent)) {
-    print(
-      color.red(
-      "Unknown --agent value: ${startAgent}. Valid: ${START_AGENTS.join(", ")}",
-    ),
-    )
-    process.exit(1)
-  }
-
-  // Seeded interactive: run the given prompt as the first turn, then hand
-  // the REPL to the user. Requires a seed prompt and a TTY (the REPL reads
-  // stdin). `--print` wins if both are passed — its whole job is to print
-  // and exit with no REPL. Without a TTY (or with `--print`) we fall
-  // through to one-shot below; `--interactive` with no prompt falls through
-  // to the plain REPL.
-  if (seededInteractive) {
-    setTitle("Agency Agent")
-    clearScreen()
-    printHeader()
-    const seededHandler = setupSession(true)
-    startInteractive(seededHandler, startAgent, positionalQuery)
-    process.exit(0)
-  }
-
-  // One-shot invocation: run one turn through the same agent the REPL uses
-  // and write the reply to stdout. No banner, no REPL. Entered when
-  // `--print` / `-p` is passed, a positional query is given, or stdin is
-  // piped (no TTY) — so the agent behaves like a Unix filter:
-  // `echo "..." | agency agent`. `--interactive` is NOT a one-shot trigger
-  // on its own: with a TTY and no prompt it falls through to the plain
-  // REPL; without a TTY the `!isTTY()` check below routes it here to
-  // degrade gracefully. The prompt comes from the positional when present,
-  // otherwise from stdin. (Title/clearScreen are skipped so piped output
-  // stays free of escape codes.)
-  const forceOneShot = args.flags.print || hasQuery
-  if (forceOneShot || !isTTY()) {
+  if (isOneShot) {
     let prompt = positionalQuery
     if (!hasQuery) {
       const fromStdin = readStdin()
@@ -2025,17 +806,13 @@ node main() {
       prompt = fromStdin
     }
     print(oneShotAgent(startAgent, prompt))
-    process.exit(0)
+    const roundedCost = "$${getCost().toFixed(4)}"
+    print(color.dim("\nSession cost: ${roundedCost}"))
+  } else {
+    setTitle("Agency Agent")
+    clearScreen()
+    print(getHeader())
+    const handler = setupSession(interactive: true)
+    startInteractive(handler, startAgent, positionalQuery)
   }
-
-  // Plain interactive REPL (no seed). `startInteractive` owns the runloop;
-  // every Enter dispatches into `_runTurn` which calls `mainAgent`.
-  // Interrupts raised during a turn propagate to the policy handler
-  // installed by the enclosing `handle` block via the AsyncLocalStorage
-  // handler stack.
-  setTitle("Agency Agent")
-  clearScreen()
-  printHeader()
-  const handler = setupSession(true)
-  startInteractive(handler, "", "")
 }