How to Configure Execution Policies in Paperclip

An execution policy is the configuration object that sits between an agent calling done and Paperclip recording done. It defines an ordered sequence of review or approval stages a task must pass before done is final. Without one, done means the agent said it's done. With one, done means the agent said it's done and the designated reviewer signed off.

If you're still working out why agents are marking tasks complete before the work is actually finished, start with the diagnosis first. This article covers the configuration.

What changes with a policy in place

When a task has an execution policy and the executor moves it to in_review, Paperclip activates the first stage and assigns it to the designated participant. Stages run in order. Only after all stages complete does the task reach actual done.

The policy lives on the task, not on the agent. The same agent runs ungated on routine work and fully gated on anything that ships or migrates, because the gate is configured at the task level. You're not making an agent more cautious globally. You're governing specific task classes.

The two gate types

Paperclip supports two stage types.

review: A peer review gate. The task is assigned to a reviewing agent or user who reads the output and either signs off or sends it back with changes requested. Use this for QA, output verification, and any deliverable where someone needs to check the actual work product.

approval: An authorization gate. Same mechanics, but semantically frames the decision as authorizing an action rather than evaluating work quality. Use this for compliance checkpoints, founder sign-off on production changes, and any go/no-go where the participant decides whether to proceed, not whether the work is good.

Both types use identical decision mechanics at the API level. The distinction signals intent to the participant.

Attaching a policy to a task

You can attach an execution policy at creation time (in the POST body when you create an issue) or update one later via PATCH. There is no separate policy endpoint — it is a field on the task.

At creation — single review stage, agent reviewer:

POST /api/companies/:companyId/issues
{
  "title": "Run PII table migration",
  "executionPolicy": {
    "stages": [
      {
        "type": "review",
        "participants": [
          { "type": "agent", "agentId": "<qa-agent-id>" }
        ]
      }
    ]
  }
}

Via PATCH — update or add a policy after creation:

PATCH /api/issues/:issueId
{
  "executionPolicy": {
    "stages": [
      {
        "type": "review",
        "participants": [
          { "type": "agent", "agentId": "<reviewer-agent-id>" }
        ]
      }
    ]
  }
}

Two-stage policy — QA agent review, then founder approval:

PATCH /api/issues/:issueId
{
  "executionPolicy": {
    "mode": "normal",
    "stages": [
      {
        "id": "stage-review",
        "type": "review",
        "participants": [
          { "id": "participant-qa", "type": "agent", "agentId": "<qa-agent-id>" }
        ]
      },
      {
        "id": "stage-approval",
        "type": "approval",
        "participants": [
          { "id": "participant-founder", "type": "user", "userId": "<your-user-id>" }
        ]
      }
    ]
  }
}

Field reference:

Field	What it does
mode	Policy mode: "normal" or "auto".
stages[]	Ordered array. Stage 0 runs first.
stages[].type	"review" or "approval" — the only two supported stage types.
stages[].approvalsNeeded	Fixed at 1. Multi-approval is not yet supported.
participants[].type	"agent" or "user"
participants[].agentId / .userId	The specific agent or user who must act on this stage.

executionState (read-only): Once a policy is active, Paperclip exposes an executionState object on the task: status (idle / pending / changes_requested / completed), currentStageType, currentParticipant, and returnAssignee. returnAssignee is auto-derived — the runtime records the original executor when it routes a changes-requested task back. You never set it by hand.

Configuring via the Board UI

You do not have to use the API directly. Paperclip's board exposes execution policies in two places.

New-issue dialog: When creating a task, the dialog includes Reviewer and Approver buttons with a participant picker. Selecting a participant here wires up the corresponding stage in the executionPolicy automatically.

Issue properties panel: On an existing task, the properties panel has editable Reviewer and Approver fields. Changes to these fields persist directly to the executionPolicy. This is the fastest path for one-off policy adjustments without touching the API.

The run-level comment backstop

Independent of any policy stages, Paperclip enforces a runtime invariant: every agent run on a task must post at least one comment before the run is considered complete. If an agent run ends without posting a comment, Paperclip re-wakes the agent once. If the re-wake also ends without a comment, the run is recorded as failed.

This is not a stage you configure — it is always on. The practical consequence: an agent cannot silently close a task. Any completed run has an audit trail showing what the agent did and said. For governance purposes, this means "the agent completed this" always comes with at least one comment of supporting evidence, regardless of whether a policy stage was involved.

How reviewers submit decisions

When a task enters a stage, Paperclip assigns it to the currentParticipant. That reviewer gets a heartbeat wake with the task in in_review. They submit their decision through the standard issue update — there is no separate execution-decision endpoint.

Approve:

PATCH /api/issues/:issueId
{
  "status": "done",
  "comment": "Approved: migration handles nulls correctly, rollback procedure verified"
}

Request changes:

PATCH /api/issues/:issueId
{
  "status": "in_progress",
  "comment": "Changes requested: rollback procedure missing for the PII table backfill"
}

Paperclip records the decision row automatically. If another stage remains, the task stays in in_review and is reassigned to the next participant. When the final stage passes, the task reaches actual done.

When a reviewer requests changes, the task returns to the executor (returnAssignee) at in_progress for a revision pass. When the executor moves it back to in_review, it resumes at the same stage and reviewer that requested changes — not from stage 0. The loop is iterative, not one-shot.

One enforcement constraint worth knowing: only currentParticipant can advance a stage. Any other actor's attempt returns a 422. The gate is only as reliable as this constraint holding.

A worked example

A Coder agent handles schema migrations. Routine column additions run ungated. Anything touching PII tables or involving DROP operations gets the two-stage policy above: QA agent review, then founder approval.

The Coder executes the migration, documents what changed and why in a comment, then PATCHes the task to in_review. Paperclip wakes the QA agent. QA reviews the script, the rollback plan, and the staging run output, then approves. Paperclip advances to stage 2 and wakes you. You review, approve. The task reaches done. Migration runs.

Same Coder agent. Same heartbeat mechanics. The gate is on the task class.

Where to start: gate the highest-stakes task classes first

Every gate adds friction. The question is whether the blast radius of a wrong done justifies it.

Gate these first:

• Tasks that push to production: deploys, schema migrations, infrastructure changes
• Tasks that send external communication: emails, API calls to third parties, webhook triggers
• Tasks that delete or archive data
• Tasks that provision access or modify permissions

Leave these ungated until you have a specific reason to gate them:

• Internal research and drafting tasks
• Reporting and analytics that do not take external action
• Anything where a bad output is immediately visible and easily reversed

The goal is not zero risk. It is catching the failures that are expensive to discover after the fact — the ones where "the agent said it was done" and no one checked until the damage was already in production.

The governance argument for this design

When an approval stage has participants: [{ "type": "user", "userId": "..." }], Paperclip records that a named person saw and signed off on this output before the task closed. That is a durable, timestamped audit trail. For operators running agent companies with external stakeholders — clients, compliance requirements, regulated contexts — this is the difference between "the agent completed this" and "a named person reviewed and authorized this."

Most governance frameworks try to configure the agent: make it more cautious, add pre-flight checks, tune the prompt. Paperclip's execution policy inverts this. The agent runs at full speed. The task class carries the governance requirement. The reviewer is named, the decision is recorded, and the constraint is enforced at the API level.

That is where serious governance of agent companies starts. For related configuration guidance, see the setup and security guides.

Subscribe below for more on running AI-native operations. Practical field notes on agents in production, straight to your inbox.