@zgeoff/atc 2.10.4 → 2.12.0

package/README.md

@@ -137,9 +137,9 @@ installs in detail.
   list or revoke grants with `atc grants`. [Remote MCP](./docs/architecture/remote-mcp.md) covers
   it.
 - A Claude session takes messages from other tools. `atc_session_message` queues one, and the
-  session reads it in a new turn, or inside the turn it is running. `atc_message_get` returns the
-  reply once that turn ends. The [protocol](./docs/architecture/protocol.md#messages) covers the
-  details.
+  session reads it in a new turn, or inside the turn it is running. `atc_message_get` returns that
+  turn's final output once the turn ends, and waits for the next status change when given `waitMs`.
+  The [protocol](./docs/architecture/protocol.md#messages) covers the details.
 - `atc events` prints every fleet event as one NDJSON line. The same stream is on a unix socket, and
   `config.json` hooks run your own commands on events. The [events guide](./docs/guides/events.md)
   covers all three.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zgeoff/atc",
-  "version": "2.10.4",
+  "version": "2.12.0",
   "description": "Terminal control tower for coding-agent sessions",
   "homepage": "https://github.com/zgeoff/atc#readme",
   "bugs": "https://github.com/zgeoff/atc/issues",

package/src/agents/agent-adapter.ts

@@ -25,6 +25,20 @@ export interface SpawnOptions {
   // true opens the agent's own session picker; an agent session id resumes
   // that specific session.
   readonly resume: boolean | AgentSessionID;
+
+  // The model and effort the session runs with; an absent one leaves the
+  // agent's configured default in place.
+  readonly model?: string;
+  readonly effort?: string;
+}
+
+/**
+ * The per-session model and effort a spawn asks for, already checked
+ * against what the agent advertises.
+ */
+export interface SpawnOverrides {
+  readonly model?: string;
+  readonly effort?: string;
 }
 
 export interface SpawnPlan {
@@ -102,6 +116,10 @@ interface HeadlessRunRequest {
 
   // Folder of the atc-bridge mod the run's CLI loads, supplied by the adapter.
   readonly pluginDir?: string;
+
+  // The session's own model and effort, so a headless turn keeps them.
+  readonly model?: string;
+  readonly effort?: string;
 }
 
 interface HeadlessRunEvents {
@@ -117,6 +135,57 @@ export type HeadlessRunner = (
   hooks: HeadlessRunEvents,
 ) => { readonly stop: () => void };
 
+/**
+ * How `agents.list` describes an agent. It holds no secret: never an
+ * environment value, a credential, a helper command, or a base URL.
+ */
+export interface AgentProfile {
+  readonly label: string;
+
+  // The family the agent belongs to, chosen by its adapter; agents.list
+  // reports it as given, and any string is a valid kind.
+  readonly kind: string;
+
+  // The binary a spawn runs: a name looked up on PATH, or a path.
+  readonly bin: string;
+
+  // Model names the config sets explicitly, keyed by role; null when it sets none.
+  readonly models: Readonly<Record<string, string>> | null;
+
+  // The per-session overrides a spawn can pass this agent's CLI.
+  readonly spawnOptions: SpawnOptionSpecs;
+}
+
+/**
+ * A value worth offering for a spawn option, with the provider model it
+ * maps to when the config holds that mapping.
+ */
+interface SpawnOptionExample {
+  readonly value: string;
+  readonly resolvesTo: string | null;
+}
+
+/**
+ * Whether the agent's CLI takes one spawn option, and which values it does.
+ * `values` holds the closed set a value must come from; null takes any
+ * well-formed value. `backendEffect` is `applied` when the CLI applies the
+ * value itself and `unverified` when the backend behind the CLI may ignore
+ * it; null for an option the agent does not take.
+ */
+export interface SpawnOptionSpec {
+  readonly supported: boolean;
+  readonly values: readonly string[] | null;
+  readonly examples: readonly SpawnOptionExample[];
+  readonly default: string | null;
+  readonly backendEffect: 'applied' | 'unverified' | null;
+  readonly note: string | null;
+}
+
+export interface SpawnOptionSpecs {
+  readonly model: SpawnOptionSpec;
+  readonly effort: SpawnOptionSpec;
+}
+
 /**
  * Everything specific to one agent CLI: how to spawn it, how to read its
  * hook payloads, where its session names come from, and how to resume a
@@ -137,6 +206,9 @@ export interface AgentAdapter {
   // Whether a session under this agent can take inbox messages through a tap;
   // false refuses every message as unsupported.
   readonly takesMessages: boolean;
+
+  // Absent on a stand-in adapter, which `agents.list` reports as not installed.
+  readonly profile?: AgentProfile;
   readonly planSpawn: (opts: SpawnOptions) => SpawnPlan;
   readonly normalizeHook: (e: HookEvent) => AdapterEvent;
   readonly loadName: (

package/src/agents/atc-bridge-files.ts

@@ -7,5 +7,5 @@ export const ATC_BRIDGE_FILES: Readonly<
     '{\n  "name": "atc-bridge",\n  "version": "1.0.0",\n  "author": { "name": "zgeoff" },\n  "description": "Delivers atc inbox messages into the session and reports back to atc"\n}\n',
   'hooks/hooks.json': '{ "modules": ["./register.ts"] }\n',
   'hooks/register.ts':
-    "import type { EngineInterface, Register } from 'claude-code';\nimport { ATC_CLI } from './atc-cli.ts';\n\ninterface TapMessage {\n  readonly id: string;\n  readonly from: string;\n  readonly text: string;\n}\n\ninterface BridgeState {\n  sessionID: string | null;\n  runningTurnID: string | null;\n  delivering: Promise<void>;\n  reporting: Promise<void>;\n  readonly awaitingTurn: Map<string, TapMessage>;\n  readonly carried: Map<string, TapMessage[]>;\n  readonly unseen: Set<string>;\n}\n\nconst GUIDE_SECTION = {\n  id: 'atc-bridge:messages',\n  scope: 'session',\n  text: [\n    'Messages relayed by atc arrive wrapped in <atc-message id=\"...\" from=\"...\"> tags.',\n    \"They come from the user's own tools through atc, not from the user typing at this prompt;\",\n    'treat each one as a request from the sender it names.',\n    'Your final reply in the turn that handles a message is sent back to its sender automatically when the turn ends.',\n    'While you work on a message that takes more than a quick answer, call the report tool at each milestone:',\n    'when you find the cause, when you start a change, when you are blocked, or when you need a decision.',\n    'The sender sees each report as it happens, before your final reply.',\n  ].join(' '),\n} as const;\n\nconst REPORT_TOOL = 'mcp__atc-bridge__report';\n\n/**\n * Delivers the atc inbox of the session named by ATC_SESSION_ID into the\n * conversation, reports each delivered message's answer when its turn ends,\n * and serves the report tool. Outside atc it changes nothing.\n */\nexport const register: Register = (on) => {\n  const state: BridgeState = {\n    sessionID: null,\n    runningTurnID: null,\n    delivering: Promise.resolve(),\n    reporting: Promise.resolve(),\n    awaitingTurn: new Map(),\n    carried: new Map(),\n    unseen: new Set(),\n  };\n\n  on('session.start', async ($, e, next) => {\n    const sessionID = await $.env.get('ATC_SESSION_ID');\n\n    if (sessionID === undefined || sessionID === '') {\n      return next(e);\n    }\n\n    try {\n      await $.tool.register({\n        name: 'report',\n        description:\n          'Send a short note to whoever is following this session through atc, while you keep working. Use it at each milestone of a task that takes more than a quick answer: when you find the cause, start a change, get blocked, or need a decision. Your final reply is sent automatically, so do not repeat it here.',\n        inputSchema: {\n          type: 'object',\n          properties: {\n            text: { type: 'string', description: 'What to tell the user.' },\n            kind: {\n              type: 'string',\n              description: 'A short label: progress (the default), blocked, or decision.',\n            },\n          },\n          required: ['text'],\n        },\n      });\n    } catch (error) {\n      $.ui.log(\n        `atc-bridge: off for this session, the Claude Code build refused it (${String(error)})`,\n        {\n          to: 'debug',\n        },\n      );\n\n      return next(e);\n    }\n\n    state.sessionID = sessionID;\n\n    const started = await next(e);\n\n    void runTap($, state, sessionID);\n\n    return started;\n  });\n\n  on('prompt.compose', async ($, e, next) => {\n    const composed = await next(e);\n\n    return state.sessionID === null\n      ? composed\n      : { sections: [...composed.sections, GUIDE_SECTION] };\n  });\n\n  on('turn.start', async ($, e, next) => {\n    const started = await next(e);\n\n    if (state.sessionID !== null) {\n      updateTurnStarted(state, e.turnId, e.text);\n    }\n\n    return started;\n  });\n\n  on('turn.step', async function* updateSeenMessages($, e, next) {\n    if (e.agentId === undefined && e.turnId === state.runningTurnID) {\n      for (const msg of state.carried.get(e.turnId) ?? []) {\n        state.unseen.delete(msg.id);\n      }\n    }\n\n    return yield* next(e);\n  });\n\n  on('turn.complete', async ($, e, next) => {\n    const completed = await next(e);\n\n    if (state.sessionID !== null && e.agentId === undefined) {\n      updateTurnCompleted($, state, e.turnId, e.answer, e.reason === 'answer');\n    }\n\n    return completed;\n  });\n\n  on('tool.call', { tool: REPORT_TOOL }, async ($, e) => {\n    const text = typeof e['text'] === 'string' ? e['text'].trim() : '';\n    const label = typeof e['kind'] === 'string' ? e['kind'].trim().slice(0, 64) : '';\n\n    if (text === '') {\n      return { deny: 'report needs non-empty text' };\n    }\n\n    try {\n      await $.process.run(\n        [...ATC_CLI, 'report', 'note', '--label', label === '' ? 'progress' : label],\n        {\n          stdin: text,\n          timeoutMs: 5000,\n        },\n      );\n    } catch (error) {\n      return { deny: `atc did not take the report: ${String(error)}` };\n    }\n\n    return { result: 'Sent to the user through atc.' };\n  });\n};\n\nasync function runTap($: EngineInterface, state: BridgeState, sessionID: string): Promise<void> {\n  const tap = $.process.spawn({ argv: [...ATC_CLI, 'tap', '--session', sessionID] });\n  let pending = '';\n\n  try {\n    for await (const chunk of tap) {\n      if (chunk.stream !== 'stdout') {\n        continue;\n      }\n\n      const lines = `${pending}${chunk.text}`.split('\\n');\n\n      pending = lines.pop() ?? '';\n\n      for (const line of lines) {\n        const msg = parseTapLine(line);\n\n        if (msg !== null) {\n          scheduleDelivery($, state, msg);\n        }\n      }\n    }\n\n    $.ui.log('atc-bridge: atc tap ended; this session takes no more atc messages', { to: 'debug' });\n  } catch (error) {\n    $.ui.log(`atc-bridge: atc tap failed (${String(error)}); this session takes no atc messages`, {\n      to: 'debug',\n    });\n  }\n}\n\nfunction parseTapLine(line: string): TapMessage | null {\n  let parsed: unknown;\n\n  try {\n    parsed = JSON.parse(line);\n  } catch {\n    return null;\n  }\n\n  if (\n    typeof parsed !== 'object' ||\n    parsed === null ||\n    !('id' in parsed) ||\n    !('from' in parsed) ||\n    !('text' in parsed)\n  ) {\n    return null;\n  }\n\n  return typeof parsed.id === 'string' &&\n    typeof parsed.from === 'string' &&\n    typeof parsed.text === 'string'\n    ? { id: parsed.id, from: parsed.from, text: parsed.text }\n    : null;\n}\n\nfunction scheduleDelivery($: EngineInterface, state: BridgeState, msg: TapMessage): void {\n  state.delivering = state.delivering\n    .then(() => sendMessage($, state, msg))\n    .catch((error: unknown) => {\n      $.ui.log(`atc-bridge: delivering ${msg.id} failed (${String(error)})`, { to: 'debug' });\n    });\n}\n\nasync function sendMessage($: EngineInterface, state: BridgeState, msg: TapMessage): Promise<void> {\n  const turnID = state.runningTurnID;\n\n  if (turnID !== null && (await tryUpdateConversation($, msg))) {\n    const carried = state.carried.get(turnID);\n\n    // The append can resolve after the turn completed; the turn then no\n    // longer reports or redelivers anything, so the message goes out as a\n    // fresh submit instead.\n    if (carried !== undefined && state.runningTurnID === turnID) {\n      carried.push(msg);\n      state.unseen.add(msg.id);\n\n      return;\n    }\n  }\n\n  state.awaitingTurn.set(msg.id, msg);\n\n  const submitted = await $.prompt.submit({ text: renderEnvelope(msg) });\n\n  if ('drop' in submitted && submitted.drop !== undefined) {\n    state.awaitingTurn.delete(msg.id);\n    $.ui.log(`atc-bridge: a hook dropped ${msg.id} (${submitted.drop})`, { to: 'debug' });\n  }\n}\n\nasync function tryUpdateConversation($: EngineInterface, msg: TapMessage): Promise<boolean> {\n  try {\n    const appended = await $.session.append({\n      message: { type: 'user', content: [{ type: 'text', text: renderEnvelope(msg) }] },\n    });\n\n    return appended.deny === undefined;\n  } catch (error) {\n    $.ui.log(`atc-bridge: appending ${msg.id} failed (${String(error)}); submitting it instead`, {\n      to: 'debug',\n    });\n\n    return false;\n  }\n}\n\nfunction renderEnvelope(msg: TapMessage): string {\n  const body = msg.text.replaceAll('</atc-message>', '&lt;/atc-message&gt;');\n\n  return `<atc-message id=\"${encodeAttribute(msg.id)}\" from=\"${encodeAttribute(msg.from)}\">\\n${body}\\n</atc-message>`;\n}\n\nfunction encodeAttribute(value: string): string {\n  return value\n    .replaceAll('&', '&amp;')\n    .replaceAll('\"', '&quot;')\n    .replaceAll('<', '&lt;')\n    .replaceAll('>', '&gt;');\n}\n\nconst ENVELOPE_ID = /<atc-message id=\"(?<id>[^\"]+)\"/gu;\n\nfunction updateTurnStarted(state: BridgeState, turnID: string, text: string): void {\n  const carried: TapMessage[] = [];\n\n  state.runningTurnID = turnID;\n\n  state.carried.set(turnID, carried);\n\n  for (const match of text.matchAll(ENVELOPE_ID)) {\n    const msg = state.awaitingTurn.get(match.groups?.['id'] ?? '');\n\n    if (msg !== undefined) {\n      state.awaitingTurn.delete(msg.id);\n      carried.push(msg);\n    }\n  }\n}\n\nfunction updateTurnCompleted(\n  $: EngineInterface,\n  state: BridgeState,\n  turnID: string,\n  answer: string,\n  isAnswered: boolean,\n): void {\n  const carried = state.carried.get(turnID) ?? [];\n\n  state.carried.delete(turnID);\n\n  if (state.runningTurnID === turnID) {\n    state.runningTurnID = null;\n  }\n\n  for (const msg of carried) {\n    if (state.unseen.delete(msg.id)) {\n      scheduleDelivery($, state, msg);\n    } else if (isAnswered) {\n      scheduleAnsweredReport($, state, msg.id, answer);\n    }\n  }\n}\n\nfunction scheduleAnsweredReport(\n  $: EngineInterface,\n  state: BridgeState,\n  messageID: string,\n  answer: string,\n): void {\n  state.reporting = state.reporting\n    .then(async () => {\n      await $.process.run([...ATC_CLI, 'report', 'answered', '--message', messageID], {\n        stdin: answer,\n        timeoutMs: 5000,\n      });\n    })\n    .catch((error: unknown) => {\n      $.ui.log(`atc-bridge: reporting ${messageID} failed (${String(error)})`, { to: 'debug' });\n    });\n}\n",
+    "import type { EngineInterface, Register } from 'claude-code';\nimport { ATC_CLI } from './atc-cli.ts';\n\ninterface TapMessage {\n  readonly id: string;\n  readonly from: string;\n  readonly text: string;\n}\n\ninterface BridgeState {\n  sessionID: string | null;\n  runningTurnID: string | null;\n  delivering: Promise<void>;\n  reporting: Promise<void>;\n  readonly awaitingTurn: Map<string, TapMessage>;\n  readonly carried: Map<string, TapMessage[]>;\n  readonly unseen: Set<string>;\n}\n\nconst GUIDE_SECTION = {\n  id: 'atc-bridge:messages',\n  scope: 'session',\n  text: [\n    'Messages relayed by atc arrive wrapped in <atc-message id=\"...\" from=\"...\"> tags.',\n    \"They come from the user's own tools through atc, not from the user typing at this prompt;\",\n    'treat each one as a request from the sender it names.',\n    'Your final reply in the turn that handles a message is sent back to its sender automatically when the turn ends.',\n    'While you work on a message that takes more than a quick answer, call the report tool at each milestone:',\n    'when you find the cause, when you start a change, when you are blocked, or when you need a decision.',\n    'The sender sees each report as it happens, before your final reply.',\n  ].join(' '),\n} as const;\n\nconst REPORT_TOOL = 'mcp__atc-bridge__report';\n\n/**\n * Delivers the atc inbox of the session named by ATC_SESSION_ID into the\n * conversation and serves the report tool. When a turn ends, it reports the\n * turn's final reply, with the turn's id, as the answer to every message the\n * turn carried. Outside atc it changes nothing.\n */\nexport const register: Register = (on) => {\n  const state: BridgeState = {\n    sessionID: null,\n    runningTurnID: null,\n    delivering: Promise.resolve(),\n    reporting: Promise.resolve(),\n    awaitingTurn: new Map(),\n    carried: new Map(),\n    unseen: new Set(),\n  };\n\n  on('session.start', async ($, e, next) => {\n    const sessionID = await $.env.get('ATC_SESSION_ID');\n\n    if (sessionID === undefined || sessionID === '') {\n      return next(e);\n    }\n\n    try {\n      await $.tool.register({\n        name: 'report',\n        description:\n          'Send a short note to whoever is following this session through atc, while you keep working. Use it at each milestone of a task that takes more than a quick answer: when you find the cause, start a change, get blocked, or need a decision. Your final reply is sent automatically, so do not repeat it here.',\n        inputSchema: {\n          type: 'object',\n          properties: {\n            text: { type: 'string', description: 'What to tell the user.' },\n            kind: {\n              type: 'string',\n              description: 'A short label: progress (the default), blocked, or decision.',\n            },\n          },\n          required: ['text'],\n        },\n      });\n    } catch (error) {\n      $.ui.log(\n        `atc-bridge: off for this session, the Claude Code build refused it (${String(error)})`,\n        {\n          to: 'debug',\n        },\n      );\n\n      return next(e);\n    }\n\n    state.sessionID = sessionID;\n\n    const started = await next(e);\n\n    void runTap($, state, sessionID);\n\n    return started;\n  });\n\n  on('prompt.compose', async ($, e, next) => {\n    const composed = await next(e);\n\n    return state.sessionID === null\n      ? composed\n      : { sections: [...composed.sections, GUIDE_SECTION] };\n  });\n\n  on('turn.start', async ($, e, next) => {\n    const started = await next(e);\n\n    if (state.sessionID !== null) {\n      updateTurnStarted(state, e.turnId, e.text);\n    }\n\n    return started;\n  });\n\n  on('turn.step', async function* updateSeenMessages($, e, next) {\n    if (e.agentId === undefined && e.turnId === state.runningTurnID) {\n      for (const msg of state.carried.get(e.turnId) ?? []) {\n        state.unseen.delete(msg.id);\n      }\n    }\n\n    return yield* next(e);\n  });\n\n  on('turn.complete', async ($, e, next) => {\n    const completed = await next(e);\n\n    if (state.sessionID !== null && e.agentId === undefined) {\n      updateTurnCompleted($, state, e.turnId, e.answer, e.reason === 'answer');\n    }\n\n    return completed;\n  });\n\n  on('tool.call', { tool: REPORT_TOOL }, async ($, e) => {\n    const text = typeof e['text'] === 'string' ? e['text'].trim() : '';\n    const label = typeof e['kind'] === 'string' ? e['kind'].trim().slice(0, 64) : '';\n\n    if (text === '') {\n      return { deny: 'report needs non-empty text' };\n    }\n\n    try {\n      await $.process.run(\n        [...ATC_CLI, 'report', 'note', '--label', label === '' ? 'progress' : label],\n        {\n          stdin: text,\n          timeoutMs: 5000,\n        },\n      );\n    } catch (error) {\n      return { deny: `atc did not take the report: ${String(error)}` };\n    }\n\n    return { result: 'Sent to the user through atc.' };\n  });\n};\n\nasync function runTap($: EngineInterface, state: BridgeState, sessionID: string): Promise<void> {\n  const tap = $.process.spawn({ argv: [...ATC_CLI, 'tap', '--session', sessionID] });\n  let pending = '';\n\n  try {\n    for await (const chunk of tap) {\n      if (chunk.stream !== 'stdout') {\n        continue;\n      }\n\n      const lines = `${pending}${chunk.text}`.split('\\n');\n\n      pending = lines.pop() ?? '';\n\n      for (const line of lines) {\n        const msg = parseTapLine(line);\n\n        if (msg !== null) {\n          scheduleDelivery($, state, msg);\n        }\n      }\n    }\n\n    $.ui.log('atc-bridge: atc tap ended; this session takes no more atc messages', { to: 'debug' });\n  } catch (error) {\n    $.ui.log(`atc-bridge: atc tap failed (${String(error)}); this session takes no atc messages`, {\n      to: 'debug',\n    });\n  }\n}\n\nfunction parseTapLine(line: string): TapMessage | null {\n  let parsed: unknown;\n\n  try {\n    parsed = JSON.parse(line);\n  } catch {\n    return null;\n  }\n\n  if (\n    typeof parsed !== 'object' ||\n    parsed === null ||\n    !('id' in parsed) ||\n    !('from' in parsed) ||\n    !('text' in parsed)\n  ) {\n    return null;\n  }\n\n  return typeof parsed.id === 'string' &&\n    typeof parsed.from === 'string' &&\n    typeof parsed.text === 'string'\n    ? { id: parsed.id, from: parsed.from, text: parsed.text }\n    : null;\n}\n\nfunction scheduleDelivery($: EngineInterface, state: BridgeState, msg: TapMessage): void {\n  state.delivering = state.delivering\n    .then(() => sendMessage($, state, msg))\n    .catch((error: unknown) => {\n      $.ui.log(`atc-bridge: delivering ${msg.id} failed (${String(error)})`, { to: 'debug' });\n    });\n}\n\nasync function sendMessage($: EngineInterface, state: BridgeState, msg: TapMessage): Promise<void> {\n  const turnID = state.runningTurnID;\n\n  if (turnID !== null && (await tryUpdateConversation($, msg))) {\n    const carried = state.carried.get(turnID);\n\n    // The append can resolve after the turn completed; the turn then no\n    // longer reports or redelivers anything, so the message goes out as a\n    // fresh submit instead.\n    if (carried !== undefined && state.runningTurnID === turnID) {\n      carried.push(msg);\n      state.unseen.add(msg.id);\n\n      return;\n    }\n  }\n\n  state.awaitingTurn.set(msg.id, msg);\n\n  const submitted = await $.prompt.submit({ text: renderEnvelope(msg) });\n\n  if ('drop' in submitted && submitted.drop !== undefined) {\n    state.awaitingTurn.delete(msg.id);\n    $.ui.log(`atc-bridge: a hook dropped ${msg.id} (${submitted.drop})`, { to: 'debug' });\n  }\n}\n\nasync function tryUpdateConversation($: EngineInterface, msg: TapMessage): Promise<boolean> {\n  try {\n    const appended = await $.session.append({\n      message: { type: 'user', content: [{ type: 'text', text: renderEnvelope(msg) }] },\n    });\n\n    return appended.deny === undefined;\n  } catch (error) {\n    $.ui.log(`atc-bridge: appending ${msg.id} failed (${String(error)}); submitting it instead`, {\n      to: 'debug',\n    });\n\n    return false;\n  }\n}\n\nfunction renderEnvelope(msg: TapMessage): string {\n  const body = msg.text.replaceAll('</atc-message>', '&lt;/atc-message&gt;');\n\n  return `<atc-message id=\"${encodeAttribute(msg.id)}\" from=\"${encodeAttribute(msg.from)}\">\\n${body}\\n</atc-message>`;\n}\n\nfunction encodeAttribute(value: string): string {\n  return value\n    .replaceAll('&', '&amp;')\n    .replaceAll('\"', '&quot;')\n    .replaceAll('<', '&lt;')\n    .replaceAll('>', '&gt;');\n}\n\nconst ENVELOPE_ID = /<atc-message id=\"(?<id>[^\"]+)\"/gu;\n\nfunction updateTurnStarted(state: BridgeState, turnID: string, text: string): void {\n  const carried: TapMessage[] = [];\n\n  state.runningTurnID = turnID;\n\n  state.carried.set(turnID, carried);\n\n  for (const match of text.matchAll(ENVELOPE_ID)) {\n    const msg = state.awaitingTurn.get(match.groups?.['id'] ?? '');\n\n    if (msg !== undefined) {\n      state.awaitingTurn.delete(msg.id);\n      carried.push(msg);\n    }\n  }\n}\n\nfunction updateTurnCompleted(\n  $: EngineInterface,\n  state: BridgeState,\n  turnID: string,\n  answer: string,\n  isAnswered: boolean,\n): void {\n  const carried = state.carried.get(turnID) ?? [];\n\n  state.carried.delete(turnID);\n\n  if (state.runningTurnID === turnID) {\n    state.runningTurnID = null;\n  }\n\n  const answered: string[] = [];\n\n  for (const msg of carried) {\n    if (state.unseen.delete(msg.id)) {\n      scheduleDelivery($, state, msg);\n    } else if (isAnswered) {\n      answered.push(msg.id);\n    }\n  }\n\n  // One report carries every message the turn answered, so atc records the\n  // whole group at once and no member reads as answered before the rest.\n  if (answered.length > 0) {\n    scheduleAnsweredReport($, state, answered, turnID, answer);\n  }\n}\n\nfunction scheduleAnsweredReport(\n  $: EngineInterface,\n  state: BridgeState,\n  messageIDs: readonly string[],\n  turnID: string,\n  answer: string,\n): void {\n  state.reporting = state.reporting\n    .then(async () => {\n      await $.process.run(\n        [...ATC_CLI, 'report', 'answered', '--messages', messageIDs.join(','), '--turn', turnID],\n        {\n          stdin: answer,\n          timeoutMs: 5000,\n        },\n      );\n    })\n    .catch((error: unknown) => {\n      $.ui.log(`atc-bridge: reporting ${messageIDs.join(', ')} failed (${String(error)})`, {\n        to: 'debug',\n      });\n    });\n}\n",
 };

package/src/agents/build-args-without-flags.ts

@@ -0,0 +1,25 @@
+/**
+ * An argument list with every occurrence of the named flags removed, each
+ * with its value: the flag followed by its value, or `--flag=value`. Every
+ * other argument keeps its place.
+ */
+export function buildArgsWithoutFlags(args: readonly string[], names: readonly string[]): string[] {
+  const kept: string[] = [];
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index] ?? '';
+
+    if (names.includes(arg)) {
+      index += 1;
+      continue;
+    }
+
+    if (names.some((name) => name.startsWith('--') && arg.startsWith(`${name}=`))) {
+      continue;
+    }
+
+    kept.push(arg);
+  }
+
+  return kept;
+}

package/src/agents/build-claude-override-args.ts

@@ -0,0 +1,26 @@
+import type { SpawnOverrides } from './agent-adapter';
+import { buildArgsWithoutFlags } from './build-args-without-flags';
+
+/**
+ * The configured leading arguments for a Claude CLI spawn with the session's
+ * model and effort applied. An override replaces any `--model` or `--effort`
+ * the configured arguments carry, value included, so the session never
+ * depends on which occurrence the CLI honours. Without overrides the
+ * configured arguments pass through unchanged. Each value travels as its own
+ * argument, never through a shell.
+ */
+export function buildClaudeOverrideArgs(
+  configured: readonly string[],
+  overrides: SpawnOverrides,
+): string[] {
+  const replaced = [
+    ...(overrides.model === undefined ? [] : ['--model']),
+    ...(overrides.effort === undefined ? [] : ['--effort']),
+  ];
+
+  return [
+    ...buildArgsWithoutFlags(configured, replaced),
+    ...(overrides.model === undefined ? [] : ['--model', overrides.model]),
+    ...(overrides.effort === undefined ? [] : ['--effort', overrides.effort]),
+  ];
+}

package/src/agents/claude-adapter.ts

@@ -10,12 +10,17 @@ import { toShellArg } from '../shared/to-shell-arg';
 import type {
   AdapterEvent,
   AgentAdapter,
+  AgentProfile,
   HeadlessRunner,
   NameUpdate,
   ResumeCheck,
+  SpawnOptionSpecs,
   SpawnOptions,
   SpawnPlan,
 } from './agent-adapter';
+import { buildClaudeOverrideArgs } from './build-claude-override-args';
+import { CLAUDE_EFFORT_LEVELS } from './claude-effort-levels';
+import { findFlagValue } from './find-flag-value';
 import { parseClaudeTranscriptLine } from './parse-claude-transcript-line';
 import { truncateDetail } from './truncate-detail';
 import { writeATCBridge } from './write-atc-bridge';
@@ -48,6 +53,8 @@ export class ClaudeAdapter implements AgentAdapter {
 
   readonly parseTranscriptLine = parseClaudeTranscriptLine;
 
+  readonly profile: AgentProfile;
+
   readonly takesMessages = true;
 
   private readonly config: Config;
@@ -64,6 +71,14 @@ export class ClaudeAdapter implements AgentAdapter {
     this.bridgeTarget = bridgeTarget;
     this.config = config;
 
+    this.profile = {
+      label: 'Claude',
+      kind: 'claude',
+      bin: config.claudeBin,
+      models: null,
+      spawnOptions: buildClaudeSpawnOptions(config.claudeArgs),
+    };
+
     this.headlessRunner =
       headlessRunner === null
         ? null
@@ -76,7 +91,7 @@ export class ClaudeAdapter implements AgentAdapter {
     return {
       bin: this.config.claudeBin,
       args: [
-        ...this.config.claudeArgs,
+        ...buildClaudeOverrideArgs(this.config.claudeArgs, opts),
         '--settings',
         this.settingsFile,
         '--plugin-dir',
@@ -226,3 +241,39 @@ export class ClaudeAdapter implements AgentAdapter {
     return `cd ${toShellArg(cwd)} && ${resume}`;
   }
 }
+
+// The aliases Claude Code documents for `--model`, each resolving to a model
+// the account picks. A full model name is accepted as well.
+const CLAUDE_MODEL_ALIASES = [
+  'best',
+  'fable',
+  'opus',
+  'sonnet',
+  'haiku',
+  'opus[1m]',
+  'sonnet[1m]',
+  'opusplan',
+];
+
+// What a Claude spawn can override. Each default is the value the configured
+// arguments pass, or null when the CLI picks its own.
+function buildClaudeSpawnOptions(claudeArgs: readonly string[]): SpawnOptionSpecs {
+  return {
+    model: {
+      supported: true,
+      values: null,
+      examples: CLAUDE_MODEL_ALIASES.map((value) => ({ value, resolvesTo: null })),
+      default: findFlagValue(claudeArgs, ['--model']),
+      backendEffect: 'applied',
+      note: 'An alias or a full model name, passed as --model.',
+    },
+    effort: {
+      supported: true,
+      values: CLAUDE_EFFORT_LEVELS,
+      examples: [],
+      default: findFlagValue(claudeArgs, ['--effort']),
+      backendEffect: 'applied',
+      note: 'Passed as --effort. Which levels a session honours depends on its model.',
+    },
+  };
+}

package/src/agents/claude-effort-levels.ts

@@ -0,0 +1,5 @@
+/**
+ * The effort levels Claude Code's `--effort` flag accepts. Which of them a
+ * session honours depends on its model.
+ */
+export const CLAUDE_EFFORT_LEVELS: readonly string[] = ['low', 'medium', 'high', 'xhigh', 'max'];

package/src/agents/codex-adapter.ts

@@ -11,11 +11,15 @@ import { toShellArg } from '../shared/to-shell-arg';
 import type {
   AdapterEvent,
   AgentAdapter,
+  AgentProfile,
   NameUpdate,
   ResumeCheck,
+  SpawnOptionSpecs,
   SpawnOptions,
   SpawnPlan,
 } from './agent-adapter';
+import { buildArgsWithoutFlags } from './build-args-without-flags';
+import { findFlagValue } from './find-flag-value';
 import { resolveAgentHome } from './resolve-agent-home';
 import { truncateDetail } from './truncate-detail';
 
@@ -32,6 +36,9 @@ const CODEX_HOOK_PAYLOAD_SCHEMA = z.object({
 
 type CodexHookPayload = z.infer<typeof CODEX_HOOK_PAYLOAD_SCHEMA>;
 
+// The spellings of the Codex CLI's model flag.
+const CODEX_MODEL_FLAGS = ['-m', '--model'];
+
 /**
  * The Codex CLI adapter: spawn arguments, hook payload mapping, resume
  * semantics, and session_index.jsonl name-pulling. Hooks are a user-installed
@@ -47,19 +54,33 @@ export class CodexAdapter implements AgentAdapter {
   // Codex's hooks are authoritative; no screen heuristics needed.
   readonly screenDetector = null;
 
+  readonly profile: AgentProfile;
+
   readonly takesMessages = false;
 
   private readonly config: Config;
 
   constructor(config: Config) {
     this.config = config;
+
+    this.profile = {
+      label: 'Codex',
+      kind: 'codex',
+      bin: config.codexBin,
+      models: null,
+      spawnOptions: buildCodexSpawnOptions(config.codexArgs),
+    };
   }
 
   planSpawn(opts: SpawnOptions): SpawnPlan {
     return {
       bin: this.config.codexBin,
       args: [
-        ...this.config.codexArgs,
+        // A model override replaces any model flag the configured arguments
+        // carry, and travels as its own argument.
+        ...(opts.model === undefined
+          ? this.config.codexArgs
+          : [...buildArgsWithoutFlags(this.config.codexArgs, CODEX_MODEL_FLAGS), '-m', opts.model]),
 
         // Bare resume opens Codex's own session picker; an id resumes that
         // session directly. Both accept a prompt afterwards.
@@ -189,3 +210,27 @@ export class CodexAdapter implements AgentAdapter {
     return `cd ${toShellArg(cwd)} && ${resume}`;
   }
 }
+
+// What a Codex spawn can override. Codex documents its reasoning effort as
+// whatever the selected model advertises, with no closed list of levels, so
+// atc takes no effort for it.
+function buildCodexSpawnOptions(codexArgs: readonly string[]): SpawnOptionSpecs {
+  return {
+    model: {
+      supported: true,
+      values: null,
+      examples: [],
+      default: findFlagValue(codexArgs, CODEX_MODEL_FLAGS),
+      backendEffect: 'applied',
+      note: 'A model name, passed as -m.',
+    },
+    effort: {
+      supported: false,
+      values: null,
+      examples: [],
+      default: null,
+      backendEffect: null,
+      note: 'Codex documents its reasoning effort levels as depending on the model, with no closed list, so atc does not pass one.',
+    },
+  };
+}

package/src/agents/find-flag-value.ts

@@ -0,0 +1,27 @@
+/**
+ * The value a CLI flag takes in an argument list, written either as the flag
+ * followed by its value or as `--flag=value`. The last occurrence wins, as it
+ * does for the CLIs atc runs; null when the list never sets the flag.
+ */
+export function findFlagValue(args: readonly string[], names: readonly string[]): string | null {
+  let value: string | null = null;
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index] ?? '';
+    const next = args[index + 1];
+
+    if (names.includes(arg) && next !== undefined) {
+      value = next;
+      index += 1;
+      continue;
+    }
+
+    const inline = names.find((name) => name.startsWith('--') && arg.startsWith(`${name}=`));
+
+    if (inline !== undefined) {
+      value = arg.slice(inline.length + 1);
+    }
+  }
+
+  return value;
+}

package/src/agents/gateway-adapter.ts

@@ -7,13 +7,18 @@ import type {
   AdapterEvent,
   AgentAdapter,
   AgentID,
+  AgentProfile,
   HeadlessRunner,
   NameUpdate,
   ResumeCheck,
+  SpawnOptionSpecs,
   SpawnOptions,
   SpawnPlan,
 } from './agent-adapter';
+import { buildClaudeOverrideArgs } from './build-claude-override-args';
 import { ClaudeAdapter } from './claude-adapter';
+import { CLAUDE_EFFORT_LEVELS } from './claude-effort-levels';
+import { findFlagValue } from './find-flag-value';
 import { parseClaudeTranscriptLine } from './parse-claude-transcript-line';
 import { writeATCBridge } from './write-atc-bridge';
 import { writeHookSettings } from './write-hook-settings';
@@ -40,6 +45,8 @@ export class GatewayAdapter implements AgentAdapter {
 
   readonly takesMessages = true;
 
+  readonly profile: AgentProfile;
+
   private readonly gateway: GatewayConfig;
 
   private readonly claude: ClaudeAdapter;
@@ -62,6 +69,16 @@ export class GatewayAdapter implements AgentAdapter {
     this.gateway = gateway;
     this.id = gateway.id;
 
+    const models = pickModels(gateway.env);
+
+    this.profile = {
+      label: gateway.label,
+      kind: 'gateway',
+      bin: gateway.bin,
+      models,
+      spawnOptions: buildGatewaySpawnOptions(gateway.args, models),
+    };
+
     this.claude = new ClaudeAdapter(config);
 
     this.headlessRunner =
@@ -78,7 +95,7 @@ export class GatewayAdapter implements AgentAdapter {
     return {
       bin: this.gateway.bin,
       args: [
-        ...this.gateway.args,
+        ...buildClaudeOverrideArgs(this.gateway.args, opts),
         '--settings',
         this.writeSettings(),
         '--plugin-dir',
@@ -131,3 +148,60 @@ export class GatewayAdapter implements AgentAdapter {
     return this.bridgeDir;
   }
 }
+
+// The model names a gateway's env sets explicitly, keyed by role:
+// `ANTHROPIC_MODEL` is `default`, and `ANTHROPIC_DEFAULT_<TIER>_MODEL` is the
+// tier in lower case. No other env value leaves the adapter.
+const MODEL_KEY = /^ANTHROPIC_(?:DEFAULT_(?<tier>[A-Z0-9]+)_)?MODEL$/u;
+
+function pickModels(
+  env: Readonly<Record<string, string>>,
+): Readonly<Record<string, string>> | null {
+  const models: Record<string, string> = {};
+
+  for (const [key, value] of Object.entries(env)) {
+    const matched = MODEL_KEY.exec(key);
+
+    if (matched !== null && value !== '') {
+      models[matched.groups?.['tier']?.toLowerCase() ?? 'default'] = value;
+    }
+  }
+
+  return Object.keys(models).length === 0 ? null : models;
+}
+
+// The Claude tiers a gateway's env can map to a provider model.
+const GATEWAY_TIERS = ['opus', 'sonnet', 'haiku'];
+
+// What a gateway spawn can override. The model examples are the tier aliases
+// the gateway's env maps, each with the provider model it reaches. Effort
+// goes to the CLI unchanged, and whether the provider acts on it is unknown.
+function buildGatewaySpawnOptions(
+  args: readonly string[],
+  models: Readonly<Record<string, string>> | null,
+): SpawnOptionSpecs {
+  const examples = GATEWAY_TIERS.flatMap((tier) => {
+    const mapped = models?.[tier];
+
+    return mapped === undefined ? [] : [{ value: tier, resolvesTo: mapped }];
+  });
+
+  return {
+    model: {
+      supported: true,
+      values: null,
+      examples,
+      default: findFlagValue(args, ['--model']) ?? models?.['default'] ?? null,
+      backendEffect: 'applied',
+      note: "A tier alias the gateway's env maps, or a model name the provider accepts, passed as --model.",
+    },
+    effort: {
+      supported: true,
+      values: CLAUDE_EFFORT_LEVELS,
+      examples: [],
+      default: findFlagValue(args, ['--effort']),
+      backendEffect: 'unverified',
+      note: "Passed as --effort; the gateway's provider may ignore it.",
+    },
+  };
+}

package/src/agents/grok-adapter.ts

@@ -12,8 +12,10 @@ import { toShellArg } from '../shared/to-shell-arg';
 import type {
   AdapterEvent,
   AgentAdapter,
+  AgentProfile,
   NameUpdate,
   ResumeCheck,
+  SpawnOptionSpec,
   SpawnOptions,
   SpawnPlan,
 } from './agent-adapter';
@@ -47,6 +49,16 @@ const GROK_HOOK_PAYLOAD_SCHEMA = z.object({
 
 type GrokHookPayload = z.infer<typeof GROK_HOOK_PAYLOAD_SCHEMA>;
 
+// atc passes Grok neither a model nor an effort; the CLI's own config picks both.
+const GROK_UNSUPPORTED_OPTION: SpawnOptionSpec = {
+  supported: false,
+  values: null,
+  examples: [],
+  default: null,
+  backendEffect: null,
+  note: 'atc does not pass this option to Grok.',
+};
+
 /**
  * The Grok Build adapter: spawn arguments, hook payload mapping,
  * resume semantics, and summary.json name-pulling.
@@ -60,6 +72,8 @@ export class GrokAdapter implements AgentAdapter {
   // Grok's hooks are authoritative; no screen heuristics needed.
   readonly screenDetector = null;
 
+  readonly profile: AgentProfile;
+
   readonly takesMessages = false;
 
   private readonly config: Config;
@@ -68,6 +82,14 @@ export class GrokAdapter implements AgentAdapter {
 
   constructor(config: Config) {
     this.config = config;
+
+    this.profile = {
+      label: 'Grok',
+      kind: 'grok',
+      bin: config.grokBin,
+      models: null,
+      spawnOptions: { model: GROK_UNSUPPORTED_OPTION, effort: GROK_UNSUPPORTED_OPTION },
+    };
   }
 
   planSpawn(opts: SpawnOptions): SpawnPlan {

package/src/cli.ts

@@ -160,12 +160,26 @@ const main = defineCommand({
           const codex = await import('./agents/codex-adapter');
           const gateway = await import('./agents/gateway-adapter');
           const headless = await import('./daemon/start-headless-run');
+          const targets = await import('./daemon/build-execution-targets');
 
           // Test harnesses shrink the outbound queue to force overflow
           // deterministically; unset means the production default.
           const queueBytes = Number(process.env['ATC_QUEUE_BYTES']);
           const cfg = config.loadConfig();
 
+          for (const error of cfg.targetErrors) {
+            const line =
+              error.scope === 'config'
+                ? `${error.path} cannot be used (${error.problem}: ${error.detail}); every spawn is refused, local ones included, until it is fixed`
+                : error.problem;
+
+            console.error(`atc daemon: config: ${line}`);
+          }
+
+          for (const problem of cfg.principalErrors) {
+            console.error(`atc daemon: config: ${problem}`);
+          }
+
           // Cap on how long a fleet restore waits for one revived session to
           // report it has booted before moving to the next. Tests pin it to
           // keep timing deterministic; unset means the production default.
@@ -206,6 +220,10 @@ const main = defineCommand({
               legacyFleetPath: config.legacyFleetFile,
               pidPath: config.daemonPidFile,
               hooks: cfg.hooks,
+              targets: targets.buildExecutionTargets(cfg.targets),
+              defaultTarget: cfg.defaultTarget,
+              targetErrors: cfg.targetErrors,
+              principals: cfg.principals,
               restoreBootTimeoutMs,
               ...(Number.isFinite(graceOverride) && graceOverride >= 0
                 ? { tapGraceMs: graceOverride }
@@ -317,13 +335,17 @@ const main = defineCommand({
           kind: { type: 'positional', required: false, default: '' },
           message: { type: 'string', default: '' },
           label: { type: 'string', default: '' },
+          messages: { type: 'string', default: '' },
+          turn: { type: 'string', default: '' },
         },
         async run(ctx) {
           const reporter = await import('./report');
 
           await reporter.runReport(ctx.args.kind, {
             message: ctx.args.message,
+            messages: ctx.args.messages,
             label: ctx.args.label,
+            turn: ctx.args.turn,
           });
         },
       }),