[{"data":1,"prerenderedAt":68},["ShallowReactive",2],{"$f1slbjcctbbnjj":3},{"href":4,"title":5,"description":6,"kind":7,"mark":7,"planned":8,"contributors":9,"provenance":7,"express":8,"bridge":8,"html":10,"headings":11},"\u002Fdocs\u002Fcontrol\u002Fgates","Gates and tool scopes","What a task may touch at all, and which of its calls wait for your approval before they happen.",null,false,[],"\u003Ch2 id=\"two-different-controls\">Two different controls\u003C\u002Fh2>\n\u003Cp>A task is held by two controls, and it needs both:\u003C\u002Fp>\n\u003Cdiv class=\"prose__table\">\n\u003Ctable>\n\u003Cthead>\n\u003Ctr>\n\u003Cth>Control\u003C\u002Fth>\n\u003Cth>The question it answers\u003C\u002Fth>\n\u003Cth>What it is not\u003C\u002Fth>\n\u003C\u002Ftr>\n\u003C\u002Fthead>\n\u003Ctbody>\n\u003Ctr>\n\u003Ctd>\u003Cstrong>Tool scope\u003C\u002Fstrong>\u003C\u002Ftd>\n\u003Ctd>May this task call this tool, with these values, at all?\u003C\u002Ftd>\n\u003Ctd>A review of what this run is about to send.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Cstrong>Gate\u003C\u002Fstrong>\u003C\u002Ftd>\n\u003Ctd>May this particular call happen now? You decide, on the exact payload.\u003C\u002Ftd>\n\u003Ctd>A substitute for connections with the least access they need.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003C\u002Ftbody>\n\u003C\u002Ftable>\n\u003C\u002Fdiv>\n\u003Cp>A connection that can publish does not mean a task may publish. A task that lists a tool does not mean the call goes\nout unseen. \u003Ca href=\"\u002Fdocs\u002Fwork\u002Ftasks#anatomy\">Guardrails\u003C\u002Fa> are neither: they are instructions to the model, and they stop\nnothing on their own.\u003C\u002Fp>\n\u003Ch2 id=\"tool-scopes\">Tool scopes\u003C\u002Fh2>\n\u003Ch3 id=\"which-tools-a-task-may-call\">Which tools a task may call\u003C\u002Fh3>\n\u003Cp>A task lists every tool its runs may call. A run is offered those tools and no others.\u003C\u002Fp>\n\u003Cdiv class=\"prose__table\">\n\u003Ctable>\n\u003Cthead>\n\u003Ctr>\n\u003Cth>Entry\u003C\u002Fth>\n\u003Cth>What it allows\u003C\u002Fth>\n\u003C\u002Ftr>\n\u003C\u002Fthead>\n\u003Ctbody>\n\u003Ctr>\n\u003Ctd>\u003Ccode>github\u003C\u002Fcode> or \u003Ccode>github.*\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>Every tool the GitHub connection offers, merging included, so the task must also declare the merge gate (see \u003Ca href=\"#merging-waits-for-you\">Merging\u003C\u002Fa>).\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>github.create_pull_request\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>That one tool.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>os.set_gate_summary\u003C\u002Fcode>, \u003Ccode>memory.ask\u003C\u002Fcode>, \u003Ccode>workspace.git_push\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>One of the OS's own tools. They need no connection, but a task still has to list them. See \u003Ca href=\"\u002Fdocs\u002Ftools\u002Fbuilt-in\">Built-in tools\u003C\u002Fa>.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003C\u002Ftbody>\n\u003C\u002Ftable>\n\u003C\u002Fdiv>\n\u003Cp>If the model calls a tool the task does not list, the run fails (\u003Ccode>tool_not_on_task\u003C\u002Fcode>); a name no tool answers to is\nhanded back to the model to correct instead. If a listed tool has no\nconnection, the run is blocked (\u003Ccode>tool_not_bound\u003C\u002Fcode>) until you connect it, and then carries on. See\n\u003Ca href=\"\u002Fdocs\u002Ftools\">Tools\u003C\u002Fa> for connecting one.\u003C\u002Fp>\n\u003Cp>The connection's own permissions still apply underneath. A read-only token cannot write, whatever the task lists, so\nconnect each tool with the least access the work needs.\u003C\u002Fp>\n\u003Ch3 id=\"narrowing-a-tool-to-some-values\">Narrowing a tool to some values\u003C\u002Fh3>\n\u003Cp>A task can pin a field of a tool to the values it may use, after a \u003Ccode>#\u003C\u002Fcode>. Values are separated by \u003Ccode>,\u003C\u002Fcode> and fields by\n\u003Ccode>;\u003C\u002Fcode>:\u003C\u002Fp>\n\u003Cpre>\u003Ccode>github.pull_request_review_write#method=create,submit_pending;!event=COMMENT\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>This task may create and submit reviews, and every review it submits is a comment: it can never approve a pull\nrequest or request changes on one.\u003C\u002Fp>\n\u003Cp>The model is shown the tool with only those values, so it is never offered the rest. A call with any other value is\nrefused before it reaches the tool, and handed back to the model to correct (\u003Ccode>tool_value_not_declared\u003C\u002Fcode>). A field\nwith \u003Ccode>!\u003C\u002Fcode> before it, like \u003Ccode>event\u003C\u002Fcode> here, ends the run instead (\u003Ccode>tool_value_refused\u003C\u002Fcode>).\u003C\u002Fp>\n\u003Cp>An argument the connection itself fixes, such as the organisation it works in, is taken out of what the model sees,\nso it cannot ask for another.\u003C\u002Fp>\n\u003Ch2 id=\"gates\">Gates\u003C\u002Fh2>\n\u003Ch3 id=\"declaring-a-gate\">Declaring a gate\u003C\u002Fh3>\n\u003Cp>A task version lists its gates, one per tool:\u003C\u002Fp>\n\u003Cpre>\u003Ccode class=\"language-json\">{ &quot;tool&quot;: &quot;github.add_issue_comment&quot;, &quot;owner&quot;: &quot;ceo&quot;, &quot;approval&quot;: &quot;specific&quot; }\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>A gate on a whole vendor (\u003Ccode>github\u003C\u002Fcode>) covers every tool it offers except the merge, which needs a gate of its own.\n\u003Ccode>approval\u003C\u002Fcode> is \u003Ccode>specific\u003C\u002Fcode>: every call asks. A gate that names what its calls act on (\u003Ccode>oneAskPer\u003C\u002Fcode>) asks once per\ntarget in an execution; see \u003Ca href=\"#merging-waits-for-you\">Merging\u003C\u002Fa>.\u003C\u002Fp>\n\u003Cp>A gate can be narrowed to some calls of its tool with \u003Ccode>match\u003C\u002Fcode>: the payload fields the call must carry, each equal\nto what the gate names, or, for a list, starting with it. So one command waits for you while every other command the\ntask runs goes ahead:\u003C\u002Fp>\n\u003Cpre>\u003Ccode class=\"language-json\">{\n    &quot;tool&quot;: &quot;workspace.run_command&quot;,\n    &quot;owner&quot;: &quot;ceo&quot;,\n    &quot;approval&quot;: &quot;specific&quot;,\n    &quot;match&quot;: { &quot;argv&quot;: [&quot;mise&quot;, &quot;run&quot;, &quot;os:infra:apply&quot;] },\n    &quot;requiresSummary&quot;: true\n}\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>\u003Ccode>requiresSummary\u003C\u002Fcode> holds that call back until the run has written a gate summary (the task must hold\n\u003Ccode>os.set_gate_summary\u003C\u002Fcode>), so what you approve is explained the way a merge is. A gate narrowed by \u003Ccode>match\u003C\u002Fcode> covers only\nthe calls it names: it does not stand in for a tool your connection marks as always needing a gate, only for an entry\nyour connection narrows the same way or further (see \u003Ca href=\"#merging-waits-for-you\">Merging waits for you\u003C\u002Fa>).\u003C\u002Fp>\n\u003Ch3 id=\"one-waiting-ask-per-target\">One waiting ask per target\u003C\u002Fh3>\n\u003Cp>\u003Ccode>oneAskPer\u003C\u002Fcode> names the payload fields that say what a call acts on, such as \u003Ccode>[&quot;owner&quot;, &quot;repo&quot;, &quot;index&quot;]\u003C\u002Fcode> for a pull\nrequest:\u003C\u002Fp>\n\u003Cpre>\u003Ccode class=\"language-json\">{\n    &quot;tool&quot;: &quot;gitea.pull_request_write&quot;,\n    &quot;owner&quot;: &quot;ceo&quot;,\n    &quot;approval&quot;: &quot;specific&quot;,\n    &quot;match&quot;: { &quot;method&quot;: &quot;merge&quot; },\n    &quot;oneAskPer&quot;: [&quot;owner&quot;, &quot;repo&quot;, &quot;index&quot;]\n}\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>When this gate opens, an earlier ask still waiting on the same tool from another run, with the same values for every\none of those fields, is replaced: the earlier gate is cancelled as superseded and its run ends, and you decide on the\nlatest ask only. A call missing any of the fields, or with one empty, replaces nothing. An ask already decided, and\nan ask from the same run, are left alone. The list must hold at least one field name, or the version is refused\n(\u003Ccode>gate_one_ask_per_invalid\u003C\u002Fcode>).\u003C\u002Fp>\n\u003Ch3 id=\"letting-the-approver-edit-a-call\">Letting the approver edit a call\u003C\u002Fh3>\n\u003Cp>\u003Ccode>editable\u003C\u002Fcode> names the payload fields whoever decides the gate may change before approving, such as a post's text:\u003C\u002Fp>\n\u003Cpre>\u003Ccode class=\"language-json\">{\n    &quot;tool&quot;: &quot;slack.post_message&quot;,\n    &quot;owner&quot;: &quot;ceo&quot;,\n    &quot;approval&quot;: &quot;specific&quot;,\n    &quot;editable&quot;: [&quot;text&quot;]\n}\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>The gate card shows an input for each named field the run wrote as text, and every other field as the run wrote it.\nApproving with a change sends the edited call: the named fields as you left them, everything else exactly as the run\nwrote 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\nmail reply edit is. A change to a field the gate does not name is refused (\u003Ccode>field_not_editable:&lt;field&gt;\u003C\u002Fcode>), and the\ngate keeps waiting.\u003C\u002Fp>\n\u003Cp>The fields are copied onto the gate when it opens, from every gate row that covers the call: a row narrowed by\n\u003Ccode>match\u003C\u002Fcode> to other calls adds nothing. A version published while the gate waits does not change what that gate allows.\nFields are top-level payload fields. The list must hold at least one field name, each once, or the version is refused\n(\u003Ccode>gate_editable_invalid\u003C\u002Fcode>). The OS's own built-in tools (\u003Ccode>os.*\u003C\u002Fcode>, \u003Ccode>workspace.*\u003C\u002Fcode>, \u003Ccode>memory.*\u003C\u002Fcode>, \u003Ccode>web.*\u003C\u002Fcode>) cannot name any\n(\u003Ccode>gate_editable_built_in_tool\u003C\u002Fcode>): a mail reply's text can always be reworded at its gate, and nothing else of a\nbuilt-in tool's call can be changed, so an edit never runs a different command or reaches a different address.\u003C\u002Fp>\n\u003Cp>Nor can a field a \u003Ccode>match\u003C\u002Fcode> reads be editable: one that a gate row on the same tool, its vendor or its wildcard\nnarrows by, or that a must-gate entry your connections mark on the tool narrows by. That field decides which rows\ncover the call and who approves it, and an approved call is sent on that approval without being sorted again, so\nan edit to it could carry the call past the gate that asked for it: a lead's approval of \u003Ccode>{ &quot;method&quot;: &quot;create&quot; }\u003C\u002Fcode>\nedited into a \u003Ccode>merge\u003C\u002Fcode> only you may approve. A version naming one is refused (\u003Ccode>gate_editable_matched_field\u003C\u002Fcode>), and a\ngate never records one, so the card shows it as the run wrote it.\u003C\u002Fp>\n\u003Ch3 id=\"a-task-created-without-gates\">A task created without gates\u003C\u002Fh3>\n\u003Cp>A task created without \u003Ccode>gates\u003C\u002Fcode>, over the API, from a chat, by a plan or on the portal's \u003Cstrong>Create task\u003C\u002Fstrong> form with\nits gates left alone, is given a gate of yours on every tool it holds that reaches outside the enterprise: anything\nthat can publish, post, send mail, spend money or change something in another system. That is every vendor tool\nexcept one your connected server marks read-only, and a whole vendor (\u003Ccode>slack\u003C\u002Fcode>, \u003Ccode>slack.*\u003C\u002Fcode>) as written, which covers\nits reads too; \u003Ccode>os.mail_send\u003C\u002Fcode> and \u003Ccode>os.mail_reply\u003C\u002Fcode>; and each tool your connections mark must-gate, by its own name, so\na task holding all of \u003Ccode>github\u003C\u002Fcode> gets a gate on \u003Ccode>github.merge_pull_request\u003C\u002Fcode> too. A task holding \u003Ccode>os.write_plan\u003C\u002Fcode> also\ngets one on \u003Ccode>os.ask_ceo\u003C\u002Fcode>, the gate a task that writes plans must carry. A vendor tool whose server cannot be\nreached when the task is created is gated, read-only or not. \u003Ccode>workspace.*\u003C\u002Fcode>, \u003Ccode>memory.*\u003C\u002Fcode> and the OS's other own tools\nget none. Each gate is \u003Ccode>{ &quot;owner&quot;: &quot;ceo&quot;, &quot;approval&quot;: &quot;specific&quot; }\u003C\u002Fcode>, saved on version 1 like any gate you declare, so\nthe CEO is asked on every such call, and you can see and remove them.\u003C\u002Fp>\n\u003Cp>To turn this off, send \u003Ccode>gates: []\u003C\u002Fcode> when you create the task: it is saved with no gates. A list you send is saved\nexactly as given, with nothing added to it. On the portal, changing the gates on \u003Cstrong>Create task\u003C\u002Fstrong>, even removing every\nrow, sends them as they stand. The row the form adds by itself when you pick a tool that needs a gate is not a\nchange: unless you then edit the gates, the task gets all the gates above, that one included. A later version never\nadds these gates back, and a clone keeps the gates of the task it was cloned from.\u003C\u002Fp>\n\u003Cp>A gate you declare on a \u003Ccode>workspace.*\u003C\u002Fcode> or \u003Ccode>memory.*\u003C\u002Fcode> tool waits like any other gated call. The gate can cover:\u003C\u002Fp>\n\u003Cul>\n\u003Cli>one tool, by its exact name, such as \u003Ccode>workspace.git_push\u003C\u002Fcode>;\u003C\u002Fli>\n\u003Cli>all the workspace tools, or all the memory tools, with a row naming just \u003Ccode>workspace\u003C\u002Fcode> or \u003Ccode>memory\u003C\u002Fcode>;\u003C\u002Fli>\n\u003Cli>only some calls of a tool, with \u003Ccode>match\u003C\u002Fcode>, as above.\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Cp>A \u003Ccode>memory.*\u003C\u002Fcode> call is checked against the memory grants first, so a call they refuse fails as it would ungated and\nnobody is asked to approve it.\u003C\u002Fp>\n\u003Cp>A gate that covers the run's own push (on \u003Ccode>workspace.git_push\u003C\u002Fcode>, or on all the workspace tools) also stops the OS\nsaving 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\nrun's branch, a \u003Cstrong>checkpoint\u003C\u002Fstrong>, whenever the run waits at a gate, is handed to another worker during a release, or\nstops because its model gave out or ran out of steps. With the push gated, the OS makes none of these checkpoints:\nthe work stays only on the worker that holds it, and is lost if that worker goes before the run pushes it. A run\nhanded to another worker, or resumed there from a gate, is told which files were lost, and must make those changes\nagain and push them before it can succeed. See\n\u003Ca href=\"\u002Fdocs\u002Ftools\u002Fworkspaces#what-waits-for-you\">Workspaces\u003C\u002Fa> for what a workspace can and cannot do without you, and the\n\u003Ca href=\"\u002Fdocs\u002Ftools\u002Fbuilt-in\">built-in tools reference\u003C\u002Fa> for which built-in tools can wait.\u003C\u002Fp>\n\u003Ch3 id=\"what-happens-at-a-gate\">What happens at a gate\u003C\u002Fh3>\n\u003Cp>When a run calls a gated tool, the OS stops the call before it reaches the tool, stores exactly what would be sent\n(the post, the email, the merge), and sets the run to \u003Ccode>waiting_on_gate\u003C\u002Fcode>. Nothing more happens in that run until you\ndecide. While it waits it holds neither its task nor its member, so other work can go on.\u003C\u002Fp>\n\u003Cdiv class=\"prose__table\">\n\u003Ctable>\n\u003Cthead>\n\u003Ctr>\n\u003Cth>Decision\u003C\u002Fth>\n\u003Cth>What happens\u003C\u002Fth>\n\u003C\u002Ftr>\n\u003C\u002Fthead>\n\u003Ctbody>\n\u003Ctr>\n\u003Ctd>\u003Cstrong>Approve\u003C\u002Fstrong>\u003C\u002Ftd>\n\u003Ctd>The stored call runs, exactly as stored: the OS checks that what it sends is what you approved. The run carries on.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Cstrong>Reject\u003C\u002Fstrong>\u003C\u002Ftd>\n\u003Ctd>The call never runs. The run is cancelled and starts no successors.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Cstrong>Request changes\u003C\u002Fstrong>\u003C\u002Ftd>\n\u003Ctd>The call never runs. The run ends \u003Ccode>succeeded\u003C\u002Fcode> with the outcome \u003Ccode>ceo_changes_requested\u003C\u002Fcode>, and your note goes to the task that follows. Offered only when the task \u003Ca href=\"\u002Fdocs\u002Fwork\u002Fhandoffs#your-answers-resume-the-work\">routes that outcome\u003C\u002Fa>, and only with a note saying what must change.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003C\u002Ftbody>\n\u003C\u002Ftable>\n\u003C\u002Fdiv>\n\u003Cp>A decided gate cannot be decided again.\u003C\u002Fp>\n\u003Ch3 id=\"gates-with-their-own-choices\">Gates with their own choices\u003C\u002Fh3>\n\u003Cp>Some gates ask what should happen, not whether a call may run. Those offer their own choices in place of \u003Cstrong>Approve\u003C\u002Fstrong>\nand \u003Cstrong>Reject\u003C\u002Fstrong>, each with a line saying what it does. A mail a member escalates to you offers three:\u003C\u002Fp>\n\u003Cdiv class=\"prose__table\">\n\u003Ctable>\n\u003Cthead>\n\u003Ctr>\n\u003Cth>Choice\u003C\u002Fth>\n\u003Cth>What happens\u003C\u002Fth>\n\u003C\u002Ftr>\n\u003C\u002Fthead>\n\u003Ctbody>\n\u003Ctr>\n\u003Ctd>\u003Cstrong>Reply\u003C\u002Fstrong>\u003C\u002Ftd>\n\u003Ctd>A reply is drafted and comes back to you as its own gate before anything is sent. You can say what it should say.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Cstrong>Snooze\u003C\u002Fstrong>\u003C\u002Ftd>\n\u003Ctd>Nothing is sent. The mail is set aside until the date and time you pick.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Cstrong>Leave it\u003C\u002Fstrong>\u003C\u002Ftd>\n\u003Ctd>No reply is sent and the mail is archived.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003C\u002Ftbody>\n\u003C\u002Ftable>\n\u003C\u002Fdiv>\n\u003Cp>Each choice is still an approval or a rejection underneath, so it resumes or cancels the run in the same way. The\ntask that runs next is told which one you chose.\u003C\u002Fp>\n\u003Ch3 id=\"where-you-decide\">Where you decide\u003C\u002Fh3>\n\u003Cp>\u003Cstrong>Gates\u003C\u002Fstrong> lists every gate waiting on you, oldest first, with the task, the tool, how long it has waited, and a\nsummary when the run wrote one. A gate waiting more than an hour says so, and one waiting more than 24 hours is marked\naged. You can approve or reject from the list, or pick one of a gate's own choices; \u003Cstrong>Request changes\u003C\u002Fstrong>, with its\nnote, is on the run's page.\u003C\u002Fp>\n\u003Cp>Each gate shows the person who asked for the work it belongs to: their picture, or their initials when they have\nnone, with their name when you hover over it and on the card itself (&quot;Asked for by …&quot;). Work nobody asked for, such\nas a scheduled or webhook run, shows a \u003Cstrong>Nobody asked\u003C\u002Fstrong> mark instead. Only your enterprise's own people are ever\nnamed: work asked for by somebody who has since left reads as nobody asked. A person who has not given a name yet\nreads as \u003Cstrong>Someone\u003C\u002Fstrong>, with a person mark rather than initials. When the gates waiting belong to more than one person,\na \u003Cstrong>Person\u003C\u002Fstrong> filter narrows the list to one person's work, or to the work nobody asked for, and it is kept when you\nleave \u003Cstrong>Gates\u003C\u002Fstrong> and come back. Once the person you chose has no gate left waiting, the list goes back to everyone's.\n\u003Cstrong>Plans\u003C\u002Fstrong> shows the same person and offers the same filter for each plan, taken from the gate the plan is decided\nthrough.\u003C\u002Fp>\n\u003Cp>The same decision appears on the run's page, and in a \u003Ca href=\"\u002Fdocs\u002Fwork\u002Fchat\">chat\u003C\u002Fa> when the work was started from one.\nIt can also be made from another system with the \u003Ca href=\"\u002Fdocs\u002Fapi\u002Fwebhooks#answer-a-gate\">webhook\u003C\u002Fa>, with an\n\u003Ca href=\"\u002Fdocs\u002Fapi\u002Fauthentication\">API token\u003C\u002Fa> scoped \u003Ccode>gates:write\u003C\u002Fcode>, or by your own agent over the \u003Ca href=\"\u002Fdocs\u002Fmcp\">MCP server\u003C\u002Fa>\nwith \u003Ccode>os.decide_gate\u003C\u002Fcode>, which takes the same decision, note, answers and choice the card does.\u003C\u002Fp>\n\u003Cp>Every gate is yours. Anyone you \u003Ca href=\"\u002Fdocs\u002Fcompany\u002Fpeople\">give access\u003C\u002Fa> to \u003Cstrong>Gates\u003C\u002Fstrong> can decide one, and so can any\nholder of a \u003Ccode>gates:write\u003C\u002Fcode> 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,\nnever answer it.\u003C\u002Fp>\n\u003Ch3 id=\"kpis-waiting-for-sign-off\">KPIs waiting for sign-off\u003C\u002Fh3>\n\u003Cp>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\ntask that feeds it records nothing. \u003Cstrong>Gates\u003C\u002Fstrong> lists the KPIs waiting, one card per company, team, role or task that\nholds them, naming them and any scheduled task that feeds them, with a link to where they are signed off. Each card\ncounts in the \u003Cstrong>Gates\u003C\u002Fstrong> badge for the enterprise's owners, and leaves once its last KPI is signed off or withdrawn. Over\nthe API, \u003Ccode>GET \u002Fv1\u002Fgates\u002Fkpi-sign-offs\u003C\u002Fcode> lists the same cards under the \u003Ccode>gates:read\u003C\u002Fcode> scope.\u003C\u002Fp>\n\u003Ch3 id=\"when-nobody-decides\">When nobody decides\u003C\u002Fh3>\n\u003Cp>A gate is never approved by silence, and an approval is never cancelled for its age. It waits until someone decides\nit, or until its run is cancelled. While it waits, every owner of the enterprise gets an email reminder at \u003Cstrong>24 hours\u003C\u002Fstrong>\nand again at \u003Cstrong>48 hours\u003C\u002Fstrong>, and no more after that. Each reminder joins the Needs you email, so you never get more than\none an hour, and it counts what is waiting without saying what it is.\u003C\u002Fp>\n\u003Cp>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\nstill closes it and cancels its run.\u003C\u002Fp>\n\u003Ch3 id=\"the-gate-summary\">The gate summary\u003C\u002Fh3>\n\u003Cp>A payload is evidence, not an explanation. Before it asks, a run can write what the decision is about with\n\u003Ccode>os.set_gate_summary\u003C\u002Fcode>: Markdown, with at least one bullet, 40 to 6,000 characters. The gate copies it when it opens,\nand \u003Cstrong>Gates\u003C\u002Fstrong> and the run's page lead with it. A gate marked \u003Ccode>requiresSummary\u003C\u002Fcode> always has one; any other gate shows\nits payload when its run wrote none, and \u003Cstrong>Gates\u003C\u002Fstrong> asks you to open the run before you decide.\u003C\u002Fp>\n\u003Ch2 id=\"questions-for-you\">Questions for you\u003C\u002Fh2>\n\u003Cp>A task can put questions to you and stop, with \u003Ccode>os.ask_ceo\u003C\u002Fcode>. This is always a gate, whatever the task declares.\nEach question carries the task's recommended answer, so you decide on a view rather than from nothing:\u003C\u002Fp>\n\u003Cdiv class=\"prose__table\">\n\u003Ctable>\n\u003Cthead>\n\u003Ctr>\n\u003Cth>On each question\u003C\u002Fth>\n\u003Cth>What it does\u003C\u002Fth>\n\u003C\u002Ftr>\n\u003C\u002Fthead>\n\u003Ctbody>\n\u003Ctr>\n\u003Ctd>\u003Cstrong>Accept\u003C\u002Fstrong>\u003C\u002Ftd>\n\u003Ctd>Take the recommended answer.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Cstrong>Answer\u003C\u002Fstrong>\u003C\u002Ftd>\n\u003Ctd>Give your own.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Cstrong>Explain\u003C\u002Fstrong>\u003C\u002Ftd>\n\u003Ctd>Say what you need to know first. The answer goes on marked as needing more detail.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003C\u002Ftbody>\n\u003C\u002Ftable>\n\u003C\u002Fdiv>\n\u003Cp>\u003Cstrong>Send answers\u003C\u002Fstrong> needs a reply on every question, and ends the run with the outcome \u003Ccode>ceo_approved\u003C\u002Fcode>; \u003Cstrong>Reject\u003C\u002Fstrong> ends\nit with \u003Ccode>ceo_rejected\u003C\u002Fcode>. Either way the run is answered, not cancelled, and your answers and note go to the task that\nfollows (see \u003Ca href=\"\u002Fdocs\u002Fwork\u002Fhandoffs#your-answers-resume-the-work\">Handoffs\u003C\u002Fa>). Answer questions in the portal or over\nthe API: the webhook cannot carry answers.\u003C\u002Fp>\n\u003Ch2 id=\"merging-waits-for-you\">Merging waits for you\u003C\u002Fh2>\n\u003Cp>Merging a pull request is the decision to go live, and it is held to stricter rules:\u003C\u002Fp>\n\u003Cul>\n\u003Cli>A task that can reach \u003Ccode>github.merge_pull_request\u003C\u002Fcode> has to declare a gate on it. Listing all of GitHub (\u003Ccode>github\u003C\u002Fcode> or\n\u003Ccode>github.*\u003C\u002Fcode>) reaches the merge as surely as naming it. A version without it is refused when you save it.\u003C\u002Fli>\n\u003Cli>The gate has to name \u003Ccode>github.merge_pull_request\u003C\u002Fcode> itself. A gate on \u003Ccode>github\u003C\u002Fcode> or \u003Ccode>github.*\u003C\u002Fcode> does not count.\u003C\u002Fli>\n\u003Cli>A run whose task has no gate on the merge is ended at the merge call, and nothing is merged.\u003C\u002Fli>\n\u003Cli>Which tools are held to this rule is your enterprise's setting, not the OS's. Each connection on \u003Cstrong>Tools\u003C\u002Fstrong> carries\nits own must-gate list. A GitHub connection starts with \u003Ccode>github.merge_pull_request\u003C\u002Fcode> on it, and connections made\nbefore this setting existed were given the same list. A connection made while the GitHub tool's settings held no\nlist started with none and is not given one later, so set its list yourself. A task that can reach any tool on any\nof your connections' lists needs a gate naming that tool. Only the CEO can change a list: send the whole list as\n\u003Ccode>mustGate\u003C\u002Fcode> to\n\u003Ccode>PATCH \u002Fv1\u002Ftools\u002Fbindings\u002F{id}\u003C\u002Fcode>. \u003Ccode>[]\u003C\u002Fcode> clears it, and connecting again with a new token keeps the list as it is.\u003C\u002Fli>\n\u003Cli>An entry on a list can be narrowed to some calls of its tool: \u003Ccode>{ &quot;tool&quot;: &quot;gitea.pull_request_write&quot;, &quot;match&quot;: { &quot;method&quot;: &quot;merge&quot; } }\u003C\u002Fcode> holds only the merges a pull-request tool makes, not its creates or edits. A task that can\nmake such a call needs a gate on the tool with no \u003Ccode>match\u003C\u002Fcode>, or with a \u003Ccode>match\u003C\u002Fcode> that asks no more than the entry's\n(\u003Ccode>{ &quot;method&quot;: &quot;merge&quot; }\u003C\u002Fcode> here). A task whose pins on the tool leave the merge out\n(\u003Ccode>gitea.pull_request_write#method=create,update\u003C\u002Fcode>) needs none, since it can never make that call. A task created\nwithout gates gets a gate narrowed the same way. At the call, a merge no gate of the task covers ends the run and\nmerges nothing; a create or edit goes ahead as the task's other gates allow.\u003C\u002Fli>\n\u003Cli>Mark the merge gate \u003Ccode>requiresSummary\u003C\u002Fcode>, and list \u003Ccode>os.set_gate_summary\u003C\u002Fcode>: the merge is then handed back to the model\nuntil the run has written its gate summary, so it never reaches you as a bare payload. The OS asks this of no\nvendor's tool on its own; the gate row says it.\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Cp>Once you approve a release, it stands for the rest of that execution. When the merge gate names its target with\n\u003Ccode>oneAskPer\u003C\u002Fcode> (the pull request's owner, repository and number), a later merge of the same pull request in the same\nexecution goes ahead without asking you again, whatever its head: main moved, conflicts were resolved, the branch\nwas brought up to date. A new execution asks again. Rejecting the merge or asking for changes is never carried: the\nnext merge in that execution asks you again. Whether a head is ready to merge (up to date, its checks passed) is the\nmerge task's to check and your code host's branch protection to enforce; the OS reads nothing of the pull request.\u003C\u002Fp>\n\u003Cp>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\nbeing asked about, as when a scheduled sweep handed a failing check to a builder while the issue's own pipeline was\nstill on its way, the later ask replaces the earlier one: the earlier gate is cancelled as superseded, its run ends,\nand you decide on the latest head and summary. Nothing is merged by the replacement, and nothing is asked twice.\nDeclare which fields name the target with \u003Ccode>oneAskPer\u003C\u002Fcode> on the gate\n(\u003Ca href=\"#one-waiting-ask-per-target\">One waiting ask per target\u003C\u002Fa>).\u003C\u002Fp>\n\u003Cp>A member operating a system through a browser, like a person, waits for you only on the browser actions its task\ngates, like any other tool. On a site its binding allows, it submits, pays, sends and deletes without asking, unless\nthe task gates the action. Two browser actions wait whatever the task declares: an upload waits for you to approve\nthe file, and a sign-in waits for a person to sign in. See \u003Ca href=\"\u002Fdocs\u002Ftools\u002Fbrowser#what-waits-for-you\">Browser\u003C\u002Fa>.\u003C\u002Fp>\n\u003Ch2 id=\"over-the-api\">Over the API\u003C\u002Fh2>\n\u003Cdiv class=\"prose__table\">\n\u003Ctable>\n\u003Cthead>\n\u003Ctr>\n\u003Cth>Call\u003C\u002Fth>\n\u003Cth>Scope\u003C\u002Fth>\n\u003Cth>What it does\u003C\u002Fth>\n\u003C\u002Ftr>\n\u003C\u002Fthead>\n\u003Ctbody>\n\u003Ctr>\n\u003Ctd>\u003Ccode>GET \u002Fv1\u002Fgates\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>gates:read\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>Every gate waiting on you, each with \u003Ccode>requestedBy\u003C\u002Fcode>: the person who asked for its work (\u003Ccode>id\u003C\u002Fcode>, \u003Ccode>name\u003C\u002Fcode>, \u003Ccode>avatarUrl\u003C\u002Fcode>), or \u003Ccode>null\u003C\u002Fcode> when nobody of your enterprise did. \u003Ccode>?requestedBy=&lt;userId&gt;\u003C\u002Fcode> lists only that person's, and \u003Ccode>?requestedBy=none\u003C\u002Fcode> only the ones nobody asked for. Each also carries \u003Ccode>people\u003C\u002Fcode>: the people it is for (\u003Ccode>id\u003C\u002Fcode>, \u003Ccode>name\u003C\u002Fcode>), and \u003Ccode>?forPerson=&lt;userId&gt;\u003C\u002Fcode> lists only the ones waiting on that person. Without it, the whole queue returns.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>POST \u002Fv1\u002Fgates\u002F{id}\u002Fdecision\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>gates:write\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>Decide one. \u003Ccode>decision\u003C\u002Fcode> is \u003Ccode>approve\u003C\u002Fcode>, \u003Ccode>reject\u003C\u002Fcode> or \u003Ccode>request_changes\u003C\u002Fcode>, with an optional \u003Ccode>note\u003C\u002Fcode>, and \u003Ccode>answers\u003C\u002Fcode> for questions. A gate already decided is a \u003Ccode>409\u003C\u002Fcode>.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003C\u002Ftbody>\n\u003C\u002Ftable>\n\u003C\u002Fdiv>\n",[12,16,19,23,26,29,32,35,38,41,44,47,50,53,56,59,62,65],{"id":13,"text":14,"level":15,"planned":8},"two-different-controls","Two different controls",2,{"id":17,"text":18,"level":15,"planned":8},"tool-scopes","Tool scopes",{"id":20,"text":21,"level":22,"planned":8},"which-tools-a-task-may-call","Which tools a task may call",3,{"id":24,"text":25,"level":22,"planned":8},"narrowing-a-tool-to-some-values","Narrowing a tool to some values",{"id":27,"text":28,"level":15,"planned":8},"gates","Gates",{"id":30,"text":31,"level":22,"planned":8},"declaring-a-gate","Declaring a gate",{"id":33,"text":34,"level":22,"planned":8},"one-waiting-ask-per-target","One waiting ask per target",{"id":36,"text":37,"level":22,"planned":8},"letting-the-approver-edit-a-call","Letting the approver edit a call",{"id":39,"text":40,"level":22,"planned":8},"a-task-created-without-gates","A task created without gates",{"id":42,"text":43,"level":22,"planned":8},"what-happens-at-a-gate","What happens at a gate",{"id":45,"text":46,"level":22,"planned":8},"gates-with-their-own-choices","Gates with their own choices",{"id":48,"text":49,"level":22,"planned":8},"where-you-decide","Where you decide",{"id":51,"text":52,"level":22,"planned":8},"kpis-waiting-for-sign-off","KPIs waiting for sign-off",{"id":54,"text":55,"level":22,"planned":8},"when-nobody-decides","When nobody decides",{"id":57,"text":58,"level":22,"planned":8},"the-gate-summary","The gate summary",{"id":60,"text":61,"level":15,"planned":8},"questions-for-you","Questions for you",{"id":63,"text":64,"level":15,"planned":8},"merging-waits-for-you","Merging waits for you",{"id":66,"text":67,"level":15,"planned":8},"over-the-api","Over the API",1794928142832]