works.iterative.claude.zio

Entry point for querying the Claude Code CLI with ZIO.

query streams messages as the CLI produces them; querySync and queryResult are convenience collectors. session opens a scoped multi-turn conversation. All operations fail with a typed CLIError.

An active Claude Code session backed by a long-lived CLI process.

A session is a stream of messages plus a way to inject user input. Turns are not modelled: the CLI owns turn boundaries, and a message read from events is not "the reply to your last send" (a background task finishing emits its own result with no send in flight, and a send issued mid-turn is merged into the running turn). See docs/adr/0001-session-is-a-stream-not-turns.md.

Completion is observed as state, not as a delivered event: send is fire-and-forget and the reliable "the turn finished" signal is the monotone resultsSeen counter behind state. Because the counter never decreases and is readable at any time, waiting on resultsSeen > n has no window to lose a race in — sendAndAwait closes the completion race outright rather than narrowing it.

The session is acquired within a Scope, whose finalizers shut down the process on both normal exit and error. Closing the scope closes the CLI's input and waits for the CLI to exit — it finishes its turn and writes the rest of its transcript first — killing it only if it has not exited within works.iterative.claude.zio.internal.cli.SessionProcess.CloseTimeout. Unless custody is off, closing then keeps the transcript one last time, bounded by its own close timeout (see ClaudeCode.session). The two bounds are paid one after the other, so releasing the scope of a session whose CLI never exits and whose keep never finishes takes both of them; a caller that needs release to be prompt can fork it.

The sessions a host has started and still holds.

A session is a running process, and a process outlives the request that started it: whoever asked for it has to be able to come back to it — after a reload, from a second tab — and reach the same agent rather than a new one. That is the whole of what this is for. Nothing about the conversation is kept here; the transcript is the CLI's own file, and this holds only what a file cannot be: the live process, by name.

Every session held is let go of when the holder's scope closes, so a host that stops leaves no agent running behind it.