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 workspace or memory;
  • 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_request has to declare a gate on it. Listing all of GitHub (github or github.*) 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_request itself. A gate on github or github.* 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_request on 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 as mustGate to PATCH /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 no match, or with a match that 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 list os.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.