Function query

src/query/query.py:1019–1916

Canonical agent loop (chapter 5, Phase A foundation). The async generator yields messages and stream events to the consumer. The final ``Terminal`` is written to ``terminal_holder.value`` just before the generator returns (Python async generators cannot return values: PEP 525). Call

(
    params: QueryParams,
    *,
    terminal_holder: TerminalHolder | None = None,
)

# Max tools to run in parallel (TS default: 10, configurable via env var).
async def query(
    params: QueryParams,
    *,
    terminal_holder: TerminalHolder | None = None,
) -> AsyncGenerator[Message | StreamEvent, None]:
    """Canonical agent loop (chapter 5, Phase A foundation).

    The async generator yields messages and stream events to the consumer.
    The final ``Terminal`` is written to ``terminal_holder.value`` just
    before the generator returns (Python async generators cannot return
    values: PEP 525). Callers who care about the terminal pass their own
    ``TerminalHolder`` and read its ``.value`` after iteration.

    See :func:`run_query` for a convenience helper that consumes the
    generator and returns ``(messages, terminal)``.

    This PR (Phase A) introduces the typed Terminal infrastructure;
    recovery integration, stop hooks, token budget, model fallback,
    and continuation nudge land in subsequent PRs.
    """
    _diag = os.environ.get("CLAWCODEX_DEBUG", "").lower() in ("1", "true", "yes")
    holder = terminal_holder or TerminalHolder()
    # Inner-only flag for the future outer two-layer wrapper (Phase G).
    # Until that lands, the flag is local; set_terminal still writes it
    # so every exit site uses the canonical helper.
    natural_termination: list[bool] = [False]
    state = QueryState(
        messages=list(params.messages),
        tool_use_context=params.tool_use_context,
        max_output_tokens_override=params.max_output_tokens_override,
    )
    config = build_query_config()
    # Created once per query() call, persisting across turns — mirrors TS
    # query.ts:311 (state built before the while(true) at :327). Any
    # successful tool result resets the counters inside the guard.
    tool_failure_guard_state = create_tool_failure_loop_guard_state()
    # ch05 round-3 G2: snapshot the turn-token baseline + budget into the
    # bootstrap globals (zero callers before this — without the snapshot,
    # get_turn_output_tokens() returns SESSION-cumulative tokens and the
    # budget check is silently wrong after any prior output). Tracker is
    # once-per-query (TS query.ts:299) — per-iteration construction would
    # disable diminishing-returns detection.
    from ..bootstrap.state import snapshot_output_tokens_for_turn

    # Top-level queries only: a nested subagent query() (Agent tool runs
    # inside the main turn's tool phase) or a sidechannel must NOT
    # re-snapshot — it would null the budget, re-baseline the turn counter,
    # and zero the continuation count mid-turn. TS snapshots only at the
    # REPL surface (REPL.tsx:2944); agent_id mirrors check_token_budget's
    # own subagent discriminator.
    if (
        getattr(params.tool_use_context, "agent_id", None) is None
        and params.query_source not in ("compact", "session_memory")
    ):
        snapshot_output_tokens_for_turn(params.token_budget)
    budget_tracker = create_budget_tracker()

    # ch07 round-3 G1: the orchestrator lane sources tool lookup AND the