@zgeoff/atc 2.6.0 → 2.8.0

package/README.md

@@ -120,6 +120,10 @@ installs in detail.
 - `atc mcp` exposes the fleet as MCP tools, so an agent can spawn, drive, and read other agents. A
   session spawned this way lists under the session that spawned it and is killed with it. Register
   it with `claude mcp add --scope user atc -- atc mcp`.
+- 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.
 - `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.6.0",
+  "version": "2.8.0",
   "description": "Terminal control tower for coding-agent sessions",
   "homepage": "https://github.com/zgeoff/atc#readme",
   "bugs": "https://github.com/zgeoff/atc/issues",
@@ -21,6 +21,7 @@
   "scripts": {
     "start": "bun src/cli.ts",
     "build:agents": "bash scripts/build-agents-md.sh agents/shared.md agents/project.md AGENTS.md",
+    "build:atc-bridge": "bun scripts/build-atc-bridge.ts && oxfmt src/agents/atc-bridge-files.ts && format-codemod --quiet src/agents/atc-bridge-files.ts",
     "build:binaries": "bash scripts/build-binaries.sh",
     "audit": "bun audit",
     "deadcode": "knip",
@@ -28,6 +29,7 @@
     "lint:fix": "oxlint --type-aware --type-check --report-unused-disable-directives-severity error --fix",
     "test": "bun test",
     "test:binary": "bun test --timeout 20000 test/daemon-e2e.test.ts",
+    "test:atc-bridge": "bash scripts/test-atc-bridge.sh",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "format": "oxfmt . && format-codemod --quiet .",
     "format:check": "oxfmt --check . && format-codemod --check --quiet .",

package/src/agents/agent-adapter.ts

@@ -1,5 +1,6 @@
 import type { HookEvent } from '../daemon/hooks';
 import type { AgentSessionID } from '../shared/agent-session-id';
+import type { SessionID } from '../shared/session-id';
 
 /**
  * Which agent a session runs under: the key the adapter registry is looked
@@ -95,6 +96,12 @@ interface HeadlessRunRequest {
   // 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;
+
+  // The atc session the run belongs to; the mod reads it to tap the inbox.
+  readonly sessionID?: SessionID;
+
+  // Folder of the atc-bridge mod the run's CLI loads, supplied by the adapter.
+  readonly pluginDir?: string;
 }
 
 interface HeadlessRunEvents {
@@ -124,6 +131,10 @@ export interface AgentAdapter {
 
   // The detector stack's screen tier; null when hooks are authoritative.
   readonly screenDetector: ScreenDetector | null;
+
+  // Whether a session under this agent can take inbox messages through a tap;
+  // false refuses every message as unsupported.
+  readonly takesMessages: boolean;
   readonly planSpawn: (opts: SpawnOptions) => SpawnPlan;
   readonly normalizeHook: (e: HookEvent) => AdapterEvent;
   readonly loadName: (

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

@@ -0,0 +1,11 @@
+// Generated by `bun run build:atc-bridge` from mods/atc-bridge; edit the mod, then rerun it.
+// oxlint-disable no-template-curly-in-string -- the strings are the mod source, template literals included
+export const ATC_BRIDGE_FILES: Readonly<
+  Record<'.claude-plugin/plugin.json' | 'hooks/hooks.json' | 'hooks/register.ts', string>
+> = {
+  '.claude-plugin/plugin.json':
+    '{\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    'To tell the user something before the turn ends (progress, a blocker, a decision you need), call the report tool.',\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 the user a short note through atc while you keep working: progress, a blocker, or a decision you need from them. Your final reply is sent automatically; use this only for what cannot wait for it.',\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",
+};

package/src/agents/build-cli-argv.ts

@@ -0,0 +1,13 @@
+import { join } from 'node:path';
+import { isCompiledBinary } from '../shared/is-compiled-binary';
+
+/**
+ * The argv that runs the atc CLI from inside a wrangled session: under bun
+ * the CLI entry path follows the runtime; a compiled binary is itself the
+ * entry.
+ */
+export function buildCLIArgv(): string[] {
+  return isCompiledBinary()
+    ? [process.execPath]
+    : [process.execPath, join(import.meta.dir, '..', 'cli.ts')];
+}

package/src/agents/build-cli-command.ts

@@ -1,5 +1,4 @@
-import { join } from 'node:path';
-import { isCompiledBinary } from '../shared/is-compiled-binary';
+import { buildCLIArgv } from './build-cli-argv';
 
 /**
  * Command line that wrangled sessions invoke for atc subcommands: under bun
@@ -7,11 +6,7 @@ import { isCompiledBinary } from '../shared/is-compiled-binary';
  * the entry.
  */
 export function buildCLICommand(subcommand: string): string {
-  const exec = process.execPath;
-
-  if (isCompiledBinary()) {
-    return `"${exec}" ${subcommand}`;
-  }
-
-  return `"${exec}" "${join(import.meta.dir, '..', 'cli.ts')}" ${subcommand}`;
+  return `${buildCLIArgv()
+    .map((part) => `"${part}"`)
+    .join(' ')} ${subcommand}`;
 }

package/src/agents/claude-adapter.ts

@@ -18,6 +18,7 @@ import type {
 } from './agent-adapter';
 import { parseClaudeTranscriptLine } from './parse-claude-transcript-line';
 import { truncateDetail } from './truncate-detail';
+import { writeATCBridge } from './write-atc-bridge';
 import { writeHookSettings } from './write-hook-settings';
 
 // Claude's hook payload keys, snake_case. An absent or wrong-typed field
@@ -47,14 +48,26 @@ export class ClaudeAdapter implements AgentAdapter {
 
   readonly parseTranscriptLine = parseClaudeTranscriptLine;
 
+  readonly takesMessages = true;
+
   private readonly config: Config;
 
   // Written on first spawn so constructing the adapter touches no state.
   private settingsFile: string | undefined;
 
-  constructor(config: Config, headlessRunner: HeadlessRunner | null = null) {
+  // Written on first spawn so constructing the adapter touches no state.
+  private bridgeDir: string | undefined;
+
+  private readonly bridgeTarget: string | undefined;
+
+  constructor(config: Config, headlessRunner: HeadlessRunner | null = null, bridgeTarget?: string) {
+    this.bridgeTarget = bridgeTarget;
     this.config = config;
-    this.headlessRunner = headlessRunner;
+
+    this.headlessRunner =
+      headlessRunner === null
+        ? null
+        : (opts, hooks) => headlessRunner({ ...opts, pluginDir: this.writeBridge() }, hooks);
   }
 
   planSpawn(opts: SpawnOptions): SpawnPlan {
@@ -66,6 +79,8 @@ export class ClaudeAdapter implements AgentAdapter {
         ...this.config.claudeArgs,
         '--settings',
         this.settingsFile,
+        '--plugin-dir',
+        this.writeBridge(),
         ...(opts.resume === true ? ['--resume'] : []),
         ...(typeof opts.resume === 'string' ? ['--resume', opts.resume] : []),
         ...(opts.prompt === '' ? [] : [opts.prompt]),
@@ -73,6 +88,12 @@ export class ClaudeAdapter implements AgentAdapter {
     };
   }
 
+  private writeBridge(): string {
+    this.bridgeDir ??= writeATCBridge(this.bridgeTarget);
+
+    return this.bridgeDir;
+  }
+
   normalizeHook(e: HookEvent): AdapterEvent {
     const parsed = CLAUDE_HOOK_PAYLOAD_SCHEMA.safeParse(e.payload);
     const payload: ClaudeHookPayload = parsed.success ? parsed.data : {};

package/src/agents/codex-adapter.ts

@@ -47,6 +47,8 @@ export class CodexAdapter implements AgentAdapter {
   // Codex's hooks are authoritative; no screen heuristics needed.
   readonly screenDetector = null;
 
+  readonly takesMessages = false;
+
   private readonly config: Config;
 
   constructor(config: Config) {

package/src/agents/gateway-adapter.ts

@@ -15,6 +15,7 @@ import type {
 } from './agent-adapter';
 import { ClaudeAdapter } from './claude-adapter';
 import { parseClaudeTranscriptLine } from './parse-claude-transcript-line';
+import { writeATCBridge } from './write-atc-bridge';
 import { writeHookSettings } from './write-hook-settings';
 
 /**
@@ -37,6 +38,8 @@ export class GatewayAdapter implements AgentAdapter {
   // The gateway runs the Claude CLI, which writes the same transcript.
   readonly parseTranscriptLine = parseClaudeTranscriptLine;
 
+  readonly takesMessages = true;
+
   private readonly gateway: GatewayConfig;
 
   private readonly claude: ClaudeAdapter;
@@ -44,11 +47,18 @@ export class GatewayAdapter implements AgentAdapter {
   // Written on first spawn so constructing the adapter touches no state.
   private settingsFile: string | undefined;
 
+  // Written on first spawn so constructing the adapter touches no state.
+  private bridgeDir: string | undefined;
+
+  private readonly bridgeTarget: string | undefined;
+
   constructor(
     gateway: GatewayConfig,
     config: Config,
     headlessRunner: HeadlessRunner | null = null,
+    bridgeTarget?: string,
   ) {
+    this.bridgeTarget = bridgeTarget;
     this.gateway = gateway;
     this.id = gateway.id;
 
@@ -57,7 +67,11 @@ export class GatewayAdapter implements AgentAdapter {
     this.headlessRunner =
       headlessRunner === null
         ? null
-        : (opts, hooks) => headlessRunner({ ...opts, settings: this.writeSettings() }, hooks);
+        : (opts, hooks) =>
+            headlessRunner(
+              { ...opts, settings: this.writeSettings(), pluginDir: this.writeBridge() },
+              hooks,
+            );
   }
 
   planSpawn(opts: SpawnOptions): SpawnPlan {
@@ -67,6 +81,8 @@ export class GatewayAdapter implements AgentAdapter {
         ...this.gateway.args,
         '--settings',
         this.writeSettings(),
+        '--plugin-dir',
+        this.writeBridge(),
         ...(opts.resume === true ? ['--resume'] : []),
         ...(typeof opts.resume === 'string' ? ['--resume', opts.resume] : []),
         ...(opts.prompt === '' ? [] : [opts.prompt]),
@@ -108,4 +124,10 @@ export class GatewayAdapter implements AgentAdapter {
 
     return this.settingsFile;
   }
+
+  private writeBridge(): string {
+    this.bridgeDir ??= writeATCBridge(this.bridgeTarget);
+
+    return this.bridgeDir;
+  }
 }

package/src/agents/grok-adapter.ts

@@ -60,6 +60,8 @@ export class GrokAdapter implements AgentAdapter {
   // Grok's hooks are authoritative; no screen heuristics needed.
   readonly screenDetector = null;
 
+  readonly takesMessages = false;
+
   private readonly config: Config;
 
   private readonly hookState = new Map<SessionID, GrokSessionHookState>();

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

@@ -0,0 +1,42 @@
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { stateDir } from '../shared/config';
+import { ATC_BRIDGE_FILES } from './atc-bridge-files';
+import { buildCLIArgv } from './build-cli-argv';
+
+/**
+ * Writes the atc-bridge mod that every Claude session loads with
+ * `--plugin-dir`, with the atc command it runs rendered for this install,
+ * and returns its folder. A file whose content already matches is left
+ * untouched, since any write reloads the mod in every running session, and
+ * the folder is never cleared, since Claude Code keeps its own type files
+ * there.
+ */
+export function writeATCBridge(dir: string = join(stateDir, 'atc-bridge')): string {
+  const files = { ...ATC_BRIDGE_FILES, 'hooks/atc-cli.ts': renderATCCLIModule(buildCLIArgv()) };
+
+  for (const [path, content] of Object.entries(files)) {
+    const file = join(dir, path);
+
+    if (tryReadFileText(file) === content) {
+      continue;
+    }
+
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, content);
+  }
+
+  return dir;
+}
+
+function renderATCCLIModule(argv: readonly string[]): string {
+  return `export const ATC_CLI: readonly string[] = ${JSON.stringify(argv)};\n`;
+}
+
+function tryReadFileText(file: string): string | null {
+  try {
+    return readFileSync(file, 'utf8');
+  } catch {
+    return null;
+  }
+}

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

@@ -1,4 +1,4 @@
-import { readFileSync, writeFileSync } from 'node:fs';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { stateDir } from '../shared/config';
@@ -14,6 +14,7 @@ export function writeHookSettings(profile: HookSettingsProfile): string {
   const file = join(stateDir, `hook-settings-${profile.id}.json`);
   const settings = buildHookSettings(profile, readStatuslinePadding());
 
+  mkdirSync(stateDir, { recursive: true });
   writeFileSync(file, JSON.stringify(settings, null, 2));
 
   return file;

package/src/cli.ts

@@ -63,6 +63,10 @@ const main = defineCommand({
           const restoreBootTimeoutMs =
             Number.isFinite(capOverride) && capOverride >= 0 ? capOverride : 15_000;
 
+          // How long a started session may go without a tap before a message
+          // to it is refused. Tests pin it to 0 to reach the refusal at once.
+          const graceOverride = Number(process.env['ATC_TAP_GRACE_MS']);
+
           const claudeAdapter = new claude.ClaudeAdapter(cfg, (runOpts, hooks) =>
             headless.startHeadlessRun({ ...runOpts, claudeBin: cfg.claudeBin }, hooks),
           );
@@ -89,6 +93,9 @@ const main = defineCommand({
             pidPath: config.daemonPidFile,
             hooks: cfg.hooks,
             restoreBootTimeoutMs,
+            ...(Number.isFinite(graceOverride) && graceOverride >= 0
+              ? { tapGraceMs: graceOverride }
+              : {}),
             ...(Number.isFinite(queueBytes) && queueBytes > 0 ? { queueBytes } : {}),
             onQuit: () => process.exit(0),
           });
@@ -152,6 +159,50 @@ const main = defineCommand({
           await reporter.runHookReport();
         },
       }),
+    tap: () =>
+      defineCommand({
+        meta: {
+          name: 'tap',
+          description: "Stream a session's inbox to stdout as NDJSON, acking each message",
+        },
+        args: {
+          session: {
+            type: 'string',
+            required: true,
+            description: 'The atc session id to tap',
+          },
+        },
+        async run(ctx) {
+          const tap = await import('./tap');
+
+          await tap.runTap(ctx.args.session);
+        },
+      }),
+    report: () =>
+      defineCommand({
+        meta: {
+          name: 'report',
+          description:
+            'Report a message answer or a note from a wrangled session to the atc socket',
+          hidden: true,
+        },
+
+        // No arg is required: a citty usage error exits nonzero, and
+        // reporters must always exit 0.
+        args: {
+          kind: { type: 'positional', required: false, default: '' },
+          message: { type: 'string', default: '' },
+          label: { type: 'string', default: '' },
+        },
+        async run(ctx) {
+          const reporter = await import('./report');
+
+          await reporter.runReport(ctx.args.kind, {
+            message: ctx.args.message,
+            label: ctx.args.label,
+          });
+        },
+      }),
     statusline: () =>
       defineCommand({
         meta: {

package/src/client/daemon-client.ts

@@ -16,10 +16,14 @@ interface Pending {
 export class DaemonClient {
   onEvent: (event: EventMsg) => void = () => {};
 
+  onClose: () => void = () => {};
+
   private queue: OutboundQueue | null = null;
 
   private buffer = '';
 
+  private readonly decoder = new TextDecoder();
+
   private nextID = 1;
 
   private readonly pending = new Map<number, Pending>();
@@ -33,13 +37,14 @@ export class DaemonClient {
       unix: socketPath,
       socket: {
         data(_s, buf) {
-          client.applyChunk(buf.toString());
+          client.applyChunk(client.decodeChunk(buf));
         },
         drain() {
           client.queue?.drain();
         },
         close() {
           client.drainPending('connection closed');
+          client.onClose();
         },
         error() {},
       },
@@ -74,6 +79,13 @@ export class DaemonClient {
     this.drainPending('client closed');
   }
 
+  // Decodes with state kept across reads, so a multi-byte character split
+  // between two reads decodes whole.
+  // oxlint-disable-next-line prefer-readonly-parameter-types -- a socket read buffer has no readonly form
+  private decodeChunk(buf: Uint8Array): string {
+    return this.decoder.decode(buf, { stream: true });
+  }
+
   private applyChunk(chunk: string): void {
     this.buffer += chunk;
 

package/src/daemon/answer-byte-cap.ts

@@ -0,0 +1 @@
+export const ANSWER_BYTE_CAP = 65_536;

package/src/daemon/build-headless-env.ts

@@ -0,0 +1,23 @@
+import { collectCleanEnv } from '../shared/collect-clean-env';
+import type { SessionID } from '../shared/session-id';
+
+interface HeadlessEnvParams {
+  readonly pluginDir?: string;
+  readonly sessionID?: SessionID;
+  readonly socketPath: string;
+}
+
+/**
+ * The clean process environment for a headless run, plus what the atc-bridge
+ * mod needs to find its session: the mod folder to load and the session and
+ * reporter socket it taps. A run without a session id carries none of them,
+ * since the mod stays off outside atc.
+ */
+export function buildHeadlessEnv(params: HeadlessEnvParams): Record<string, string> {
+  return collectCleanEnv({
+    ...(params.pluginDir === undefined ? {} : { CLAUDE_CODE_PLUGIN_DIRS: params.pluginDir }),
+    ...(params.sessionID === undefined
+      ? {}
+      : { ATC_SESSION_ID: params.sessionID, ATC_SOCKET: params.socketPath }),
+  });
+}

package/src/daemon/build-session-message-event.ts

@@ -0,0 +1,29 @@
+import { truncateDetail } from '../agents/truncate-detail';
+import { PROTOCOL_V } from '../protocol/protocol';
+import type { EventMsg } from '../protocol/protocol';
+import type { SessionID } from '../shared/session-id';
+import type { MessageRecord } from '../store/message-record';
+
+/**
+ * The `SessionMessage` event for one message status change, addressed by
+ * the atc session id the message currently belongs to. The event carries
+ * short previews of the text and answer, never the full content, so a
+ * broadcast stays small; `message.get` returns the full message. Delivery
+ * and answer fields appear only once they are set.
+ */
+// oxlint-disable-next-line prefer-readonly-parameter-types -- every field is readonly; the branded id has no readonly form to wrap it in
+export function buildSessionMessageEvent(sessionID: SessionID, record: MessageRecord): EventMsg {
+  return {
+    v: PROTOCOL_V,
+    ev: 'SessionMessage',
+    s: sessionID,
+    message: record.id,
+    status: record.status,
+    from: record.from,
+    textPreview: truncateDetail(record.text),
+    sentAt: record.sentAt,
+    ...(record.deliveredAt === undefined ? {} : { deliveredAt: record.deliveredAt }),
+    ...(record.answeredAt === undefined ? {} : { answeredAt: record.answeredAt }),
+    ...(record.answer === undefined ? {} : { answerPreview: truncateDetail(record.answer) }),
+  };
+}

package/src/daemon/build-session-report-event.ts

@@ -0,0 +1,24 @@
+import { PROTOCOL_V } from '../protocol/protocol';
+import type { EventMsg } from '../protocol/protocol';
+import type { SessionID } from '../shared/session-id';
+import type { NoteReport } from './parse-report';
+
+/**
+ * The `SessionReport` event for a note an agent sent mid-turn, addressed by
+ * the atc session that sent it. The note's label travels as the event's
+ * `kind`.
+ */
+export function buildSessionReportEvent(
+  sessionID: SessionID,
+  report: NoteReport,
+  reportedAt: number,
+): EventMsg {
+  return {
+    v: PROTOCOL_V,
+    ev: 'SessionReport',
+    s: sessionID,
+    kind: report.label,
+    text: report.text,
+    reportedAt,
+  };
+}