From e71e4ac83eb25cf842892387869c278b78aec043 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Sun, 26 Jul 2026 23:10:24 -0400 Subject: [PATCH] docs: explain why steering waits for the current tool-call batch (#114249) * docs: explain why steering waits for the current tool-call batch * docs: regenerate docs map for steering batch section --- docs/concepts/queue-steering.md | 11 +++++++++++ docs/docs_map.md | 1 + 2 files changed, 12 insertions(+) diff --git a/docs/concepts/queue-steering.md b/docs/concepts/queue-steering.md index fc4a486074cf..822482e5655d 100644 --- a/docs/concepts/queue-steering.md +++ b/docs/concepts/queue-steering.md @@ -2,6 +2,7 @@ summary: "How active-run steering queues messages at runtime boundaries" read_when: - Explaining how steer behaves while an agent is using tools + - Explaining why steering does not cancel an in-flight tool-call batch - Changing active-run queue behavior or runtime steering integration - Comparing steering with followup, collect, and interrupt queue modes title: "Steering queue" @@ -27,6 +28,16 @@ The native Codex app-server harness exposes `turn/steer` instead of OpenClaw run Codex review and manual compaction turns reject same-turn steering. When a runtime cannot accept steering in `steer` mode, OpenClaw waits for the active run to finish before starting the prompt. +## Why steering waits for the current batch + +Steering applies corrections at the next model step instead of cancelling tool calls the assistant already requested. This is a deliberate design decision, not a missing feature: + +- A tool-call batch is one unit of work. When the model requests several tool calls in one assistant message, they usually depend on each other, for example edits across multiple files. Cancelling the not-yet-started calls leaves that work half applied, and the next model step typically has to redo the whole batch to get back to a consistent state. +- Every tool call keeps a real result. Dropping requested calls means fabricating aborted results for them, and models routinely misread synthetic failures as real ones, then retry or route around tools that never actually failed. +- The context stays append-only. Steered messages are appended at the tail, so nothing already sent to the model is rewritten and provider prompt caches stay valid. + +The wait is bounded by the current tool-call batch, not by the run: a steered correction is visible to the model at its next reasoning step. Stopping the current work is a different intent than redirecting it; use `/queue interrupt` (or `/stop`) when the newest message should abort the active run instead of steering it. + ## Modes | Mode | Active-run behavior | Later behavior | diff --git a/docs/docs_map.md b/docs/docs_map.md index cd6392a9a631..07949d104206 100644 --- a/docs/docs_map.md +++ b/docs/docs_map.md @@ -2929,6 +2929,7 @@ Do not edit it by hand; run `pnpm docs:map:gen`. - Route: /concepts/queue-steering - Headings: - H2: Runtime boundary + - H2: Why steering waits for the current batch - H2: Modes - H2: Burst example - H2: Scope