Session Tools

A session is a scoped assessment run against a single agent. Every command executed and every insight saved during a session is linked back to it, so findings remain reproducible and auditable. The seven session tools cover the full lifecycle — start, get, list, list executions, and submit — plus the session groups that bundle related sessions under the conversation or run that started them.

Session Lifecycle

A session moves through a small state machine:

You start a session, run commands and save insights against it, then submit. From pending_review, only a human reviewer moves the session to completed. Submitting is not the same as terminating — submitting marks the session ready for review.

Within a single session group, an agent has at most one running session. Different groups can each run a session against the same agent at the same time, unless one of them was opened exclusively with session_start. If a prior session in the same group was left running, submit it before starting a new one.

session_start

Opens a new session for an agent. Returns the session_id that every subsequent session-scoped tool needs (agent_exec_*, insight_save, session_submit, session_get, session_list_executions). Pass that session_id back; do not pass agent_id to those tools — it is derived from the session.

Parameter	Type	Required	Description
agent_id	string	✓	The target agent ID.
playbook	string	✓	The playbook name driving this session.
description	string	—	Optional description of the session's purpose.
exclusive	boolean	—	When true, refuses to start if another group already has a running session on this agent. Default false.

session_start is idempotent within a group: calling it again for the same agent while a session is still running returns the same session_id rather than opening a second one. When other groups are running their own sessions against the same agent, the response includes a concurrent_sessions list as advisory metadata so you know the host is in use elsewhere.

Set exclusive to true to take an exclusive hold on the agent for destructive or remediation playbooks — the start fails if any other group is already running on it, and while your session runs no other group can start one. Leave it false for read-only assessments so concurrent reviews can proceed.

Idle sessions and groups close themselves. After roughly 30 minutes of inactivity, a chat or interactive session is moved from running to interrupted and its group is ended; non-chat runs hold for about 2 hours before closing. Start a fresh session to resume.

Use cases. Open a session before running any agent_exec_* command. Group a sequence of commands and findings under one playbook for audit. Reopen work on a host after a previous session has been submitted.

Example prompt.

"Start a security review session on agent 7b1c4d2e-3f8a-4c2d-9e6f-1a2b3c4d5e6f."

session_get

Returns details for a single session by session_id, including execution count and current status.

Example prompt.

"What's the status of session 4a9c7e21-6b3d-4f18-a2e5-9c0d1f8b7a6e?"

session_list

Lists sessions, most recent first. Use it for "what assessments has this host had recently", "what's currently running", or "which sessions are awaiting review".

Parameter	Type	Required	Description
agent_id	string	—	Filter by agent ID.
group_id	string	—	Filter by session group ID.
hostname	string	—	Filter by hostname.
playbook	string	—	Filter by playbook name.
status	string	—	running, pending_review, completed, failed, or interrupted.
limit	number	—	Default 20.
offset	number	—	Pagination offset.

Example prompt.

"Show me all sessions awaiting review."

session_list_executions

Returns every command executed during a session, in chronological order. Each execution carries the command text, target capability, output, exit code, and timing. Pass the session_id only.

Use cases. Reconstruct exactly what ran during a session for audit. Inspect failed steps to debug a playbook. Build a chronological narrative for a final report.

Example prompt.

"List every command executed during session 4a9c7e21-6b3d-4f18-a2e5-9c0d1f8b7a6e."

session_submit

Submits an active session for human review and writes a summary. Use this when the user says "submit", "finish", "hand off", "wrap up", or asks you to summarize assessment work — the summary argument is where the recap goes, so you do not need a separate lookup call first.

session_submit transitions the session from running to pending_review. From there, only a human reviewer moves it to completed. Do not use this tool to terminate a session early without a meaningful summary.

Parameter	Type	Required	Description
session_id	string	✓	The session ID to submit.
summary	string	✓	A written recap of what was accomplished.

Example prompt.

"We're done — submit the session and summarize the findings."

Session Groups

A session group is the container that ties a chat conversation or agentic run to the agent sessions it started. Groups are created automatically — one per conversation — and give their sessions a shared lifecycle: when the conversation ends, its group closes and every session underneath it closes too. Within a group, an agent has at most one running session at a time, but different groups can run their own sessions against the same agent concurrently unless one holds it exclusively. You never create groups yourself; the two tools below are read-only views for audit and continuity.

session_group_list

Lists session groups with optional filters. Use it to answer "what did that conversation run" or "which groups are still active".

Parameter	Type	Required	Description
status	string	—	active, completed, interrupted, or failed.
kind	string	—	chat, agentic_run, or manual.
conversation_id	string	—	Filter by the linked conversation.
started_by	string	—	Filter by user ID.
from / to	string	—	RFC3339 bounds on the start time.
limit	number	—	Default 50.
offset	number	—	Pagination offset.

Example prompt.

"List all session groups that are still active."

session_group_get

Returns one session group by group_id — the group's lifecycle metadata and the linked conversation or run ID. Drill into individual sessions with session_list and session_get.

Example prompt.

"Show me the session group for this conversation — what work did it do?"

See Also

For the agent execution tools that run inside a session, see Agent Tools. For saving findings produced during a session, see Insights. For the playbooks that drive sessions, see Playbooks and Running Assessments.