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. When an archive is configured, closing the scope also waits for the final transcript mirror, bounded by a close timeout (see ClaudeCode.session); a caller that needs release to be prompt can fork it.