[ThomasK33]

Why

The operator wants every valid finding shipped now. The verifiers of #287 and #301 found that a CliError from the session host loses its details on the way to the CLI. The host RPC sent only code and message. So a live snapshot or screenshot printed "details": {}, while the same error offline had details.path (and, with #301, details.errno).

What changed

• src/protocol/messages.ts: RpcErrorSchema allows an optional details record. It stays .strict().
• src/host/rpcServer.ts: an error response for a CliError carries its details when it has any. It leaves them out when they do not serialize to JSON (a BigInt or a circular object) or take more than 65,536 characters, and keeps the code and message (verifier findings F1 and F2). An error that is not a CliError still becomes RPC_ERROR without details.
• src/host/rpcClient.ts: sendRpc rebuilds the CliError with the response's details.
• Docs: src/protocol/README.md and src/host/README.md.

Behavior changes for CLI and JSON users

• A live command's error envelope now has the host error's details. For example, snapshot/screenshot on a running session whose artifacts path is a file give details: { path } instead of {}. The envelope shape and the error codes do not change: details was already there, and it now gets filled.
• Batch step records do not change. They keep only code and message.
• Details that are too large or not serializable stay off the wire. Without that limit, a live snapshot with a 4 KB artifact manifest of 1,000 empty entries gave exit 9 RPC_ERROR "RPC response exceeds maximum buffer size." instead of exit 8 MANIFEST_VALIDATION_ERROR, and a BigInt or circular value made the host crash.

Compatibility

Host started by	CLI	Error with details
older agent-tty	this version	works, details: {} as before
this version	this version	works, details filled
this version	older agent-tty	exit 9 RPC_ERROR "RPC response failed schema validation.", retryable: true, but retrying does not help

The last row is a downgrade: an older CLI on a session that a newer agent-tty started. Every RPC schema is .strict() on both sides, so any added field breaks that pairing. Successes and errors without details still work there. The per-session host is an internal implementation detail, and the repo supports upgrades, not downgrades, for running sessions (for example the socket-path fallback in #288). src/protocol/README.md states the limit.

Verification

• Red first (ac60d81): the RpcServer to sendRpc round trip in test/unit/host/rpcServer.test.ts and the live case in test/integration/screenshot-out.test.ts fail on main with details: {}. Then 2b79858: details over 1 MiB fail with "RPC response exceeds maximum buffer size.", and a BigInt or circular value makes the server throw (an unhandled rejection), on bb7d8ff.
• Live, on 547a445: a live snapshot with the 1,000-entry manifest exits 8 MANIFEST_VALIDATION_ERROR with details: {}.
• vitest run test/unit: 1942 passed. vitest run --maxWorkers=1 --retry=2 on screenshot-out, host-renderer-rpc, empty-session-capture and batch: 37 passed.
• npm run typecheck, npm run lint, npm run format:check pass.
• Live, every host and CLI pairing (main ca7c636 and this branch), using snapshot with a file at artifacts: the results match the table above.

Refs #255

---

Generated with xum • Model: anthropic:claude-opus-5-5 • Thinking: xhigh

[ThomasK33]

@codex review

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-11-04T00:50:38.012830Z	547a445	Manual request

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. 👍

Reviewed commit: bb7d8ff126

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[ThomasK33]

@codex review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. You're on a roll.

Reviewed commit: 547a4459d4

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".