@zgeoff/atc 0.1.12 → 1.0.0

package/README.md

@@ -27,11 +27,11 @@ atc
 ```
 
 Needs [Bun](https://bun.sh) (atc runs from source through it) and the `claude` CLI on your PATH.
-Grok sessions also need the `grok` CLI, and Codex sessions the `codex` CLI. From a checkout,
-`bun src/cli.ts` runs the same thing. atc is built to pair with
-[zoxide](https://github.com/ajeetdsouza/zoxide): the spawn directory picker feeds on its frecency
-list, so with zoxide installed every directory you visit is two keystrokes from a session. Without
-it the picker falls back to atc's own spawn history.
+Grok sessions also need the `grok` CLI, and Codex sessions the `codex` CLI — the agent picker lists
+only the agents whose binary it can find. From a checkout, `bun src/cli.ts` runs the same thing. atc
+is built to pair with [zoxide](https://github.com/ajeetdsouza/zoxide): the spawn directory picker
+feeds on its frecency list, so with zoxide installed every directory you visit is two keystrokes
+from a session. Without it the picker falls back to atc's own spawn history.
 
 The first invocation auto-spawns the daemon (`atc daemon` runs it in the foreground for systemd or
 debugging); the TUI is a thin client, so quitting or crashing it leaves every session running. Runs
@@ -52,7 +52,7 @@ fine nested inside zellij/tmux (give the pane locked mode so Ctrl-Space reaches
 | `a`             | overlay        | ack notification without attaching                                                                                                                                      |
 | `p`             | overlay        | pin or unpin the selected session — pinned sessions stay at the top of the list                                                                                         |
 | `g`             | overlay        | toggle the grouped view: sessions cluster under repository headers                                                                                                      |
-| `H`             | overlay        | eject to headless (Claude only). Hidden and ignored on a Grok row.                                                                                                      |
+| `H`             | overlay        | eject to headless. Hidden and ignored on a row whose agent has no headless handoff.                                                                                     |
 | `P`             | overlay        | revive: a fresh terminal resumes a headless or killed session in place                                                                                                  |
 | `y`             | overlay        | yank the resume command (`claude --resume <id>`, `grok --resume <id>`, or `codex resume <id>`)                                                                          |
 | `Y`             | overlay        | eject: yank the resume command, then kill the session here                                                                                                              |
@@ -65,13 +65,14 @@ The overlay orders sessions by pinned first, then attention state, then most rec
 the session you want is nearly always near the top. The grouped view (`g`) keeps that order but
 clusters sessions under dim repository headers, with pinned sessions leading in their own cluster; a
 git worktree clusters with its main repository, and a directory outside any repository stands alone.
-A reserved column after the pin mark shows a dim `g` on Grok rows; Claude rows keep a space so names
-stay aligned. The `atc_session_update` MCP tool renames and pins sessions, so an agent can organise
-the fleet for you.
+A reserved column after the pin mark shows a dim letter per agent — `g` on Grok rows, `x` on Codex
+rows, and whatever letter a gateway was given; Claude rows keep a space so names stay aligned. The
+`atc_session_update` MCP tool renames and pins sessions, so an agent can organise the fleet for you.
 
 Revive (`P`) resumes the session from its saved transcript, so a session killed before its first
 exchange has nothing on disk yet, and the overlay says so in its message column instead of resuming.
-Headless eject (`H`) is Claude-only and uses the same transcript; Grok has no headless handoff.
+Headless eject (`H`) uses the same transcript, and a gateway session ejects to its own backend. Grok
+and Codex have no headless handoff, so the key is hidden on their rows.
 
 Everything else is passed through to the focused session, which owns the full screen. Fleet state
 renders inside Claude Code's own status line (injected via the same `--settings` file): your
@@ -147,6 +148,7 @@ session.
   "grokArgs": [],
   "codexBin": "codex",
   "codexArgs": [],
+  "gateways": {},
   "leader": "ctrl-space"
 }
 ```
@@ -159,15 +161,51 @@ session.
 | `grokArgs`   | `[]`           | Prepended to every Grok spawn. A user `--leader` in this list is dropped; atc always appends `--no-leader`. |
 | `codexBin`   | `"codex"`      | The binary spawned for Codex sessions.                                                                      |
 | `codexArgs`  | `[]`           | Prepended to every Codex spawn.                                                                             |
+| `gateways`   | `{}`           | Claude-compatible backends, keyed by agent id. Each becomes its own row in the agent picker.                |
 | `leader`     | `"ctrl-space"` | The overlay toggle: `ctrl-` plus a letter or one of `\` `]` `^` `_`, e.g. `"ctrl-]"`.                       |
 
 Pick a different leader when `Ctrl-Space` is taken on your machine — Raycast on macOS claims it, and
 `ctrl-]` is a solid replacement that no common terminal, multiplexer, or OS shortcut wants. An
 unknown or reserved value falls back to the default.
 
+### Gateways
+
+A gateway runs the Claude CLI against a Claude-compatible backend, under its own agent id. Claude
+and GLM sessions then sit side by side in one fleet:
+
+```json
+{
+  "gateways": {
+    "zai": {
+      "label": "GLM (z.ai)",
+      "mark": "z",
+      "baseURL": "https://api.z.ai/api/anthropic",
+      "apiKeyHelper": "~/.local/bin/atc-zai-key",
+      "env": { "ANTHROPIC_DEFAULT_SONNET_MODEL": "glm-5.2" }
+    }
+  }
+}
+```
+
+| Field          | Default     | Meaning                                                                                         |
+| -------------- | ----------- | ----------------------------------------------------------------------------------------------- |
+| `baseURL`      | required    | The backend's Anthropic-format endpoint. An entry without one is left out of the picker.        |
+| `label`        | the id      | The row shown in the agent picker.                                                              |
+| `mark`         | the id      | The overlay column letter; the first character is used.                                         |
+| `bin`, `args`  | `claudeBin` | The binary and leading arguments, when the backend needs a different build of the CLI.          |
+| `apiKeyHelper` | none        | Command the CLI runs to read the credential, so no token is written into atc's state directory. |
+| `env`          | `{}`        | Extra environment for the session, such as the model each Claude tier maps to.                  |
+
+Two backends may be given the same `mark`. atc does not check, and a clash makes them
+indistinguishable in the overlay column.
+
+The id may not be `claude`, `grok`, or `codex`. atc writes one settings file per id and passes it as
+`--settings`, on the terminal spawn and on a headless turn alike, so a gateway session reaches its
+own backend rather than whatever the terminal exported.
+
 `atc mcp` exposes the fleet as MCP tools (list, spawn, drive, organise) to any MCP client, wrangled
-sessions included. `atc_session_spawn` takes an optional `agent` (`claude`, `grok`, or `codex`) and
-defaults to Claude; it never reads the TUI last-used value.
+sessions included. `atc_session_spawn` takes an optional `agent` id and defaults to Claude; it never
+reads the TUI last-used value.
 
 ```sh
 claude mcp add --scope user atc -- atc mcp

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zgeoff/atc",
-  "version": "0.1.12",
+  "version": "1.0.0",
   "description": "Terminal control tower for Claude Code sessions",
   "homepage": "https://github.com/zgeoff/atc#readme",
   "bugs": "https://github.com/zgeoff/atc/issues",
@@ -36,7 +36,11 @@
     "@xterm/addon-serialize": "0.14.0",
     "@xterm/headless": "6.0.0",
     "bun-pty": "0.4.10",
-    "citty": "0.2.2"
+    "citty": "0.2.2",
+    "kysely": "0.29.5",
+    "ts-pattern": "5.9.0",
+    "xstate": "5.32.5",
+    "zod": "4.4.3"
   },
   "devDependencies": {
     "@commitlint/cli": "21.2.0",
@@ -52,6 +56,7 @@
     "oxlint": "1.73.0",
     "oxlint-tsgolint": "0.24.0",
     "tslib": "2.8.1",
+    "type-fest": "5.8.0",
     "typescript": "7.0.2"
   },
   "packageManager": "bun@1.3.10"

package/src/{agent-adapter.ts → agents/agent-adapter.ts}

@@ -1,21 +1,29 @@
-import type { HookEvent } from './hooks';
+import type { HookEvent } from '../daemon/hooks';
+import type { AgentSessionID } from '../shared/agent-session-id';
 
-export type AgentKind = 'claude' | 'grok' | 'codex';
+/**
+ * Which agent a session runs under: the key the adapter registry is looked
+ * up by. Every agent CLI supplies one, and so does every configured backend
+ * that drives a CLI it does not own, so two ids can share one kind.
+ */
+export type AgentID = string;
 
 /**
- * Missing, empty, and unknown values become Claude so a fleet written
- * before the agent column still restores as Claude.
+ * Missing and empty values become Claude so a fleet written before the agent
+ * column still restores as Claude. Any other string is returned as it stands,
+ * registered or not: an id whose adapter is gone must reach the caller intact
+ * so the session can be shown and refused, never quietly run as Claude.
  */
-export function toAgentKind(raw: unknown): AgentKind {
-  return raw === 'grok' || raw === 'codex' ? raw : 'claude';
+export function toAgentID(raw: unknown): AgentID {
+  return typeof raw === 'string' && raw !== '' ? raw : 'claude';
 }
 
 export interface SpawnOptions {
   readonly prompt: string;
 
-  // true opens the agent's own session picker; a string resumes that
-  // specific agent session id.
-  readonly resume: boolean | string;
+  // true opens the agent's own session picker; an agent session id resumes
+  // that specific session.
+  readonly resume: boolean | AgentSessionID;
 }
 
 export interface SpawnPlan {
@@ -25,7 +33,7 @@ export interface SpawnPlan {
 
 export interface AdapterEvent {
   kind: 'started' | 'needs-input' | 'turn-done' | 'prompt-submitted' | 'ended' | 'heartbeat';
-  agentSessionID?: string;
+  agentSessionID?: AgentSessionID;
   message?: string;
 
   // Fuller activity text than message: what the agent last said or was
@@ -57,15 +65,19 @@ interface ScreenDetector {
 }
 
 export interface ResumeCheck {
-  readonly agentSessionID?: string;
+  readonly agentSessionID?: AgentSessionID;
   readonly transcriptSource?: string;
 }
 
 interface HeadlessRunRequest {
   readonly cwd: string;
   readonly prompt: string;
-  readonly resume?: string;
+  readonly resume?: AgentSessionID;
   readonly permissionMode?: string;
+
+  // Settings file the run's CLI is started with, so a headless turn reaches
+  // the same backend the session's terminal did.
+  readonly settings?: string;
 }
 
 interface HeadlessRunEvents {
@@ -85,7 +97,9 @@ export type HeadlessRunner = (
  * session outside atc. The session core never sees past this interface.
  */
 export interface AgentAdapter {
-  readonly kind: AgentKind;
+  // What the registry is keyed by, and what a session records. Unique across
+  // registered adapters.
+  readonly id: AgentID;
 
   // Runs one headless turn over a session; null means eject is unsupported
   // for this agent.
@@ -100,5 +114,8 @@ export interface AgentAdapter {
     namedBy: 'user' | 'auto' | 'agent',
   ) => Promise<NameUpdate | null>;
   readonly canResume: (session: ResumeCheck) => boolean;
-  readonly buildResumeCommand: (cwd: string, agentSessionID: string | undefined) => string | null;
+  readonly buildResumeCommand: (
+    cwd: string,
+    agentSessionID: AgentSessionID | undefined,
+  ) => string | null;
 }

package/src/{build-cli-command.ts → agents/build-cli-command.ts}

@@ -9,7 +9,7 @@ export function buildCLICommand(subcommand: string): string {
   const exec = process.execPath;
 
   if (basename(exec) === 'bun' || basename(exec) === 'bun.exe') {
-    return `"${exec}" "${join(import.meta.dir, 'cli.ts')}" ${subcommand}`;
+    return `"${exec}" "${join(import.meta.dir, '..', 'cli.ts')}" ${subcommand}`;
   }
 
   return `"${exec}" ${subcommand}`;

package/src/agents/build-hook-settings.ts

@@ -0,0 +1,59 @@
+import type { AgentID } from './agent-adapter';
+import { buildCLICommand } from './build-cli-command';
+
+/**
+ * What one agent id needs on top of the shared instrumentation. The
+ * environment block and the credential helper point the CLI at a backend
+ * other than the default one; both are absent for the stock agent.
+ */
+export interface HookSettingsProfile {
+  readonly id: AgentID;
+  readonly env?: Readonly<Record<string, string>>;
+  readonly apiKeyHelper?: string;
+}
+
+/**
+ * The settings object injected into wrangled sessions via
+ * `claude --settings`. The user's own settings are untouched; these hooks
+ * only exist in sessions atc spawns, and identify themselves via
+ * ATC_SESSION_ID in the env.
+ *
+ * A settings-file env block outranks a shell export of the same variable, so
+ * a session's backend is decided here rather than by whatever the terminal
+ * happened to carry. The credential is never part of it: the helper command
+ * supplies that at run time, so it never reaches a file atc writes.
+ */
+export function buildHookSettings(
+  profile: HookSettingsProfile,
+  statuslinePadding: number,
+): Record<string, unknown> {
+  const entry = [
+    { hooks: [{ type: 'command', command: buildCLICommand('hook-report'), timeout: 5 }] },
+  ];
+
+  return {
+    hooks: {
+      // SessionStart carries the session id at spawn/resume time, before any
+      // interaction — without it a session only enters the fleet file after
+      // its first prompt/notification.
+      SessionStart: entry,
+      Notification: entry,
+      Stop: entry,
+      UserPromptSubmit: entry,
+      SessionEnd: entry,
+    },
+
+    // Fleet status renders inside Claude Code's own status line; the injected
+    // command chains the user's configured statusline first, so mirror their
+    // padding.
+    statusLine: {
+      type: 'command',
+      command: buildCLICommand('statusline'),
+      padding: statuslinePadding,
+    },
+    ...(profile.env === undefined || Object.keys(profile.env).length === 0
+      ? {}
+      : { env: profile.env }),
+    ...(profile.apiKeyHelper === undefined ? {} : { apiKeyHelper: profile.apiKeyHelper }),
+  };
+}

package/src/{claude-adapter.ts → agents/claude-adapter.ts}

@@ -1,6 +1,12 @@
-import { existsSync, readFileSync, writeFileSync } from 'node:fs';
-import { homedir } from 'node:os';
-import { join } from 'node:path';
+import { existsSync } from 'node:fs';
+import { z } from 'zod';
+import type { HookEvent } from '../daemon/hooks';
+import type { AgentSessionID } from '../shared/agent-session-id';
+import { buildOptionalString } from '../shared/build-optional-string';
+import type { Config } from '../shared/config';
+import { isRecord } from '../shared/report';
+import { toAgentSessionID } from '../shared/to-agent-session-id';
+import { toShellArg } from '../shared/to-shell-arg';
 import type {
   AdapterEvent,
   AgentAdapter,
@@ -10,18 +16,28 @@ import type {
   SpawnOptions,
   SpawnPlan,
 } from './agent-adapter';
-import { buildCLICommand } from './build-cli-command';
-import type { Config } from './config';
-import { stateDir } from './config';
-import type { HookEvent } from './hooks';
-import { isRecord } from './report';
+import { truncateDetail } from './truncate-detail';
+import { writeHookSettings } from './write-hook-settings';
+
+// Claude's hook payload keys, snake_case. An absent or wrong-typed field
+// parses to undefined rather than failing the payload, so a broken reporter
+// never breaks the session it reports on.
+const CLAUDE_HOOK_PAYLOAD_SCHEMA = z.object({
+  session_id: buildOptionalString(),
+  transcript_path: buildOptionalString(),
+  message: buildOptionalString(),
+  last_assistant_message: buildOptionalString(),
+  prompt: buildOptionalString(),
+});
+
+type ClaudeHookPayload = z.infer<typeof CLAUDE_HOOK_PAYLOAD_SCHEMA>;
 
 /**
  * The Claude Code adapter: spawn arguments, `--settings` instrumentation,
  * resume semantics, transcript name-pulling, and statusline chaining.
  */
 export class ClaudeAdapter implements AgentAdapter {
-  readonly kind = 'claude';
+  readonly id = 'claude';
 
   readonly headlessRunner: HeadlessRunner | null;
 
@@ -39,7 +55,7 @@ export class ClaudeAdapter implements AgentAdapter {
   }
 
   planSpawn(opts: SpawnOptions): SpawnPlan {
-    this.settingsFile ??= writeHookSettings();
+    this.settingsFile ??= writeHookSettings({ id: this.id });
 
     return {
       bin: this.config.claudeBin,
@@ -55,19 +71,21 @@ export class ClaudeAdapter implements AgentAdapter {
   }
 
   normalizeHook(e: HookEvent): AdapterEvent {
-    const sessionID = e.payload['session_id'];
-    const transcript = e.payload['transcript_path'];
+    const parsed = CLAUDE_HOOK_PAYLOAD_SCHEMA.safeParse(e.payload);
+    const payload: ClaudeHookPayload = parsed.success ? parsed.data : {};
 
     const base: AdapterEvent = {
       kind: 'heartbeat',
-      ...(typeof sessionID === 'string' ? { agentSessionID: sessionID } : {}),
+      ...(payload.session_id === undefined
+        ? {}
+        : { agentSessionID: toAgentSessionID(payload.session_id) }),
     };
 
     const named: AdapterEvent = {
       ...base,
-      ...(typeof transcript === 'string'
-        ? { nameSource: transcript, transcriptSource: transcript }
-        : {}),
+      ...(payload.transcript_path === undefined
+        ? {}
+        : { nameSource: payload.transcript_path, transcriptSource: payload.transcript_path }),
     };
 
     switch (e.event) {
@@ -75,30 +93,29 @@ export class ClaudeAdapter implements AgentAdapter {
         return { ...named, kind: 'started' };
       }
       case 'Notification': {
-        const message = e.payload['message'];
+        const message = payload.message;
 
         return {
           ...base,
           kind: 'needs-input',
-          ...(typeof message === 'string' && message !== ''
+          ...(message !== undefined && message !== ''
             ? { message, detail: truncateDetail(message) }
             : {}),
         };
       }
       case 'Stop': {
-        const lastMessage = e.payload['last_assistant_message'];
+        const lastMessage = payload.last_assistant_message;
 
         return {
           ...named,
           kind: 'turn-done',
-          ...(typeof lastMessage === 'string' && lastMessage !== ''
+          ...(lastMessage !== undefined && lastMessage !== ''
             ? { detail: truncateDetail(lastMessage) }
             : {}),
         };
       }
       case 'UserPromptSubmit': {
-        const prompt = e.payload['prompt'];
-        const preview = typeof prompt === 'string' ? prompt.slice(0, 80) : '';
+        const preview = payload.prompt === undefined ? '' : payload.prompt.slice(0, 80);
 
         return {
           ...named,
@@ -178,66 +195,10 @@ export class ClaudeAdapter implements AgentAdapter {
   }
 
   // Shell command that re-opens this session outside atc (or anywhere).
-  buildResumeCommand(cwd: string, agentSessionID: string | undefined): string | null {
+  buildResumeCommand(cwd: string, agentSessionID: AgentSessionID | undefined): string | null {
     const resume =
       agentSessionID === undefined ? 'claude --resume' : `claude --resume ${agentSessionID}`;
 
-    const quoted = cwd.replaceAll("'", String.raw`'\''`);
-
-    return `cd '${quoted}' && ${resume}`;
+    return `cd ${toShellArg(cwd)} && ${resume}`;
   }
 }
-
-// Settings file injected into wrangled sessions via `claude --settings`.
-// The user's own settings are untouched; these hooks only exist in sessions
-// atc spawns, and identify themselves via ATC_SESSION_ID in the env.
-function writeHookSettings(): string {
-  const cmd = buildCLICommand('hook-report');
-  const entry = [{ hooks: [{ type: 'command', command: cmd, timeout: 5 }] }];
-
-  const settings = {
-    hooks: {
-      // SessionStart carries the session id at spawn/resume time, before any
-      // interaction — without it a session only enters the fleet file after
-      // its first prompt/notification.
-      SessionStart: entry,
-      Notification: entry,
-      Stop: entry,
-      UserPromptSubmit: entry,
-      SessionEnd: entry,
-    },
-  };
-
-  // Fleet status renders inside Claude Code's own status line; the injected
-  // command chains the user's configured statusline first, so mirror their
-  // padding.
-  let padding = 0;
-
-  try {
-    const settingsPath = join(homedir(), '.claude', 'settings.json');
-    const raw = readFileSync(settingsPath, 'utf8');
-    const user: unknown = JSON.parse(raw);
-    const statusLine = isRecord(user) ? user['statusLine'] : undefined;
-    const userPadding = isRecord(statusLine) ? statusLine['padding'] : undefined;
-
-    if (typeof userPadding === 'number') {
-      padding = userPadding;
-    }
-  } catch {}
-
-  const statusline = {
-    type: 'command',
-    command: buildCLICommand('statusline'),
-    padding,
-  };
-
-  const file = join(stateDir, 'hook-settings.json');
-
-  writeFileSync(file, JSON.stringify({ ...settings, statusLine: statusline }, null, 2));
-
-  return file;
-}
-
-function truncateDetail(text: string): string {
-  return text.length <= 600 ? text : `${text.slice(0, 599)}…`;
-}

package/src/{codex-adapter.ts → agents/codex-adapter.ts}

@@ -1,6 +1,13 @@
 import { existsSync, readFileSync } from 'node:fs';
-import { homedir } from 'node:os';
 import { join } from 'node:path';
+import { z } from 'zod';
+import type { HookEvent } from '../daemon/hooks';
+import type { AgentSessionID } from '../shared/agent-session-id';
+import { buildOptionalString } from '../shared/build-optional-string';
+import type { Config } from '../shared/config';
+import { isRecord } from '../shared/report';
+import { toAgentSessionID } from '../shared/to-agent-session-id';
+import { toShellArg } from '../shared/to-shell-arg';
 import type {
   AdapterEvent,
   AgentAdapter,
@@ -9,9 +16,21 @@ import type {
   SpawnOptions,
   SpawnPlan,
 } from './agent-adapter';
-import type { Config } from './config';
-import type { HookEvent } from './hooks';
-import { isRecord } from './report';
+import { resolveAgentHome } from './resolve-agent-home';
+import { truncateDetail } from './truncate-detail';
+
+// Codex's hook payload keys, snake_case. An absent or wrong-typed field
+// parses to undefined rather than failing the payload, so a broken reporter
+// never breaks the session it reports on.
+const CODEX_HOOK_PAYLOAD_SCHEMA = z.object({
+  session_id: buildOptionalString(),
+  transcript_path: buildOptionalString(),
+  prompt: buildOptionalString(),
+  last_assistant_message: buildOptionalString(),
+  tool_name: buildOptionalString(),
+});
+
+type CodexHookPayload = z.infer<typeof CODEX_HOOK_PAYLOAD_SCHEMA>;
 
 /**
  * The Codex CLI adapter: spawn arguments, hook payload mapping, resume
@@ -20,7 +39,7 @@ import { isRecord } from './report';
  * trusts once in the Codex TUI; atc never writes into the user's Codex config.
  */
 export class CodexAdapter implements AgentAdapter {
-  readonly kind = 'codex';
+  readonly id = 'codex';
 
   // Codex has no headless handoff.
   readonly headlessRunner = null;
@@ -50,18 +69,22 @@ export class CodexAdapter implements AgentAdapter {
   }
 
   normalizeHook(e: HookEvent): AdapterEvent {
-    const sessionID = e.payload['session_id'];
-    const transcript = e.payload['transcript_path'];
+    const parsed = CODEX_HOOK_PAYLOAD_SCHEMA.safeParse(e.payload);
+    const payload: CodexHookPayload = parsed.success ? parsed.data : {};
 
     const base: AdapterEvent = {
       kind: 'heartbeat',
-      ...(typeof sessionID === 'string' ? { agentSessionID: sessionID } : {}),
+      ...(payload.session_id === undefined
+        ? {}
+        : { agentSessionID: toAgentSessionID(payload.session_id) }),
     };
 
     const named: AdapterEvent = {
       ...base,
-      ...(typeof sessionID === 'string' ? { nameSource: sessionID } : {}),
-      ...(typeof transcript === 'string' ? { transcriptSource: transcript } : {}),
+      ...(payload.session_id === undefined ? {} : { nameSource: payload.session_id }),
+      ...(payload.transcript_path === undefined
+        ? {}
+        : { transcriptSource: payload.transcript_path }),
     };
 
     switch (e.event) {
@@ -69,18 +92,17 @@ export class CodexAdapter implements AgentAdapter {
         return { ...named, kind: 'started' };
       }
       case 'PermissionRequest': {
-        const toolName = e.payload['tool_name'];
+        const toolName = payload.tool_name;
 
         const message =
-          typeof toolName === 'string' && toolName !== ''
+          toolName !== undefined && toolName !== ''
             ? `waiting for approval: ${toolName}`
             : 'waiting for approval';
 
         return { ...base, kind: 'needs-input', message, detail: message };
       }
       case 'UserPromptSubmit': {
-        const prompt = e.payload['prompt'];
-        const preview = typeof prompt === 'string' ? prompt.slice(0, 80) : '';
+        const preview = payload.prompt === undefined ? '' : payload.prompt.slice(0, 80);
 
         return {
           ...named,
@@ -89,12 +111,12 @@ export class CodexAdapter implements AgentAdapter {
         };
       }
       case 'Stop': {
-        const lastMessage = e.payload['last_assistant_message'];
+        const lastMessage = payload.last_assistant_message;
 
         return {
           ...named,
           kind: 'turn-done',
-          ...(typeof lastMessage === 'string' && lastMessage !== ''
+          ...(lastMessage !== undefined && lastMessage !== ''
             ? { detail: truncateDetail(lastMessage) }
             : {}),
         };
@@ -116,7 +138,7 @@ export class CodexAdapter implements AgentAdapter {
       return Promise.resolve(null);
     }
 
-    const index = join(resolveCodexHome(), 'session_index.jsonl');
+    const index = join(resolveAgentHome('CODEX_HOME', '.codex'), 'session_index.jsonl');
     let text: string;
 
     try {
@@ -159,20 +181,9 @@ export class CodexAdapter implements AgentAdapter {
   }
 
   // Shell command that re-opens this session outside atc (or anywhere).
-  buildResumeCommand(cwd: string, agentSessionID: string | undefined): string | null {
+  buildResumeCommand(cwd: string, agentSessionID: AgentSessionID | undefined): string | null {
     const resume = agentSessionID === undefined ? 'codex resume' : `codex resume ${agentSessionID}`;
-    const quoted = cwd.replaceAll("'", String.raw`'\''`);
 
-    return `cd '${quoted}' && ${resume}`;
+    return `cd ${toShellArg(cwd)} && ${resume}`;
   }
 }
-
-function resolveCodexHome(): string {
-  const home = process.env['CODEX_HOME'];
-
-  return home !== undefined && home !== '' ? home : join(homedir(), '.codex');
-}
-
-function truncateDetail(text: string): string {
-  return text.length <= 600 ? text : `${text.slice(0, 599)}…`;
-}