What is the intended use case for Handoff?

[patricka3125]

Hi, I have a question for the maintainers and community.

I've recently started integrating cao into my current development workflow, and I have a question about the intention of handoff vs assign orchestration patterns. One of the issues I've encountered so far is that the model will decide to use handoff or assign sporadically, especially if it is not explicitly instructed in the user prompt. There are instances where multiple tasks need to be assigned, but because the model makes the mistake of using handoff, the entire development pipeline gets blocked, and all inbox messages get clogged because the CLI is stuck waiting for the handoff task to finish.

This leads me to the asking - What is the actual intended use case of handoff, and why can't every subtask be delegated to a new worker using assign? Although assign is an asynchronous operation, the agent is expected to stop running and stay in IDLE mode once all tasks are assigned. Thus I would make the argument that assign is still effectively a blocking operation, under the condition that all tasks have been assigned. Assuming that assign flow works as intended and the agent is able to stop at correct points during the development pipeline, I feel that handoff is redundant and only adds an extra signal that increases the overall pipeline failure rate.

Wanted to start a discussion here to ask whether anyone else has this problem, or whether there is a use case of handoff that I am not seeing. Either way, overall I find the project very intriguing and hope to learn more. cheers!

[patricka3125]

Hey @haofeif and team, would love to hear your opinion on this, appreciate the work!

[haofeif]

HI @patricka3125 just give me my 2 cents. @tuanknguyen feel free to comment too.

In my opinion, the design is clear:

• handoff for sequential orchestration
• assign for parallel orchestration.
  The symptom you mentioned that somewhat the assign is still a blocking operation is a valid point, even though it is acting in the parallel orchestration fashion, but for implementation it is not 100%. However, we might be able to figure out a way to fix it so that it will not be a blocking operation.

On the other hand, when we started the project last year, majority of the workflows were sequential. At that time, among all the cli agent providers, only Claude Code had the subagents, Codex/Kiro-Cli didnt have . So majority of the users were using handoff to start with. Assign was something that @tuanknguyen came up at that time, without the agent features to be available. But we could definitely review this as you brought up.

Again, thanks very much for contributing and raising the question. Your voice and contribution meant a lot to this project!

[CorellisOrg]

his is a great question and I think it surfaces something deeper than handoff vs assign.
The real issue is: who decides the orchestration pattern? Right now the model picks handoff or assign based on prompt interpretation, which means the orchestration topology is non-deterministic. Sometimes it guesses right, sometimes your pipeline gets blocked.
We ran into the same problem running 28 agents in production. Our solution was to separate the "what to do" from the "how to orchestrate" — we call it goal decomposition. Instead of letting the model choose the pattern at runtime, we decompose goals into a dependency DAG upfront:

• Independent subtasks → parallel (your assign)
• Sequential dependencies → chained (your handoff)
• The topology is explicit, not inferred

The model still decides what the subtasks are, but the execution pattern is determined by the dependency graph, not by the model's interpretation of the prompt.
We open-sourced this as part of Corellis (https://github.com/CorellisOrg/corellis), built on OpenClaw. Different scope than CAO — we're focused on the governance/planning layer rather than CLI orchestration — but the goal decomposition approach might be relevant to the handoff/assign design question.
Curious if the team has considered making the orchestration pattern explicit in the task definition rather than model-inferred?

[kinthaiofficial]

Handoff is the most important primitive in multi-agent CLI orchestration, and it's underspecified in most implementations.

Three handoff use cases with different requirements:

1. Task delegation (permanent handoff): Agent A hands off a complete task to Agent B. From this point, B owns the task. The handoff should carry: task description, relevant context (not all context — just what B needs), budget envelope, deadline, and success criteria. A doesn't need to know how B does it.

2. Subprocedure call (temporary handoff): Agent A asks Agent B for a specific capability, gets the result, and continues. Like a function call. The handoff should carry: specific request, B's output schema, timeout, max cost. A waits for B to return.

3. Escalation (upward handoff): Agent A encounters something it can't handle and escalates to a supervisor agent. The handoff should carry: what A was doing, why it can't proceed, current state, and any partial work. The supervisor decides whether to take over, delegate to someone else, or send A more instructions.

Each type needs different context propagation, budget handling, and failure modes. Getting them confused leads to agents that either duplicate work (delegation implemented as subprocedure) or lose work (escalation implemented as delegation).

For CLIs specifically, handoffs across shell session boundaries need extra care: state must be serialized to disk/database, not just passed in memory.

More on coordination patterns: https://blog.kinthai.ai/221-agents-multi-agent-coordination-lessons