> ## Documentation Index
> Fetch the complete documentation index at: https://docs.auto.sh/llms.txt
> Use this file to discover all available pages before exploring further.
# Auto.* and Checks.* Tools
> The platform coordination tools every agent can carry: spawning and messaging sibling sessions, bindings, session introspection, connections, resource dry-runs, webhooks, secrets — and checks.* for GitHub check runs.
`auto.*` is the agent's control surface over the platform itself: start sibling sessions, message live ones, bind external targets so future events route back, inspect any session's transcript, start OAuth consent flows, validate `.auto/` changes, reserve webhooks, and mint secrets. `checks.*` drives GitHub check runs a trigger declared. This page documents every tool with its parameters. Read it when you are writing prompts that orchestrate multiple agents or that manage auto resources from inside a session.
`auto.*` tools register on a session when the agent declares a `kind: local, implementation: auto` tool (see the [tools reference](/reference/tools)):
```yaml theme={null}
tools:
auto:
kind: local
implementation: auto
```
Harnesses see flattened names — `auto.sessions.spawn` is `mcp__auto__auto_sessions_spawn` under claude-code (see [Auto MCP](/runtime/auto-mcp)).
## Catalog
| Family | Tools |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Session coordination | `auto.session.get`, `auto.sessions.list`, `auto.agents.list`, `auto.sessions.spawn`, `auto.sessions.message`, `auto.sessions.stop`, `auto.sessions.archive_current` |
| Bindings | `auto.bindings.targets`, `auto.bind`, `auto.unbind`, `auto.bindings.update`, `auto.bindings.list` |
| Requester identity | `auto.resolve_requester_identity` |
| Connections & OAuth | `auto.connections.providers.list`, `auto.connections.list`, `auto.connections.start`, `auto.agent_tools.connect` |
| GitHub Sync | `auto.sync.list`, `auto.sync.enable` |
| Resources & templates | `auto.resources.get`, `auto.resources.dry_run`, `auto.templates.list` |
| Webhooks | `auto.webhooks.list`, `auto.webhooks.get`, `auto.webhooks.create` |
| Secrets | `auto.secrets.create` |
| Introspection (read-only) | `auto.sessions.get`, `auto.sessions.summary`, `auto.sessions.search`, `auto.sessions.conversation`, `auto.sessions.tools`, `auto.sessions.triggers`, `auto.sessions.bindings`, `auto.sessions.commands` |
| Checks | `checks.list`, `checks.begin`, `checks.success`, `checks.failure` |
Deprecated aliases still registered for older prompts: `auto.artifacts.record` / `auto.artifacts.release` (aliases of `auto.bind` / `auto.unbind`) and `auto.chat.subscribe` / `auto.chat.unsubscribe` (aliases of bind/unbind with a `slack.thread` target). Write new prompts against the canonical names.
Two further families register but are not general-purpose: `auto.onboarding.*` progress tools serve the hosted onboarding flow, and `auto.billing.offer_auto_reload` exists only for sessions whose `auto` tool declares `capabilities: { billing: write }`.
## Session coordination
### auto.session.get
No parameters. Returns the calling session's own identity and scope: `id`, `agent`, `displayTitle`, `ambientStatus`, `status`, timestamps, `organizationId`, `projectId`. Useful for an agent that needs to reference itself — for example, learning its own session id before passing it to an introspection tool.
### auto.sessions.list
List sessions in the current project, most recently active first.
| Parameter | Type | Notes |
| --------- | -------------- | ---------------------------- |
| `status` | session status | Optional filter. |
| `agent` | string | Optional agent-name filter. |
| `since` | ISO datetime | Only sessions created after. |
| `limit` | int 1–50 | Default 20. |
Each row carries a `url` — the session's canonical web page, ready to hand to a human who wants to watch it live.
### auto.agents.list
No parameters. Lists agents in the project this session can spawn, each with `name` and its tool aliases.
### auto.sessions.spawn
Start another agent's session with an initial message.
| Parameter | Type | Notes |
| ---------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `agent` | string | Agent name in the current project. |
| `message` | string | The initial message the new session receives. |
| `idempotencyKey` | string | Optional; repeat calls with the same key return the same session. |
| `requester` | see below | Who the work is for. Pass it on every spawn. |
| `observation` | `{ mode, context?, eventContext? }` | `mode: "auto" \| "always" \| "never"` (default `auto`) — whether the spawner observes the child via an `auto.session` binding. |
Returns `{ session (with url), created, workflowId }`.
**Requester attribution.** The `requester` parameter keeps humans attached to delegated work:
* Preferred — a verified chat-message reference: `{ "kind": "chat-message", "provider": "slack", "threadId", "messageId" }`, with the ids exactly as a trigger delivery or `chat.history` rendered them. The server resolves the author from its own intake record of that message, so the result is trusted like direct intake — including for git author attribution.
* Fallback — a freeform origin: `{ "kind": "provider", "provider", "externalId", "displayName?" }` or `{ "kind": "user", "userId" }`. Recorded as an *asserted* claim: displayed and stamped as a `Requested-by` trailer, never trusted for git authorship.
* Omitted — the child inherits the spawner's requester, tagged *inherited*.
**Singletons.** Spawning an agent whose triggers route as a singleton claims its `agent.singleton` binding. If a live singleton session already exists the spawn is refused with an error naming it — message that session instead.
### auto.sessions.message
Send a message into another live session.
| Parameter | Type | Notes |
| ------------------------ | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sessionId` *or* `agent` | string | Exactly one. `agent` resolves the agent's single live session by name — no session-id handshake needed, and the name keeps resolving after the session is cycled. Unknown agents, agents with no live session, or more than one are rejected with descriptive errors. |
| `message` | string | Required. |
| `requester` | freeform origin | Optional provenance on the command (asserted, never git-trusted). |
Returns a command receipt `{ command: { id, sessionId, status, createdAt }, created, workflowId }`.
### auto.sessions.stop
Stop a session this session controls — itself, or a session of an agent type listed in this agent's `manages:` (see [runtime controls](/reference/runtime-controls)). Stopping an already-terminal session is an idempotent no-op; the target's bindings stay intact and go dormant.
| Parameter | Type | Notes |
| ----------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `sessionId` | string | Required. |
| `respawn` | boolean | Cycle a `replace: auto` agent: after it stops, the pool reconciler spawns one replacement on the latest agent spec. Ignored otherwise. |
| `handoff` | object | Wind-down state persisted on the stopped session; a respawn replacement receives it as predecessor-handoff context. |
### auto.sessions.archive\_current
Archive the calling session as semantically done. Archived sessions leave the default active lists but are revived automatically by future routed work or operator messages.
| Parameter | Type | Notes |
| --------- | ------ | --------------------------------------------------- |
| `handoff` | object | Optional state for whoever picks the work up later. |
A self-archive is **rejected while the session holds active held-policy bindings** — for example an open PR the platform bound to it. Finish or release the bound work first; on a `release: true` trigger delivery (e.g. PR closed), archive in that turn.
## Bindings
A binding is a passive routing pointer: "events about this target should continue this session." It grants no authority over the target and delivers nothing by itself — the agent must also declare a trigger whose routing binds/matches the target. See [triggers](/reference/triggers) for the routing side.
### auto.bindings.targets
No parameters. Lists the target types *this* session can bind, derived from its agent's triggers — each with `lifecycle` (`manual`/`held`), `continuity` (`session`/`agent`), the matching triggers, and ready-made `bindWith`/`unbindWith` example inputs. `auto.session` is always available as a pure observation pointer even with no triggers.
### auto.bind
Bind a target to the calling session.
| Parameter | Type | Notes |
| -------------- | ---------------------------------------------- | -------------------------------------------------------------------------------------- |
| `type` | enum | `github.pull_request`, `github.issue`, `linear.issue`, `slack.thread`, `auto.session`. |
| `connection` | string | Optional connection name when several could match. |
| `github` | `{ repository, number }` | Required for `github.*` types. |
| `linear` | `{ issue }` | Required for `linear.issue`. |
| `slack` | `{ provider: "slack" \| "discord", threadId }` | Required for `slack.thread` (the type covers both Slack and Discord threads). |
| `session` | `{ id }` or `{ name }` | Required for `auto.session`. |
| `payload` | JSON | Optional target payload. |
| `context` | JSON object ≤ 16 KiB | Freeform relationship context carried on the binding. |
| `eventContext` | JSON object ≤ 16 KiB | Context stamped onto deliveries this binding routes. |
Exactly one provider arm matching `type` must be present. Returns `{ binding: { targetType, externalId, created, ownerSessionId, … } }`. Binding a `slack.thread` also performs the provider-level ingest subscribe so unmentioned thread replies are emitted at all.
`context` and `eventContext` accept a JSON-encoded object *string* as well as an object — an escape hatch for models whose constrained tool-call decoding cannot emit freeform object maps.
### auto.unbind
Release a binding this session owns, so matching events stop routing here. Same target arms as `auto.bind`, plus `authorizationAttempt: { id }` for the `auto.connection.authorization_attempt` target — the one platform-held binding an owner may explicitly drop (when intentionally abandoning an in-flight authorization). All other platform-held bindings are protected: the platform releases them (for example when a bound PR closes with `release: true`), not the agent. Optional `context` explains the release in the resulting unbound event.
### auto.bindings.update
Update the `context` on an active binding without creating one.
| Parameter | Type | Notes |
| ------------------------- | ------------------------ | --------------------------------------------------------------------------- |
| `bindingId` *or* `target` | string / typed selector | Exactly one. The `target` selector uses the same typed arms as `auto.bind`. |
| `context` | object \| string \| null | Required. `null` clears — valid only with `mode: "replace"`. |
| `mode` | `"merge"` \| `"replace"` | Default `merge`. |
| `expectedRevision` | int | Optimistic concurrency: fails if the binding's revision moved. |
| `eventContext` | object | Optional context on the emitted update event. |
A real change bumps the binding's `revision` and emits an `auto.session.binding.updated` event (see [lifecycle events](/reference/events/lifecycle)); a no-op write is silent. Agents use this as a structured status channel — for example a coder session publishing a "PR ready" packet on its PR binding that its supervising agent receives as an event.
### auto.bindings.list
No parameters. The calling session's active bindings: `id`, `targetType`, `externalId`, `source`, `status`, `releasePolicy`, `continuity`, `revision`, `context`, `payload`, timestamps.
## Requester identity
### auto.resolve\_requester\_identity
Render a requester as a mentionable identity on one output surface.
| Parameter | Type | Notes |
| ---------------- | ------------------------------------- | ------------------------------------------------------ |
| `targetProvider` | `"slack"` \| `"github"` \| `"linear"` | The surface being written to. |
| `requester` | freeform origin | Optional; defaults to the calling session's requester. |
Returns `{ displayName, mentionHandle, resolved }` — the provider-native mention token (Slack `<@U…>`, GitHub `@login`, Linear `@name`) when the person is mapped on that provider, else `mentionHandle: null`. Render the plain `displayName` in that case; never guess or hardcode a people map.
## Connections and OAuth
### auto.connections.providers.list
No parameters. Provider connection types this deployment can start: GitHub, Slack, Linear, Telegram, Discord, model-token providers, and the built-in hosted MCP providers.
### auto.connections.list
| Parameter | Type | Notes |
| ---------- | ------ | ---------------- |
| `provider` | string | Optional filter. |
The organization's provider connections. Call it after a consent flow completes to read the new grant's name.
### auto.connections.start
Start a provider consent flow on behalf of the user.
| Parameter | Type | Notes |
| --------------------- | ------- | ------------------------------------------------------------------------ |
| `provider` | string | e.g. `"github"`, `"slack"`, `"linear"`. |
| `allowCurrentProject` | boolean | Default `true`: pre-authorize the current project on the new connection. |
Returns `{ status, provider, authorizationUrl?, message, steps? }` — hand the URL (or the steps) to the user. The terminal outcome (completed, failed, expired) is **reported back to the session automatically** through an authorization-handoff binding; do not poll.
### auto.agent\_tools.connect
Start or inspect OAuth for a remote MCP tool declared with `auth.kind: mcp_oauth` — usable before the agent even exists.
| Parameter | Type | Notes |
| ---------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `agent` + `tool` | strings | For an already-applied agent's tool. |
| `files` | `[{ path, content }]` | Alternative: staged `.auto` source fragments containing exactly one MCP OAuth tool (or pass `tool` to pick one). |
| `redirectUri` | URL | Optional override. |
Returns `connected` when a live connection already backs the tool, else `authorization_required` with an `authorizationUrl`.
## GitHub Sync
### auto.sync.list / auto.sync.enable
`auto.sync.list({ kind: "github" })` returns the project's [GitHub Sync](/concepts/github-sync) bindings. `auto.sync.enable` creates or updates the merge-to-apply binding:
| Parameter | Type | Notes |
| ------------ | --------------------------------- | ---------------------------------------------------------------------------- |
| `kind` | `"github"` | Required. |
| `connection` | string | GitHub connection name. |
| `repo` | `owner/repo` | The configuration repository. |
| `branch` | string | The production branch. |
| `repoId` | string | Optional stable repo id. |
| `ciWatchdog` | `{ workflows: [{ workflowId }] }` | Only for required GitHub Actions workflows that support `workflow_dispatch`. |
## Resources and templates
### auto.resources.get
Read one live applied resource's full spec.
| Parameter | Type | Notes |
| --------- | ------------- | ------------------------------------------------------------ |
| `kind` | resource kind | An inspectable kind (`agent`, `environment`, `identity`, …). |
| `name` | string | Resource name. |
Inline agent identities apply as a generated identity resource sharing the agent's name, so an agent's live identity reads as `{ kind: "identity", name: "" }`.
### auto.resources.dry\_run
Validate and plan `.auto/` changes **without applying anything**. Returns `{ dryRun: true, plan, diagnostics, triggers }` where each plan entry is `{ action: create | update | unchanged | archive, kind, name, diff? }`. Validation failures return structured diagnostics with remediation guidance.
Inside a sandbox, the agent-bridge presents a **path-first facade**: call it with no arguments to validate the full working-tree `.auto` directory (with prune on, so resources absent from the tree plan as archived), or pass `paths: [".auto/agents/x.yaml"]` for a focused run — local imports are followed automatically, up to 100 files / 3,000,000 bytes. Programmatic callers outside a sandbox pass inline `files: [{ path, content }]` or typed `resources` instead (same byte cap; exactly one dialect per call, `resourceRoot` defaults to `.auto`, `prune` defaults to false).
Two behaviors worth knowing:
* When the project has exactly one GitHub Sync binding and/or one GitHub connection, the `repoFullName` and `githubConnection` context variables are defaulted the same way Sync injects them — so a bundle that would apply under Sync validates cleanly. Declared `variables:` always win.
* Binary identity avatar assets cannot travel through the string-only interface: an avatar-reference stop after parsing and schema validation pass is expected — keep the asset committed and let the GitHub Sync apply validate the bytes.
### auto.templates.list
No parameters. The [managed template](/reference/managed-templates) registry: each template's name, description, published versions, latest version's importable file paths, required variables, and public (unauthenticated) source URLs. Import syntax is `@scope/name@latest/`, or pin an exact version.
## Webhooks
### auto.webhooks.list / auto.webhooks.get
`list` takes no parameters; `get` takes `{ endpoint: "" }`. Both return endpoint inspections: ingest URL, auth kind (`hmac_sha256` | `bearer_token` | `none`), whether the referenced secret exists (values are never returned), the triggers attached to the endpoint, and diagnostic problems.
### auto.webhooks.create
Reserve a webhook endpoint name **before** committing files that reference its URL.
| Parameter | Type | Notes |
| ---------------- | ----------------------------------------------- | ---------------------------------------------------------------------- |
| `endpoint` | string ≤ 255 | Project-scoped name. |
| `auth.kind` | `"bearer_token"` \| `"hmac_sha256"` \| `"none"` | Required. |
| `auth.secretRef` | string | Required unless kind is `none`; must name an existing secret in scope. |
Returns `{ name, slug, ingestUrl, reservedUntil, created }`. Endpoint names are project-scoped but the public slug is **globally unique** and may be suffixed — always use the returned `slug`/`ingestUrl`, never a constructed one. The reservation holds for one hour; a trigger declaring `endpoint: ` with identical auth binds it permanently on apply, and re-calling with the same name and auth refreshes the window. See [cron and webhooks](/reference/events/cron-and-webhooks).
## Secrets
### auto.secrets.create
Create a secret in the session's project scope (organization scope for org-scoped sessions).
| Parameter | Type | Notes |
| --------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | resource name | Required. |
| `value` *or* `generate` | string | Exactly one. `generate` is a bounded regex pattern — e.g. `[A-Za-z0-9]{48}` — from which the platform draws a uniformly random value server-side. |
| `description` | string | Optional. |
| `protected` | boolean | Write-only secret. |
| `expiresAt` / `idleExpirySeconds` | datetime / int | Optional expiry. |
| `overwrite` | boolean | Required to replace a live same-name secret or to shadow an inherited org secret from a project. |
A generated value is **never returned**, so it never enters the session transcript — prefer `generate` unless an external system dictates the value. Patterns support printable-ASCII literals, character classes, `\d`, `\w`, groups, alternation, and bounded quantifiers (`{n}`, `{n,m}`, `?`); unbounded quantifiers (`*`, `+`, `{n,}`) and `.` are rejected. See [secrets](/reference/secrets).
## Session introspection
Eight read-only tools examine any session in the calling session's project — the calling session included. All large payloads headed into the context window are truncated to a byte budget by default (`{ truncatedPreview, originalBytes, truncated: true }`); full content stays recoverable through targeted reads.
| Tool | Parameters | Returns |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `auto.sessions.get` | `{ sessionId }` | Full detail: lifecycle timestamps, timing, input, error, requester, workflowId, archive handoff, web `url`. |
| `auto.sessions.summary` | `{ sessionId }` | Dense diagnostic summary: timing, conversation stats, per-tool call/error/duration stats, trigger provenance, bindings, turns, commands, checks, and runtime-restart diagnostics with a redacted log tail. **Call this first.** |
| `auto.sessions.search` | `{ sessionId, queries (1–10 substrings, OR, case-insensitive), kinds?, roles?, afterSequence?, beforeSequence?, limit? ≤ 100 }` | Grep the transcript; snippet windows tagged per matching term. |
| `auto.sessions.conversation` | `{ sessionId, afterSequence?, beforeSequence?, order?, limit? ≤ 100 (default 25), kinds?, roles?, toolResults?: "truncated" \| "full" \| "omit" }` | Page conversation entries — newest first by default, oldest-first when `afterSequence` is set. |
| `auto.sessions.tools` | `{ sessionId, toolName?, errorsOnly?, afterSequence?, beforeSequence?, order?, limit?, payloads? }` | Paired tool call/result exchanges with per-step `durationMs`. |
| `auto.sessions.triggers` | `{ sessionId, payloads? }` | What spawned the session and every subsequent event delivery — signaled, dropped (with reasons), warned, errored — chronologically. |
| `auto.sessions.bindings` | `{ sessionId }` | Another session's active bindings, read-only. |
| `auto.sessions.commands` | `{ sessionId }` | Inbound command history (message / answer / lifecycle) with senders, dispatch status, timestamps. |
The recovery recipe for one full entry found by search: `auto.sessions.conversation({ afterSequence: seq - 1, limit: 1, toolResults: "full" })`.
`auto.session.get` (singular) is the calling session's own identity; `auto.sessions.get` (plural) is the detail view of any session by id. Both exist, and prompts routinely use both.
## checks.\* — GitHub check runs
When a trigger declares `checks:` (only `github.pull_request.*` triggers can — see [triggers](/reference/triggers)), the spawned session gets four `checks.*` tools and the platform requires the harness to see them before the first turn. Their tool descriptions embed the session's configured check catalog: each check's name, display name, description, instructions, and timeout (phase, deadline, and the conclusion applied on timeout). Transitions project to real GitHub check runs on the PR.
| Tool | Parameters | Behavior |
| ---------------- | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `checks.list` | `{}` | The configured checks with current status, conclusion, timeout metadata, and the provider's external URL. |
| `checks.begin` | `{ name? \| names? }` (at least one) | Mark checks `in_progress`; arms the completion-deadline watchdog. |
| `checks.success` | `{ name?/names?, title? ≤ 256, summary?, text? ≤ 65,535 }` | Complete with conclusion `success`. Defaults: title "Check passed", summary "Check passed." |
| `checks.failure` | same as `success` | Complete with conclusion `failure`. Include `summary`/`text` describing what failed — they render in the check output on GitHub. |
The expected lifecycle in a review agent's prompt: `checks.begin` when starting, do the work, then exactly one of `checks.success` or `checks.failure` with a substantive summary. A check left in progress past its deadline is concluded by the timeout watchdog with the configured conclusion.