Approvals and grants
Nothing an agent does on your account happens without you saying yes. Workspace changes, managed runs, experiments and publishing each take two steps. A prepare call returns a plan, and the matching apply, create or execute call only goes ahead once you have approved that exact plan.
What a plan contains
Read these fields before you approve anything:
| Field | Why it matters |
|---|---|
| Base revision | Which exact state of the workspace the change applies to |
| Digest | Binds the approval to this plan and no other |
| Findings | What the preflight checks noticed, including missing evidence |
| Side effects | What the call will create, overwrite or spend |
| Expiry | Plans are short-lived; an expired plan must be prepared again |
If the revision or the digest has moved by the time you approve, the apply is refused and your agent has to prepare a new plan again. That refusal is the point. What you read is no longer what would run.
Publishing publicly is never covered by a grant. That approval is always separate, every time.
Two-step pairs
| Prepare | Apply | Covers |
|---|---|---|
workspace_change_prepare | workspace_change_apply | Edits to a private lab you own |
run_prepare | run_create | One managed run |
experiment_prepare | experiment_create | Every arm of an experiment, under one approval |
publish_prepare | publish_execute | One release |
Run grants
Approving five runs one at a time gets old. A run grant lets one approval cover repeated runs of the same plan.
- Up to 10 runs per grant.
- Valid for between 60 seconds and 24 hours, and you choose the window.
- Bound to one plan. A different plan needs a different grant.
- Revocable at any time with
run_grant_revoke.
Check what is left on a grant with run_grant_get.
Workflow grants
A workflow grant goes further. It covers up to 10 paired actions, each one a managed run plus a private publication of the result.
- Every run and publication plan in the grant must bind the same workspace revision.
- The publication in each pair must be private. A grant that asks for a public release is refused with
workflow_publication_must_be_private. - Same 60-second to 24-hour window, same revocation, via
workflow_grant_revoke.
Revoking
Revoking stops whatever is left on the grant. It won’t cancel work already running and it deletes nothing already produced. Cancel an individual run with run_cancel if that’s what you want.
Duplicate submissions
Submit a run that matches one already in flight and you get the original Run ID back. Nothing ran twice, and nothing was charged twice.
Next steps
- Agent tool reference: the grant tools and their scopes
- Run an experiment: several arms under one approval
- Visibility and sharing: what private and public mean
- Package and publish: the publication path in full