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):
auto.sessions.spawn is mcp__auto__auto_sessions_spawn under claude-code (see Auto MCP).
Catalog
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.
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 withname and its tool aliases.
auto.sessions.spawn
Start another agent’s session with an initial message.
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 orchat.historyrendered 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 aRequested-bytrailer, never trusted for git authorship. - Omitted — the child inherits the spawner’s requester, tagged inherited.
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.
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’smanages: (see runtime controls). Stopping an already-terminal session is an idempotent no-op; the target’s bindings stay intact and go dormant.
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.
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 for the routing side.auto.bindings.targets
No parameters. Lists the target types this session can bind, derived from its agent’s triggers — each withlifecycle (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.
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 asauto.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 thecontext on an active binding without creating one.
A real change bumps the binding’s
revision and emits an auto.session.binding.updated event (see lifecycle events); 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.
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
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.
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 withauth.kind: mcp_oauth — usable before the agent even exists.
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 bindings. auto.sync.enable creates or updates the merge-to-apply binding:
Resources and templates
auto.resources.get
Read one live applied resource’s full spec.
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: "<agent 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
repoFullNameandgithubConnectioncontext variables are defaulted the same way Sync injects them — so a bundle that would apply under Sync validates cleanly. Declaredvariables: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 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/<path>, or pin an exact version.
Webhooks
auto.webhooks.list / auto.webhooks.get
list takes no parameters; get takes { endpoint: "<slug>" }. 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.
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: <name> with identical auth binds it permanently on apply, and re-calling with the same name and auth refreshes the window. See cron and webhooks.
Secrets
auto.secrets.create
Create a secret in the session’s project scope (organization scope for org-scoped sessions).
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.
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.
The recovery recipe for one full entry found by search:
auto.sessions.conversation({ afterSequence: seq - 1, limit: 1, toolResults: "full" }).
checks.* — GitHub check runs
When a trigger declareschecks: (only github.pull_request.* triggers can — see 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.
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.