Gates and tool scopes
What a task may touch at all, and which of its calls wait for your approval before they happen.
Two different controls
A task is held by two controls, and it needs both:
| Control | The question it answers | What it is not |
|---|---|---|
| Tool scope | May this task call this tool, with these values, at all? | A review of what this run is about to send. |
| Gate | May this particular call happen now? You decide, on the exact payload. | A substitute for connections with the least access they need. |
A connection that can publish does not mean a task may publish. A task that lists a tool does not mean the call goes out unseen. Guardrails are neither: they are instructions to the model, and they stop nothing on their own.
Tool scopes
Which tools a task may call
A task lists every tool its runs may call. A run is offered those tools and no others.
| Entry | What it allows |
|---|---|
github or github.* |
Every tool the GitHub connection offers, merging included, so the task must also declare the merge gate (see Merging). |
github.create_pull_request |
That one tool. |
os.set_gate_summary, memory.ask, workspace.git_push |
One of the OS's own tools. They need no connection, but a task still has to list them. See Built-in tools. |
If the model calls a tool the task does not list, the run fails (tool_not_on_task); a name no tool answers to is
handed back to the model to correct instead. If a listed tool has no
connection, the run is blocked (tool_not_bound) until you connect it, and then carries on. See
Tools for connecting one.
The connection's own permissions still apply underneath. A read-only token cannot write, whatever the task lists, so connect each tool with the least access the work needs.
Narrowing a tool to some values
A task can pin a field of a tool to the values it may use, after a #. Values are separated by , and fields by
;:
github.pull_request_review_write#method=create,submit_pending;!event=COMMENT
This task may create and submit reviews, and every review it submits is a comment: it can never approve a pull request or request changes on one.
The model is shown the tool with only those values, so it is never offered the rest. A call with any other value is
refused before it reaches the tool, and handed back to the model to correct (tool_value_not_declared). A field
with ! before it, like event here, ends the run instead (tool_value_refused).
An argument the connection itself fixes, such as the organisation it works in, is taken out of what the model sees, so it cannot ask for another.
Gates
Declaring a gate
A task version lists its gates, one per tool:
{ "tool": "github.add_issue_comment", "owner": "ceo", "approval": "specific" }
A gate on a whole vendor (github) covers every tool it offers except the merge, which needs a gate of its own.
approval is specific: every call asks. A gate that names what its calls act on (oneAskPer) asks once per
target in an execution; see Merging.
A gate can be narrowed to some calls of its tool with match: the payload fields the call must carry, each equal
to what the gate names, or, for a list, starting with it. So one command waits for you while every other command the
task runs goes ahead:
{
"tool": "workspace.run_command",
"owner": "ceo",
"approval": "specific",
"match": { "argv": ["mise", "run", "os:infra:apply"] },
"requiresSummary": true
}
requiresSummary holds that call back until the run has written a gate summary (the task must hold
os.set_gate_summary), so what you approve is explained the way a merge is. A gate narrowed by match covers only
the calls it names: it does not stand in for a tool your connection marks as always needing a gate, only for an entry
your connection narrows the same way or further (see Merging waits for you).
One waiting ask per target
oneAskPer names the payload fields that say what a call acts on, such as ["owner", "repo", "index"] for a pull
request:
{
"tool": "gitea.pull_request_write",
"owner": "ceo",
"approval": "specific",
"match": { "method": "merge" },
"oneAskPer": ["owner", "repo", "index"]
}
When this gate opens, an earlier ask still waiting on the same tool from another run, with the same values for every
one of those fields, is replaced: the earlier gate is cancelled as superseded and its run ends, and you decide on the
latest ask only. A call missing any of the fields, or with one empty, replaces nothing. An ask already decided, and
an ask from the same run, are left alone. The list must hold at least one field name, or the version is refused
(gate_one_ask_per_invalid).
Letting the approver edit a call
editable names the payload fields whoever decides the gate may change before approving, such as a post's text:
{
"tool": "slack.post_message",
"owner": "ceo",
"approval": "specific",
"editable": ["text"]
}
The gate card shows an input for each named field the run wrote as text, and every other field as the run wrote it.
Approving with a change sends the edited call: the named fields as you left them, everything else exactly as the run
wrote it. The run's own draft is kept beside your edit, with who made it, and the change is kept as a learning, as a
mail reply edit is. A change to a field the gate does not name is refused (field_not_editable:<field>), and the
gate keeps waiting.
The fields are copied onto the gate when it opens, from every gate row that covers the call: a row narrowed by
match to other calls adds nothing. A version published while the gate waits does not change what that gate allows.
Fields are top-level payload fields. The list must hold at least one field name, each once, or the version is refused
(gate_editable_invalid). The OS's own built-in tools (os.*, workspace.*, memory.*, web.*) cannot name any
(gate_editable_built_in_tool): a mail reply's text can always be reworded at its gate, and nothing else of a
built-in tool's call can be changed, so an edit never runs a different command or reaches a different address.
Nor can a field a match reads be editable: one that a gate row on the same tool, its vendor or its wildcard
narrows by, or that a must-gate entry your connections mark on the tool narrows by. That field decides which rows
cover the call and who approves it, and an approved call is sent on that approval without being sorted again, so
an edit to it could carry the call past the gate that asked for it: a lead's approval of { "method": "create" }
edited into a merge only you may approve. A version naming one is refused (gate_editable_matched_field), and a
gate never records one, so the card shows it as the run wrote it.
A task created without gates
A task created without gates, over the API, from a chat, by a plan or on the portal's Create task form with
its gates left alone, is given a gate of yours on every tool it holds that reaches outside the enterprise: anything
that can publish, post, send mail, spend money or change something in another system. That is every vendor tool
except one your connected server marks read-only, and a whole vendor (slack, slack.*) as written, which covers
its reads too; os.mail_send and os.mail_reply; and each tool your connections mark must-gate, by its own name, so
a task holding all of github gets a gate on github.merge_pull_request too. A task holding os.write_plan also
gets one on os.ask_ceo, the gate a task that writes plans must carry. A vendor tool whose server cannot be
reached when the task is created is gated, read-only or not. workspace.*, memory.* and the OS's other own tools
get none. Each gate is { "owner": "ceo", "approval": "specific" }, saved on version 1 like any gate you declare, so
the CEO is asked on every such call, and you can see and remove them.
To turn this off, send gates: [] when you create the task: it is saved with no gates. A list you send is saved
exactly as given, with nothing added to it. On the portal, changing the gates on Create task, even removing every
row, sends them as they stand. The row the form adds by itself when you pick a tool that needs a gate is not a
change: unless you then edit the gates, the task gets all the gates above, that one included. A later version never
adds these gates back, and a clone keeps the gates of the task it was cloned from.
A gate you declare on a workspace.* or memory.* tool waits like any other gated call. The gate can cover:
- one tool, by its exact name, such as
workspace.git_push; - all the workspace tools, or all the memory tools, with a row naming just
workspaceormemory; - only some calls of a tool, with
match, as above.
A memory.* call is checked against the memory grants first, so a call they refuse fails as it would ungated and
nobody is asked to approve it.
A gate that covers the run's own push (on workspace.git_push, or on all the workspace tools) also stops the OS
saving the run's work for it. Without such a gate, the OS saves a run's work by committing it and pushing it to the
run's branch, a checkpoint, whenever the run waits at a gate, is handed to another worker during a release, or
stops because its model gave out or ran out of steps. With the push gated, the OS makes none of these checkpoints:
the work stays only on the worker that holds it, and is lost if that worker goes before the run pushes it. A run
handed to another worker, or resumed there from a gate, is told which files were lost, and must make those changes
again and push them before it can succeed. See
Workspaces for what a workspace can and cannot do without you, and the
built-in tools reference for which built-in tools can wait.
What happens at a gate
When a run calls a gated tool, the OS stops the call before it reaches the tool, stores exactly what would be sent
(the post, the email, the merge), and sets the run to waiting_on_gate. Nothing more happens in that run until you
decide. While it waits it holds neither its task nor its member, so other work can go on.
| Decision | What happens |
|---|---|
| Approve | The stored call runs, exactly as stored: the OS checks that what it sends is what you approved. The run carries on. |
| Reject | The call never runs. The run is cancelled and starts no successors. |
| Request changes | The call never runs. The run ends succeeded with the outcome ceo_changes_requested, and your note goes to the task that follows. Offered only when the task routes that outcome, and only with a note saying what must change. |
A decided gate cannot be decided again.
Gates with their own choices
Some gates ask what should happen, not whether a call may run. Those offer their own choices in place of Approve and Reject, each with a line saying what it does. A mail a member escalates to you offers three:
| Choice | What happens |
|---|---|
| Reply | A reply is drafted and comes back to you as its own gate before anything is sent. You can say what it should say. |
| Snooze | Nothing is sent. The mail is set aside until the date and time you pick. |
| Leave it | No reply is sent and the mail is archived. |
Each choice is still an approval or a rejection underneath, so it resumes or cancels the run in the same way. The task that runs next is told which one you chose.
Where you decide
Gates lists every gate waiting on you, oldest first, with the task, the tool, how long it has waited, and a summary when the run wrote one. A gate waiting more than an hour says so, and one waiting more than 24 hours is marked aged. You can approve or reject from the list, or pick one of a gate's own choices; Request changes, with its note, is on the run's page.
Each gate shows the person who asked for the work it belongs to: their picture, or their initials when they have none, with their name when you hover over it and on the card itself ("Asked for by …"). Work nobody asked for, such as a scheduled or webhook run, shows a Nobody asked mark instead. Only your enterprise's own people are ever named: work asked for by somebody who has since left reads as nobody asked. A person who has not given a name yet reads as Someone, with a person mark rather than initials. When the gates waiting belong to more than one person, a Person filter narrows the list to one person's work, or to the work nobody asked for, and it is kept when you leave Gates and come back. Once the person you chose has no gate left waiting, the list goes back to everyone's. Plans shows the same person and offers the same filter for each plan, taken from the gate the plan is decided through.
The same decision appears on the run's page, and in a chat when the work was started from one.
It can also be made from another system with the webhook, with an
API token scoped gates:write, or by your own agent over the MCP server
with os.decide_gate, which takes the same decision, note, answers and choice the card does.
Every gate is yours. Anyone you give access to Gates can decide one, and so can any
holder of a gates:write token or connected app, or of your webhook secret. A member never decides a gate: the OS's tools let a member see what is waiting,
never answer it.
KPIs waiting for sign-off
A KPI counts only once a person signs it off. Until then no run sees it or records a reading for it, so a scheduled
task that feeds it records nothing. Gates lists the KPIs waiting, one card per company, team, role or task that
holds them, naming them and any scheduled task that feeds them, with a link to where they are signed off. Each card
counts in the Gates badge for the enterprise's owners, and leaves once its last KPI is signed off or withdrawn. Over
the API, GET /v1/gates/kpi-sign-offs lists the same cards under the gates:read scope.
When nobody decides
A gate is never approved by silence, and an approval is never cancelled for its age. It waits until someone decides it, or until its run is cancelled. While it waits, every owner of the enterprise gets an email reminder at 24 hours and again at 48 hours, and no more after that. Each reminder joins the Needs you email, so you never get more than one an hour, and it counts what is waiting without saying what it is.
A sign-in gate is the one exception: it asks a person to sign in rather than to decide, so the enterprise's gate timeout still closes it and cancels its run.
The gate summary
A payload is evidence, not an explanation. Before it asks, a run can write what the decision is about with
os.set_gate_summary: Markdown, with at least one bullet, 40 to 6,000 characters. The gate copies it when it opens,
and Gates and the run's page lead with it. A gate marked requiresSummary always has one; any other gate shows
its payload when its run wrote none, and Gates asks you to open the run before you decide.
Questions for you
A task can put questions to you and stop, with os.ask_ceo. This is always a gate, whatever the task declares.
Each question carries the task's recommended answer, so you decide on a view rather than from nothing:
| On each question | What it does |
|---|---|
| Accept | Take the recommended answer. |
| Answer | Give your own. |
| Explain | Say what you need to know first. The answer goes on marked as needing more detail. |
Send answers needs a reply on every question, and ends the run with the outcome ceo_approved; Reject ends
it with ceo_rejected. Either way the run is answered, not cancelled, and your answers and note go to the task that
follows (see Handoffs). Answer questions in the portal or over
the API: the webhook cannot carry answers.
Merging waits for you
Merging a pull request is the decision to go live, and it is held to stricter rules:
- A task that can reach
github.merge_pull_requesthas to declare a gate on it. Listing all of GitHub (githuborgithub.*) reaches the merge as surely as naming it. A version without it is refused when you save it. - The gate has to name
github.merge_pull_requestitself. A gate ongithuborgithub.*does not count. - A run whose task has no gate on the merge is ended at the merge call, and nothing is merged.
- Which tools are held to this rule is your enterprise's setting, not the OS's. Each connection on Tools carries
its own must-gate list. A GitHub connection starts with
github.merge_pull_requeston it, and connections made before this setting existed were given the same list. A connection made while the GitHub tool's settings held no list started with none and is not given one later, so set its list yourself. A task that can reach any tool on any of your connections' lists needs a gate naming that tool. Only the CEO can change a list: send the whole list asmustGatetoPATCH /v1/tools/bindings/{id}.[]clears it, and connecting again with a new token keeps the list as it is. - An entry on a list can be narrowed to some calls of its tool:
{ "tool": "gitea.pull_request_write", "match": { "method": "merge" } }holds only the merges a pull-request tool makes, not its creates or edits. A task that can make such a call needs a gate on the tool with nomatch, or with amatchthat asks no more than the entry's ({ "method": "merge" }here). A task whose pins on the tool leave the merge out (gitea.pull_request_write#method=create,update) needs none, since it can never make that call. A task created without gates gets a gate narrowed the same way. At the call, a merge no gate of the task covers ends the run and merges nothing; a create or edit goes ahead as the task's other gates allow. - Mark the merge gate
requiresSummary, and listos.set_gate_summary: the merge is then handed back to the model until the run has written its gate summary, so it never reaches you as a bare payload. The OS asks this of no vendor's tool on its own; the gate row says it.
Once you approve a release, it stands for the rest of that execution. When the merge gate names its target with
oneAskPer (the pull request's owner, repository and number), a later merge of the same pull request in the same
execution goes ahead without asking you again, whatever its head: main moved, conflicts were resolved, the branch
was brought up to date. A new execution asks again. Rejecting the merge or asking for changes is never carried: the
next merge in that execution asks you again. Whether a head is ready to merge (up to date, its checks passed) is the
merge task's to check and your code host's branch protection to enforce; the OS reads nothing of the pull request.
A pull request has one go-live ask at a time. When a second run reaches the merge of a pull request you are already
being asked about, as when a scheduled sweep handed a failing check to a builder while the issue's own pipeline was
still on its way, the later ask replaces the earlier one: the earlier gate is cancelled as superseded, its run ends,
and you decide on the latest head and summary. Nothing is merged by the replacement, and nothing is asked twice.
Declare which fields name the target with oneAskPer on the gate
(One waiting ask per target).
A member operating a system through a browser, like a person, waits for you only on the browser actions its task gates, like any other tool. On a site its binding allows, it submits, pays, sends and deletes without asking, unless the task gates the action. Two browser actions wait whatever the task declares: an upload waits for you to approve the file, and a sign-in waits for a person to sign in. See Browser.
Over the API
| Call | Scope | What it does |
|---|---|---|
GET /v1/gates |
gates:read |
Every gate waiting on you, each with requestedBy: the person who asked for its work (id, name, avatarUrl), or null when nobody of your enterprise did. ?requestedBy=<userId> lists only that person's, and ?requestedBy=none only the ones nobody asked for. Each also carries people: the people it is for (id, name), and ?forPerson=<userId> lists only the ones waiting on that person. Without it, the whole queue returns. |
POST /v1/gates/{id}/decision |
gates:write |
Decide one. decision is approve, reject or request_changes, with an optional note, and answers for questions. A gate already decided is a 409. |