[{"data":1,"prerenderedAt":44},["ShallowReactive",2],{"$f2ffp9bhswqbeu":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\u002Fapi\u002Ftasks","Tasks over the API","Create a task from code, change it without overwriting anyone else's change, start it with input, and read how the run went.",null,false,[],"\u003Cp>What a task is, and what each part of it does, is on \u003Ca href=\"\u002Fdocs\u002Fwork\u002Ftasks\">Tasks\u003C\u002Fa>. This page is the same task as JSON.\nCreating or changing a task needs \u003Ccode>tasks:write\u003C\u002Fcode>. Starting through \u003Ccode>POST \u002Fv1\u002Fruns\u003C\u002Fcode> needs \u003Ccode>runs:write\u003C\u002Fcode>;\nthe original task-specific start route needs \u003Ccode>tasks:write\u003C\u002Fcode>. Reading runs needs \u003Ccode>runs:read\u003C\u002Fcode>. See\n\u003Ca href=\"\u002Fdocs\u002Fapi\u002Fauthentication\">Authentication\u003C\u002Fa>.\u003C\u002Fp>\n\u003Ch2 id=\"a-task-as-json\">A task as JSON\u003C\u002Fh2>\n\u003Cpre>\u003Ccode class=\"language-json\">{\n    &quot;name&quot;: &quot;Triage new issues&quot;,\n    &quot;assigneeRole&quot;: &quot;support-engineer&quot;,\n    &quot;goal&quot;: &quot;Every new issue is labelled and answered within a day.&quot;,\n    &quot;metric&quot;: { &quot;text&quot;: &quot;Share of new issues labelled within 24 hours&quot; },\n    &quot;guardrails&quot;: [&quot;Never close an issue.&quot;, &quot;Never promise a release date.&quot;],\n    &quot;skillMd&quot;: &quot;# Triage an issue\\n\\n1. Read the issue.\\n2. Label it bug, feature or question.\\n3. Reply once: thank the author and say what happens next.\\n&quot;,\n    &quot;tools&quot;: [&quot;github.issue_read&quot;, &quot;github.issue_write&quot;, &quot;github.add_issue_comment&quot;],\n    &quot;gates&quot;: [{ &quot;tool&quot;: &quot;github.add_issue_comment&quot;, &quot;owner&quot;: &quot;ceo&quot;, &quot;approval&quot;: &quot;specific&quot; }],\n    &quot;inputs&quot;: [\n        { &quot;key&quot;: &quot;repo&quot;, &quot;label&quot;: &quot;Repository&quot;, &quot;type&quot;: &quot;string&quot;, &quot;required&quot;: true },\n        { &quot;key&quot;: &quot;issue&quot;, &quot;label&quot;: &quot;Issue number&quot;, &quot;type&quot;: &quot;number&quot;, &quot;required&quot;: true }\n    ],\n    &quot;spend&quot;: { &quot;moneyUsdPerRun&quot;: 0.5, &quot;maxModelTier&quot;: &quot;mid&quot; }\n}\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>Only \u003Ccode>name\u003C\u002Fcode> is required. Everything else has a default, but a task with no \u003Ccode>assigneeRole\u003C\u002Fcode> has nobody to run it, and\ncannot start a run.\u003C\u002Fp>\n\u003Cdiv class=\"prose__table\">\n\u003Ctable>\n\u003Cthead>\n\u003Ctr>\n\u003Cth>Field\u003C\u002Fth>\n\u003Cth>What it is\u003C\u002Fth>\n\u003C\u002Ftr>\n\u003C\u002Fthead>\n\u003Ctbody>\n\u003Ctr>\n\u003Ctd>\u003Ccode>name\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>Required. 1 to 200 characters.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>slug\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>Unique in your enterprise; webhooks and other tasks' successors find the task by it. Made from \u003Ccode>name\u003C\u002Fcode> when you leave it out. Either way it is cleaned: lower case, accents dropped, and every run of characters other than letters and digits turned into one \u003Ccode>-\u003C\u002Fcode>. At most 80 characters.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>assigneeRole\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>The slug of a role: each run goes to a member who holds that role and is free, on any team or on no team, the one who has waited longest first. A holder whose teams are all switched off is skipped. A task cannot be given to one member, nor to a team: a task belongs to a role, and a team has the tasks of the roles its members hold. A non-null \u003Ccode>teamId\u003C\u002Fcode> is refused with \u003Ccode>task_team_removed\u003C\u002Fcode>. See \u003Ca href=\"\u002Fdocs\u002Fcompany\u002Froles\">Roles\u003C\u002Fa>.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>kind\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>llm\u003C\u002Fcode>, the default, runs a model. \u003Ccode>deterministic\u003C\u002Fcode> runs none, and so may list no tools.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>status\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>active\u003C\u002Fcode>, the default, or \u003Ccode>deprecated\u003C\u002Fcode>. A deprecated task starts no new runs, from the API, its webhook, a schedule or the portal, and answers \u003Ccode>task_not_runnable\u003C\u002Fcode>. Runs already under way finish.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>overlapPolicy\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>skip\u003C\u002Fcode>, the default: a run waits while its member is busy with another. \u003Ccode>os\u003C\u002Fcode>: runs beside the member's other work, for a short check on a schedule that should never queue.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>serializeOn\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>The input keys that split the task's work into lanes, such as \u003Ccode>[&quot;repo&quot;, &quot;issue&quot;]\u003C\u002Fcode>. Runs in different lanes run at once; two runs in the same lane never do. Left out or \u003Ccode>null\u003C\u002Fcode>, the task has one lane: one run at a time. At most 8 keys of letters, digits, \u003Ccode>_\u003C\u002Fcode>, \u003Ccode>.\u003C\u002Fcode> and \u003Ccode>-\u003C\u002Fcode>. See \u003Ca href=\"\u002Fdocs\u002Fwork\u002Ftasks#runs-at-once\">Runs at once\u003C\u002Fa>.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>goal\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>One sentence: what the task is for.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>metric\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>{ &quot;text&quot;: &quot;…&quot; }\u003C\u002Fcode>: how you would know it works.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>guardrails\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>Rules the model must not break, one string each.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>skillMd\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>The skill, in Markdown: how to do the job. A heading with the slug until you write one.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>tools\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>Every tool a run may call: a tool name, or an object \u003Ccode>{ &quot;name&quot;: &quot;sentry&quot;, &quot;optional&quot;: true }\u003C\u002Fcode>. A run goes ahead without an optional tool no connection serves, and uses it when one does (\u003Ca href=\"\u002Fdocs\u002Fwork\u002Ftasks#optional-tools\">Optional tools\u003C\u002Fa>); \u003Ccode>optional\u003C\u002Fcode> that is not \u003Ccode>true\u003C\u002Fcode> or \u003Ccode>false\u003C\u002Fcode> is refused as \u003Ccode>tool_entry_optional_invalid\u003C\u002Fcode>. See \u003Ca href=\"\u002Fdocs\u002Fcontrol\u002Fgates#tool-scopes\">Gates and tool scopes\u003C\u002Fa>, and \u003Ca href=\"\u002Fdocs\u002Ftools\u002Fbuilt-in\">Built-in tools\u003C\u002Fa> for the OS's own.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>gates\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>The calls that wait for you: \u003Ccode>tool\u003C\u002Fcode>, \u003Ccode>owner\u003C\u002Fcode> and \u003Ccode>approval\u003C\u002Fcode>. Leave it out and the task gets a CEO gate on every tool it holds that reaches outside the enterprise: see \u003Ca href=\"\u002Fdocs\u002Fcontrol\u002Fgates#a-task-created-without-gates\">A task created without gates\u003C\u002Fa>. Send \u003Ccode>gates: []\u003C\u002Fcode> to create it with no gates, or a list, which is saved exactly as given. See \u003Ca href=\"\u002Fdocs\u002Fcontrol\u002Fgates\">Gates and tool scopes\u003C\u002Fa>.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>inputs\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>The fields a run starts with: \u003Ccode>key\u003C\u002Fcode>, \u003Ccode>label\u003C\u002Fcode>, \u003Ccode>type\u003C\u002Fcode> (\u003Ccode>string\u003C\u002Fcode> or \u003Ccode>number\u003C\u002Fcode>), and optionally \u003Ccode>required\u003C\u002Fcode>, \u003Ccode>default\u003C\u002Fcode> and \u003Ccode>placeholder\u003C\u002Fcode>. The portal's \u003Cstrong>Start a run\u003C\u002Fstrong> form is built from them.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>spend\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>moneyUsdPerRun\u003C\u002Fcode> in US dollars, and which model runs it. Leave \u003Ccode>model\u003C\u002Fcode> out, or send \u003Ccode>&quot;auto&quot;\u003C\u002Fcode>, and a model is chosen for each run, no higher than \u003Ccode>maxModelTier\u003C\u002Fcode> (\u003Ccode>economical\u003C\u002Fcode>, \u003Ccode>mid\u003C\u002Fcode> or \u003Ccode>frontier\u003C\u002Fcode>) when you set one. Send an exact \u003Ccode>model\u003C\u002Fcode> to use it for every run. \u003Ccode>spend.maxSteps\u003C\u002Fcode> is how many steps each run of the version gets, a whole number from 1 to 400. Leave it out for the default for the task's tools. A run's own input \u003Ccode>maxSteps\u003C\u002Fcode> and the operator's \u003Ccode>LLM_MAX_STEPS\u003C\u002Fcode> still win over it. See \u003Ca href=\"\u002Fdocs\u002Fcontrol\u002Fspend\">Spend and models\u003C\u002Fa>. See \u003Ca href=\"\u002Fdocs\u002Fwork\u002Fruns#steps\">Steps\u003C\u002Fa>.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>workspace\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>For a task that works in a repository: its branch, and which files it may write. See \u003Ca href=\"\u002Fdocs\u002Ftools\u002Fworkspaces\">Workspaces\u003C\u002Fa>.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>successors\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>What runs after it: each a \u003Ccode>slug\u003C\u002Fcode>, with optionally \u003Ccode>on\u003C\u002Fcode>, \u003Ccode>when\u003C\u002Fcode>, \u003Ccode>delayMinutes\u003C\u002Fcode>, \u003Ccode>maxRunsPerIssue\u003C\u002Fcode> and \u003Ccode>resumeConversation\u003C\u002Fcode>. See \u003Ca href=\"\u002Fdocs\u002Fwork\u002Fhandoffs\">Handoffs\u003C\u002Fa>.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>toolSlots\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>Slots the task's tools may be named by instead of one vendor's tool type: \u003Ccode>[{ &quot;key&quot;: &quot;codehost&quot;, &quot;label&quot;: &quot;Code host&quot;, &quot;description&quot;: &quot;…&quot; }]\u003C\u002Fcode>, at most 16. Each company fills a slot with one of its connections, and a run calls that connection's tools by its own tool type. Keys read like a tool type; \u003Ccode>os\u003C\u002Fcode>, \u003Ccode>workspace\u003C\u002Fcode>, \u003Ccode>memory\u003C\u002Fcode> and \u003Ccode>web\u003C\u002Fcode> are refused (\u003Ccode>tool_slot_key_reserved:&lt;key&gt;\u003C\u002Fcode>). A slot may declare \u003Ccode>actions\u003C\u002Fcode> (\u003Ccode>[{ &quot;name&quot;: &quot;pr.merge&quot;, &quot;description&quot;: &quot;…&quot; }]\u003C\u002Fcode>, at most 32, names of lowercase words joined by dots), which the task names under the key (\u003Ccode>codehost.pr.merge\u003C\u002Fcode>) and the filling connection maps to its own tools; refused as \u003Ccode>tool_slot_action_invalid:&lt;key&gt;.&lt;name&gt;\u003C\u002Fcode>, \u003Ccode>tool_slot_action_duplicate:&lt;key&gt;.&lt;name&gt;\u003C\u002Fcode> or \u003Ccode>tool_slot_actions_invalid:&lt;key&gt;\u003C\u002Fcode>. See \u003Ca href=\"\u002Fdocs\u002Fwork\u002Ftool-slots\">Tool slots\u003C\u002Fa>.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>callLimits\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>How often one run may make a call: \u003Ccode>[{ &quot;tool&quot;: &quot;gitea.issue_write&quot;, &quot;match&quot;: { &quot;method&quot;: &quot;create&quot; }, &quot;perRun&quot;: 2 }]\u003C\u002Fcode>, at most 16. \u003Ccode>tool\u003C\u002Fcode> is one tool the task's \u003Ccode>tools\u003C\u002Fcode> reach, by its exact name; \u003Ccode>match\u003C\u002Fcode> names fields the call must carry to count, as a gate's does; \u003Ccode>perRun\u003C\u002Fcode> is a whole number of at least 1. A call past the limit is not sent, and the run reads \u003Ccode>call_limit_reached\u003C\u002Fcode>. Refused as \u003Ccode>call_limit_tool_invalid\u003C\u002Fcode>, \u003Ccode>call_limit_match_invalid:&lt;tool&gt;\u003C\u002Fcode>, \u003Ccode>call_limit_per_run_invalid:&lt;tool&gt;\u003C\u002Fcode> or \u003Ccode>call_limits_invalid\u003C\u002Fcode>. See \u003Ca href=\"\u002Fdocs\u002Fwork\u002Ftasks#call-limits\">Call limits\u003C\u002Fa>.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>finishesOn\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>The outcomes a run ends on that finish the work, as a list of outcome words: \u003Ccode>[&quot;succeeded&quot;]\u003C\u002Fcode> for a plain success. A run that ends on one, with nothing following it, is recorded as finished, so the work is not listed on \u003Cstrong>Waiting\u003C\u002Fstrong>. At most 16 words; \u003Ccode>failed\u003C\u002Fcode> and \u003Ccode>terminal\u003C\u002Fcode> are refused (\u003Ccode>finishes_on_invalid\u003C\u002Fcode>). Left out, nothing finishes the work but a person. See \u003Ca href=\"\u002Fdocs\u002Fwork\u002Fhandoffs#finished-work\">Finished work\u003C\u002Fa>.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>maxRunsPerExecution\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>The most times this task may run in one execution before its next start is logged or stopped for you, as a whole number of at least 1 (\u003Ccode>execution_cap_invalid\u003C\u002Fcode> otherwise, the same check as a successor's \u003Ccode>maxRunsPerIssue\u003C\u002Fcode>). Counted per task across the whole execution, whichever handoff started each run and whether or not it names an issue or pull request. Left out or \u003Ccode>null\u003C\u002Fcode>, the deployment's \u003Ccode>EXECUTION_MAX_TASK_RUNS\u003C\u002Fcode> applies (10 unless it says otherwise). It is never applied below the highest \u003Ccode>maxRunsPerIssue\u003C\u002Fcode> on a handoff into the task. A CEO decision, or your Retry, starts the count again.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>mailboxAction\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>Where a mailbox offers the task as a one-click button, as \u003Ccode>{ &quot;on&quot;: &quot;mailbox&quot; | &quot;mail&quot;, &quot;label&quot;: &quot;Clean inbox&quot; }\u003C\u002Fcode>. \u003Ccode>mailbox\u003C\u002Fcode> is a button above the mailbox's list; \u003Ccode>mail\u003C\u002Fcode> is a button on one open message, which starts the run with that message's id as its \u003Ccode>emailId\u003C\u002Fcode> input, so the version has to declare an input with that key (\u003Ccode>mailbox_action_needs_email_input\u003C\u002Fcode>). The label is the button's words, at most 40 characters (\u003Ccode>mailbox_action_label_invalid\u003C\u002Fcode>); an unknown \u003Ccode>on\u003C\u002Fcode> is \u003Ccode>mailbox_action_invalid\u003C\u002Fcode>. A person's inbox offers every task of the enterprise that declares one, and every public template that does and nobody cloned; a member's page offers those that run as a role the member holds. Left out, the task puts no button anywhere. See \u003Ca href=\"\u002Fdocs\u002Fcompany\u002Fpeople#a-persons-mailbox\">A person's mailbox\u003C\u002Fa>.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003C\u002Ftbody>\n\u003C\u002Ftable>\n\u003C\u002Fdiv>\n\u003Ch2 id=\"create-a-task\">Create a task\u003C\u002Fh2>\n\u003Cpre>\u003Ccode class=\"language-bash\">curl -X POST https:\u002F\u002Fapi.zerohuman.com\u002Fv1\u002Ftasks \\\n  -H &quot;Authorization: Bearer zhos_…&quot; \\\n  -H &quot;content-type: application\u002Fjson&quot; \\\n  -d @triage-new-issues.json\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>It answers \u003Ccode>201\u003C\u002Fcode> with the task, as \u003Ccode>GET \u002Fv1\u002Ftasks\u002F{id}\u003C\u002Fcode> reads it:\u003C\u002Fp>\n\u003Cdiv class=\"prose__table\">\n\u003Ctable>\n\u003Cthead>\n\u003Ctr>\n\u003Cth>Field\u003C\u002Fth>\n\u003Cth>What it is\u003C\u002Fth>\n\u003C\u002Ftr>\n\u003C\u002Fthead>\n\u003Ctbody>\n\u003Ctr>\n\u003Ctd>\u003Ccode>id\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>The task's id. Every other call names the task by it.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>slug\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>The slug it was given: \u003Ccode>triage-new-issues\u003C\u002Fcode> here.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>currentVersionId\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>Its current version's id. Send it as \u003Ccode>baseVersionId\u003C\u002Fcode> when you change the task.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>currentVersion\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>The current version's definition.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>skillMd\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>The current skill.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>versions\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>Every version, newest first, with how many runs used each.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>definitionIssues\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>What the \u003Ca href=\"#the-checks\">checks\u003C\u002Fa> found that did not stop it saving.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>teams\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>The teams that have the task, each \u003Ccode>{ &quot;id&quot;, &quot;slug&quot;, &quot;name&quot; }\u003C\u002Fcode>: every team a member who holds its role sits on or leads. Read-only, and empty while nobody on a team holds the role.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>webhook\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>The URL that starts it from another system, and the header your webhook secret goes in. See \u003Ca href=\"\u002Fdocs\u002Fapi\u002Fwebhooks\">Webhooks\u003C\u002Fa>.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>canEditDefinition\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>false\u003C\u002Fcode> for a clone, whose definition belongs to the original's owner, and for the OS's own tasks, which are the same in every enterprise and change only with a release of the OS.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003C\u002Ftbody>\n\u003C\u002Ftable>\n\u003C\u002Fdiv>\n\u003Cdiv class=\"prose__table\">\n\u003Ctable>\n\u003Cthead>\n\u003Ctr>\n\u003Cth>Status\u003C\u002Fth>\n\u003Cth>Code\u003C\u002Fth>\n\u003Cth>Why\u003C\u002Fth>\n\u003C\u002Ftr>\n\u003C\u002Fthead>\n\u003Ctbody>\n\u003Ctr>\n\u003Ctd>\u003Ccode>400\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>invalid_name\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>name\u003C\u002Fcode> is empty, or longer than 200 characters.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>400\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>invalid_slug\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>The slug is empty once cleaned, or longer than 80 characters.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>400\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>invalid_task_definition\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>The definition fails one of \u003Ca href=\"#the-checks\">the checks\u003C\u002Fa>.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>400\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>llm_model_not_in_catalogue\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>spend.model\u003C\u002Fcode> is not a model your connected provider offers. \u003Ccode>GET \u002Fv1\u002Fllm\u002Fmodels\u003C\u002Fcode> lists them.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>400\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>spend_max_steps_invalid\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>spend.maxSteps\u003C\u002Fcode> is not a whole number from 1 to 400.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>400\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>assignee_member_removed\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>The body names a member in \u003Ccode>assigneeMemberId\u003C\u002Fcode>. A task is given to a role: send \u003Ccode>assigneeRole\u003C\u002Fcode>.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>400\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>serialize_on_invalid\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>serializeOn\u003C\u002Fcode> is not \u003Ccode>null\u003C\u002Fcode> or a list of up to 8 input keys.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>400\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>task_team_removed\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>The body names a \u003Ccode>teamId\u003C\u002Fcode>. A task belongs to a role, not a team: seat a holder of its role on the team instead.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>409\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>task_slug_taken\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>Your enterprise already has a task with that slug.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003C\u002Ftbody>\n\u003C\u002Ftable>\n\u003C\u002Fdiv>\n\u003Ch3 id=\"a-task-that-merges\">A task that merges\u003C\u002Fh3>\n\u003Cp>A task that can merge a pull request must declare a gate on the merge. Mark the gate \u003Ccode>requiresSummary\u003C\u002Fcode> and hold\n\u003Ccode>os.set_gate_summary\u003C\u002Fcode> so its run has to tell you what you are approving. Send all three in the same call:\u003C\u002Fp>\n\u003Cpre>\u003Ccode class=\"language-json\">{\n    &quot;name&quot;: &quot;Merge approved pull requests&quot;,\n    &quot;assigneeRole&quot;: &quot;release-engineer&quot;,\n    &quot;tools&quot;: [&quot;github.pull_request_read&quot;, &quot;github.merge_pull_request&quot;, &quot;os.set_gate_summary&quot;],\n    &quot;gates&quot;: [{ &quot;tool&quot;: &quot;github.merge_pull_request&quot;, &quot;owner&quot;: &quot;ceo&quot;, &quot;approval&quot;: &quot;specific&quot;, &quot;requiresSummary&quot;: true }]\n}\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>If you leave \u003Ccode>gates\u003C\u002Fcode> out, the task is given that gate along with its other defaults, so this refusal does not apply.\nIf you send \u003Ccode>gates\u003C\u002Fcode> without a gate on the merge, \u003Ccode>gates: []\u003C\u002Fcode> included, the call is refused with\n\u003Ccode>gate_required_for_tool\u003C\u002Fcode>.\nThat holds however \u003Ccode>tools\u003C\u002Fcode> reaches the merge:\nby its name, or through \u003Ccode>github\u003C\u002Fcode> or \u003Ccode>github.*\u003C\u002Fcode>, which hold every GitHub tool. The gate must name\n\u003Ccode>github.merge_pull_request\u003C\u002Fcode> itself: a gate on \u003Ccode>github\u003C\u002Fcode> or \u003Ccode>github.*\u003C\u002Fcode> does not count. If a task without that gate\nreaches a run anyway, the run ends at the merge call with \u003Ccode>gate_required_for_tool\u003C\u002Fcode>, and nothing is merged.\u003C\u002Fp>\n\u003Cp>The merge is on this rule because your GitHub connection marks it must-gate. Every connection carries such a list\n(\u003Ccode>mustGate\u003C\u002Fcode> on \u003Ccode>GET \u002Fv1\u002Ftools\u002Fbindings\u003C\u002Fcode>), a GitHub connection starts with the merge on it, and only the CEO can change\nit. Create, save and a new version are all checked against the lists of every connection your enterprise has. See\n\u003Ca href=\"\u002Fdocs\u002Fcontrol\u002Fgates#merging-waits-for-you\">Gates\u003C\u002Fa>.\u003C\u002Fp>\n\u003Ch2 id=\"the-checks\">The checks\u003C\u002Fh2>\n\u003Cp>Creating a task and saving a version both check the definition against your enterprise's other tasks. An error\nrefuses the call with a \u003Ccode>400\u003C\u002Fcode>:\u003C\u002Fp>\n\u003Cpre>\u003Ccode class=\"language-json\">{\n    &quot;error&quot;: &quot;invalid_task_definition&quot;,\n    &quot;message&quot;: &quot;A deterministic task has no model to call its tools, so every run fails. Use kind \\&quot;llm\\&quot;.&quot;,\n    &quot;issues&quot;: [\n        {\n            &quot;severity&quot;: &quot;error&quot;,\n            &quot;code&quot;: &quot;deterministic_with_tools&quot;,\n            &quot;message&quot;: &quot;A deterministic task has no model to call its tools, so every run fails. Use kind \\&quot;llm\\&quot;.&quot;\n        }\n    ]\n}\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>\u003Ccode>message\u003C\u002Fcode> joins every error's sentence, and \u003Ccode>issues\u003C\u002Fcode> lists them one by one. A warning does not refuse the call: it\nis listed in the task's \u003Ccode>definitionIssues\u003C\u002Fcode> (read the task after a save to see them) and, for an active task, on\n\u003Ccode>GET \u002Fv1\u002Fblockers\u003C\u002Fcode> under \u003Ccode>taskProblems\u003C\u002Fcode>, until you fix it. A warning about a task your enterprise does not have\nalso carries \u003Ccode>missingTask\u003C\u002Fcode>, that task's slug, so you can look for it in the catalog (\u003Ccode>GET \u002Fv1\u002Fcatalog\u002Ftasks?search=\u003C\u002Fcode>).\u003C\u002Fp>\n\u003Cdiv class=\"prose__table\">\n\u003Ctable>\n\u003Cthead>\n\u003Ctr>\n\u003Cth>Code\u003C\u002Fth>\n\u003Cth>Severity\u003C\u002Fth>\n\u003Cth>When\u003C\u002Fth>\n\u003C\u002Ftr>\n\u003C\u002Fthead>\n\u003Ctbody>\n\u003Ctr>\n\u003Ctd>\u003Ccode>gate_required_for_tool\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>error\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>tools\u003C\u002Fcode> can reach a tool one of the enterprise's bindings marks must-gate (GitHub's \u003Ccode>github.merge_pull_request\u003C\u002Fcode>, when its binding carries the GitHub tool's defaults), by its name or through \u003Ccode>github\u003C\u002Fcode> or \u003Ccode>github.*\u003C\u002Fcode>, and \u003Ccode>gates\u003C\u002Fcode> declares no gate naming it; or \u003Ccode>tools\u003C\u002Fcode> lists \u003Ccode>os.mail_send\u003C\u002Fcode> and \u003Ccode>gates\u003C\u002Fcode> declares no gate on it; or \u003Ccode>tools\u003C\u002Fcode> lists \u003Ccode>os.write_plan\u003C\u002Fcode> and \u003Ccode>gates\u003C\u002Fcode> declares no gate on \u003Ccode>os.ask_ceo\u003C\u002Fcode>. Left out, \u003Ccode>gates\u003C\u002Fcode> gets each of these, so only a list you send can be refused.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>gate_summary_tool_required\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>error\u003C\u002Ftd>\n\u003Ctd>A gate is marked \u003Ccode>requiresSummary\u003C\u002Fcode>, or \u003Ccode>tools\u003C\u002Fcode> lists \u003Ccode>os.mail_reply\u003C\u002Fcode>, but \u003Ccode>tools\u003C\u002Fcode> does not list \u003Ccode>os.set_gate_summary\u003C\u002Fcode>.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>deterministic_with_tools\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>error\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>kind\u003C\u002Fcode> is \u003Ccode>deterministic\u003C\u002Fcode> and \u003Ccode>tools\u003C\u002Fcode> is not empty.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>successor_when_unknown\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>error\u003C\u002Ftd>\n\u003Ctd>A successor's \u003Ccode>when\u003C\u002Fcode> is not \u003Ccode>has_issue\u003C\u002Fcode>, \u003Ccode>has_pr\u003C\u002Fcode>, \u003Ccode>no_pr\u003C\u002Fcode>, \u003Ccode>has_work_item\u003C\u002Fcode> or \u003Ccode>no_work_item\u003C\u002Fcode>.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>successor_cap_invalid\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>error\u003C\u002Ftd>\n\u003Ctd>A successor's \u003Ccode>maxRunsPerIssue\u003C\u002Fcode> is not a whole number of at least 1.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>execution_cap_invalid\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>error\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>maxRunsPerExecution\u003C\u002Fcode> is set and is not a whole number of at least 1.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>successor_delay_invalid\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>error\u003C\u002Ftd>\n\u003Ctd>A successor's \u003Ccode>delayMinutes\u003C\u002Fcode> is not more than 0 and at most 1440.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>unconditional_loop\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>error\u003C\u002Ftd>\n\u003Ctd>Successors on \u003Ccode>terminal\u003C\u002Fcode> lead back to this task, so it would restart for ever.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>call_limit_tool_not_declared\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>error\u003C\u002Ftd>\n\u003Ctd>A call limit names a tool the task's \u003Ccode>tools\u003C\u002Fcode> do not reach, so it would limit nothing.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>successor_unknown_slug\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>warning\u003C\u002Ftd>\n\u003Ctd>A successor names a task your enterprise does not have, so the work stops there.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>tool_slot_unused\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>warning\u003C\u002Ftd>\n\u003Ctd>A slot is declared in \u003Ccode>toolSlots\u003C\u002Fcode>, but no tool or gate is named by it, so filling it changes nothing.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>tool_slot_action_undeclared\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>warning\u003C\u002Ftd>\n\u003Ctd>A tool or gate is named under a slot that declares actions, but it is not one of them, so it is one server's own tool name and the task runs only where that server fills the slot.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>outcome_not_routed:&lt;word&gt;\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>warning\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>skillMd\u003C\u002Fcode> tells a run to end on \u003Ccode>{&quot;outcome&quot;:&quot;&lt;word&gt;&quot;}\u003C\u002Fcode>, and no successor routes that word, \u003Ccode>finishesOn\u003C\u002Fcode> does not list it, and it is not \u003Ccode>succeeded\u003C\u002Fcode> or \u003Ccode>ok\u003C\u002Fcode>, so a run that ends on it stops as a dead end. One per word. An outcome \u003Ccode>finishesOn\u003C\u002Fcode> lists always finishes the work, so it is never one.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>self_loop_unconditional\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>warning\u003C\u002Ftd>\n\u003Ctd>A successor names the task's own slug on \u003Ccode>succeeded\u003C\u002Fcode> (or with no \u003Ccode>on\u003C\u002Fcode>) or on a named outcome, with no \u003Ccode>delayMinutes\u003C\u002Fcode>, so every run that ends that way starts another. \u003Ccode>ceo_approved\u003C\u002Fcode>, \u003Ccode>ceo_changes_requested\u003C\u002Fcode> and a delayed successor are not.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>asks_ceo_without_resume\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>warning\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>tools\u003C\u002Fcode> reach \u003Ccode>os.ask_ceo\u003C\u002Fcode>, \u003Ccode>skillMd\u003C\u002Fcode> names another of the task's tools after it, and no successor on \u003Ccode>ceo_approved\u003C\u002Fcode> names the task's own slug, so nothing resumes the work once the CEO answers.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003C\u002Ftbody>\n\u003C\u002Ftable>\n\u003C\u002Fdiv>\n\u003Cp>These three are warnings on \u003Ccode>POST \u002Fv1\u002Ftasks\u003C\u002Fcode> and \u003Ccode>POST \u002Fv1\u002Ftasks\u002F{id}\u002Fversions\u003C\u002Fcode>: the task or version is saved and\n\u003Ccode>definitionIssues\u003C\u002Fcode> lists them. A create made through the OS's own MCP server (\u003Ccode>os.create_task\u003C\u002Fcode>) is refused with \u003Ccode>400\u003C\u002Fcode>\nand \u003Ccode>error: &quot;definition_issues&quot;\u003C\u002Fcode>, listing each in \u003Ccode>issues\u003C\u002Fcode>, and nothing is saved.\u003C\u002Fp>\n\u003Ch2 id=\"change-a-task\">Change a task\u003C\u002Fh2>\n\u003Cp>\u003Ccode>POST \u002Fv1\u002Ftasks\u002F{id}\u002Fversions\u003C\u002Fcode> publishes the task's next version. Send only what changes: every field you leave\nout keeps its value from the current version, \u003Ccode>skillMd\u003C\u002Fcode> included. To clear \u003Ccode>inputs\u003C\u002Fcode>, \u003Ccode>workspace\u003C\u002Fcode>, \u003Ccode>successors\u003C\u002Fcode>,\n\u003Ccode>finishesOn\u003C\u002Fcode>, \u003Ccode>toolSlots\u003C\u002Fcode>, \u003Ccode>callLimits\u003C\u002Fcode>, \u003Ccode>mailboxAction\u003C\u002Fcode> or \u003Ccode>maxRunsPerExecution\u003C\u002Fcode>, send \u003Ccode>null\u003C\u002Fcode>.\u003C\u002Fp>\n\u003Cp>Send \u003Ccode>baseVersionId\u003C\u002Fcode> too: the \u003Ccode>currentVersionId\u003C\u002Fcode> you read before you made your change. It is required: a save\nwithout one is refused, and the task is left as it was:\u003C\u002Fp>\n\u003Cpre>\u003Ccode class=\"language-json\">{\n    &quot;error&quot;: &quot;base_version_required&quot;,\n    &quot;message&quot;: &quot;base_version_required: name the version this change was made from (baseVersionId). Read the task and send its currentVersionId.&quot;,\n    &quot;statusCode&quot;: 400\n}\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cpre>\u003Ccode class=\"language-bash\">curl -X POST https:\u002F\u002Fapi.zerohuman.com\u002Fv1\u002Ftasks\u002F$TASK_ID\u002Fversions \\\n  -H &quot;Authorization: Bearer zhos_…&quot; \\\n  -H &quot;content-type: application\u002Fjson&quot; \\\n  -d '{\n    &quot;baseVersionId&quot;: &quot;0b7c4a52-3d1e-4f6a-8c2b-9e5d7a1f3c60&quot;,\n    &quot;guardrails&quot;: [&quot;Never close an issue.&quot;, &quot;Never promise a release date.&quot;, &quot;Reply in English.&quot;]\n  }'\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>It answers \u003Ccode>201\u003C\u002Fcode> with the new version: its \u003Ccode>id\u003C\u002Fcode>, its \u003Ccode>version\u003C\u002Fcode> number, its definition and \u003Ccode>&quot;unchanged&quot;: false\u003C\u002Fcode>.\nThat \u003Ccode>id\u003C\u002Fcode> is your next \u003Ccode>baseVersionId\u003C\u002Fcode>.\u003C\u002Fp>\n\u003Cp>A save whose definition and skill are the same as the current version's publishes nothing. It answers \u003Ccode>201\u003C\u002Fcode> with\nthe current version and \u003Ccode>&quot;unchanged&quot;: true\u003C\u002Fcode>: the version history records decisions, and that save decided nothing.\u003C\u002Fp>\n\u003Cp>If someone published a version after the one you read (a person, a script, a plan, or a self-improvement change you\napproved), your save is refused, so it cannot put the older definition back over theirs. The refusal names the\nversion that is current now:\u003C\u002Fp>\n\u003Cpre>\u003Ccode class=\"language-json\">{\n    &quot;message&quot;: &quot;task_version_conflict&quot;,\n    &quot;error&quot;: &quot;Conflict&quot;,\n    &quot;statusCode&quot;: 409,\n    &quot;currentVersionId&quot;: &quot;5d1f0c3e-7a2b-4e8d-9c6f-1b3a5e7d9f20&quot;,\n    &quot;currentVersion&quot;: 4\n}\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>Read that version, make your change to what is there now, and save against its id. Two saves made from the same\nread at the same moment give one new version and one refusal.\u003C\u002Fp>\n\u003Cp>The same call takes the task's own fields: \u003Ccode>name\u003C\u002Fcode>, \u003Ccode>slug\u003C\u002Fcode>, \u003Ccode>assigneeRole\u003C\u002Fcode>, \u003Ccode>serializeOn\u003C\u002Fcode>, \u003Ccode>status\u003C\u002Fcode> and \u003Ccode>kind\u003C\u002Fcode>. These are\nnot part of a version. They change the task at once, and the version history does not record them; a save that\nchanges only these publishes no version. A new \u003Ccode>slug\u003C\u002Fcode> changes the task's webhook URL, and successors that name the\nold slug no longer find it. It is cleaned as it is when you create a task: lower case, accents dropped, every run of\ncharacters other than letters and digits turned into one \u003Ccode>-\u003C\u002Fcode>, at most 80 characters. A slug another task of your\nenterprise has is refused, and the task is left as it was: no new version, and no other field of the save applied.\nSending the slug the task already has, exactly as you read it, is no rename: it is neither cleaned nor checked.\u003C\u002Fp>\n\u003Cdiv class=\"prose__table\">\n\u003Ctable>\n\u003Cthead>\n\u003Ctr>\n\u003Cth>Status\u003C\u002Fth>\n\u003Cth>Code\u003C\u002Fth>\n\u003Cth>Why\u003C\u002Fth>\n\u003C\u002Ftr>\n\u003C\u002Fthead>\n\u003Ctbody>\n\u003Ctr>\n\u003Ctd>\u003Ccode>400\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>base_version_required\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>The body names no \u003Ccode>baseVersionId\u003C\u002Fcode>.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>400\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>invalid_slug\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>The new slug is empty once cleaned, or longer than 80 characters.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>400\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>invalid_task_definition\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>The new version fails one of \u003Ca href=\"#the-checks\">the checks\u003C\u002Fa>.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>400\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>assignee_member_removed\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>The body names a member in \u003Ccode>assigneeMemberId\u003C\u002Fcode>. A task is given to a role: send \u003Ccode>assigneeRole\u003C\u002Fcode>.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>400\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>task_team_removed\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>The body names a \u003Ccode>teamId\u003C\u002Fcode>. A task belongs to a role, not a team.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>400\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>serialize_on_invalid\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>serializeOn\u003C\u002Fcode> is not \u003Ccode>null\u003C\u002Fcode> or a list of up to 8 input keys.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>400\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>skillMd_required\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>The skill would be empty.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>400\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>llm_model_not_in_catalogue\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>spend.model\u003C\u002Fcode> is not a model your connected provider offers.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>400\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>spend_max_steps_invalid\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>spend.maxSteps\u003C\u002Fcode> is not a whole number from 1 to 400.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>403\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>task_definition_read_only\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>The task is a clone: its definition belongs to the original's owner. Copy it to make your own.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>404\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>task_not_found\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>No task with that id in your enterprise.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>409\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>task_version_conflict\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>Someone published a newer version than your \u003Ccode>baseVersionId\u003C\u002Fcode>. The body names it: \u003Ccode>currentVersionId\u003C\u002Fcode>, \u003Ccode>currentVersion\u003C\u002Fcode>.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>409\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>task_slug_taken\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>Another task in your enterprise already has the new slug, once cleaned.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>409\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>os_task_immutable\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>It is one of the OS's own tasks: the same in every enterprise, changed only with a release of the OS, never through the API.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003C\u002Ftbody>\n\u003C\u002Ftable>\n\u003C\u002Fdiv>\n\u003Cp>Saving a version declines any self-improvement recommendation still waiting on the task, since it was written\nagainst the version before. See \u003Ca href=\"\u002Fdocs\u002Fcontrol\u002Fself-improvement\">Self-improvement\u003C\u002Fa>.\u003C\u002Fp>\n\u003Ch3 id=\"publishing-to-the-catalogue\">Publishing to the catalogue\u003C\u002Fh3>\n\u003Cp>Add \u003Ccode>&quot;visibility&quot;: &quot;public&quot;\u003C\u002Fcode> to a save to put the task in the catalogue, where other companies can clone it. It also\nneeds \u003Ccode>catalog:write\u003C\u002Fcode>, and a plan that includes catalog publishing. \u003Ccode>&quot;visibility&quot;: &quot;private&quot;\u003C\u002Fcode> takes it out again;\ncompanies that already cloned it keep what they have.\u003C\u002Fp>\n\u003Cp>You publish once. From then on, every version you save, with no \u003Ccode>visibility\u003C\u002Fcode>, goes to the catalogue too, and companies\nthat cloned the task are offered it as an update. A quiet one, which changes no tool, gate, input or workspace, reaches\ntheir clones automatically where they keep auto-update on (see \u003Ca href=\"\u002Fdocs\u002Fwork\u002Ftasks#clone-and-copy\">Clone and copy\u003C\u002Fa>).\nA save that changes nothing sends nothing.\u003C\u002Fp>\n\u003Cp>A version the catalogue turns down never stops your own save. The version is saved, the catalogue keeps the version\nit had, and the answer's \u003Ccode>catalogPublication\u003C\u002Fcode> says why:\u003C\u002Fp>\n\u003Cpre>\u003Ccode class=\"language-json\">{\n    &quot;id&quot;: &quot;…&quot;,\n    &quot;version&quot;: 8,\n    &quot;unchanged&quot;: false,\n    &quot;catalogPublication&quot;: {\n        &quot;id&quot;: &quot;…&quot;,\n        &quot;visibility&quot;: &quot;public&quot;,\n        &quot;version&quot;: 3,\n        &quot;sourceVersion&quot;: 7,\n        &quot;updated&quot;: false,\n        &quot;refusal&quot;: {\n            &quot;error&quot;: &quot;catalog_tenant_content&quot;,\n            &quot;message&quot;: &quot;Remove tenant-specific passages before publishing to the catalog: skillMd: …&quot;,\n            &quot;passages&quot;: [{ &quot;field&quot;: &quot;skillMd&quot;, &quot;identifier&quot;: &quot;…&quot;, &quot;passage&quot;: &quot;…&quot; }]\n        }\n    }\n}\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>\u003Ccode>version\u003C\u002Fcode> is the catalogue's own version number and \u003Ccode>sourceVersion\u003C\u002Fcode> the version of yours it holds. \u003Ccode>updated\u003C\u002Fcode> is\n\u003Ccode>true\u003C\u002Fcode> when this save reached the catalogue. When it is \u003Ccode>false\u003C\u002Fcode>, \u003Ccode>refusal\u003C\u002Fcode> says why, or is \u003Ccode>null\u003C\u002Fcode> when the save made\nno new version. Fix what it names and save again, or send \u003Ccode>&quot;visibility&quot;: &quot;public&quot;\u003C\u002Fcode>, and the catalogue catches up.\u003C\u002Fp>\n\u003Cdiv class=\"prose__table\">\n\u003Ctable>\n\u003Cthead>\n\u003Ctr>\n\u003Cth>Code\u003C\u002Fth>\n\u003Cth>Why the catalogue kept its version\u003C\u002Fth>\n\u003C\u002Ftr>\n\u003C\u002Fthead>\n\u003Ctbody>\n\u003Ctr>\n\u003Ctd>\u003Ccode>catalog_tenant_content\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>The version names your company, a member, one of your domains or something a connection is bound to. \u003Ccode>passages\u003C\u002Fcode> lists each one.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>template_tools_missing\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>The version names no tool. A clone needs to know what to connect.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>catalog_publish_not_in_plan\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>Your plan no longer includes catalog publishing. \u003Ccode>upgradePath\u003C\u002Fcode> says where to change it.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>catalog_entry_deprecated\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>You deprecated the catalogue entry. It stays as it is until you publish with \u003Ccode>&quot;visibility&quot;: &quot;public&quot;\u003C\u002Fcode> again.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003C\u002Ftbody>\n\u003C\u002Ftable>\n\u003C\u002Fdiv>\n\u003Cp>A save that carries \u003Ccode>&quot;visibility&quot;: &quot;public&quot;\u003C\u002Fcode> is refused outright for the same reasons, and then nothing is saved.\u003C\u002Fp>\n\u003Ch3 id=\"versions\">Versions\u003C\u002Fh3>\n\u003Cp>\u003Ccode>GET \u002Fv1\u002Ftasks\u002F{id}\u002Fversions\u003C\u002Fcode> lists every version, newest first. \u003Ccode>GET \u002Fv1\u002Ftasks\u002F{id}\u002Fversions\u002F{versionId}\u003C\u002Fcode> reads\none as it was, with its \u003Ccode>skillMd\u003C\u002Fcode>, how many runs used it, and whether it is \u003Ccode>current\u003C\u002Fcode>. A version never changes\nonce saved. To go back to an earlier one, read it and publish its fields as a new version.\u003C\u002Fp>\n\u003Ch2 id=\"start-a-run\">Start a run\u003C\u002Fh2>\n\u003Cp>\u003Ccode>POST \u002Fv1\u002Ftasks\u002F{id}\u002Fruns\u003C\u002Fcode> starts a run on the task's current version. The body is the run's input, a JSON object:\u003C\u002Fp>\n\u003Cpre>\u003Ccode class=\"language-bash\">curl -X POST https:\u002F\u002Fapi.zerohuman.com\u002Fv1\u002Ftasks\u002F$TASK_ID\u002Fruns \\\n  -H &quot;Authorization: Bearer zhos_…&quot; \\\n  -H &quot;content-type: application\u002Fjson&quot; \\\n  -d '{&quot;repo&quot;: &quot;acme\u002Fweb&quot;, &quot;issue&quot;: 128}'\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>It answers \u003Ccode>201\u003C\u002Fcode> with the new run and its \u003Ccode>id\u003C\u002Fcode>. The run is \u003Ccode>queued\u003C\u002Fcode>, or \u003Ccode>pending\u003C\u002Fcode> when the task already has a run\nunder way or every member holding its role is busy: a \u003Ccode>pending\u003C\u002Fcode> run starts when the task and a holder of its role are\nfree. A run waiting at a gate does not make either busy.\u003C\u002Fp>\n\u003Cp>The body becomes the run's input as sent. It is not checked against the task's \u003Ccode>inputs\u003C\u002Fcode>, and their defaults are\nnot filled in, so send every value the run needs.\u003C\u002Fp>\n\u003Cp>\u003Ccode>{id}\u003C\u002Fcode> is the task's id. To find it from the slug, \u003Ccode>GET \u002Fv1\u002Ftasks?slug=triage-new-issues\u003C\u002Fcode> lists the tasks whose\nslug contains it. A \u003Ca href=\"\u002Fdocs\u002Fapi\u002Fwebhooks\">webhook\u003C\u002Fa> starts a task by its slug instead, with your webhook secret\nrather than a token.\u003C\u002Fp>\n\u003Cdiv class=\"prose__table\">\n\u003Ctable>\n\u003Cthead>\n\u003Ctr>\n\u003Cth>Status\u003C\u002Fth>\n\u003Cth>Code\u003C\u002Fth>\n\u003Cth>Why\u003C\u002Fth>\n\u003C\u002Ftr>\n\u003C\u002Fthead>\n\u003Ctbody>\n\u003Ctr>\n\u003Ctd>\u003Ccode>404\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>task_not_found\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>No task with that id in your enterprise.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>404\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>task_not_runnable\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>It cannot take new work: it is \u003Ccode>deprecated\u003C\u002Fcode>, or nobody can run it (it has no \u003Ccode>assigneeRole\u003C\u002Fcode>, or nobody holds that role). A deprecated task answers this even while a run of it is under way.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>404\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>task_disabled\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>It is switched off: its run status is \u003Ccode>disabled\u003C\u002Fcode>. Nothing starts it, from the API, its webhook, a schedule, another task's handoff, a retry or the portal, until it is set back to \u003Ccode>active\u003C\u002Fcode>. A run made before it was switched off still goes ahead: one under way finishes, and one waiting for the task to be free or delayed until later still starts when its turn comes. A task that is also deprecated answers \u003Ccode>task_not_runnable\u003C\u002Fcode> instead.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003C\u002Ftbody>\n\u003C\u002Ftable>\n\u003C\u002Fdiv>\n\u003Cp>The same input sent again while its run is still \u003Ccode>pending\u003C\u002Fcode> answers with that run, not a second one. Once the run\nhas started, the same input starts another, so starting a run is not safe to repeat blindly: see\n\u003Ca href=\"\u002Fdocs\u002Fapi\u002Fconventions#safe-retries\">Safe retries\u003C\u002Fa>.\u003C\u002Fp>\n\u003Ch2 id=\"activation-through-mcp\">Activation through MCP\u003C\u002Fh2>\n\u003Cp>External agents can use these \u003Ca href=\"\u002Fdocs\u002Fmcp\u002Ftools\">MCP tools\u003C\u002Fa> after publishing a task:\u003C\u002Fp>\n\u003Cdiv class=\"prose__table\">\n\u003Ctable>\n\u003Cthead>\n\u003Ctr>\n\u003Cth>Tool\u003C\u002Fth>\n\u003Cth>Required scope\u003C\u002Fth>\n\u003Cth>Effect\u003C\u002Fth>\n\u003C\u002Ftr>\n\u003C\u002Fthead>\n\u003Ctbody>\n\u003Ctr>\n\u003Ctd>\u003Ccode>os.set_task_run_status\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>tasks:write\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>Set \u003Ccode>runStatus\u003C\u002Fcode> to \u003Ccode>active\u003C\u002Fcode> or \u003Ccode>disabled\u003C\u002Fcode>.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>os.set_task_schedule\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>tasks:write\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>Replace a schedule with \u003Ccode>id\u003C\u002Fcode>, \u003Ccode>cron\u003C\u002Fcode>, and optional \u003Ccode>timezone\u003C\u002Fcode>, \u003Ccode>enabled\u003C\u002Fcode>, and \u003Ccode>input\u003C\u002Fcode>.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>os.remove_task_schedule\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>tasks:write\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>Remove a schedule without cancelling existing runs.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>os.set_task_input_values\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>tasks:write\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>Replace your enterprise's own input values with \u003Ccode>id\u003C\u002Fcode> and \u003Ccode>values\u003C\u002Fcode>, keyed by input key; \u003Ccode>{}\u003C\u002Fcode> clears them. Works on a linked clone.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>os.start_task\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>runs:write\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>Start by \u003Ccode>taskId\u003C\u002Fcode> or \u003Ccode>slug\u003C\u002Fcode>, with optional \u003Ccode>input\u003C\u002Fcode> and a required \u003Ccode>idempotencyKey\u003C\u002Fcode>.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>os.read_context\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>enterprise:read\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>Read one workflow bookkeeping \u003Ccode>key\u003C\u002Fcode>.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>os.write_context\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>enterprise:write\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>Replace that key's \u003Ccode>value\u003C\u002Fcode> with a JSON object of at most 16 KB.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>memory.ask\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>memory:read\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>Recall knowledge for a \u003Ccode>purpose\u003C\u002Fcode>, with optional \u003Ccode>teamId\u003C\u002Fcode>, \u003Ccode>projectId\u003C\u002Fcode>, and \u003Ccode>limit\u003C\u002Fcode>.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003C\u002Ftbody>\n\u003C\u002Ftable>\n\u003C\u002Fdiv>\n\u003Cp>The start tool calls \u003Ccode>POST \u002Fv1\u002Fruns\u003C\u002Fcode> with a structured envelope:\u003C\u002Fp>\n\u003Cpre>\u003Ccode class=\"language-json\">{\n    &quot;slug&quot;: &quot;triage-new-issues&quot;,\n    &quot;input&quot;: { &quot;repo&quot;: &quot;acme\u002Fweb&quot;, &quot;issue&quot;: 128 },\n    &quot;idempotencyKey&quot;: &quot;triage-128-first-start&quot;\n}\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>Pass exactly one of \u003Ccode>taskId\u003C\u002Fcode> and \u003Ccode>slug\u003C\u002Fcode>. The key must be nonempty and at most 200 characters. Reusing it for the\nsame authenticated caller and task returns the original run even if the input differs; new work needs a new key.\nThe response is \u003Ccode>{runId, status, taskId, slug, origin}\u003C\u002Fcode>. Your enterprise's own input values, task input defaults,\nplanning, disabled-task checks, assignment and spend controls apply as they do to a requested start in the portal.\u003C\u002Fp>\n\u003Cp>Enabling a task permits starts but does not start it. Setting a schedule on a disabled task leaves it unable to\nrun. A schedule fires only when the deployment's scheduler is running. Read it back with \u003Ccode>os.read_task_definition\u003C\u002Fcode>.\u003C\u002Fp>\n\u003Cp>Context tools use \u003Ccode>GET\u003C\u002Fcode> and \u003Ccode>PUT \u002Fv1\u002Fenterprise\u002Fcontext\u002F{key}\u003C\u002Fcode>. Writes replace the entire object and record the\nauthenticated caller, so read before changing selected fields. Context holds workflow state; knowledge belongs\nin memory. \u003Ccode>memory.ask\u003C\u002Fcode> calls \u003Ccode>GET \u002Fv1\u002Fmemory\u002Fask\u003C\u002Fcode> and returns the existing answer, evidence and availability\nenvelope scoped to the caller's enterprise, without needing a task or run.\u003C\u002Fp>\n\u003Ch2 id=\"read-the-run\">Read the run\u003C\u002Fh2>\n\u003Cp>\u003Ccode>GET \u002Fv1\u002Fruns\u002F{id}\u003C\u002Fcode>, with \u003Ccode>runs:read\u003C\u002Fcode>, reads the run with its events and gates:\u003C\u002Fp>\n\u003Cpre>\u003Ccode class=\"language-json\">{\n    &quot;run&quot;: {\n        &quot;id&quot;: &quot;5c0e9f7a-1b2d-4e3f-a4b5-c6d7e8f90a1b&quot;,\n        &quot;status&quot;: &quot;succeeded&quot;,\n        &quot;input&quot;: { &quot;repo&quot;: &quot;acme\u002Fweb&quot;, &quot;issue&quot;: 128 },\n        &quot;costUsdCents&quot;: 4,\n        &quot;startedAt&quot;: &quot;2026-09-28T09:00:03.000Z&quot;,\n        &quot;finishedAt&quot;: &quot;2026-09-28T09:01:41.000Z&quot;\n    },\n    &quot;events&quot;: [\n        { &quot;id&quot;: &quot;…&quot;, &quot;type&quot;: &quot;run.succeeded&quot;, &quot;payload&quot;: { &quot;result&quot;: &quot;…&quot; }, &quot;createdAt&quot;: &quot;2026-09-28T09:01:41.000Z&quot; }\n    ],\n    &quot;gates&quot;: []\n}\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>The answer also carries the task and version it ran, what came before it and what it handed to, its execution, and\nits cost.\u003C\u002Fp>\n\u003Cp>The API does not call you when a run ends, so read it until it has:\u003C\u002Fp>\n\u003Cul>\n\u003Cli>\u003Ccode>succeeded\u003C\u002Fcode>, \u003Ccode>failed\u003C\u002Fcode> or \u003Ccode>cancelled\u003C\u002Fcode>: it has ended. A \u003Ccode>run.succeeded\u003C\u002Fcode> event carries its \u003Ccode>result\u003C\u002Fcode>, and a\n\u003Ccode>run.failed\u003C\u002Fcode> event its \u003Ccode>reason\u003C\u002Fcode>.\u003C\u002Fli>\n\u003Cli>\u003Ccode>waiting_on_gate\u003C\u002Fcode>: it waits for your decision, and \u003Ccode>gates\u003C\u002Fcode> holds what it waits on. Decide it on \u003Cstrong>Gates\u003C\u002Fstrong>, or with\n\u003Ccode>POST \u002Fv1\u002Fgates\u002F{id}\u002Fdecision\u003C\u002Fcode> and a token scoped \u003Ccode>gates:write\u003C\u002Fcode>.\u003C\u002Fli>\n\u003Cli>\u003Ccode>blocked\u003C\u002Fcode>: it is held for a reason outside the task, such as a refused credential or a provider outage, and\n\u003Ccode>blockedReason\u003C\u002Fcode> says which. Most blocked runs resume by themselves. One held by an outage or a timeout is tried\nagain five times, over about two hours, and then waits on Blockers for you to retry or cancel it.\u003C\u002Fli>\n\u003Cli>\u003Ccode>paused_spend\u003C\u002Fcode>: a spend cap was reached. It is queued again when the cap is raised or spend limits are turned\noff. See \u003Ca href=\"\u002Fdocs\u002Fcontrol\u002Fspend\">Spend and models\u003C\u002Fa>.\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Cp>Every status is on \u003Ca href=\"\u002Fdocs\u002Fwork\u002Fruns\">Runs\u003C\u002Fa>. On later reads, send \u003Ccode>afterEventId\u003C\u002Fcode> with the id of the newest event you\nhold, and only the events recorded since come back. A few from the same second may come again: skip the ids you\nalready have.\u003C\u002Fp>\n\u003Cp>\u003Ccode>GET \u002Fv1\u002Fruns\u002F{id}\u002Flog\u003C\u002Fcode> answers with the run's full log in \u003Ccode>body\u003C\u002Fcode> once it is stored, and \u003Ccode>404\u003C\u002Fcode> (\u003Ccode>log_not_found\u003C\u002Fcode>)\nuntil then. \u003Ccode>GET \u002Fv1\u002Fruns?taskId=…\u003C\u002Fcode> lists a task's runs, newest first.\u003C\u002Fp>\n",[12,16,19,23,26,29,32,35,38,41],{"id":13,"text":14,"level":15,"planned":8},"a-task-as-json","A task as JSON",2,{"id":17,"text":18,"level":15,"planned":8},"create-a-task","Create a task",{"id":20,"text":21,"level":22,"planned":8},"a-task-that-merges","A task that merges",3,{"id":24,"text":25,"level":15,"planned":8},"the-checks","The checks",{"id":27,"text":28,"level":15,"planned":8},"change-a-task","Change a task",{"id":30,"text":31,"level":22,"planned":8},"publishing-to-the-catalogue","Publishing to the catalogue",{"id":33,"text":34,"level":22,"planned":8},"versions","Versions",{"id":36,"text":37,"level":15,"planned":8},"start-a-run","Start a run",{"id":39,"text":40,"level":15,"planned":8},"activation-through-mcp","Activation through MCP",{"id":42,"text":43,"level":15,"planned":8},"read-the-run","Read the run",1794928142709]