Session Tools

Session tools enable persistent, asynchronous coordination between agent sessions.

Available Tools

sessions_list

List sessions visible to the current policy.

Input:

{
  "filter": "optional text",
  "limit": 20
}

sessions_history

Read message history from a target session.

Input:

{
  "key": "agent:research:main",
  "limit": 20,
  "offset": 0
}

sessions_search

Search prior session history for relevant snippets. By default the current session is excluded when _session_key is available in tool context.

{
  "query": "checkpoint rollback",
  "limit": 5,
  "exclude_current": true
}

sessions_send

Send a message to another session, optionally waiting for reply.

{
  "key": "agent:coder:main",
  "message": "Please implement JWT middleware",
  "wait_for_reply": true,
  "context": "coordinator"
}

Session Access Policy

Configure policy in a preset to control what sessions a sub-agent can access:

[agents.presets.coordinator]
tools.allow = ["sessions_list", "sessions_history", "sessions_search", "sessions_send", "task_list", "spawn_agent"]
sessions.can_send = true

[agents.presets.observer]
tools.allow = ["sessions_list", "sessions_history", "sessions_search"]
sessions.key_prefix = "agent:research:"
sessions.can_send = false

Policy fields:

• key_prefix: restrict visibility by session-key prefix
• allowed_keys: extra explicit session keys
• can_send: controls sessions_send (default: true)
• cross_agent: allow access to sessions owned by other agents (default: false)

When no policy is configured, all sessions are visible and sendable.

Coordination Patterns

Use spawn_agent when work is short-lived and synchronous. For longer delegated work, call spawn_agent with nonblocking: true; it returns a task_id while the sub-agent continues in the background. Use spawn_status to check progress, spawn_result to fetch the final output, spawn_list to recover task IDs after context loss, and cancel_spawn to stop work that is no longer needed.

Use active_tools and tool_choice to prevent model drift on small/cheap LLMs. These controls apply per agent run (not per iteration within a run) and are available on agent presets, spawn_agent, and cron agentTurn payloads.

• active_tools filters the tool schemas visible to the agent.
• tool_choice controls provider-level tool selection:
  • auto — model decides (default).
  • any — model must call some tool but chooses which one.
  • none — no tools sent; forces text-only output.
  • tool + name — model must call the named tool.

Supported on Anthropic, OpenAI (Responses and Chat Completions), and OpenAI-compatible providers.

Classify-then-generate pattern — use two spawn_agent calls, each with its own tool controls:

// Turn 1: forced classifier
{
  "task": "Classify whether the reply should be inline, file, or PR.",
  "active_tools": ["classify_destination"],
  "tool_choice": { "type": "tool", "name": "classify_destination" },
  "nonblocking": true
}
// Turn 2: scoped generation (parent reads classifier result, spawns again)
{
  "task": "Generate the report and send it as a document.",
  "active_tools": ["write_file", "send_document"],
  "tool_choice": { "type": "auto" }
}

Example preset defaults:

[agents.presets.destination-router.tool_controls]
active_tools = ["classify_destination"]

[agents.presets.destination-router.tool_controls.tool_choice]
type = "tool"
name = "classify_destination"

Example scheduled agent turn:

{
  "kind": "agentTurn",
  "message": "Generate the report and send it as a document.",
  "active_tools": ["write_file", "send_document"],
  "tool_choice": { "type": "any" }
}

Use session tools when you need:

• long-lived specialist sessions
• handoffs with durable history
• asynchronous team-style orchestration

Common coordinator flow:

1. sessions_list to discover workers
2. sessions_search to find prior related work
3. sessions_history to inspect progress
4. sessions_send to dispatch next tasks
5. task_list to track cross-session work items