Handoffs

How one task hands its result to the next: by outcome, by condition, after a delay, and back to you when a decision is needed.

What a handoff is

A task can name the tasks that run after it: its successors. When a run ends, the OS starts every successor whose rule matches how it ended. The successor's run joins the same execution, so one piece of work can move from task to task, member to member and team to team, and still read as one thing.

Successors are part of the task's definition, so changing them publishes a new version. A successor can be any task in your enterprise. Its run is done by a holder of that task's role, on whatever team they sit.

A handoff happens when a run has ended. The run that hands off does not wait for its successor, and does not resume afterwards.

Each successor is one rule:

Field What it says
slug The task to start.
on The ending it follows. succeeded if you leave it out.
when A condition on the input the successor would receive. Optional.
delayMinutes Wait this long before starting it: 1 to 1440 minutes. Optional.
maxRunsPerIssue The loop cap for this rule. Optional; see Loops.
resumeConversation For a rule that follows your decision back to the same task: carry on the conversation that asked you. See Your answers resume the work.

By outcome: on

on Fires when
succeeded The run succeeded and named no outcome, or named plain success.
failed The run failed.
terminal The run ended, however it ended.
A named outcome The run succeeded and named that outcome, such as needs_changes or complete.
ceo_approved, ceo_rejected, ceo_changes_requested You decided on the run's question or gate. Only your decision sets these.

Named outcomes

A task's skill can end its run on a word that says which way the work went. The model ends its final message with a JSON object:

{ "outcome": "needs_changes" }

The OS compares that word with each rule's on. A named outcome is a branch: it replaces succeeded, it does not add to it. A run that ends needs_changes starts the rules on needs_changes and on terminal, and not the rules on succeeded.

  • Words that only mean "finished" (success, successful, okay, done, finished) count as plain success, unless the task has a rule on that exact word.
  • A run that failed follows failed and terminal, whatever outcome it named.
  • An outcome is only ever the model's word. ceo_approved, ceo_rejected and ceo_changes_requested come from your decision; a run whose model types one fails instead.

The task's instructions to the model list the outcomes its rules route, so a skill ends on a word that goes somewhere. You can define your own outcome names in these rules; the OS does not require them to appear in a built-in list. The skill must return the exact name its rule routes. A successor that names a missing task still produces a warning (successor_unknown_slug).

By condition: when

A condition is checked on the input the successor would receive:

when True when
has_issue The input carries an issue number (issue).
has_pr The input carries a pull request number (number).
no_pr It does not.
has_work_item The input carries a work item (workItem): one the run claimed from one of its teams' work lists, or was handed.
no_work_item It does not.

Any other when is refused when you save the task.

What a successor receives

A finished run builds one input, and every successor it starts receives the same one:

  • The run's own input, carried forward. What the OS uses to control a run (retry and resume markers) is left out.
  • From the run's result: issue, repo and the pull request number, if its final JSON names them. A run that opens or finds a pull request names its number there: that is the only way its successors learn it, and a run whose result names none hands no number on (so no_pr holds, unless its own input already carried one). A result that names a pull request but no issue only fills in repo when the input has none; it never moves the work to another repository. If the result names a different issue or repository, the branch the work was on is not carried forward.
  • The work item the run holds, as workItem: an item it claimed from one of its teams' work lists with os.claim_work_item, or was handed itself. The successor holds the item from the moment it starts, so the runs on one item are one execution, and a person sees who holds it on the item's history. An item is taken over only from the run before it, which has ended, or from nobody. If another run is still working it, including one waiting for your decision at a gate, the successor waits as pending until that run ends, then takes the item. It does not start, and it does not open a gate, while the item is held. An item still waiting for a person to approve it is not taken; that run starts and records why (run.work_item_not_held). An item a stopped pipeline holds is taken over by the retry or the successor that carries it on, and by nothing else.
  • Your decision, if the run was decided by you: your note as ceoNote, and your answers as ceoAnswers.

Nothing else in the result is passed on. Your note and answers reach the next task only: a task that needs them later has to write them somewhere lasting, such as a comment on the issue.

Delayed successors

A rule with delayMinutes starts its successor later: it waits as pending and starts once the delay has passed. Use it for a check that should look again in a while, such as re-reading a build that is still running.

When the successor is busy

A task has one run under way at a time, and so does a member. If the successor task already has a run under way, or every member holding its role is busy with other work, the successor waits as pending and starts when the task and one of them are free. A run waiting for your decision at a gate does not count as busy for that task or that member, so a different issue can use them. The same issue or pull request waits: a second run of that task stays pending until the gate is decided, and does not open another gate for it. The work item still keeps one piece of work to one run at a time, gate included. The same successor is not queued twice for the same input.

Loops and the loop cap

A rule may point back to an earlier task: review, fix, review again. A loop made only of terminal rules would never stop, so it is refused when you save it (unconditional_loop).

Every other loop is capped, for work about one issue, pull request or work item (an issue, number or workItem in its input): each rule may start its successor 4 times by default for that piece of work, and maxRunsPerIssue changes the cap for one rule. The count starts again after each decision of yours and each time a person retries a run of that work, and rules on ceo_approved or ceo_changes_requested are never capped. Work with none of these in its input is not capped, so give a loop over anything else its own way to stop. An issue or pull request names the work when the input carries one; a work item carried beside it rides along, and names the work only when there is neither.

At the cap, the OS does not start another lap. It records a blocked run with the reason loop_cap, which appears on Blockers for a person to retry or cancel. A retry by a person starts every rule's count for that issue or pull request again, so the work goes on until a rule reaches its cap once more. A retry by a task does not. See Runs.

When a pipeline stops

A run that ends on an outcome no rule routes is a dead end. The run itself still reads succeeded, but the OS records that the pipeline stopped there, and which successors it did not start, and Blockers lists the work as stopped so it is not lost.

A run that names no outcome at all is a dead end only when the task has neither a succeeded nor a failed rule to fall back on. Before it ends like that, the model is asked once to name its outcome. A task whose only rules are on terminal declares no outcomes, and a run of it is simply the end of the pipeline.

Rules that name a task your enterprise does not have are saved with a warning (successor_unknown_slug): the pipeline ends there.

Finished work

A pipeline that ends cleanly has stopped, but the OS does not know whether the work is done or only set down. A run that merges a pull request and a run that parks an issue for later both end succeeded with nothing after them. So a task says which of its endings finish the work: Finishes the work on on its page, finishesOn in the API.

The last run ends What happens to the work
On an outcome its task declares as finishing, with no step after it It is finished. It shows as complete on Executions and is never listed on Waiting.
Any other way, with nothing after it It is still open. It is listed on Waiting until someone restarts it or marks it finished.

List an outcome word for each ending that is the end of the work, and succeeded for a plain success:

{ "finishesOn": ["succeeded"] }

A task that can end either way declares only the ending that finishes, and its skill tells the model to name it. A task that closes an issue or leaves it parked might end {"outcome":"closed"} when it closed it and {"reason":"…","waitsOn":"…"} when it did not, and declare ["closed"]. The parked issue stays on Waiting, with the reason and waitsOn its run gave shown beside it.

Three things to know:

  • A finish is recorded only when nothing follows the run. If a successor starts on that outcome, the work carries on.
  • A finishing outcome is never a dead end (above), even on a task whose successors branch on other named outcomes and none routes it: the run is recorded as finished. succeeded is never a dead end either. An outcome the skill ends on that is neither routed nor finishing is saved with a warning (outcome_not_routed).
  • New work on the same issue, pull request or work item opens it again. If that work also ends without finishing, it is listed on Waiting again.
  • A work item the finishing run holds is closed as done with the finish, with the run named on the item's history. A run that closed the item itself leaves it as it closed it. On Waiting, work keyed on an item is listed by the item's title.

The OS does not read your issue tracker to decide this. Work you close by hand in the tracker stays on Waiting until someone marks it finished there.

Your answers resume the work

A task that needs a decision from you asks it and stops. It puts one or more questions to you, each with a recommended answer, and waits at a gate. When you decide:

Your decision The run's outcome What its successors receive
Send answers ceo_approved ceoAnswers, one per question, and your note as ceoNote
Reject ceo_rejected Your note as ceoNote
Request changes on a gate ceo_changes_requested Your note as ceoNote

Route those outcomes like any other: an approved plan on to the task that carries it out, a request for changes back to the task that proposed it. Rejecting a gated tool call is different: it cancels the run, and nothing follows. See Gates.

A rule back to the same task can set resumeConversation: true. The successor then carries on the conversation that asked you, instead of starting fresh: the model sees what it did before, then your decision, your note and each answer, and is told how long the question waited.

Planned

Waiting on another team

A run will be able to hand part of its work to another team's task and wait for it (waiting_on_run): the other team's run does its part, and the first run resumes when it finishes, or fails with its reason. Today a handoff starts its successor when the run has ended, and nothing waits for it.