Reporting outcomes

Some steps Patchwork cannot perform: something that happens in your UI, on a device, or by a person. Those are declared as proposed_action patches. The agent proposes; you act; you report. Needs an agent wiring a proposed_action patch. No connection or signing required — the whole point is that you do the work.

The loop

const BASE = "https://api.usepatchwork.co/v1/loom";

async function handleProposals(threadId, headers) {
  const { data } = await fetch(`${BASE}/threads`, { headers }).then((r) => r.json());
  const proposal = data.find((t) => t.id === threadId)?.pending_action;
  if (!proposal) return;

  let state = "occurred";
  let detail = {};

  try {
    detail = await perform(proposal.patch_ref, proposal.args);
  } catch (err) {
    state = "failed";
    detail = { reason: err.message };
  }

  await fetch(`${BASE}/runs/${proposal.run_id}/outcome`, {
    method: "POST",
    headers,
    body: JSON.stringify({ tool_call_id: proposal.tool_call_id, state, detail }),
  });
}

args is exactly what the agent proposed. Dispatch on patch_ref to whatever your product does:

async function perform(patchRef, args) {
  switch (patchRef.split("@")[0]) {
    case "collect_signature":
      return { signed_at: await openSignatureModal(args.document_id) };
    case "scan_document":
      return { pages: await scanner.capture() };
    default:
      throw new Error(`No handler for ${patchRef}`);
  }
}

Report failures honestly

failed is a first-class answer. The model is told, and can respond — offer an alternative, ask a clarifying question, or explain. Reporting occurred for something that did not happen teaches the agent a false fact and it will act on it later. Include a reason. It reaches the model and produces a better next turn.

Safe to retry

Posting an outcome for a tool call that already has one succeeds without changing anything. If your network call fails and you are unsure, just post again.

Not the same as a confirmation

	Outcome	Confirmation
State	`awaiting_outcome`	`awaiting_input`
Field	`pending_action`	`pending_confirmation`
Who acts	you	Patchwork, after you approve
You report	what happened	what should happen

See Approving a write for the other half.

​The loop

​Report failures honestly

​Safe to retry

​Not the same as a confirmation

The loop

Report failures honestly

Safe to retry

Not the same as a confirmation