Outcomes - Patchwork

Some work Patchwork cannot do. A step that must happen in your UI, on a device, or by a human is declared as a proposed_action patch. The agent proposes it, the run pauses in awaiting_outcome, and waits for you to say what happened. This is the mirror image of a confirmation: there we ask permission before acting, here you act and then report.

Finding a pending action

GET /v1/loom/threads returns pending_action on the thread:

{
  "pending_action": {
    "run_id": "7c9e6679-…",
    "tool_call_id": "9b1deb4d-…",
    "patch_ref": "collect_signature@2",
    "args": { "document_id": "doc_881" }
  }
}

args is what the agent proposed. Carry it out however your product does.

Reporting

curl -X POST https://api.usepatchwork.co/v1/loom/runs/<run_id>/outcome \
  -H "Authorization: Bearer sk_live_..." \
  -H "Patchwork-Subject: user_9f2" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_call_id": "9b1deb4d-…",
    "state": "occurred",
    "detail": { "signed_at": "2026-08-30T12:04:00Z" }
  }'

`state`	Meaning
`occurred`	The action happened.
`failed`	It did not. The model is told, and can respond.

detail is optional, recorded on the outcome, and passed to the model. A short structured reason produces a better next turn than a bare failed. The response is 202 and the run resumes.

Idempotent

Posting an outcome for a tool call that already has one returns success without doing anything. Safe to retry.

Errors

Code	Status	When
`unknown_action`	`404`	No proposed action with that `tool_call_id` on that run.
`not_awaiting_outcome`	`422`	The run is not waiting for one.
`invalid_state`	`422`	`state` was not `occurred` or `failed`.