Skip to content
Documentation
Valdr MCP
pm_session

pm_session

Sovereign
Sovereign tier required. Every pm_session action routes to a Sovereign-gated underlying tool. Session control — reading events, sending input, launching tasks, managing lifecycle — is part of the Sovereign tier. Raider and Vanguard tiers cannot use pm_session actions.

The pm_session tool manages agent sessions — the running agent workers that execute tasks, do reviews, and produce output. Sessions have ULIDs, worktree configuration, environment, and streaming output.

This is one of the most complex MCP tools because it covers the full runtime: starting sessions, sending input, streaming deltas, purging data, and launching task executions as a single atomic operation.

Actions

list, get, events, prompt, config, spec, live_deltas, input, start, run, abort, restart, purge, launch_task, help

list

List agent sessions.

Parameters

FieldTypeRequiredNotes
limitnumberNoDefault 200
contextRefstringNoFilter by context ref (e.g., task key)

get

Fetch a session by ULID.

Parameters

FieldTypeRequired
sessionUlidstringYes

events

Fetch the event stream for a session. Events include messages, tool calls, commands, and provider lifecycle markers.

Parameters

FieldTypeRequired
sessionUlidstringYes

prompt

Fetch the stored system prompt that was used when the session launched.

Parameters

FieldTypeRequired
sessionUlidstringYes

config

Fetch the parsed launcher config used for this session.

Parameters

FieldTypeRequired
sessionUlidstringYes

spec

Fetch the full spec details for a session — complete configuration including prompt, tools, worktree, and provider settings.

Parameters

FieldTypeRequired
sessionUlidstringYes

live_deltas

Fetch live text deltas (streaming output) from a running session.

Parameters

FieldTypeRequiredNotes
sessionUlidstringYes
sinceSeqnumberNoCursor for incremental streaming

input

Send a prompt/input to a running session (e.g., answer a question the agent asked, provide additional context).

Parameters

FieldTypeRequired
sessionUlidstringYes
promptstringYes

Example 

pm_session {
  action: "input",
  sessionUlid: "01HXYZ...",
  prompt: "Use the existing MiddlewareChain class instead of creating a new one."
}

start

Start a provider-backed session. This is the low-level session launch — for task-scoped launches, use launch_task instead.

Parameters

FieldTypeRequiredNotes
clientRequestIdstringYesIdempotency key — use pm_generate_ulid
actorstringYesWho is launching
contextRefstringYesContext reference (e.g., task key)
rolestringYesSession role
providerstringYesProvider key
systemPromptstringYesSystem prompt
launcherConfigKeystringNoPreset to apply
worktreeobjectNo{ baseRef, branchPrefix, templateRef, projectKey, disabled }
envarrayNoArray of { name, valueRef }
bootstrapCommandsstring[]NoCommands to run before first turn
toolsstring[]NoTool IDs to attach
configobjectNoProvider config object

run

Execute a turn for a session.

Parameters

FieldTypeRequiredNotes
sessionUlidstringYes
promptstringNoOptional prompt for this turn
configurationobjectNoConfig override
dbPathstringNoDB path override

abort

Abort an in-flight run.

Parameters

FieldTypeRequired
sessionUlidstringYes

restart

Restart a closed session using its prior thread/worktree.

Parameters

FieldTypeRequiredNotes
clientRequestIdstringYesIdempotency key
actorstringYesActor string
sessionUlidstringConditionalOne of sessionUlid / providerSessionId required
providerSessionIdstringConditionalExisting provider thread id
promptstringNoOptional prompt for the restart run
runbooleanNoDispatch run immediately (default true)

purge

Delete a session and optionally its artifacts. Destructive.

Parameters

FieldTypeRequiredNotes
sessionUlidstringYes
deleteFilesbooleanNoDelete transcript/worktree files (default true)
dryRunbooleanNoPreview without deleting
deleteFiles defaults to true — if you want to preserve worktree files and transcripts, pass deleteFiles: false explicitly.

launch_task

The high-level task launch — creates a session scoped to a task with full context. This is how orchestrators dispatch work.

Parameters

FieldTypeRequiredNotes
clientRequestIdstringYesIdempotency key
actorstringYesActor string (e.g., "@pm")
taskKeystringYesTask key (e.g., "PROJ-123")
launcherConfigKeystringYesLauncher preset key
agentIdstringNoSpecific agent ID
agentHandlestringNoAgent handle
providerstringNoProvider override (must match launcher config)
rolestringNoRole (default executor)
promptstringNoOptional initial user message override. When provided, launch uses a minimal generated system prompt instead of the built task/capability prompt.
capabilityKeysstring[]NoCapability keys to load
additionalInstructionsstringNoExtra context for this run
sessionUlidToAuditstringNoSession to audit (for auditor role)
worktreeobjectNo{ baseRef, branchPrefix, templateRef, disabled }
configobjectNoConfig overrides
maxRuntimeSecondsnumberNoRuntime cap
runbooleanNoRun immediately (default true)

Example 

pm_session {
  action: "launch_task",
  clientRequestId: "01HXYZ...",
  actor: "@skadi",
  taskKey: "MYAPI-42",
  launcherConfigKey: "coder-claude",
  agentHandle: "claude-coder"
}

The session inherits:

  • Task description and acceptance criteria
  • Linked requirements
  • Capability set from the agent
  • Provider config from the preset
  • Worktree policy from the preset

This is the atomic “delegate a task” operation — agents call this when they decide to dispatch work to an executor.

help 

pm_session { action: "help" }

Related

  • Agent Sessions feature guide — product-level overview of MCP launches, chained execution, and session inspection
  • pm_task — sessions launch against tasks
  • pm_review — launch_reviewer wraps session start with review context
  • pm_audit — launch wraps session start with audit context
  • pm_provider — launcher presets consumed by launcherConfigKey
  • pm_health — pm_generate_ulid for idempotency keys
pm_reviewpm_audit