One agent starting another

Your session is deep in a real job and a side task falls out of it - a migration script, a test data generator, a question about another part of the codebase. You could open a new session yourself and paste the context across. The better habit: tell the agent to hand the work off itself, and collect the answer when it is ready.

One word before the first step, because the title uses a shorthand. An agent is the tool - Claude Code, Codex. What an agent starts is a session: a new running instance, with its own terminal, its own context, and its own place on the rail. Your agent starts one by running a single command.

About ten minutes. You need a Gateway, the DevThrottle command line, and one running session - start one if nothing is running.

1. Tell your session to hand the work off

   Prompt the session you already have with something like: "Spawn a helper session in this repository to map every place the orders table is read or written, and collect its answer when it is done." Underneath, the agent runs:

   What your agent runs

   cc-devthrottle session spawn D:/work/my-repo --name "Map the orders table usage" --prompt "Find every place the orders table is read or written in this repository. When you are finished, print a list of the files and what each one does with the table, then wait."

   One judgment call sits in that command: this errand only reads the repository, so the helper can share the folder your session is already working in. The moment a helper must edit files, give it its own copy of the code first - two sessions writing in one folder edit over each other - by cutting a worktree and spawning the session there: repositories and worktrees shows how.

   There is nothing to configure first - provided your Director is attached to a Gateway. A session launched on a Gateway-attached Director is given its own credential pair, stamped into its environment at launch - CC_GATEWAY_URL says which Gateway to call and CC_GATEWAY_SESSION_KEY is that session's own key for it, stamped as a pair or not at all - which is why the fleet commands simply work from inside your sessions. Without that pair - a Director with no Gateway, or a shell outside any session - the commands stop with a plain sentence saying they only work inside a DevThrottle session on a machine attached to a Gateway; nothing half-works.

2. Read the rail: a Worker appears, and it will never page you

   The new session shows up like any other - on the Director rail, on the fleet map, and in cc-devthrottle session list. But it arrives with a difference: a session spawned from inside another session defaults to a Worker supervised by its spawner. The spawner - if you declared no role for it - wears a Manager badge while its Worker lives. The roles tutorial walks the whole cast; here only one consequence matters.

   A supervised Worker never turns red. When it stops and needs input, it does not join your "needs you" pile - it recedes to a quiet slate colour (the fleet map's legend calls it Sub-agent), and its supervisor deals with it. For you that means red stays honest: a red session is always one that faces you, and a handoff between agents never pages the human in the middle. If the supervising session dies, the Worker stops being a Worker and anything it needs turns red again - nothing waits silently on a supervisor that will never answer.

   That quiet is only safe because the Worker has a channel of its own, and v2.0.6 shipped it. When a Worker hits something it cannot decide inside its mandate, it puts its hand up to the session driving it:

   What a blocked Worker runs

   cc-devthrottle session raise "Two schemas fit the requirement and only one is reversible - which?"

   The command's own help draws the line: raise it only while you are still working and have hit an ambiguous requirement, an irreversible step, a real design fork, or an authorisation you do not hold - "not for progress, and not for 'I finished' - stopping already says that". The hand lowers itself when the turn ends, and --clear takes it back down once the decision is answered.

   The other half is the read. A supervisor is not meant to be messaged "notice me"; it looks:

   What the spawner runs

   cc-devthrottle session workers

   That lists the sessions you are driving, what state each is in, and which of them have their hand up with what they are blocked on - one line instead of opening each in turn. Both commands default to the current session and take a --target if you mean another one.

   Note

   The subordinate Worker is the default, not the only shape. A session can start a human-facing peer instead with --standalone: that session has no supervisor, faces you, and turns red at you like any session you started yourself.

3. Get the answer back

   When the spawner wants the result, it asks - and waits:

   Ask and wait for the answer

   cc-devthrottle message ask "Map the orders table usage" "Are you done? Give me the list."

   The question lands in the Worker's terminal like any prompt. The asking session holds the line until the Worker finishes its turn - up to two minutes by default, longer with --timeout-ms - and then prints what the Worker wrote as the answer. For a one-way nudge that does not wait, there is cc-devthrottle message send. Either way the message arrives stamped by the Gateway with the sender's own name, machine, and id - the receiving agent always knows who is talking, and the sender cannot forge the stamp.

   Warning

   A message is an interruption: it lands in the receiving agent's stream even mid-task. That is why messaging is fenced - send all reaches only your own team, and a genuine fleet-wide broadcast needs a human-issued grant. The full safety rails are on sessions talking to sessions.

4. Close the loop: the spawner cleans up

   A finished helper should not linger on your rail - and closing it is the spawner's job, not the helper's. Once the answer is collected and read, the session that opened the helper flags it:

   Collect first, then close

   cc-devthrottle session done "Map the orders table usage"

   It is not an instant kill. The flag starts a grace window of about thirty seconds - long enough for the flagged session's final output to flush - and the owning Director's reaper sweeps about every thirty seconds after that, removing a flagged session once it is no longer working. The helper is gone within about a minute.

   Resist the tempting shortcut of telling the helper to flag itself as its last act. A helper that runs session done the moment it finishes can be reaped before anyone comes back for the answer - the reaper does not know an ask is still coming. Collect, review, then close: make "after you have read the answer, run session done on the helper" part of the handoff habit, so a day of handoffs does not leave a rail full of exited helpers to sweep up by hand.

Next

The full facts behind this page - the three verbs, the sender stamp, team scope, and the broadcast rails - live on sessions talking to sessions. For giving a writing helper its own copy of the code, read repositories and worktrees. And when one helper becomes a team with a plan, put names on the pattern with workflows.