@zooid/acp-client 0.7.0 → 0.7.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zooid/acp-client",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "Zooid's ACP client: spawn agent subprocesses, drive them via Agent Client Protocol, route events and permission requests through callbacks.",
   "type": "module",
   "license": "MIT",

package/src/acp-client.tap.test.ts

@@ -2,7 +2,9 @@ import { describe, expect, it, vi } from 'vitest'
 import { EventEmitter } from 'node:events'
 import { Readable, Writable } from 'node:stream'
 import type { ChildProcess } from 'node:child_process'
+import { RequestError } from '@agentclientprotocol/sdk'
 import { AcpClient } from './acp-client.js'
+import type { TapEvent } from './turn-tracker.js'
 
 class FakeChild extends EventEmitter {
   stdout = new Readable({ read() {} })
@@ -34,3 +36,66 @@ describe('AcpClient onTap', () => {
     }).not.toThrow()
   })
 })
+
+describe('AcpClient — error TapEvent emission', () => {
+  function makeClient(onTap: (e: TapEvent) => void) {
+    const child = new FakeChild() as unknown as ChildProcess
+    const rt = { spawn: vi.fn().mockReturnValue(child) }
+    const client = new AcpClient({
+      agent: { id: 'alice', command: 'foo', args: [] },
+      onEvent: () => {},
+      onApprovalRequest: async () => ({ decision: 'cancel' }),
+      runtime: rt,
+      onTap,
+    })
+    return client
+  }
+
+  it('emits {kind:"error",...} when prompt throws a RequestError', async () => {
+    const seen: TapEvent[] = []
+    const client = makeClient((e) => seen.push(e))
+
+    const fakeConn = {
+      newSession: vi.fn().mockResolvedValue({ sessionId: 'sess-1' }),
+      prompt: vi.fn().mockRejectedValue(
+        new RequestError(-32000, 'Authentication required', undefined),
+      ),
+      loadSession: vi.fn(),
+    }
+    ;(client as unknown as Record<string, unknown>).connection = fakeConn
+    ;(client as unknown as Record<string, unknown>).initialized = true
+
+    await expect(
+      client.prompt({ threadId: 'thread-1', content: [{ type: 'text', text: 'hi' }] }),
+    ).rejects.toThrow()
+
+    const errEvt = seen.find((e) => e.kind === 'error')
+    expect(errEvt).toBeDefined()
+    expect(errEvt!.code).toBe('auth_missing')
+    expect(errEvt!.acp_error).toMatchObject({ code: -32000, message: 'Authentication required' })
+    expect(errEvt!.sessionId).toBe('sess-1')
+    expect(errEvt!.turnId).not.toBeNull()
+  })
+
+  it('emits with sessionId=null when ensureSession throws (newSession failure)', async () => {
+    const seen: TapEvent[] = []
+    const client = makeClient((e) => seen.push(e))
+
+    const fakeConn = {
+      newSession: vi.fn().mockRejectedValue(new Error('ACP connection closed')),
+      prompt: vi.fn(),
+      loadSession: vi.fn(),
+    }
+    ;(client as unknown as Record<string, unknown>).connection = fakeConn
+    ;(client as unknown as Record<string, unknown>).initialized = true
+
+    await expect(
+      client.prompt({ threadId: 'thread-1', content: [{ type: 'text', text: 'hi' }] }),
+    ).rejects.toThrow()
+
+    const errEvt = seen.find((e) => e.kind === 'error')
+    expect(errEvt).toBeDefined()
+    expect(errEvt!.sessionId).toBeNull()
+    expect(errEvt!.code).toBe('container_exit')
+  })
+})

package/src/acp-client.ts

@@ -16,6 +16,7 @@ import {
   approvalDecisionToPermissionResponse,
 } from './event-mapping.js'
 import { TurnTracker, type TapEvent } from './turn-tracker.js'
+import { classify } from './errors.js'
 import type {
   AgentConfig,
   AgentEvent,
@@ -37,6 +38,8 @@ export interface SpawnRuntime {
     cwd?: string
     /** Container image. Honoured by container runtimes; ignored by local spawners. */
     image?: string
+    /** Bind mounts. Honoured by container runtimes; ignored by local spawners. */
+    mounts?: Array<{ path: string; target: string; mode: 'ro' | 'rw' }>
   }): ChildProcess
 }
 
@@ -108,6 +111,7 @@ export class AcpClient {
         env: this.options.agent.env,
         cwd: this.options.agent.cwd,
         image: this.options.agent.image,
+        mounts: this.options.agent.mounts,
       })
       this.runtimeChild = child
       if (!child.stdout || !child.stdin) {
@@ -253,11 +257,13 @@ export class AcpClient {
   }
 
   async prompt(input: PromptInput): Promise<PromptResult> {
-    const sessionId = await this.ensureSession(input.threadId, input.channelId)
-    const promptText = stringifyPromptForLog(input.content)
-    this.turns?.startTurn({ sessionId, promptText })
-    debugLog(this.options.agent.id, 'prompt →', { sessionId, content: input.content })
+    let sessionId: string | null = null
+    let turnId: string | null = null
     try {
+      sessionId = await this.ensureSession(input.threadId, input.channelId)
+      const promptText = stringifyPromptForLog(input.content)
+      turnId = this.turns?.startTurn({ sessionId, promptText }) ?? null
+      debugLog(this.options.agent.id, 'prompt →', { sessionId, content: input.content })
       const result = await this.connection!.prompt({
         sessionId,
         prompt: input.content,
@@ -266,7 +272,19 @@ export class AcpClient {
       debugLog(this.options.agent.id, 'prompt ←', { sessionId, stopReason: result.stopReason })
       return { stopReason: result.stopReason }
     } catch (err) {
-      this.turns?.endTurn({ sessionId, stopReason: 'error' })
+      const c = classify(err)
+      this.options.onTap?.({
+        kind: 'error',
+        agentId: this.options.agent.id,
+        sessionId,
+        turnId,
+        code: c.code,
+        message: err instanceof Error ? err.message : String(err),
+        detail: err instanceof Error && err.stack ? err.stack.slice(0, 2000) : undefined,
+        transient: c.transient,
+        acp_error: c.acp_error,
+      })
+      if (sessionId) this.turns?.endTurn({ sessionId, stopReason: 'error' })
       throw err
     }
   }

package/src/errors.test.ts

@@ -0,0 +1,101 @@
+import { describe, it, expect } from 'vitest'
+import { RequestError } from '@agentclientprotocol/sdk'
+import { classify } from './errors.js'
+
+describe('classify — RequestError', () => {
+  it('claude-agent-acp -32000 "Authentication required" → auth_missing', () => {
+    const err = new RequestError(-32000, 'Authentication required', undefined)
+    const r = classify(err)
+    expect(r.code).toBe('auth_missing')
+    expect(r.transient).toBe(false)
+    expect(r.acp_error).toEqual({
+      code: -32000,
+      message: 'Authentication required',
+      data: undefined,
+    })
+  })
+
+  it('-32002 (spec-compliant authRequired) → auth_missing', () => {
+    const err = RequestError.authRequired()
+    expect(classify(err).code).toBe('auth_missing')
+  })
+
+  it('invalid/expired/revoked credential → auth_invalid', () => {
+    expect(classify(new RequestError(-32000, 'API key invalid')).code).toBe('auth_invalid')
+    expect(classify(new RequestError(-32000, 'token expired')).code).toBe('auth_invalid')
+    expect(classify(new RequestError(-32000, 'credential revoked')).code).toBe('auth_invalid')
+  })
+
+  it('rate limit → model_rate_limit (transient)', () => {
+    const r = classify(new RequestError(-32000, 'rate limit exceeded'))
+    expect(r.code).toBe('model_rate_limit')
+    expect(r.transient).toBe(true)
+  })
+
+  it('5xx / overloaded / unknown model → model_unavailable (transient)', () => {
+    expect(classify(new RequestError(-32000, 'upstream 503')).code).toBe('model_unavailable')
+    expect(classify(new RequestError(-32000, 'service overloaded')).code).toBe('model_unavailable')
+    expect(classify(new RequestError(-32000, 'unknown model claude-5')).code).toBe('model_unavailable')
+  })
+
+  it('JSON-RPC standard codes → acp_protocol', () => {
+    for (const code of [-32700, -32600, -32601, -32602]) {
+      expect(classify(new RequestError(code, 'malformed')).code).toBe('acp_protocol')
+    }
+  })
+
+  it('-32603 (internal JSON-RPC error) → internal', () => {
+    expect(classify(new RequestError(-32603, 'internal')).code).toBe('internal')
+  })
+
+  it('preserves acp_error verbatim including data', () => {
+    const err = new RequestError(-32000, 'something', { trace: 'abc' })
+    expect(classify(err).acp_error).toEqual({
+      code: -32000,
+      message: 'something',
+      data: { trace: 'abc' },
+    })
+  })
+
+  it('unmatched -32000…-32099 message → internal (not auth-mis-fire)', () => {
+    expect(classify(new RequestError(-32000, 'gobbledygook')).code).toBe('internal')
+  })
+})
+
+describe('classify — out-of-band errors', () => {
+  it('mount-failed engine error → mount_failed (non-transient)', () => {
+    const err = new Error(
+      "docker: Error response from daemon: error while creating mount source path '/home/zooid/.codex': mkdir /home/zooid/.codex: permission denied",
+    )
+    const r = classify(err)
+    expect(r.code).toBe('mount_failed')
+    expect(r.transient).toBe(false)
+    expect(r.acp_error).toBeUndefined()
+  })
+
+  it('image pull failure → image_pull_failed (transient)', () => {
+    const err = new Error(
+      'image prepull failed for ghcr.io/zooid-ai/agent-codex:latest:\nmanifest unknown',
+    )
+    expect(classify(err).code).toBe('image_pull_failed')
+    expect(classify(err).transient).toBe(true)
+  })
+
+  it('ACP stream closed → container_exit (transient)', () => {
+    const err = new Error('ACP connection closed')
+    expect(classify(err).code).toBe('container_exit')
+    expect(classify(err).transient).toBe(true)
+  })
+
+  it('unmatched error → internal with String(err) preserved', () => {
+    const r = classify(new Error('weird thing happened'))
+    expect(r.code).toBe('internal')
+    expect(r.transient).toBe(false)
+  })
+
+  it('non-Error thrown value → internal', () => {
+    expect(classify('a bare string').code).toBe('internal')
+    expect(classify(null).code).toBe('internal')
+    expect(classify(undefined).code).toBe('internal')
+  })
+})

package/src/errors.ts

@@ -0,0 +1,63 @@
+import { RequestError } from '@agentclientprotocol/sdk'
+
+export type ErrorCode =
+  | 'auth_missing'
+  | 'auth_invalid'
+  | 'model_rate_limit'
+  | 'model_unavailable'
+  | 'image_pull_failed'
+  | 'mount_failed'
+  | 'container_exit'
+  | 'acp_protocol'
+  | 'permission_denied'
+  | 'internal'
+
+export interface Classified {
+  code: ErrorCode
+  transient: boolean
+  /** Verbatim ACP RequestError triple — forwarded into eco.zoon.error.acp_error. */
+  acp_error?: { code: number; message: string; data?: unknown }
+}
+
+const PROTOCOL_CODES = new Set([-32700, -32600, -32601, -32602])
+
+export function classify(err: unknown): Classified {
+  if (err instanceof RequestError) {
+    const acp_error = { code: err.code, message: err.message, data: err.data }
+    if (PROTOCOL_CODES.has(err.code)) return { code: 'acp_protocol', transient: false, acp_error }
+    if (err.code === -32603) return { code: 'internal', transient: false, acp_error }
+    // -32002 (spec authRequired) → auth_missing
+    if (err.code === -32002) return { code: 'auth_missing', transient: false, acp_error }
+    // -32000…-32099 generic: classify by message
+    const m = err.message
+    if (/^auth(entication)? required$/i.test(m)) {
+      return { code: 'auth_missing', transient: false, acp_error }
+    }
+    if (/\b(token|api ?key|credential)\b/i.test(m) && /\b(invalid|expired|revoked)\b/i.test(m)) {
+      return { code: 'auth_invalid', transient: false, acp_error }
+    }
+    if (/\brate ?limit\b|\b429\b/i.test(m)) {
+      return { code: 'model_rate_limit', transient: true, acp_error }
+    }
+    if (/\b5\d\d\b|\boverloaded\b|\bunavailable\b|\bunknown model\b/i.test(m)) {
+      return { code: 'model_unavailable', transient: true, acp_error }
+    }
+    return { code: 'internal', transient: false, acp_error }
+  }
+
+  // Out-of-band errors (no RequestError → no acp_error).
+  if (err instanceof Error) {
+    const m = err.message
+    if (/error while creating mount source path|mkdir .* permission denied/i.test(m)) {
+      return { code: 'mount_failed', transient: false }
+    }
+    if (/^image prepull failed/i.test(m)) {
+      return { code: 'image_pull_failed', transient: true }
+    }
+    if (/ACP connection closed/i.test(m)) {
+      return { code: 'container_exit', transient: true }
+    }
+  }
+
+  return { code: 'internal', transient: false }
+}

package/src/index.ts

@@ -2,7 +2,12 @@ export { AcpClient } from './acp-client.js'
 export { AgentProcess } from './agent-process.js'
 export { SessionMap } from './session-map.js'
 export { PRESETS, resolvePreset, isPreset } from './presets.js'
-export type { PresetName, PresetSpec } from './presets.js'
+export type {
+  PresetName,
+  PresetSpec,
+  PresetMount,
+  PresetMountContext,
+} from './presets.js'
 export {
   acpUpdateToAgentEvent,
   approvalDecisionToPermissionResponse,
@@ -23,3 +28,5 @@ export type { SessionKey, SessionRecord } from './session-map.js'
 export type { AcpClientOptions } from './acp-client.js'
 export { TurnTracker } from './turn-tracker.js'
 export type { TapEvent, SessionUpdate, TurnTrackerOpts } from './turn-tracker.js'
+export { classify } from './errors.js'
+export type { ErrorCode, Classified } from './errors.js'

package/src/presets.mounts.test.ts

@@ -0,0 +1,82 @@
+import { describe, it, expect } from 'vitest'
+import { PRESETS } from './presets.js'
+
+const ctx = {
+  agentName: 'alice',
+  agentDataDir: '/data/agents/alice',
+  containerWorkdir: '/workspace',
+  daemonHome: '/home/zooid',
+}
+
+describe('preset mount declarations — home / data / config', () => {
+  it('claude declares a single `home` mount at ${daemonHome}/.claude', () => {
+    const mounts = PRESETS.claude.mounts!(ctx)
+    expect(mounts).toHaveLength(1)
+    expect(mounts[0]).toMatchObject({
+      id: 'home',
+      host: '/home/zooid/.claude',
+      target: '/root/.claude',
+      mode: 'rw',
+      create: false,
+    })
+  })
+
+  it('codex declares a single `home` mount at ${daemonHome}/.codex', () => {
+    const mounts = PRESETS.codex.mounts!(ctx)
+    expect(mounts).toHaveLength(1)
+    expect(mounts[0]).toMatchObject({
+      id: 'home',
+      host: '/home/zooid/.codex',
+      target: '/root/.codex',
+      mode: 'rw',
+      create: false,
+    })
+  })
+
+  it('opencode declares `data` + `config` from XDG dirs', () => {
+    const mounts = PRESETS.opencode.mounts!(ctx)
+    const byId = Object.fromEntries(mounts.map((m) => [m.id, m]))
+    expect(Object.keys(byId).sort()).toEqual(['config', 'data'])
+    expect(byId.data).toMatchObject({
+      host: '/home/zooid/.local/share/opencode',
+      target: '/root/.local/share/opencode',
+      mode: 'rw',
+      create: false,
+    })
+    expect(byId.config).toMatchObject({
+      host: '/home/zooid/.config/opencode',
+      target: '/root/.config/opencode',
+      mode: 'rw',
+      create: false,
+    })
+  })
+
+  it('preset mounts do not reference `ctx.agentDataDir` (per-agent isolation is opt-in via user mounts)', () => {
+    const claudeMounts = PRESETS.claude.mounts!(ctx)
+    const codexMounts = PRESETS.codex.mounts!(ctx)
+    const opencodeMounts = PRESETS.opencode.mounts!(ctx)
+    for (const m of [...claudeMounts, ...codexMounts, ...opencodeMounts]) {
+      expect(m.host).not.toContain('/data/agents/alice')
+    }
+  })
+
+  it('cline / kiro / gemini have no preset-declared mounts', () => {
+    expect(PRESETS.cline.mounts?.(ctx) ?? []).toEqual([])
+    expect(PRESETS.kiro.mounts?.(ctx) ?? []).toEqual([])
+    expect(PRESETS.gemini.mounts?.(ctx) ?? []).toEqual([])
+  })
+})
+
+describe('preset default images (unchanged from cycle 1)', () => {
+  it('claude, codex, opencode declare a default ghcr image', () => {
+    expect(PRESETS.claude.image).toBe('ghcr.io/zooid-ai/agent-claude-code:latest')
+    expect(PRESETS.codex.image).toBe('ghcr.io/zooid-ai/agent-codex:latest')
+    expect(PRESETS.opencode.image).toBe('ghcr.io/zooid-ai/agent-opencode:latest')
+  })
+
+  it('cline / kiro / gemini declare no default image', () => {
+    expect(PRESETS.cline.image).toBeUndefined()
+    expect(PRESETS.kiro.image).toBeUndefined()
+    expect(PRESETS.gemini.image).toBeUndefined()
+  })
+})

package/src/presets.test.ts

@@ -3,20 +3,20 @@ import { PRESETS, resolvePreset, isPreset } from './presets.js'
 
 describe('PRESETS registry', () => {
   it('includes the ACP-native harnesses from SPEC.md', () => {
-    expect(PRESETS.opencode).toEqual({ command: 'opencode', args: ['acp'] })
-    expect(PRESETS.cline).toEqual({ command: 'cline', args: ['--acp'] })
-    expect(PRESETS.kiro).toEqual({ command: 'kiro', args: ['--acp'] })
-    expect(PRESETS.gemini).toEqual({ command: 'gemini', args: ['--acp'] })
+    expect(PRESETS.opencode).toMatchObject({ command: 'opencode', args: ['acp'] })
+    expect(PRESETS.cline).toMatchObject({ command: 'cline', args: ['--acp'] })
+    expect(PRESETS.kiro).toMatchObject({ command: 'kiro', args: ['--acp'] })
+    expect(PRESETS.gemini).toMatchObject({ command: 'gemini', args: ['--acp'] })
   })
 
   it('includes the vendored-shim harnesses', () => {
-    expect(PRESETS.claude).toEqual({
+    expect(PRESETS.claude).toMatchObject({
       command: 'npx',
       args: ['-y', '@agentclientprotocol/claude-agent-acp'],
     })
-    expect(PRESETS.codex).toEqual({
+    expect(PRESETS.codex).toMatchObject({
       command: 'npx',
-      args: ['-y', '@zed-industries/codex-acp'],
+      args: ['-y', '@zed-industries/codex-acp', '-c', 'web_search="live"'],
     })
   })
 })
@@ -62,13 +62,15 @@ describe('resolvePreset', () => {
     ])
   })
 
-  it('appends --model <id> to codex when opts.model is set', () => {
+  it('passes model to codex via `-c model="..."` (codex-acp uses TOML config overrides)', () => {
     const spec = resolvePreset('codex', { model: 'gpt-5.5' })
     expect(spec.args).toEqual([
       '-y',
       '@zed-industries/codex-acp',
-      '--model',
-      'gpt-5.5',
+      '-c',
+      'web_search="live"',
+      '-c',
+      'model="gpt-5.5"',
     ])
   })
 

package/src/presets.ts

@@ -7,28 +7,116 @@
 //
 // See epics/002-ZOD019-acp-runtime/SPEC.md §"Agent compatibility matrix".
 
+export interface PresetMountContext {
+  agentName: string
+  /** Per-agent host state root (`<dataDir>/agents/<agentName>`). Kept on the
+   *  context for forward compatibility — v1 default declarations don't use
+   *  it, but presets that opt into per-agent isolation can. */
+  agentDataDir: string
+  /** Resolved container working directory, e.g. `/workspace`. */
+  containerWorkdir: string
+  /** Daemon user's `$HOME`. Source of `~/.<preset>` for the v1 `home` /
+   *  `data` / `config` defaults. Threaded from `buildAcpRegistry` so tests
+   *  can inject without mutating `process.env.HOME`. */
+  daemonHome: string
+}
+
+export interface PresetMount {
+  id: string
+  host: string
+  target: string
+  mode: 'ro' | 'rw'
+  create?: boolean
+}
+
 export interface PresetSpec {
   command: string
   args: string[]
+  /**
+   * Default container image for this preset. Last fallback in the
+   * `buildAcpRegistry` image-resolution chain (agent > workforce > preset).
+   * Omit when no first-party image is published yet.
+   */
+  image?: string
+  /**
+   * Canonical-id mounts this preset wants set up. Called once per agent
+   * during registry construction with `{ agentName, agentDataDir, containerWorkdir }`.
+   */
+  mounts?: (ctx: PresetMountContext) => PresetMount[]
 }
 
+type PresetInternal = PresetSpec
+
 const PRESETS_INTERNAL = {
-  opencode: { command: 'opencode', args: ['acp'] },
+  opencode: {
+    command: 'opencode',
+    args: ['acp'],
+    image: 'ghcr.io/zooid-ai/agent-opencode:latest',
+    mounts: (ctx: PresetMountContext): PresetMount[] => [
+      {
+        id: 'data',
+        host: `${ctx.daemonHome}/.local/share/opencode`,
+        target: '/root/.local/share/opencode',
+        mode: 'rw',
+        create: false,
+      },
+      {
+        id: 'config',
+        host: `${ctx.daemonHome}/.config/opencode`,
+        target: '/root/.config/opencode',
+        mode: 'rw',
+        create: false,
+      },
+    ],
+  },
   cline: { command: 'cline', args: ['--acp'] },
   kiro: { command: 'kiro', args: ['--acp'] },
   gemini: { command: 'gemini', args: ['--acp'] },
-  claude: { command: 'npx', args: ['-y', '@agentclientprotocol/claude-agent-acp'] },
-  codex: { command: 'npx', args: ['-y', '@zed-industries/codex-acp'] },
-} as const satisfies Record<string, PresetSpec>
+  claude: {
+    command: 'npx',
+    args: ['-y', '@agentclientprotocol/claude-agent-acp'],
+    image: 'ghcr.io/zooid-ai/agent-claude-code:latest',
+    mounts: (ctx: PresetMountContext): PresetMount[] => [
+      {
+        id: 'home',
+        host: `${ctx.daemonHome}/.claude`,
+        target: '/root/.claude',
+        mode: 'rw',
+        create: false,
+      },
+    ],
+  },
+  codex: {
+    command: 'npx',
+    // web_search="live" forces live web fetches instead of codex's cached snippet
+    // index, which doesn't know about recently-launched sites (e.g. zooid.dev).
+    args: ['-y', '@zed-industries/codex-acp', '-c', 'web_search="live"'],
+    image: 'ghcr.io/zooid-ai/agent-codex:latest',
+    mounts: (ctx: PresetMountContext): PresetMount[] => [
+      {
+        id: 'home',
+        host: `${ctx.daemonHome}/.codex`,
+        target: '/root/.codex',
+        mode: 'rw',
+        create: false,
+      },
+    ],
+  },
+} as const satisfies Record<string, PresetInternal>
 
 export type PresetName = keyof typeof PRESETS_INTERNAL
 
 export const PRESETS: Record<PresetName, PresetSpec> = Object.freeze(
   Object.fromEntries(
-    (Object.keys(PRESETS_INTERNAL) as PresetName[]).map((k) => [
-      k,
-      { command: PRESETS_INTERNAL[k].command, args: [...PRESETS_INTERNAL[k].args] },
-    ]),
+    (Object.keys(PRESETS_INTERNAL) as PresetName[]).map((k) => {
+      const e = PRESETS_INTERNAL[k]
+      const copy: PresetSpec = { command: e.command, args: [...e.args] }
+      if ('image' in e && e.image) copy.image = e.image
+      if ('mounts' in e && typeof e.mounts === 'function') {
+        copy.mounts = e.mounts as PresetSpec['mounts']
+      }
+      return [k, copy]
+    }),
   ),
 ) as Record<PresetName, PresetSpec>
 
@@ -43,9 +131,10 @@ export interface ResolvePresetOpts {
 }
 
 // null = preset has its own model channel (opencode reads opencode.json); undefined = not implemented yet.
-const MODEL_FLAG_PER_PRESET: Partial<Record<PresetName, string | null>> = {
-  claude: '--model',
-  codex: '--model',
+// codex-acp doesn't accept --model; it takes config overrides via `-c key=value` (TOML).
+const MODEL_ARGS_PER_PRESET: Partial<Record<PresetName, ((model: string) => string[]) | null>> = {
+  claude: (m) => ['--model', m],
+  codex: (m) => ['-c', `model="${m.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`],
   opencode: null,
 }
 
@@ -57,8 +146,8 @@ export function resolvePreset(name: string, opts: ResolvePresetOpts = {}): Prese
   const entry = PRESETS_INTERNAL[name]
   const args: string[] = [...entry.args]
   if (opts.model !== undefined) {
-    const flag = MODEL_FLAG_PER_PRESET[name]
-    if (flag) args.push(flag, opts.model)
+    const builder = MODEL_ARGS_PER_PRESET[name]
+    if (builder) args.push(...builder(opts.model))
   }
   return { command: entry.command, args }
 }

package/src/turn-tracker.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, it, vi } from 'vitest'
 import { TurnTracker, type TapEvent } from './turn-tracker.js'
+import type { ErrorCode } from './errors.js'
 
 describe('TurnTracker', () => {
   it('emits turn_started → session_update* → turn_completed in order', () => {
@@ -68,3 +69,33 @@ describe('TurnTracker', () => {
     expect(onTap).not.toHaveBeenCalled()
   })
 })
+
+describe('TapEvent error variant (ZOD055)', () => {
+  it('is a discriminated union member with the expected fields', () => {
+    const e: TapEvent = {
+      kind: 'error',
+      agentId: 'alice',
+      sessionId: 'sess-1',
+      turnId: 'turn-1',
+      code: 'auth_missing' as ErrorCode,
+      message: 'Authentication required',
+      detail: 'classified from RequestError',
+      transient: false,
+      acp_error: { code: -32000, message: 'Authentication required', data: undefined },
+    }
+    expect(e.kind).toBe('error')
+  })
+
+  it('sessionId and turnId may be null (failure preceded session/new)', () => {
+    const e: TapEvent = {
+      kind: 'error',
+      agentId: 'alice',
+      sessionId: null,
+      turnId: null,
+      code: 'container_exit' as ErrorCode,
+      message: 'Agent container exited',
+      transient: true,
+    }
+    expect(e.sessionId).toBeNull()
+  })
+})

package/src/turn-tracker.ts

@@ -1,4 +1,5 @@
 import type { SessionNotification } from '@agentclientprotocol/sdk'
+import type { ErrorCode } from './errors.js'
 
 export type SessionUpdate = SessionNotification['update']
 
@@ -24,6 +25,17 @@ export type TapEvent =
       turnId: string
       stopReason: string
     }
+  | {
+      kind: 'error'
+      agentId: string
+      sessionId: string | null
+      turnId: string | null
+      code: ErrorCode
+      message: string
+      detail?: string
+      transient: boolean
+      acp_error?: { code: number; message: string; data?: unknown }
+    }
 
 export interface TurnTrackerOpts {
   agentId: string

package/src/types.ts

@@ -8,6 +8,17 @@ import type {
 } from '@agentclientprotocol/sdk'
 import type { PresetName } from './presets.js'
 
+/**
+ * Structural copy of `@zooid/core`'s `AcpMount` shape. Kept here to avoid a
+ * back-edge to core; both files describe the same `{ path, target, mode }`
+ * tuple the docker runtime consumes.
+ */
+export interface AcpMountSpec {
+  path: string
+  target: string
+  mode: 'ro' | 'rw'
+}
+
 export interface AgentConfig {
   id: string
   /** Short-hand for a known ACP harness. Resolves to command/args via the preset registry. */
@@ -22,6 +33,8 @@ export interface AgentConfig {
   cwd?: string
   /** Container image. Forwarded to the spawn runtime; ignored by host-spawn paths. */
   image?: string
+  /** Bind mounts. Forwarded to the spawn runtime; ignored by host-spawn paths. */
+  mounts?: AcpMountSpec[]
 }
 
 export interface PromptInput {