Skip to content

Sub-agents: working slots - #323

Merged
shoom1 merged 10 commits into
developfrom
feature/working-slots
Nov 18, 2026
Merged

shoom1 merged 10 commits into
developfrom
feature/working-slots

Conversation

@shoom1

@shoom1 shoom1 commented Nov 18, 2026

Copy link
Copy Markdown
Owner

Sub-agent runs work in slots: at most SubAgentPolicy.max_active (default 4) runs work at once per conversation, at any depth. The root never takes one.

  • workflow/agents/slots.py::SlotPool is an asyncio counter with a heap of waiting runs, ordered by priority, then arrival. A run waiting for its slot back (RETURNING) goes ahead of runs that have not started (NEW).
  • Queued and running. A run that must wait reports AGENT_RUN queued, then running once it has a slot. A working run's record status is running, queued or input_required, as /agents and the events box show.
  • A parent waiting on its children lends its slot. The last child's slot goes straight back to it (hand_back), so nested fan-out with max_active=1 completes. A slot is taken back once, by the run's last wait. A take-back queued meanwhile ends without a slot.
  • A run waiting on the user lends its slot. This covers a question (request_user_input) and a permission prompt (the engine lends around its prompt lock, so two runs at prompts with one slot cannot deadlock). The run reports input_required, then running.
    • A prompt no one can be shown lends nothing. BaseWorkflowManager.can_request_user_input(), new, is false when no input callback is set or the turn has ended.
  • Queued time is not counted against a run's timeout. Ctrl+C while runs are queued or lent stops the turn, starts no queued run, and leaves the pool clean.
  • task's description says how many sub-agents work at once.

Tests: new tests written first and seen failing. Pool unit tests cover each cancellation case. Contract scenarios on both backends cover:

  • nested fan-out with one slot;
  • a returning parent going first;
  • a third parallel call queued;
  • Ctrl+C with runs queued and lent;
  • a prompt lending its slot;
  • a headless prompt lending nothing.

The full offline suite passes in the worktree, except TestChildImportOrigin, which fails the same way on develop under the worktree wrapper.

SlotPool lets a set number of runs work at once; the others wait in a heap ordered by priority, then arrival, a run taking its slot back ahead of the runs that have not started (asyncio.Semaphore wakes in arrival order, with no priority). A run lends its slot while it waits, nested lends counting once, and takes it back after; a child's slot can go straight back to the parent waiting on it alone. A cancelled waiter leaves the heap, one handed a slot as it is cancelled hands it on, and a run cancelled while it lends takes nothing back.
A run's record says running from its start, and queued (waiting for a free working slot) or input_required (waiting on the user) when an AGENT_RUN says so, until its end; a working status after the end changes nothing. /agents shows running, queued and needs you, and the events box writes a run's line when it waits for a slot or for the user and when it works again.
Each conversation's runs share a pool of SubAgentPolicy.max_active working slots, at any depth; the root takes none. A run takes a slot right before its hook and its time limit start, waiting queued (then running) when every slot is held, and gives it back at its end. A run that delegates lends its slot while it waits for its children, and the child that ends last hands it straight back, so the tree in progress goes on ahead of the runs that have not started and nested fan-out never deadlocks. A queued run cancelled, by its turn or alone, leaves the queue; the time it waited is not counted against its timeout.
waiting_on_user(): a sub-agent run says input_required, lends its working slot for the wait, takes a slot back ahead of the runs that have not started and says running; nested waits count once, a cancel takes nothing back, the root's work is untouched. request_user_input waits so, and the permission engine from before its one-prompt lock until after it: a run waiting for its slot while holding the lock would hold every other run's prompt, which with one slot and two runs at prompts was a deadlock.
The limits paragraph of task's description now opens with "At most 4 sub-agents work at once; more calls in one response wait for a free slot.", the number the policy's max_active, before the runs a turn may start.
Two waits of one run that do not overlap (two calls of one response, one asking the user after the other's answer) could each queue to take the run's slot back: the second started while the first waited in the heap, found the slot lent and lent nothing, and both then took a slot. With one slot the run held it while its other call waited for another, a deadlock; with more, the pool lost a slot for the rest of the manager's life. A run's slot now has one take-back at a time: a wait that starts while one is queued withdraws it (that wait ends without the slot, since the run waits again) and takes it back itself, and a hand-back or a release withdraws it too; a slot handed to a withdrawn wait in the same tick goes on to the next waiter.
The CHANGELOG says that at most max_active sub-agent runs work at once (more parallel delegations queue, a run waiting on its children or the user lends its slot), and gives the working statuses of a run's AGENT_RUN, its record and /agents; CLAUDE.md's structure lines and the sub-agent passage describe the pool, the lending and waiting_on_user; the README's limits passage and project tree name them.
A take-back handed the slot before it could go on, while another wait of the same run started and ended at once (a prompt answered without waiting), left that wait's own take-back in the heap: the run held its slot while one of its calls waited for another, a hang with one slot. A take-back that holds the slot now withdraws any queued since, which ends without one. The pool test's two cancels in a finally are two statements.
The parent's wait is over and it waits in the heap for its slot when its child hands the slot back: that take-back ends without one, and the parent holds the child's slot.
Headless (no input callback for the turn), a sub-agent run's permission prompt is denied at once, yet the engine lent the run's slot first: the run queued for one took it and worked its whole run before the asking run could go on. BaseWorkflowManager.can_request_user_input() says whether a request could reach the user now (a callback set for this context, its turn not ended), and the engine lends only when it can; request_user_input already raised before lending. A callback that answers without waiting still lends, as its docstring says.
@shoom1
shoom1 merged commit 0d4d4e5 into develop Nov 18, 2026
6 checks passed
@shoom1
shoom1 deleted the feature/working-slots branch November 18, 2026 01:43
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