@zgeoff/atc 2.11.0 → 2.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zgeoff/atc",
-  "version": "2.11.0",
+  "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 {
@@ -133,6 +151,39 @@ export interface AgentProfile {
 
   // 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;
 }
 
 /**

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

@@ -14,9 +14,13 @@ import type {
   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';
@@ -66,7 +70,14 @@ export class ClaudeAdapter implements AgentAdapter {
   constructor(config: Config, headlessRunner: HeadlessRunner | null = null, bridgeTarget?: string) {
     this.bridgeTarget = bridgeTarget;
     this.config = config;
-    this.profile = { label: 'Claude', kind: 'claude', bin: config.claudeBin, models: null };
+
+    this.profile = {
+      label: 'Claude',
+      kind: 'claude',
+      bin: config.claudeBin,
+      models: null,
+      spawnOptions: buildClaudeSpawnOptions(config.claudeArgs),
+    };
 
     this.headlessRunner =
       headlessRunner === null
@@ -80,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',
@@ -230,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

@@ -14,9 +14,12 @@ import type {
   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';
 
@@ -33,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
@@ -56,14 +62,25 @@ export class CodexAdapter implements AgentAdapter {
 
   constructor(config: Config) {
     this.config = config;
-    this.profile = { label: 'Codex', kind: 'codex', bin: config.codexBin, models: null };
+
+    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.
@@ -193,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

@@ -11,10 +11,14 @@ import type {
   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';
@@ -65,11 +69,14 @@ 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: pickModels(gateway.env),
+      models,
+      spawnOptions: buildGatewaySpawnOptions(gateway.args, models),
     };
 
     this.claude = new ClaudeAdapter(config);
@@ -88,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',
@@ -162,3 +169,39 @@ function pickModels(
 
   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

@@ -15,6 +15,7 @@ import type {
   AgentProfile,
   NameUpdate,
   ResumeCheck,
+  SpawnOptionSpec,
   SpawnOptions,
   SpawnPlan,
 } from './agent-adapter';
@@ -48,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.
@@ -71,7 +82,14 @@ export class GrokAdapter implements AgentAdapter {
 
   constructor(config: Config) {
     this.config = config;
-    this.profile = { label: 'Grok', kind: 'grok', bin: config.grokBin, models: null };
+
+    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 }

package/src/client/daemon-client.ts

@@ -65,9 +65,12 @@ export class DaemonClient {
     return this.sendRequest('daemon.hello', { client: build, auth: { scheme: 'none' } });
   }
 
+  // A request with a principal acts as that principal, within what the
+  // connection may reach.
   sendRequest(
     m: string,
     p?: Readonly<Record<string, unknown>>,
+    as?: string,
   ): Promise<Readonly<Record<string, unknown>>> {
     if (this.closedReason !== null) {
       return Promise.reject(new DaemonError('internal', this.closedReason));
@@ -77,7 +80,16 @@ export class DaemonClient {
     const resolvers = Promise.withResolvers<Readonly<Record<string, unknown>>>();
 
     this.pending.set(id, { resolve: resolvers.resolve, reject: resolvers.reject });
-    this.queue?.send(encodeMessage({ v: PROTOCOL_V, id, m, ...(p === undefined ? {} : { p }) }));
+
+    this.queue?.send(
+      encodeMessage({
+        v: PROTOCOL_V,
+        id,
+        m,
+        ...(p === undefined ? {} : { p }),
+        ...(as === undefined ? {} : { as }),
+      }),
+    );
 
     return resolvers.promise;
   }
@@ -138,7 +150,7 @@ export class DaemonClient {
     if (msg.err === undefined) {
       waiter.resolve(msg.ok ?? {});
     } else {
-      waiter.reject(new DaemonError(msg.err.code, msg.err.msg));
+      waiter.reject(new DaemonError(msg.err.code, msg.err.msg, msg.err.data));
     }
   }
 

package/src/client/spawn-picker.ts

@@ -1,5 +1,6 @@
 import { homedir } from 'node:os';
 import type { AgentID } from '../agents/agent-adapter';
+import { DaemonError } from '../protocol/daemon-error';
 import { loadConfig } from '../shared/config';
 import { collectAgentPicks } from './collect-agent-picks';
 import type { AgentPick } from './collect-agent-picks';
@@ -32,7 +33,8 @@ export interface SpawnPickerDeps<TMirror> {
 /**
  * The modal flow behind n and r: agent, then directory, then name, then an
  * optional first prompt. Every path out of it either attaches the new
- * session or returns the client to the screen it came from.
+ * session or returns the client to the screen it came from. A spawn the
+ * daemon refuses is no path out: the flow stays open and shows why.
  */
 export class SpawnPicker<TMirror extends { readonly id: string }> {
   private readonly deps: SpawnPickerDeps<TMirror>;
@@ -60,6 +62,10 @@ export class SpawnPicker<TMirror extends { readonly id: string }> {
 
   private agent: AgentID = 'claude';
 
+  // The daemon's refusal of the last spawn, shown in place of the hint until
+  // the next key.
+  private refusal: string | null = null;
+
   constructor(deps: SpawnPickerDeps<TMirror>) {
     this.deps = deps;
   }
@@ -82,12 +88,15 @@ export class SpawnPicker<TMirror extends { readonly id: string }> {
 
     this.agent = this.picks[this.selected]?.agent ?? this.deps.getLastUsedAgent();
     this.step = 'agent';
+    this.refusal = null;
 
     process.stdout.write(ansi.clear);
     this.render();
   }
 
   applyKey(buf: Buffer) {
+    this.refusal = null;
+
     const edit = planTextEdit(buf, this.input, {
       isLeaderKey: this.deps.isLeaderKey,
       moves: this.step === 'agent' || this.step === 'dir',
@@ -168,7 +177,7 @@ export class SpawnPicker<TMirror extends { readonly id: string }> {
         selected: -1,
         input: this.input,
         placeholder: formatDirName(this.dir),
-        hint: `session name for ${formatDir(this.dir)} · ⏎ accept · esc back`,
+        hint: this.refusal ?? `session name for ${formatDir(this.dir)} · ⏎ accept · esc back`,
       });
     } else {
       drawPicker({
@@ -177,7 +186,7 @@ export class SpawnPicker<TMirror extends { readonly id: string }> {
         selected: -1,
         input: this.input,
         placeholder: 'optional — ⏎ to start interactive',
-        hint: 'first message for the session · ⏎ spawn · esc back',
+        hint: this.refusal ?? 'first message for the session · ⏎ spawn · esc back',
       });
     }
 
@@ -320,7 +329,21 @@ export class SpawnPicker<TMirror extends { readonly id: string }> {
 
         return;
       }
-    } catch {}
+    } catch (error) {
+      // A refused spawn keeps the picker on the step that sent it, with the
+      // entered text back in the input, so the user can fix the cause and
+      // retry or back out.
+      const reason =
+        error instanceof DaemonError ? `${error.code}: ${error.message}` : String(error);
+
+      this.refusal = `${reason} · ⏎ retry · esc back`;
+      this.input = this.resume ? this.name : prompt;
+
+      process.stdout.write(ansi.clear);
+      this.render();
+
+      return;
+    }
 
     this.deps.toBase();
   }

package/src/daemon/build-agent-list.ts

@@ -1,4 +1,4 @@
-import type { AgentAdapter } from '../agents/agent-adapter';
+import type { AgentAdapter, SpawnOptionSpec } from '../agents/agent-adapter';
 
 interface AgentCapabilities {
   // Only an installed agent can start a session.
@@ -21,6 +21,19 @@ export interface AgentEntry {
   readonly installed: boolean;
   readonly capabilities: AgentCapabilities;
   readonly models: Readonly<Record<string, string>> | null;
+  readonly spawnOptions: SpawnOptionEntries;
+}
+
+// A spawn option as `agents.list` shows it: the agent's own spec, plus
+// whether a spawn on this host can pass it now. Only an installed agent's
+// supported option is available.
+export interface SpawnOptionEntry extends SpawnOptionSpec {
+  readonly available: boolean;
+}
+
+interface SpawnOptionEntries {
+  readonly model: SpawnOptionEntry;
+  readonly effort: SpawnOptionEntry;
 }
 
 /**
@@ -53,6 +66,29 @@ export function buildAgentList(
         input: true,
       },
       models: profile?.models ?? null,
+      spawnOptions: {
+        model: buildSpawnOptionEntry(profile?.spawnOptions.model, installed),
+        effort: buildSpawnOptionEntry(profile?.spawnOptions.effort, installed),
+      },
     };
   });
 }
+
+// A stand-in adapter declares no spawn options, so it takes none.
+const NO_SPAWN_OPTION: SpawnOptionSpec = {
+  supported: false,
+  values: null,
+  examples: [],
+  default: null,
+  backendEffect: null,
+  note: null,
+};
+
+function buildSpawnOptionEntry(
+  spec: SpawnOptionSpec | undefined,
+  installed: boolean,
+): SpawnOptionEntry {
+  const resolved = spec ?? NO_SPAWN_OPTION;
+
+  return { ...resolved, available: installed && resolved.supported };
+}