docs(constitution): add anti-polling rule for sub-agent waiting strategy#4098
Closed
Mr-Moon121 wants to merge 2 commits into
Closed
docs(constitution): add anti-polling rule for sub-agent waiting strategy#4098Mr-Moon121 wants to merge 2 commits into
Mr-Moon121 wants to merge 2 commits into
Conversation
When the parent launches sub-agents and runs out of independent work, it currently falls into a wasteful peek+sleep polling loop instead of passively waiting for subagent_completion events. This burns turns and budget without changing the outcome (sub-agents don't finish faster because you polled them). Add explicit 'Waiting, not polling' guidance to the Sub-Agent Strategy section: do not poll with peek/status, do not use sleep as a wait primitive, and if the runtime gives you a new turn with no user message while children are running, stop immediately. Closes Hmbown#4097
|
Thanks @Mr-Moon121 for taking the time to contribute. This repository is observing a maintainer-managed PR intake gate in dry-run mode, so this pull request is staying open. This note helps maintainers prepare the allowlist before any enforcement is considered. Please read |
…agents When the parent turn ends because it has no independent work left but sub-agents are still running, inject a runtime event telling the model to wait passively instead of polling with peek/status/sleep. This is the runtime-side complement to the constitution.md anti-polling rule. Together they form a two-layer defense against the wasteful polling loop documented in Hmbown#4097. Refs: Hmbown#4097
This was referenced Jul 8, 2026
Closed
|
Thanks @Mr-Moon121 — your contribution landed in
Closing this PR now that the code is on If you want to land more work and would prefer your future PRs merge cleanly without a harvest step, the |
6 tasks
Hmbown
added a commit
that referenced
this pull request
Jul 8, 2026
Make the visible mode roster Act/Plan/Operate with no Multitask or numeric gaps, keep yolo/4 as invisible Act+Bypass shorthand, mirror /model picker memory onto /provider, and credit the #4098 harvest.
pull Bot
pushed a commit
to 1sLand99/CodeWhale
that referenced
this pull request
Jul 8, 2026
Harvest the anti-polling guidance from PR Hmbown#4098 onto current main. The constitution section it patched was slimmed away, so the rule now lands in prompts/modes/agent.md (the delegation baseline shared by Agent, Multitask, and Operate modes): never loop agent(action=peek/status) and never use sleep as a waiting strategy — completion sentinels arrive on their own. The turn_loop hunk applies as authored: when a turn ends with children still running, inject an internal waiting_for_subagents runtime event so the model's next turn starts with an explicit do-not-poll reminder. Adds Mr-Moon121 to AUTHOR_MAP (verified GitHub id 56358802). Runtime enforcement (agent action=wait + peek throttling) follows in the next commit; this one carries the contributed prompt/hint layer. Part of Hmbown#4097. Harvested from PR Hmbown#4098 by @Mr-Moon121 Co-authored-by: Jeffrey Luna <56358802+Mr-Moon121@users.noreply.github.com>
pull Bot
pushed a commit
to 1sLand99/CodeWhale
that referenced
this pull request
Jul 8, 2026
…d peeks Fixes the Hmbown#4097 polling loop at the runtime layer. The parent model had no sanctioned way to block on children — peek returns a synchronous snapshot and completions only surface between tool steps or on the idle path — so models faked a join with peek→sleep loops (13 peeks + 140s of sleep in the reported session, 84% of session cost). Two mechanisms: - agent(action="wait") blocks until a running child settles (leaves Running: completed/failed/cancelled/interrupted/budget-exhausted), then returns a compact settled/running summary — full results still arrive as <codewhale:subagent.done> sentinels via the existing drain. With agent_id it joins that child; without, the next settle. Bad refs fail fast; nothing running returns immediately; timeout_secs (default 300, max 1800) returns a still-running snapshot instead of erroring. Cancel-safe: observes the turn cancel token, takes no lock across an await. Read-only, auto-approved, aliases join/await/block. - Repeat peek/status on a running child whose model-visible state is unchanged (status, steps, result/checkpoint/needs_input presence) within 30s now returns a compact unchanged:true nudge pointing at wait, instead of another full projection. Terminal children always project in full so result fetches are never throttled. Mode prompts (agent/operate/multitask) now name the contract: never poll or sleep-as-wait; end the turn or make one wait call for fan-in. Covered by six new tests: immediate return, settle wake, timeout snapshot, bad-ref rejection, peek throttle, action aliases. Closes Hmbown#4097. Follows the prompt/hint layer harvested from PR Hmbown#4098.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
When the parent launches sub-agents and runs out of independent work, it falls into a wasteful peek-sleep-peek-sleep polling loop instead of passively waiting for subagent_completion events. This burns turns and budget without changing the outcome (sub-agents don't finish faster because you poll them).
Evidence: issue #4097 documents a real session where 3 sub-agents triggered 13 peek calls and 5 artificial sleep calls (140s blocked), with $0.086 sub-agent cost where the majority was polling overhead.
Solution
Add explicit "Waiting, not polling" guidance to the Sub-Agent Strategy section in constitution.md:
The runtime already delivers subagent.done sentinels as user messages when children complete. Polling is pure waste.
Change
One file: crates/tui/src/prompts/constitution.md — new bullet in the Sub-Agent Strategy section.
Closes #4097