# Agent Runtime Guide

Claim Playbook Runs, work through Doku-issued Work Items, and finish safely through Doku MCP.



Doku turns a selected Playbook into a Playbook Run. The dashboard creates a Run Intent, then an external harness such as Codex or Claude claims that intent through the Doku MCP resource URL.

## Connect [#connect]

Use the MCP resource URL from the Agent Work Brief. It is scoped to one Workspace and backed by an Agent Credential, not by the user's dashboard session.

If the harness is not authorized yet, ask the user to complete the Agent Installation authorization shown in Doku before claiming the Run.

## Claim a Run [#claim-a-run]

Use the Run Intent ID from the Agent Work Brief. The Launch Snapshot and its assignments are immutable once the Run Intent is created.

```ts
const work = await tools.doku.playbooks.runs.claim({
  intentId: "intent_...",
});
```

The claim creates the Playbook Run and returns a bounded packet containing an opaque `executionHandle`, current Task Work Items, Variable resolution Work Items, and typed blockers. Keep the returned packet and use only the handles Doku issues.

## Discover tools [#discover-tools]

Use CodeMode discovery as the live contract for tool names and parameters.

```ts
await tools.search({ query: "playbook run work" });
await tools.describe.tool("doku.playbooks.runs.claim");
```

Do not rely on memory if tool contracts differ from this guide. Discovery wins.

## Work loop [#work-loop]

1. Inspect the latest packet. Work only on a Task that has a Doku-issued `workItemHandle`.

2. If one or more Variables have resolution Work Items and human input is required, request one bounded Human Resolution batch through the opaque handles:

   ```ts
   const human = await tools.doku.playbooks.variables.requestHumanResolution({
     workItemHandles: ["rwi_..."],
     presentation: "Confirm the missing values.",
   });
   ```

   Doku returns a concrete Handoff when the private owner is waiting. A direct authenticated member answers in focused Run UI; only a later, continue-only `runs.continue` boundary validates and materializes that answer once, consumes the bound Work Item, and returns resolved recovery with the latest Packet—it does not restore or reissue that consumed Work Item. An identical immediate continue replays the stored resolved result while the Packet is unchanged. An originating agent may relay a chat answer only through `submitHumanAnswers`; that action atomically validates agent-relayed policy/provenance, materializes accepted or downgraded Variables, consumes Work Items, and returns authoritative packet/recovery exactly once. Use that result; re-enter or continue only when it indicates. Relay rejection/block leaves the request waiting for direct UI; owner rejection, cancellation, or expiry is authoritative—do not retry closed state or invent handles.

   ```ts
   await tools.doku.playbooks.variables.submitHumanAnswers({
     requestHandle: human.requestHandle,
     answers,
   });
   ```

3. Read the Task's bounded guidance and Connector resources through its Work Item, perform the work, and complete the Task:

   ```ts
   await tools.doku.playbooks.runs.completeTask({ workItemHandle: "rwi_..." });
   ```

4. After each mutation, or after any interruption, re-enter from current Doku state:

   ```ts
   const nextWork = await tools.doku.playbooks.runs.continue({
     executionHandle: work.executionHandle,
   });
   ```

   `runs.continue` is the synchronization boundary after a direct member answer. A relay is synchronized by `submitHumanAnswers`; use its authoritative packet/recovery and re-enter or continue only when indicated. Use opaque handles: the continue-only direct path materializes the owner answer once and consumes the bound Work Item; an identical immediate continue replays the stored resolved result while the Packet is unchanged, while changed or stale state requires the latest Packet. Do not poll generic Handoff, approval, or Question APIs.

5. When the packet includes `finishWorkItem`, finish with a truthful completion note:

   ```ts
   await tools.doku.playbooks.runs.finish({
     workItemHandle: nextWork.finishWorkItem.handle,
     completionNote: "Summarize the completed work and any material caveats.",
   });
   ```

If Doku returns a typed blocker or Human Resolution Handoff, follow the owning Doku or human action. For a direct member answer, call `runs.continue` with the latest execution handle; for an agent relay, use the `submitHumanAnswers` packet/recovery. Direct member answers and agent-relayed answers remain separately authorized and attributed; Doku is the source of runtime authority.

## Variables and checkpoints [#variables-and-checkpoints]

Launch assignments are frozen in the Launch Snapshot. A runtime Variable that still needs resolution appears as an opaque Variable Work Item in the packet. Use `tools.doku.playbooks.variables.resolve` only for a known safe value supplied through that Work Item. For missing values or human input, request Human Resolution with the bounded Work Item handles Doku issued; do not invent a Variable handle, task-level Question, or launch-state mutation.

For connector-backed choices, use the connector and resource-discovery tools exposed by Doku. If a value cannot be resolved safely, leave the checkpoint open and explain the blocker.

## Evidence [#evidence]

Evidence records what you inspected or produced while doing the work. Submit it against the Claim whose statement it supports. A completed Task without the required Claim Evidence is not a completed Outcome.

## Blocked work [#blocked-work]

If you are blocked:

* record the blocker in evidence when useful;
* leave blocked Tasks incomplete;
* do not invent missing connector credentials, approvals, or user decisions;
* follow the owning Doku or human checkpoint, then re-enter with the latest Work packet.

## Recover after interruption or Handoff [#recover-after-interruption-or-handoff]

If the agent is interrupted, use the latest Work packet and call `tools.doku.playbooks.runs.continue({ executionHandle })`. A Run Work mutation may return a concrete Handoff inline; wait for that private owner and do not poll generic Handoff, approval, or Agent Question APIs for Run Work. A direct member answers in focused UI; after that, the continue-only `runs.continue` boundary validates and materializes the answer once, consumes the bound Work Item, and returns resolved recovery with the latest Packet—it does not restore or reissue that consumed Work Item. An identical immediate continue replays the stored resolved result while the Packet is unchanged. The originating agent may relay chat only through `submitHumanAnswers`, which atomically materializes accepted or downgraded values and returns authoritative packet/recovery exactly once. Changed payloads and stale or closed handles require a fresh packet.

Takeover is the only ownership transition. When Doku says takeover is required, use its takeover operation and the fresh execution handle it returns; never reuse an old execution or Work Item handle. Safety-paused, failed, and cancelled states are authoritative blockers and must not be bypassed.

Every protected MCP call is independently authenticated for the exact Workspace resource. Doku does not create transport continuation state or expose a generic interaction status/resume API. The private Agent Question Owner does not replace the Run Work Handoff returned by a Human Resolution request: a direct member answer recovers with `runs.continue`, while an allowed agent relay uses `submitHumanAnswers` and its packet/recovery, with no extra retry unless that result requires re-entry. Relay rejection/block leaves the request waiting for direct UI; owner rejection, cancellation, and expiry close it and never become a successful Variable value.

## Safety [#safety]

Never bypass Doku runtime state. Do not mark work complete unless the required task work and evidence exist. If Doku rejects completion, treat the feedback as the next task list.