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 five session tools cover the full lifecycle: start, get, list, list executions, and submit.

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.

InfraScout enforces one running session per agent. If a prior session 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.

ParameterTypeRequiredDescription
agent_idstring✓The target agent ID.
playbookstring✓The playbook name driving this session.
descriptionstring—Optional description of the session's purpose.

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 ag_3f8a1c2d."

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 sess_8c4d9e2f?"

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".

ParameterTypeRequiredDescription
agent_idstring—Filter by agent ID.
hostnamestring—Filter by hostname.
playbookstring—Filter by playbook name.
statusstring—running, pending_review, completed, failed, or interrupted.
limitnumber—Default 20.
offsetnumber—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 sess_8c4d9e2f."

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.

ParameterTypeRequiredDescription
session_idstring✓The session ID to submit.
summarystring✓A written recap of what was accomplished.

Example prompt.

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

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.