@zgeoff/atc 2.7.0 → 2.8.1

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.7.0",
+  "version": "2.8.1",
   "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 {

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    '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",
+};

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
@@ -54,9 +55,19 @@ export class ClaudeAdapter implements AgentAdapter {
   // 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 {
@@ -68,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]),
@@ -75,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/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';
 
 /**
@@ -46,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;
 
@@ -59,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 {
@@ -69,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]),
@@ -110,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/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

@@ -182,20 +182,25 @@ const main = defineCommand({
       defineCommand({
         meta: {
           name: 'report',
-          description: 'Report a message event from a wrangled session to the atc socket',
+          description:
+            'Report a message answer or a note from a wrangled session to the atc socket',
           hidden: true,
         },
 
-        // Neither arg is required: a citty usage error exits nonzero, and
+        // 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, ctx.args.message);
+          await reporter.runReport(ctx.args.kind, {
+            message: ctx.args.message,
+            label: ctx.args.label,
+          });
         },
       }),
     statusline: () =>

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-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,
+  };
+}

package/src/daemon/daemon-connection.ts

@@ -165,6 +165,13 @@ export class DaemonConnection {
     this.queue = new OutboundQueue(peer, ctx.queueBytes);
   }
 
+  /**
+   * Ends the connection. Safe to call more than once.
+   */
+  dispose(): void {
+    this.peer.end();
+  }
+
   sendEvent(event: EventMsg): void {
     if (this.helloed && !this.queue.send(encodeMessage(event))) {
       this.peer.end();

package/src/daemon/daemon.ts

@@ -13,6 +13,7 @@ import { AttachRegistry } from './attach-registry';
 import { buildFleetEvents } from './build-fleet-events';
 import { buildSessionEvent } from './build-session-event';
 import { buildSessionMessageEvent } from './build-session-message-event';
+import { buildSessionReportEvent } from './build-session-report-event';
 import { DaemonConnection } from './daemon-connection';
 import type { DaemonContext, OutputClient, TapClient } from './daemon-connection';
 import { EventSignal } from './event-signal';
@@ -236,6 +237,18 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
       return;
     }
 
+    if (report.kind === 'note') {
+      const sender = mgr.sessions.find((x) => x.id === e.atcId);
+
+      if (sender !== undefined) {
+        const capped = { ...report, text: truncateToBytes(report.text, ANSWER_BYTE_CAP) };
+
+        emitEvent(buildSessionReportEvent(sender.id, capped, Date.now()), findHookScope(sender.id));
+      }
+
+      return;
+    }
+
     const s = mgr.sessions.find((x) => x.id === e.atcId);
     const owner = s === undefined ? { atcID: e.atcId } : buildMessageOwner(s);
 
@@ -974,6 +987,12 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
   });
 
   stopDaemon = async () => {
+    // Ends each client itself so every peer sees the close: a stopped
+    // listener does not reliably end the connections it already accepted.
+    for (const client of clients) {
+      client.dispose();
+    }
+
     server.stop(true);
     eventsServer?.stop();
     reporter.stop(true);

package/src/daemon/parse-report.ts

@@ -1,20 +1,25 @@
 import { z } from 'zod';
 import type { MessageID } from '../shared/message-id';
-import { REPORT_KINDS } from '../shared/report-kinds';
-import type { ReportKind } from '../shared/report-kinds';
 import { toMessageID } from '../shared/to-message-id';
 
-export interface Report {
-  readonly kind: ReportKind;
+interface AnsweredReport {
+  readonly kind: 'answered';
   readonly message: MessageID;
   readonly answer: string;
 }
 
-const REPORT_SCHEMA = z.object({
-  kind: z.enum(REPORT_KINDS),
-  message: z.string().min(1),
-  answer: z.string(),
-});
+export interface NoteReport {
+  readonly kind: 'note';
+  readonly label: string;
+  readonly text: string;
+}
+
+export type Report = AnsweredReport | NoteReport;
+
+const REPORT_SCHEMA = z.discriminatedUnion('kind', [
+  z.object({ kind: z.literal('answered'), message: z.string().min(1), answer: z.string() }),
+  z.object({ kind: z.literal('note'), label: z.string().min(1).max(64), text: z.string().min(1) }),
+]);
 
 /**
  * Parses a Report envelope's payload into the report its kind discriminates,
@@ -27,8 +32,12 @@ export function parseReport(payload: Readonly<Record<string, unknown>>): Report
     return null;
   }
 
+  if (parsed.data.kind === 'note') {
+    return { kind: 'note', label: parsed.data.label, text: parsed.data.text };
+  }
+
   return {
-    kind: parsed.data.kind,
+    kind: 'answered',
     message: toMessageID(parsed.data.message),
     answer: parsed.data.answer,
   };

package/src/daemon/start-headless-run.ts

@@ -1,8 +1,10 @@
 import { query } from '@anthropic-ai/claude-agent-sdk';
 import type { AgentSessionID } from '../shared/agent-session-id';
-import { collectCleanEnv } from '../shared/collect-clean-env';
+import { socketPath } from '../shared/config';
 import { isCompiledBinary } from '../shared/is-compiled-binary';
 import { isRecord } from '../shared/report';
+import type { SessionID } from '../shared/session-id';
+import { buildHeadlessEnv } from './build-headless-env';
 import { resolveHeadlessExecutable } from './resolve-headless-executable';
 
 const PERMISSION_MODES = [
@@ -21,6 +23,8 @@ interface HeadlessRunOptions {
   readonly resume?: AgentSessionID;
   readonly permissionMode?: string;
   readonly settings?: string;
+  readonly sessionID?: SessionID;
+  readonly pluginDir?: string;
 }
 
 interface HeadlessRunHooks {
@@ -54,7 +58,11 @@ export function startHeadlessRun(
         prompt: opts.prompt,
         options: {
           cwd: opts.cwd,
-          env: collectCleanEnv(),
+          env: buildHeadlessEnv({
+            socketPath,
+            ...(opts.pluginDir === undefined ? {} : { pluginDir: opts.pluginDir }),
+            ...(opts.sessionID === undefined ? {} : { sessionID: opts.sessionID }),
+          }),
           abortController: controller,
           stderr: (data: string) => {
             stderrTail = `${stderrTail}${data}`.slice(-2000);

package/src/daemon/start-headless-turn.ts

@@ -31,6 +31,7 @@ export function startHeadlessTurn(
       prompt,
       ...(s.agentSessionID === undefined ? {} : { resume: s.agentSessionID }),
       permissionMode: 'auto',
+      sessionID,
     },
     {
       onOutput: (text) => {

package/src/mcp-server.ts

@@ -190,7 +190,7 @@ const TOOLS: readonly MCPTool[] = [
   {
     name: 'atc_session_message',
     description:
-      "Send a session a message and get its id back; poll atc_message_get with the id for its status and answer. The message waits in the session inbox until the session takes it, and its status moves accepted, delivered, answered. A message is refused as unsupported when the session's agent has no message tap (Grok, Codex), or when a Claude session reported SessionStart more than 15 seconds ago and no tap has attached since. It is refused as session_dead when the session has no live process and as no_such_session for an unknown id. Otherwise it queues, including while a session restores or after its tap dropped. The message is never typed into the terminal.",
+      "Send a session a message and get its id back. Follow up by polling atc_message_get with the id until its status is answered, which returns the session's final reply; don't read the session's screen or transcript to check on it. The message waits in the session inbox until the session takes it, and its status moves accepted, delivered, answered. A message is refused as unsupported when the session's agent has no message tap (Grok, Codex), or when a Claude session reported SessionStart more than 15 seconds ago and no tap has attached since. It is refused as session_dead when the session has no live process and as no_such_session for an unknown id. Otherwise it queues, including while a session restores or after its tap dropped. The message is never typed into the terminal.",
     inputSchema: {
       type: 'object',
       properties: {

package/src/report.ts

@@ -1,13 +1,19 @@
 import { sendReport } from './shared/report';
 import { REPORT_KINDS } from './shared/report-kinds';
 
+interface ReportOptions {
+  readonly message: string;
+  readonly label: string;
+}
+
 /**
- * Runs inside wrangled sessions: reads the final text from stdin verbatim
- * and forwards it to the atc socket as a Report envelope of the given kind
- * for the given message. Always exits 0 so it never blocks the session it
- * reports on.
+ * Runs inside wrangled sessions: reads stdin verbatim and forwards it to the
+ * atc socket as a Report envelope of the given kind. An `answered` report
+ * carries stdin as the final text for the given message; a `note` carries
+ * it as text for the user under the given label, `progress` when none is
+ * given. Always exits 0 so it never blocks the session it reports on.
  */
-export async function runReport(kind: string, message: string): Promise<void> {
+export async function runReport(kind: string, options: ReportOptions): Promise<void> {
   try {
     const sock = process.env['ATC_SOCKET'];
     const atcId = process.env['ATC_SESSION_ID'];
@@ -17,16 +23,37 @@ export async function runReport(kind: string, message: string): Promise<void> {
       sock !== '' &&
       atcId !== undefined &&
       atcId !== '' &&
-      REPORT_KINDS.some((known) => known === kind) &&
-      message !== ''
+      REPORT_KINDS.some((known) => known === kind)
     ) {
-      const answer = await new Response(Bun.stdin.stream()).text();
+      const stdin = await new Response(Bun.stdin.stream()).text();
 
-      const line = `${JSON.stringify({ atcId, event: 'Report', payload: { kind, message, answer } })}\n`;
+      const payload = buildReportPayload(kind, options, stdin);
 
-      await sendReport(sock, line, 2000);
+      if (payload !== null) {
+        const line = `${JSON.stringify({ atcId, event: 'Report', payload })}\n`;
+
+        await sendReport(sock, line, 2000);
+      }
     }
   } catch {}
 
   process.exit(0);
 }
+
+function buildReportPayload(
+  kind: string,
+  options: ReportOptions,
+  stdin: string,
+): Record<string, string> | null {
+  if (kind === 'answered') {
+    return options.message === '' ? null : { kind, message: options.message, answer: stdin };
+  }
+
+  if (kind === 'note') {
+    return stdin.trim() === ''
+      ? null
+      : { kind, label: options.label === '' ? 'progress' : options.label, text: stdin };
+  }
+
+  return null;
+}

package/src/shared/report-kinds.ts

@@ -1,3 +1 @@
-export const REPORT_KINDS = ['answered'] as const;
-
-export type ReportKind = (typeof REPORT_KINDS)[number];
+export const REPORT_KINDS = ['answered', 'note'] as const;