adopt

Put an agent on work that already exists, naming the branch it is on.

Agentwritesnot idempotentMCP tool

A pull request URL or number is refused as invalid_argument, so read the branch off it and name that. The workflow decides the repository, and it has to be one whose agents get a worktree of their own. Komrad works out where the agent runs: a worktree on that branch when nothing holds it, or the checkout already holding it when a human made one by hand. The branch is the human's, so nothing here creates it, resets it, or deletes it afterwards. A branch that already has an agent on it is refused as already_exists naming that agent, since git could not check it out twice anyway, so read the refusal rather than retrying. Each call otherwise spawns another agent, and only a repeat carrying the same idempotency_key is answered with the agent it already launched.

Calling it#

curl -X POST http://127.0.0.1:8787/agent.v1.AgentService/Adopt \
  -H 'Content-Type: application/json' \
  -d '{
  "ref": "<ref>",
  "workflowId": "<workflowId>"
}'

komrad rpc adopt \
  --ref <string> \
  --workflow-id <string>

{
  "name": "adopt",
  "arguments": {
    "ref": "<ref>",
    "workflowId": "<workflowId>"
  }
}

Offered by the komrad MCP server to orchestrator agents.

Request#

AdoptRequest#

Field	Type	Description
`ref`	string	The branch to put an agent on, which has to exist on the remote or on disk. required, at most 400 characters
`workflowId`	string	Which workflow to launch into, which is what decides the repository. required
`prompt`	string	The opening briefing, blank to launch the CLI with nothing to read. at most 50000 characters
`title`	string	What to call it in the panel, blank to have komrad name it. at most 200 characters
`flags`	string	Flags for its CLI, blank to take the workflow's own. at most 500 characters
`harness`	string	Which CLI to run, blank to take the workflow's own. at most 40 characters, matching ^[a-z0-9-]*$
`idempotencyKey`	string	A key that makes a retry safe, answering a repeat with the agent it already launched. at most 200 characters

Response#

AdoptResponse#

Field	Type	Description
`agent`	Agent	The agent as launched, on the branch it was adopted onto.

Types#

Agent#

Field	Type	Description
`id`	string	The handle every other call names this agent by, and what mail is addressed to.
`name`	string	What the panel lists it as, which is also its tmux window name at launch.
`cwd`	string	The directory it is running in, its own worktree when the workflow provisions one.
`flags`	string	The command-line flags its CLI was started with.
`prompt`	string	The whole briefing it was launched with.
`paneId`	string	The tmux pane its CLI is running in, which is what capture-pane reads.
`state`	AgentState	What the panel last decided it was doing, read off the tail of its pane.
`sessionId`	string	The CLI's own conversation id, which is the handle a resume needs.
`harness`	string	Which CLI it runs, such as claude or codex.
`workflowId`	string	Which workflow it is filed under, whose context it took at launch.
`createdAt`	string	When it was launched, in RFC 3339.
`archivedAt`	string	When it was hidden from the panel, unset while it is live.
`scheduleId`	string	The schedule that launched it, unset for an agent a person or another agent spawned.
`alive`	bool	Whether its pane is still there, which a dormant agent's is not.
`hidden`	bool	Whether the panel draws a row for it, which changes nothing about the agent itself.
`metadata`	list of AgentMetadata	Facts it has recorded about its own work, such as the ticket it is implementing.
`idempotencyKey`	string	The key a retry of its create carried, which is what answers a repeat with this agent.
`spawnedByAgentId`	string	Which agent called create, unset for one a person spawned.
`parentAgentId`	string	The agent this one is attached to, where spawned_by_agent_id is only who called create.
`branch`	string	The git branch its worktree is on, unset for an agent that provisions none.
`repositoryUrl`	string	The canonical web address of the repository its checkout pushes to, such as https://github.com/harrisoncramer/komrad, unset when the checkout is gone or its origin is not a forge.
`headSha`	string	The commit its checkout has checked out, unset when the checkout is gone or git cannot read it.
`worktreeRemoved`	bool	Whether its checkout has been taken away, which leaves the record and the transcript.
`sequenceInProgress`	bool	Whether a merge, a rebase or a cherry-pick is part-way through its checkout, waiting on somebody to settle it.
`failedRun`	bool	Whether a script komrad fired for the agent failed and nobody has looked at it since.
`failedRunLog`	int32	The run log that failure was written to, which is the run the panel opens on.
`stateChangedAt`	string	When the state above last moved, in RFC 3339.
`reportedReason`	string	What the agent's own CLI last reported it was doing, which annotates the state the pane decided rather than replacing it.
`role`	AgentRole	What the agent was launched to do, which decides the half of the review briefing it is sent.
`promptTruncated`	bool	Whether prompt holds only its opening, which a summary listing returns so that a page of agents does not carry every briefing they were launched with.
`treeStanding`	ReviewTreeStanding	Where the agent's worktree stood when last measured against the round tree_standing_sha names.
`treeStandingSha`	string	The snapshot of the round tree_standing was measured against, empty before any measurement.
`movedSinceRound`	string	The snapshot of its newest round while its worktree no longer hashes to it, empty otherwise.
`heldAt`	string	When a person stopped this agent and took its worktree, empty while nobody is holding it.

AgentMetadata#

Field	Type	Description
`key`	string	What the fact is filed under, such as pr or branch.
`value`	string	The fact as the panel shows it, which is why a URL belongs here whole.

AgentState#

AgentState is what the panel last decided an agent was doing, read off the tail of its pane.

Value	Description
`AGENT_STATE_IDLE`	The pane is at rest with nothing typed.
`AGENT_STATE_THINKING`	The CLI is working on a turn.
`AGENT_STATE_WAITING`	The CLI is blocked on a human answering a selection.
`AGENT_STATE_SETTING_UP`	The agent is being launched and has no pane to read yet.
`AGENT_STATE_FAILED_TO_CREATE`	The launch failed, which retry_agent is for.
`AGENT_STATE_FAILED_TO_CLEANUP`	A delete failed to take the worktree down, and the reason is on the row.
`AGENT_STATE_UNCERTAIN`	The pane could be read but its tail decided nothing.

AgentRole#

AgentRole is what an agent was launched to do.

Value	Description
`AGENT_ROLE_IMPLEMENTER`	An agent that lands work on a branch of its own.
`AGENT_ROLE_REVIEWER`	A child that reads another agent's work and gives a review.
`AGENT_ROLE_ORCHESTRATOR`	The agent drawn on a workflow's own row that hands work out.

ReviewTreeStanding#

ReviewTreeStanding is where an agent's worktree stands against the round its last verdict was given on.

Value	Description
`REVIEW_TREE_STANDING_MOVED`	The worktree differs from the round and the base does not hold the round.
`REVIEW_TREE_STANDING_LANDED`	The base holds the round whole and the worktree carries nothing beyond the base.
`REVIEW_TREE_STANDING_LANDED_MOVED`	The base holds the round whole and the worktree carries new work on top of the base.