Session

Split work between Main and Child Sessions, coordinate execution, and read bounded history

Session Power reads the current Agent's Chat, Work, and archived history. Use check to obtain the target session_id and session_category. Historical content is reference data. Reading pending interactions does not grant permission to answer or approve them.

Split and execute work

Chat uses session.start to create an autonomous Work Main. The Work Main owns the complete task: it inspects the necessary context and understands the goal, constraints, completion criteria, and dependencies before deciding whether to split work. It creates Children for independently actionable threads only when separate context or parallel execution helps. It completes simple or tightly coupled work directly.

The Main retains the overall approach, key decisions, substantive execution, integration, and verification. Do not forward the entire assignment unchanged to a single Child or create multiple Children just to split work. The same responsibilities apply when delegating to another Agent with agent.delegate.

Each delegated query includes a specific goal, necessary context, scope, expected output, and completion criteria. The new Session does not inherit the caller's conversation. The Main coordinates dependencies and file ownership across threads; separate contexts do not isolate files in a shared Workspace.

For example, when implementing login, the Main first examines the authentication architecture and establishes the interface and state flow. Once the boundaries are clear, it can delegate the frontend interaction and backend authentication interface separately, advance the integration work itself, and verify the complete login flow.

start returns a creation receipt, and execution results return automatically to the actual caller. The Main advances other work while waiting, then checks evidence, resolves gaps and conflicts, and verifies the integrated result against the complete task before delivery. A Child finishing establishes only that its thread has ended. Use send to continue a directly created Work Session; do not poll for results.

Child and Task Sessions cannot delegate further. A Work Main waits for its current Turn's child work to finish before completing that Turn. Stopping a Main stops its active Children. Stopping a Chat reply leaves its autonomous Mains running. Questions and approvals remain in the Session that raised them for the user to handle.

Read session history

check lists each record's storage_id, logical session_id, category, and archived state. For archived details, pass its exact storage_id together with session_id and session_category to check, messages, and every following part request. Omitting storage_id reads only the active address. Several archived records may share a logical ID after the main conversation is recreated; their record UUIDs remain distinct.

The UUID is a read address within the current Agent's existing permissions. It does not grant control: send, reply, stop, and archive retain their own caller and parent/child checks and do not accept an archived read address.

archive accepts optional operation_id and root_storage_id as a recovery handle. Keep the original handle after partial failure and pass it again to continue the same saved subtree plan. A completed replay reports changed: false; it never targets a recreated active record. Recovery still checks the caller against the original root's direct parent relation. A record UUID or operation ID alone grants no control permission.

messages returns a canonical-history directory: message IDs, sequences, roles, states, timestamps, Part counts, source locations, and short Part previews. The directory uses a 64 KiB source-page budget and may contain fewer messages than limit. source: canonical_history identifies the source; view and truncated describe the directory. All model-bound tool results, including check, messages, and part, use the shared 16 KiB result disclosure contract described below.

{
  "action": "messages",
  "args": { "session_id": "target_session", "session_category": "work", "limit": 15 }
}

Pass next_before_sequence as before_sequence to read older messages. Each message previews its first few Parts. Use its message_id and sequence to list all Parts:

{
  "action": "part",
  "args": {
    "session_id": "target_session",
    "session_category": "work",
    "message_id": "message_id",
    "message_sequence": 30,
    "limit": 20
  }
}

Continue with after_part_sequence: next_after_part_sequence until has_more is false. Each Part includes its stable part_id, available fields, original byte length, and a preview. To read a field, provide both part_id and field:

{
  "action": "part",
  "args": {
    "session_id": "target_session",
    "session_category": "work",
    "message_id": "message_id",
    "message_sequence": 30,
    "part_id": "tool_part_id",
    "field": "output",
    "offset": 0,
    "length": 2048
  }
}

Select a top-level Part field such as text, input, output, error, or data. Strings are returned verbatim. Structured fields are serialized as JSON text; fragments marked encoding: json_text are text rather than standalone JSON values. Offsets and lengths use UTF-16 code units. Follow next_offset until end: true instead of assuming a fixed increment. Normal cursors avoid splitting emoji surrogate pairs. An empty field or an offset exactly at the end returns an empty terminal segment. Invalid fields and out-of-range offsets produce explicit errors.

Read a saved tool result

Every model-bound tool executes once. The runtime saves the complete result in its canonical Tool Part before returning a readable reference. Results whose final UTF-8 JSON payload is at most 16 KiB retain their business structure without an extra envelope. Larger results return view: folded_result, a head-and-tail preview, omitted_characters counted as Unicode code points, total_bytes, total_lines, result_ref, and next_cursor. The entire folded packet, including metadata and escaping, fits within 16 KiB.

Use the general lookup tool to read that same immutable result:

lookup({ result_ref: "res_1_…", cursor: next_cursor, limit: 100 })

Omit cursor to start at the beginning. limit defaults to 100 lines and accepts 1–200; the complete page also fits within 16 KiB, so long lines may span pages. A page returns view: result_page, text, next_cursor, and eof. Pass the opaque cursor unchanged; it is bound to this result and format version. At EOF, next_cursor is null. JSON is read as fixed-format json_text, without JSONPath or structural queries. Reading a result never executes its tool again or resends attachments and interactive content. Long-running tools return a snapshot for each call; a later log-read call produces another snapshot. lookup does not follow a live log.

result_ref identifies saved output; tool_call_id identifies execution. References do not grant access to another Agent's sessions. Readable archived results remain available under the existing session permissions; deleted or unavailable results return a small error. If saving fails after execution, the runtime reports that execution occurred and does not automatically rerun the operation.

Canonical Parts preserve complete output separately from the actual model_output, disclosure_version, and result_ref. History replay and summaries use only disclosed content, including pages already read; unread original text is not automatically injected. SDK calls retain complete business data. Use session.part for historical Part structure and field evidence.