Skip to main content

​
Session Tools

Session tools let an Agent inspect session state, fetch transcript snippets, send messages into another session, or spawn a bounded sub-agent run. For the product ownership model, read Agents, Sessions, And Tasks.

​
Tool Names

  • sessions_list
  • sessions_history
  • sessions_send
  • sessions_spawn

​
Key Model

Common session keys: global and unknown are reserved and are not listed. If legacy config uses session.scope = "global", tools expose it as main.

​
sessions_list

Lists session rows. Parameters:
  • kinds?: string[]
  • limit?: number
  • activeMinutes?: number
  • messageLimit?: number
Rows can include the key, kind, channel, display name, timestamps, session id, model/context counters, send policy, delivery context, transcript path, and optional recent messages. When running in a sandboxed session, visibility is clamped by the sandbox policy described below.

​
sessions_history

Fetches transcript messages for one session. Parameters:
  • sessionKey
  • limit?: number
  • includeTools?: boolean
sessionKey accepts main, a full session key, or a session id string that can be resolved by the gateway. By default, tool-result messages are filtered out.

​
sessions_send

Sends a message into another session. Parameters:
  • sessionKey?
  • label?
  • agentId?
  • message
  • timeoutSeconds?: number
Use either sessionKey or label, not both. When label is used, agentId can disambiguate same-name sessions if cross-agent policy allows it. Behavior:
  • timeoutSeconds = 0: enqueue and return immediately.
  • timeoutSeconds > 0: wait for completion or timeout through gateway agent.wait.
  • inter-session messages are stored with message.provenance.kind = "inter_session".
  • reply-back loops are bounded by session.agentToAgent.maxPingPongTurns.
  • announce steps can reply ANNOUNCE_SKIP to stay silent.

​
sessions_spawn

Spawns a sub-agent run in an isolated session and announces the result back to the requester channel when delivery is available. Parameters:
  • task
  • label?
  • agentId?
  • model?
  • thinking?
  • runTimeoutSeconds?
  • timeoutSeconds? (back-compat alias for runTimeoutSeconds)
  • thread?
  • runtime?
  • mode?
  • cleanup?
Rules:
  • runtime is subagent by default; acp targets an ACP harness runtime
  • allowed target Agents come from agents.defaults.subagents.allowAgents or agents.list[].subagents.allowAgents
  • sub-agent sessions use agent:<agentId>:subagent:<uuid>
  • sub-agents do not receive session tools by default
  • nested spawns are blocked unless the sub-agent depth policy explicitly allows them
  • the tool returns { status: "accepted", runId, childSessionKey }
  • channel plugins may bind thread=true spawns to thread routing when supported

​
Visibility

Session tools can be scoped:
Meanings:
  • self: current session only.
  • tree: current session plus sessions spawned by it.
  • agent: any session for the current Agent.
  • all: any session, subject to cross-agent policy.
  • sandboxed sessions clamp to the configured sandbox visibility.

​
Channel Session Commands

External channel chats expose a small command layer for the same model:
These commands mutate route, session, or task state. The session tools above are Agent tool APIs used from inside a run.

​
Send Policy

Delivery can be blocked by channel/chat type:
Runtime overrides can be set with owner-only /send on, /send off, and /send inherit commands.