Skip to content

Sub-agents: per-run control, limits and steering - #322

Merged
shoom1 merged 15 commits into
developfrom
feature/run-control
Nov 18, 2026
Merged

shoom1 merged 15 commits into
developfrom
feature/run-control

Conversation

@shoom1

@shoom1 shoom1 commented Nov 18, 2026

Copy link
Copy Markdown
Owner

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.

  • Cancelling one run. 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 ends cancelled with cancelled_by and 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.
    • The last allowed call keeps its tools declared and ends with a note asking for the best answer now. Claude refuses a request whose history holds tool calls when it declares none.
    • A tool call in that answer is dropped. The run ends completed, partial, "step limit reached".
    • No call past the limit is made.
    • On ADK this is 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. A task call over the limit returns the error result and starts no run. task's description says so.
  • A limit at a prompt. When a run is stopped while it waits at a permission prompt or a question, its dialog is withdrawn and the call is answered as not run. The turn goes on.
  • Steering. 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.

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.
@shoom1
shoom1 merged commit d52cab6 into develop Nov 18, 2026
6 checks passed
@shoom1
shoom1 deleted the feature/run-control branch November 18, 2026 00:19
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant