> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usepatchwork.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Reporting outcomes

> Handling an action the agent proposes for you to carry out.

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

```js theme={null}
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:

```js theme={null}
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](/examples/approving-writes) for the other half.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.