Tasks

The definition of a repeatable job: its goal, its limits, the tools it may use, and what happens next. A task never runs; a run does.

A task is a definition

A task is a repeatable job description: what the job is for, how to do it, what it may touch, and what happens after it. Creating one does no work. Work happens in a run, and a run starts from a person, a schedule, a webhook, or the task before it in a handoff.

Create one on Tasks → Create task, or over the API. Create a task when a capability is missing, not for one piece of work: "triage an issue" is a task, and "fix issue 42" is a run of one.

Anatomy

Most of a task lives in its version, which is fixed once saved:

Part What it is
Goal One sentence of what the task is for. The model reads it on every run, and self-improvement aims at it.
Success metric How you would know it is working, one line per metric. Free text today.
Guardrails Rules the model must not break, one per line: "never email a customer", "escalate if unsure". They are instructions to the model. What actually stops a call is a tool scope or a gate.
Skill The SKILL.md: how to do the job, step by step, in plain language.
Tools Every tool a run may call, and nothing else. A tool can be narrowed to some values of its fields. See Gates and tool scopes.
Inputs The fields a run starts with: each has a key, a label, a type (Text, Number, Link, Yes/no or File), and optionally a default and whether it is required.
Gates The tool calls that wait for your approval before they happen.
Spend A budget per run, and which model runs it: Auto, where a model is chosen for each run up to a highest tier you may set, or an exact model. See Spend and models.
Workspace For a task that works in a repository: the branch it works on and which files it may write. See Workspaces.
Successors The tasks that run after it, and on which outcome. See Handoffs.
Finishes the work on The outcomes that end the work for good, one per line. A run that ends on one, with no step after it, finishes the work, so it never shows on Waiting. Left empty, the work stays open until someone marks it finished. See Finished work.

Some things belong to the task itself rather than to a version, so the version history does not record them:

Part What it is
Name and slug The slug is unique in your enterprise. Successors, webhooks and the API find the task by it, so choose it deliberately.
Who runs it 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 task cannot be given to one member or to a team. See Roles.
Teams Shown, not set: the teams that have the task, because a member who holds its role sits on or leads them. A task's page reads "No team yet: nobody holds this role on a team" when there are none. A run is done for the teams of the member it goes to.
Runs at once Its lanes, if it declares any. See Runs at once.
Status active, or deprecated: a deprecated task starts no new runs. Start, the API and its webhook refuse it, its schedule stops firing, and runs waiting to start are closed. Runs already under way finish.
Schedule Its cadence, if it has one. Changing it publishes no new version. See Schedules and webhooks.

A task's page in the portal also shows its runs, its triggers, and any self-improvement recommendations waiting on it.

What a task can call

Use Add Tool when creating a task or editing its version. The picker shows the connections available to its role and the teams that have it, plus the built-in actions. Choose Add toolset to let the model choose among a connected server's actions, or Choose actions to select individual ones. You do not need to type tool names. Selected tools appear as cards; Remove removes an assignment from the draft. Saving publishes a new version.

A whole toolset is a permission to use its discovered actions, not an action itself. The model still calls an individual action with its input fields. If a connection cannot list its actions, the picker shows a retry and the run reports those actions as unavailable rather than offering the catalog name as a callable tool.

When an action requires an approval gate, selecting it adds that gate to the draft. Review the Gates before saving. Existing tool scopes and approval checks still apply to whole toolsets.

A task that should work with whichever tool a company connected, such as any code host, names its tools by a tool slot instead of a vendor: it declares the slot under Tool slots, and each company fills it with one of its own connections on Tools.

For an OAuth connection, choose its Permissions from the server’s advertised list before connecting. Nothing is selected automatically. To change access later, open Tools → Edit on that connection, change the checked permissions and click Reconnect / change permissions. Authorize at the vendor, then return to OS. Existing team/member assignment and tool restrictions stay in place. OS checks the catalog after authorization and explains when no actions are available.

If the task picker cannot load actions, use Manage connection to open that connection’s settings. Authentication failures require reconnecting; network failures can be retried. Servers that do not advertise permissions can use their defaults or administrator-supplied scopes.

On Tools, add or edit a connection to upload an Image or logo. PNG, JPEG, WebP and GIF files up to 5 MB are resized for the cards. You can preview or remove the image before saving. For an OAuth connection, connect first, then edit its image.

A run can call only its task's selected tools, including the actions of a selected toolset. They come in two kinds:

  • Built-in tools, which the OS answers itself: os.*, workspace.*, memory.*, web.*, and the actions of a browser. The built-in tools reference is the exact list, with what each takes, whether it writes, and which can wait at a gate.
  • Vendor tools, from the systems your enterprise connects: GitHub, Slack and the rest. The Tools directory lists each system, and how to connect it.

How to narrow a tool to some values, and which calls wait for you, is in Gates and tool scopes.

Optional tools

A task can use a tool when your company has connected it and go ahead without it when you have not. Tick Optional on the tool's card when editing the task, or send the entry as { "name": "sentry", "optional": true } in tools (Tasks API). A task that triages issues might read your error tracker and your analytics when they are connected, and still triage from the issue alone when they are not:

{
    "tools": [
        "codehost.issue.read",
        "codehost.issue.comment",
        { "name": "sentry", "optional": true },
        { "name": "metabase", "optional": true }
    ]
}

When no connection that reaches a run serves an optional tool, the run starts anyway. The model is not offered the tool, is told it is not connected, and is asked to skip any step that needs it and say what it skipped. A call to it anyway is handed back as tool_not_connected without ending the run. Once you connect the tool, later runs use it. A required tool that is not connected still holds the run as tool_not_bound:<tool> until you connect it, and an optional tool never appears among the connections a role holder is missing. Gates and scopes apply to an optional tool exactly as to a required one. A tool slot can be optional too: name its tools in optional entries, and a company that fills no binding for the slot runs without them.

Call limits

A version can cap how many times one run makes a call, with callLimits (Tasks API). Each limit names one of the task's tools, an optional match on the call's fields, read the way a gate's match is, and perRun, how many such calls a run may make. A task that files issues and may open at most two a run, while editing as many as it needs:

{
    "tools": ["gitea.issue_write"],
    "callLimits": [{ "tool": "gitea.issue_write", "match": { "method": "create" }, "perRun": 2 }]
}

The OS counts the run's own calls that matched. The call past the limit is never sent and asks nobody: the run reads call_limit_reached as the tool's answer and carries on with the rest of its work. A call the tool refused, or the OS refused before sending it, does not count. Each run has its own count, so a retry or the next task in a handoff starts again from none. It works the same for a connected tool and a built-in one.

A task created without gates asks the CEO before every call of a tool it holds that reaches outside the enterprise: each vendor tool its connected server does not mark read-only, os.mail_send and os.mail_reply, and each tool your connections mark must-gate, by name. Send gates: [] to create it with none, or your own list, which is saved exactly as given. A later version never adds them back. See A task created without gates.

Runs at once

A task runs one run at a time unless it says how its work splits. Declare the input keys that split it, its lanes, with serializeOn (Tasks API): a task that works one issue of one repository at a time might declare ["repo", "issue"]. Then runs on different issues run at once, and two runs on the same issue never do: the second waits, or is skipped, as it would for a task with one lane.

  • A lane is the values of those inputs, trimmed and in lower case, so Acme/Web and acme/web are the same lane.
  • A member still does one run at a time, or up to their tasks at once on the Enterprise plan. Lanes run side by side only when the task's role holders have the room between them.
  • Keys are yours to choose: a repository, a campaign, a region. The OS never reads meaning into them.

Versions

Every save publishes a new version, numbered from 1. A version is never changed after it is saved.

  • A run keeps the version it started on. Saving a new version while a run is under way changes nothing for that run; the next run uses the new one. A run that has not started yet, waiting as pending or queued, takes whichever version is current when it starts. A run that picks up another run's work after a release keeps that run's version.
  • Version history on the task shows every version as it was, read-only, and the runs that used it.
  • Going back to an earlier definition means opening that version and saving its content as a new version. There is no one-click restore.

Editing safely

Edit on a task opens its current version; Save as new version publishes your changes as the next one.

If someone (a person, or a self-improvement change you approved) published a newer version while you were editing, your save is refused rather than putting the older definition back over theirs. Copy what you want to keep, then Cancel edit to load the newer version and make your change on top of it. Over the API, the same protection is baseVersionId: send the version you read, and a save made after someone else's is refused with a 409.

Checks when you save

A version that could never run is refused, and one with a likely mistake is saved with a warning:

Code Refused or warned Why
gate_required_for_tool Refused The task can merge a pull request or send a new mail but declares no gate on it, or it can write a plan (a team, role, member, task or spend change) but declares no CEO gate on asking the CEO.
gate_summary_tool_required Refused A gate of the task asks for a summary (requiresSummary), or it can reply to mail, but it cannot write one.
deterministic_with_tools Refused A task that runs no model (deterministic) lists tools it could never call.
successor_when_unknown Refused A successor's when is not one the OS knows.
successor_cap_invalid Refused A successor's loop cap is not a whole number of at least 1.
successor_delay_invalid Refused A successor's delay is not more than 0 and at most 1440 minutes.
unconditional_loop Refused Successors on terminal loop back to the task, so it would never stop.
successor_unknown_slug Warned A successor names a task your enterprise does not have.
outcome_not_routed:<word> Warned The skill tells a run to end on {"outcome":"<word>"}, but no successor routes that word, the task does not list it as finishing the work, and it is not plain success (succeeded or ok), so a run that ends on it stops as a dead end. One per word.
self_loop_unconditional Warned A successor starts the task itself again on succeeded (or with no outcome named) or on a named outcome, with no delay, so every run that ends that way starts another, for ever. A successor back to itself on ceo_approved or ceo_changes_requested, or with a delay, is fine.
asks_ceo_without_resume Warned The task asks the CEO (os.ask_ceo), its skill does more work with the answer, but no successor on ceo_approved goes back to the task itself, so nothing picks the work up once the CEO answers.

An outcome the task lists as finishing the work (finishesOn) always finishes it, whatever its successors branch on, so it never needs a successor of its own.

Warnings show on the task, and on Blockers under Task definitions, until they are fixed. The two read from the skill's text, outcome_not_routed and asks_ceo_without_resume, show on the task's page only: Blockers does not read every task's skill each time it loads. A run that does end on an outcome nothing routes still shows on Blockers when it stops its pipeline, and a task whose runs keep ending that way is listed under Task definitions.

outcome_not_routed, self_loop_unconditional and asks_ceo_without_resume are warnings when you save in the portal or over the API. A task created over the OS's own MCP server (os.create_task) is held to them instead: the create is refused with definition_issues, naming each one, and nothing is saved until the definition is fixed. Publishing a new version over MCP (os.publish_task_version) still saves and returns them as warnings.

Inputs

A task's inputs are what a run starts with. Start a run on the task's page shows them as a form, filled with your enterprise's own values for them, else their defaults, and will not start while a required one is empty. The same keys are what a schedule, a webhook body, or the task before it provide.

However a run starts, an input it leaves out or blank takes your enterprise's own value for it, else its default, and a required input with none of those refuses the start with input_required naming it: a schedule's firing, a release, a webhook, the API, MCP and chat alike. The one exception is a run the task before it starts: its input is whatever that run handed on, with your values and the defaults filling what it left out, and a required input still missing is left unset for that run to explain rather than refused. Keys the task does not declare pass through to the run as sent.

Your own input values

A version's defaults are part of the task's definition, so only the enterprise that owns the definition can change them, and a task published to the Catalog carries none. Input values on the task's page are where your enterprise keeps its own value for each input instead: a repository, a project key, a map of IDs. They sit on the task, beside its schedule, not on a version, so saving them cuts no version and works on a clone you cannot edit.

Every run of the task takes them, however it starts, in this order:

  1. A value the start gives: the Start form, an API or MCP call, a schedule's or release trigger's run input, a webhook body, or what the task before it handed on.
  2. Your enterprise's own value.
  3. The version's default.

A retry or a restart repeats the input its run had, so a value the run already carried stays; one it lacked is filled from your values as they are now.

Each value has to be of the type its input declares, and only inputs the current version declares can have one, so a save naming another key is refused with input_undeclared and a value of the wrong kind with input_invalid, each naming the input. A File input takes none: the file is given at each start. When a newer version stops declaring an input, or changes its type, the value you saved for it is kept but no run takes it, and the task's page lists it so you can clear it. A built-in task runs one shared definition for every enterprise and takes no values of any one enterprise's own.

Over the API, GET /v1/tasks/:id returns them as inputValues, with ignoredInputValues naming any the current version does not take; PUT /v1/tasks/:id/input-values with { "values": { ... } } replaces them and DELETE /v1/tasks/:id/input-values clears them. Through MCP the tool is os.set_task_input_values.

The task form names each type in plain words. Over the API, a task's inputs carry the stored word:

Type Stored as What a start gives
Text string Any text.
Number number A number.
Link link A full http or https address. Anything else refuses the start with input_invalid, naming the input.
Yes/no boolean true or false.
File file A file, chosen with a file picker on Start a run, or sent as a data: URL over the API. It takes no default. A browser can attach it to a page.

Clone and copy

Community → Catalog lists the tasks you can take into your enterprise, in two ways:

Clone Copy
What you get Your own installation of the original, linked to it A new, independent task
Who owns the definition The original's owner You
Can you edit it No: Edit is disabled, and self-improvement does not run on it Yes
Starts on The original's current version Version 1, with the original's definition
Later versions A newer version of the original is offered on the clone's page, with the tools it adds or drops and any input it now needs a value for, and Update takes it. While your enterprise's Auto-update cloned tasks setting is on, a quiet update follows automatically, usually within a minute of the original publishing it; updates that change tools, gates, inputs or the workspace's credentials or push rules still wait for a person to press Update None: it is yours from here
You choose Nothing: it lands with the original's name, slug and role Its name, slug and role

A quiet update is one that adds or removes no tool or gate, needs no new input value, and leaves the task's workspace as it is: the credentials its repository commands get from your connected tools, and what it may write and push. The automatic update takes it exactly as Update would: the clone's name, role, schedule, input values and status stay as they are, a run already going finishes on the version it started on, and the clone's version history shows the new version as Applied automatically from source vN, N being the original's version. An update your plan does not allow is held, as Update is, and so is every update while the setting is off.

A clone keeps the original's role, and a copy keeps it unless you choose another. Neither is put on a team: either runs once someone holds that role, and every team a holder sits on or leads has it.

Either way, you can run it, schedule it, set its input values and delete it. Neither brings a schedule, input values, run history, credentials or memory: you connect your own tools, set your own input values, and a clone may not write memory above its own task. Successors that pointed at the original point at your copy; other successors look for tasks with the same slugs in your enterprise.

Copy also works on your own tasks, from the task's page, to start a variant without touching the original.

What a task needs to work in an enterprise that is not its author's, before you publish it to the Catalog, is in Writing a clonable task.

The OS's own tasks are part of the product, not of the catalog: the same in every enterprise, and changed only with a release of the OS. They cannot be cloned or copied, and nobody can edit, reschedule or delete one. You can still start them. See Enterprise.

Deleting a task

Delete on a task removes its definition and every version of it. Runs that already happened are kept.

Over the API

With an API token scoped tasks:read (and tasks:write to change them):

Call What it does
POST /v1/tasks Create a task, with its first version.
GET /v1/tasks/{id} The task, its current version and skill, its version list, and its definition warnings.
POST /v1/tasks/{id}/versions Save a new version. Send baseVersionId.
POST /v1/tasks/{id}/copy Copy it, with a new name and slug, and optionally a new role.
PUT /v1/tasks/{id}/schedule Set its schedule.
POST /v1/tasks/{id}/runs Start a run.

See Tasks over the API for the full shape of a task.