Skip to main content
A run takes one piece of work through one workflow revision. Open a project’s Runs tab to start runs and see active and past ones.

​
Start a run

In Runs, fill in the form and choose Start run. An agent can start a run with start_run, using the matching fields: For an agent, “you” is the person who signed the agent in, or the Admin who issued its MCP key. Set the people explicitly when someone else should decide.
  • Owner is responsible for the run. Handed-off steps go to the Owner, and the Owner can cancel the run.
  • Approves the plan and Approves the result need a project role allowed on that step. In Development, the person who approves the result must be an Admin or Reviewer.
  • The person starting the run must be allowed to do the first step.
start_run returns 400 ineligible_decision_maker when an approver lacks an allowed role, 400 invalid_responsible_user when the Owner is not a project member, and 404 workflow_not_found when the workflow or revision is not published.

​
Follow a run

The run page shows each step’s state, its attempts, check results, who did what, and the actions open to you. Agents read the same information with get_run. nextActions lists what the current person or agent can do now: start_step, submit_step, decide_step, report_blocker, handoff_step, report_check, request_rework or cancel_run. Act on it rather than on someone’s role. Accepting one step makes the next one ready. Kiwi does not start the next step for you.

​
Decisions

Only people make decisions, and only in the app.
  • Approve the plan. When the Plan step is submitted, the person in Approves the plan accepts it or sends it back with a reason. Sending it back reopens Plan.
  • Approve the result. When Human acceptance is submitted, the person in Approves the result accepts it or requests rework with a reason.
Agents can submit the Plan step, but they cannot approve it, and they cannot submit or approve Human acceptance.

​
Rework

After the plan is accepted, an Admin or Reviewer can request rework from the run page with a reason. By default rework returns the run to Implement and keeps the accepted plan. Choose to revise the plan to return to Plan instead. Rework clears the current candidate. Earlier check results and reviews stay in the history but no longer count; run the checks and review again for the new candidate. A failed check, a blocked or not-applicable check, or a review verdict other than pass needs rework.

​
Blockers and handoffs

  • Blocker. Whoever is working on a step can report a blocker with a reason (report_blocker). Only the same person, or the same agent session, can resume it by starting the step again with the same attempt ID.
  • Handoff. Whoever is working on a step can hand it to the run’s Owner with notes (handoff_step). Kiwi creates a new attempt that only the Owner can start, in the app.
The Handoff step at the end of a workflow is different: it records where the finished work was delivered.

​
Cancel a run

The Owner or a project Admin can cancel a run from the run page with a reason. Cancelling stops Kiwi from accepting further changes to the run. It does not stop agents, CI jobs or anything else running outside Kiwi.

​
Retries

Every change to a run carries a command ID and the current run version: commandId and expectedRunVersion in MCP, command_id and expected_run_version in the checker API. Kiwi records a command ID once. Sending the same command again returns the original result instead of recording it twice. Never reuse a command ID with different content; Kiwi returns 409 idempotency_conflict. See Error codes for each code. Attempt IDs. When a ready step has no current attempt, create a new UUID as its attempt ID. After that, use the attempt ID Kiwi returns. Attempt IDs cannot be reused.

​
Activity

The project’s Activity tab lists everything recorded across its runs: steps started and submitted, decisions, check results, blockers, handoffs, rework and cancellations. Filter by run or event type, and open a run from any event. Activity shows only what was reported to Kiwi. It does not include agent transcripts, CI logs or work nobody reported.