Resolve a consequential question before generation
A method can encounter a decision its existing context does not settle. When that decision would change the proposed artifact, Wildo can ask the product owner before generating it.
The owner can answer, delegate the decision or stop the waiting run. Questions and answers remain together, so the resulting work can be reviewed with the decisions that shaped it.
Example — Clarify how customers will be charged
A pricing brief does not settle whether the product charges per person or per organization. A participating generation method asks because the answer changes the product model, then continues with the response in its brief.
For engineers
Opt the method into clarification
A method declares suspendsForClarification: true. The companion supplies a clarification port to the generation runner, with prior answers and a bounded round budget.
The model receives the same brief used for generation and is asked only about decisions that cannot be derived from supplied context and would change the artifact. Routine preferences and information already available in the framework should not interrupt work.
This source excerpt shows the interrupt returning before the generation attempt loop:
if (requests.length > 0) {
await trace.event({
type: PlaybookExecutionTraceEvent.CLARIFICATION_REQUESTED,
summary: `"${output.family}" stopped for ${requests.length} decision(s) only the creator can make`,
payload: { family: output.family, requests: requests.map((request) => ({ ref: request.ref, question: request.question })) },
});
return { suspended: true, playbookRef: input.playbookRef, family: output.family, requests };
}
}
const rejectedFindings: string[] = [];
let accepted: unknown;
let attempts = 0;
while (attempts < maximumAttempts) {
attempts += 1;
const prompt = attempts === 1
The pause belongs to this participating artifact-generation invocation. It is not a promise that an enclosing choreography has performed no earlier work.
Continue through the companion
The host lists waiting work at GET /api/companion/playbooks/suspended and resumes a selected run at POST /api/companion/playbooks/runs/:runId/resume.
| Response action | Effect |
|---|---|
| Accept | Add supplied answers to the accumulated answers and continue |
| Decline | Continue without asking another round, with the delegated-decision context |
| Cancel | Consume the waiting checkpoint and stop that continuation |
The resume request carries action and, for an answer, answers containing ref and answer. References identify the questions shown by the suspended run. Reuse those references rather than inventing labels when submitting responses.
Understand what resume preserves
The checkpoint keeps the creator brief, declared interview answers, accumulated clarification questions and answers, and the rounds spent. Resume calls the playbook again with that context; it does not restore an in-memory model call. The old checkpoint is consumed after continuation returns, while another suspension saves its successor.
Questions are accumulated by reference with their original wording. The generation landing carries the exchange beside the artifacts it shaped. A declined decision should be visible as an assumption wherever the artifact can express it, rather than being presented as an answer the creator supplied.
Treat clarification as guidance, not authorization
The clarification check fails softly: a model error or unparsable response lets generation proceed. The question and round bounds also prevent repeated interruption from becoming an endless interview. This mechanism improves the information used for a derivation; it is not an approval gate or an independent safety check.
Preserve decisions across a pause
Accepted answers must match the outstanding questions: duplicates, unknown references, blank text and invalid choices are refused without consuming the waiting run. Confirmation answers use the same yes/no interpretation as declared interviews. Declining a later question delegates that question while preserving earlier answers as the creator’s decisions.
A dry run stays a preview after clarification. Resuming does not turn it into file writes, even if the caller sends dryRun: false; start a new ordinary run when ready to produce files. Older disposable checkpoints without a recorded mode resume as previews.