Ambient

A subagent that returns before it answers

The harness already had a background-task manager and a soft-interrupt mechanism; both were used by background shell commands. The Always patch adds a fourth variant to the subagent tool's output mode and wires it into the existing machinery. The doc comment on the new variant is the whole design in four lines:

// Subagent background completions need the FULL final answer inlined
// (not the 500-char preview) — the host LLM must see the complete result
// to integrate it on its next turn. Falls back to preview if the file
// is missing, empty, or exceeds the cap.
let full_subagent_output = if task.tool_name == "subagent" {
    std::fs::read_to_string(&task.output_file)
        .ok()
        .filter(|s| !s.is_empty() && s.len() <= 256_000)
} else {
    None
};

The design that was thrown away

By the time those text_delta events reach the voice stack, the hard problem is no longer producing them. It is reading them. The chat client only reads its socket from inside a chat() call, so events emitted between turns queue in the kernel buffer and are then misattributed to whatever turn reads next.

The first attempt merged ambient reading into the chat client's connection pool: one socket per session, a dedicated reader thread, and demultiplexing by message id. The documentation still describes that design. The module that replaced it opens with a post-mortem of why it did not work:

Deciding what is worth saying out loud

Reading the events is not enough. A woken host model produces the same stream it produces for any turn — including planning chatter that reads badly when a speaker says it into an empty room. The gateway therefore applies three independent controls before anything is synthesised.

Suppression

The callback's first act, after the debug-only soft_interrupt_injected marker, is to check state.foreground_turn_active. If a user-initiated turn is in flight, the ambient buffer is cleared, the chunk index is reset to zero, and the event is dropped. The foreground path is already synthesising those same deltas via _send_turn_result; without this check the user would hear every sentence twice. Notably it is not gated on state.is_speaking, because ambient synthesis sets that flag itself and would suppress its own continuation.

The narratable filter

_ambient_text_is_narratable() lower-cases the normalised text and rejects it if it contains any of eleven substrings. The list is a direct transcript of what a model sounds like when it is thinking aloud:

_AMBIENT_INTERNAL_MARKERS = (
    "<think", "analysis:", "reasoning:",
    "the user is asking", "the user asked",
    "i need to", "i should", "we need to",
    "let me inspect", "let me check", "tool call",
)

Chunking, which is off by default

This is the detail most likely to surprise someone who has only read the architecture document. ALWAYS_AMBIENT_STREAM_TTS defaults to false. With that default, a text_delta is appended to the buffer and the callback returns immediately — no ambient_text_delta frame, no sentence-boundary flush, no size-based flush. The buffer is merely trimmed to its last 8,000 characters. Everything is spoken in a single chunk when message_end arrives.

Why the browser keeps ambient audio separate

Ambient audio and foreground audio arrive on the same WebSocket as the same audio_chunk message type, distinguished only by an ambient: true flag the gateway sets. The client keeps two arrays and a strict priority:

• foregroundAudioQueueRef — cleared whenever a chunk with index === 0 arrives, so a new answer always cancels the previous one.
• ambientAudioQueueRef — appended to, never cleared by foreground activity.
• playNextAudio() shifts from the foreground queue first and only falls through to the ambient queue when it is empty. On a playback failure the item is pushed back onto the queue it came from.

The invariant that falls out of this is the one the feature needs: a narration that begins while you are silent will not be destroyed by you then speaking — it is deprioritised, not discarded. Meanwhile the suppression check in the gateway ensures no ambient audio is generated during that foreground turn in the first place, so the two mechanisms bracket the same hazard from both ends.