Repository navigation
Sub-agents: per-run control, limits and steering - #322
Merged
Merged
Conversation
RunControl holds one sub-agent run's limits, cancels the run's own task alone (the first cancel winning, none once it has ended) and tells the hook whether a cancel is the run's own, runs its time limit while a block does, counts its model calls (the last allowed one said so) and its tokens (past max_tokens the answer in progress is its last), and keeps the messages steered to it until its next model call. Nothing uses it yet.
Delegations makes each run's RunControl with its type's limits over the policy's, binds it to the run's task, hands it to the hook and keeps it while the run works: control(run) finds it and cancel(run_id, by=, error=) stops the run alone. The hook runs under the run's time limit. A run its control stopped ends cancelled, with who stopped it and what the hook had; a run that made its last allowed model call completes partial (step limit reached); the turn's cancel still wins (interrupted).
A turn starts at most max_runs_per_turn sub-agent runs, at any depth: the turn's span counts them, and a task call past the limit is an error result that starts no run (its brief read first, no instance numbered). task's description says At most N runs per turn.
Each backend's hook takes its run's own cancel (a limit, its parent) and returns the run's last text and the shared state it changed: ADK's run stops as a stopped turn's (its abort signal, its open calls sealed in its child session), Deep Agents' stream is closed. Any other cancel goes on. The contract suite stops one of two parallel runs while the other finishes, and ends a run at its time limit, on both backends.
A sub-agent run stopped by its limit or its parent while its question or permission prompt is on screen cancels the asking task alone: thinking-prompt withdraws the dialog, and the events box now comes back, since the turn goes on (Ctrl+C still leaves it closed). The contract suite pins the rest on both backends: the call answered as not run, the run cancelled by its limit, the turn and the next turn's prompts going on.
Each sub-agent's stack keeps its run's limits at its model calls, ADK's RunControlPlugin in each sub-agent chain and Deep Agents' RunControlMiddleware on each sub-agent's model side: the last allowed call ends with the step-limit note (its tools still declared, since Claude refuses tool calls in a request that defines none), each answer's tokens are counted, and the run's last answer, at its step limit or past its tokens, has its tool calls dropped, so nothing runs after it and no call past a limit is made.
A message steered to a working run (RunControl.steer) is added after its last message, as the user's, before its next model call, and stays in its transcript: ADK appends it to the run's child session and the request, Deep Agents adds it to the run's state. It comes before the step limit's note.
The CHANGELOG says the sub-agent policy's limits and runs per turn are enforced (the step, time and token limits, how each ends a run, the default policy's numbers among the behaviour a user will notice) and that one run can be cancelled alone and steered; CLAUDE.md's structure lines and the sub-agent passage describe RunControl, the run control plugin and middleware, the turn's run count and the withdrawn prompt; the README's sub-agent section gives the envelope's cancelled status and a run's limits, and its limits rows no longer say no run is stopped by them.
A message steered to a sub-agent run after a tool result starts a turn of its own, so the fit guard and the overflow handler's trim could leave out everything before it, the run's task message included, and the run would go on from the steered message alone. In a sub-agent type's chain both now keep the run's task message (its invocation's user content) whatever they leave out: an inheriting run's history goes first, then the turns after the task message, and the first kept turn's opening content joins the task message after the note, as one user content.
ADK stamps a model call's answer before the call's callbacks run, so the message RunControlPlugin appends to a run's child session in before_model_callback was newer than the answer that followed it, and a durable store, which reads a session's events back by time, put it after that answer, between a call and its result. The plugin now stamps each event of the run from a steer on just after the steered message (two microseconds, past what the store keeps of a time), and lets go of its record as the run ends.
An answer that crossed a run's max_tokens ended the run cancelled by its limit even when it made no tool call, so the run was ending anyway, and its parent read a failure and might redo finished work. RunControl.used now takes calls= (whether the answer makes tool calls, True when not said): only an answer past the limit that would go on is the run's last, cancelled by its limit, its calls dropped; one that makes none ends the run completed, its result whole. The tokens are counted either way. Both backends pass whether the answer makes calls.
…cancel alone model_call() set final_call from the step limit alone, so a call after one the token limit made the last was no longer the last; it is now kept once set. cancel() cancelled the run's task even while the turn's cancel (Ctrl+C) was unwinding it, and a time limit firing then cut the run's cleanup short and made the hook take the turn's cancel for the run's own; it now records the cancel and leaves that task to its turn. The time limit's clock test gets a wider margin (a 1 s limit) for a loaded runner.
… usage Pins what held under review: a parent run cancelled alone ends its working child interrupted; the turn's cancel wins while the hook cleans up after its own; a run cancelled already is not cancelled again. The contract scenarios check that the cancelled run's tool was stopped and that its sibling was working when the cancel landed. On both backends a model that reports no usage is not limited by tokens.
…her placement The hooks' docstrings and the message processor named a limit and a parent as who stops a run alone; Delegations.cancel(by="user") stops one too. The comment before the dialog no longer says that any raise means the turn is unwinding, since a cancel of the asking task alone is not. The contract scenarios say what they test rather than citing a document that does not ship. The real-session withdrawal test runs in both dialog placements.
… run keeps its task The CHANGELOG, the README and CLAUDE.md say that an answer past max_tokens that asks for tools is the run's last, cancelled by its limit, while one that asks for none ends the run completed, its result whole, and that a model which reports no usage is not limited by tokens. CLAUDE.md also says that a sub-agent run's task message is never trimmed on ADK, that a steered message's later events are stamped after it, and that the user's cancel withdraws a run's prompt too.
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
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.
Every sub-agent run gets a control of its own (
workflow/agents/control.py::RunControl), and the policy's limits are enforced on both backends.Delegations.cancel(run_id, by=, error=)cancels the run's inner task. The backend stops the child: on ADK by the abort signal, then the runner closed; on Deep Agents by the child's task. It returns what the run has so far, and the run endscancelledwithcancelled_byand its error. Its siblings and the turn go on. A turn's cancel (Ctrl+C) still ends every run interrupted, and wins over a run's own.timeout. The run's work, from the hook's start, runs under its time limit. Past it, the run is cancelled by the limit.max_model_calls.completed,partial, "step limit reached".RunControlPlugin, in each sub-agent's chain; on Deep Agents,RunControlMiddleware.max_tokens. Input plus output is counted after each model call. An answer that crosses the limit and still calls tools ends the run cancelled by the limit: its text is the result and its calls are dropped. An answer that crosses it with no tool calls completes the run with its whole result. A model that reports no usage is not limited by tokens.max_runs_per_turn. A turn starts at most that many runs, at any depth. Ataskcall over the limit returns the error result and starts no run.task's description says so.RunControl.steer(message): before the run's next model call, the messages steered since its last are added after its last message. They stay in its transcript. On ADK, a steered run's trimmed request keeps its task message, and a steered message is stored before the answer it prompted.Tests: new tests written first and seen failing; contract scenarios on both backends for each limit, for stopping one of two parallel runs, for a limit at a prompt and for steering. The full offline suite passes in the worktree except
TestChildImportOrigin, which fails the same way on develop under the worktree wrapper.