pm_session

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.

Use the launch actions to start work, input to continue an existing conversation, and events or delivery receipts to inspect progress. Session creation and provider execution are separate stages: a returned session ID does not mean the agent has completed its task.

Actions

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

list

List agent sessions.

Parameters

get

Fetch a session by ULID.

Parameters

events

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

Parameters

For incremental reads, pass the greatest returned event seq as the next sinceSeq. Use a bounded limit to keep large transcripts out of the agent’s context.

prompt

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

Parameters

config

Fetch the parsed provider config used for this session.

Parameters

spec

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

Parameters

live_deltas

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

Parameters

input

Send a prompt/input to an existing session (e.g., answer a question the agent asked, provide additional context). Choose how the message is delivered:

• Queue (delivery: "queue", the default) waits for the current turn to finish, then dispatches another turn. It can also re-engage idle or closed sessions when the provider supports resume. OpenCode queued follow-ups continue the same conversation.
• Steer (delivery: "steer") sends guidance to an active supported Codex or Claude ad-hoc turn. It requires an active turn; OpenCode and workflow-owned turns do not support steering. Unsupported or inactive targets return an error instead of silently queuing the message.

Use list first, then wake an existing session instead of launching a duplicate reviewer, executor, or auditor.

Parameters

Example

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

Delivery result

The structured response identifies the accepted message:

queued means the message was saved for delivery. For steering, completed confirms the provider acknowledged the guidance; the active turn may still be running. Steering failures or uncertain acceptance return isError: true with the structured receipt.

Reuse the same clientRequestId and message when retrying an uncertain request to read its existing receipt. An ambiguous steering request is never automatically submitted again. Inspect the session events before deciding whether another distinct message is needed.

start

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

Parameters

run

Execute a turn for a session.

This is the run action: pm_session { action: "run", sessionUlid: "..." }. It is distinct from the boolean run: true flag on launch_task and restart, which auto-starts the first turn when a session is created or resumed.

Parameters

abort

Abort an in-flight run.

Parameters

restart

Restart a closed session using its prior thread/worktree.

Parameters

run: true is an auto-dispatch flag for the resumed session. If you already have an open session and want to send another turn, use the run action instead.

purge

Delete a session and optionally its artifacts. Destructive.

Parameters

Example

pm_session { action: "purge", sessionUlid: "01HXYZ...", dryRun: true }
pm_session { action: "purge", sessionUlid: "01HXYZ...", deleteFiles: true }

launch_task

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

Parameters

The run field here is a boolean auto-start flag. It is not the same as action: "run", which dispatches a turn for an already-started session.

Example

This example chooses the branch name for a new linked task worktree:

pm_session {
  action: "launch_task",
  clientRequestId: "01HXYZ...",
  actor: "@skadi",
  taskKey: "MYAPI-42",
  launcherConfigKey: "coder-claude",
  agentHandle: "claude-coder",
  worktree: {
    requireLinked: true,
    branchName: "feature/myapi-42-rate-limiting"
  }
}

Use a valid Git branch name. If a local branch with that name already exists, Valdr appends -1, -2, and so on; use the returned branchName for the actual name. Omitting branchName keeps the existing automatic branch-naming behavior; linked worktrees default to valdr-task/<taskKey>.

The task’s project must have an available registered Git repository, and the preset must allow worktree creation. Use worktree.repoId if repository selection is ambiguous. Do not combine requireLinked: true with branchPrefix or disabled, or use this option when reusing a source worktree. Branch naming applies to launch_task creating a new worktree, rather than start, launch_prompt, or session continuation.

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

Retain the returned session identity and inspect its state or events. Retry an uncertain launch with the same clientRequestId and arguments before creating another execution.

launch_prompt

Launch a taskless session from an authored prompt and saved provider preset. This fits repository exploration or content work that does not need a task record.

pm_session {
  action: "launch_prompt",
  clientRequestId: "<generated-request-id>",
  actor: "@operator",
  launcherConfigKey: "<existing-preset-key>",
  prompt: "Using only these notes, return a JSON object with an announcement field: this release adds configurable per-IP authentication limits.",
  executionProfile: "content_only",
  worktree: { disabled: true }
}

content_only requires worktree.disabled: true, empty or omitted tools and bootstrapCommands, and no config overrides. The resolved provider must support this profile. Keep the profile unchanged when retrying the same launch ID. For new linked task branches with a chosen name, use launch_task.

help

pm_session { action: "help" }

The help payload describes the supported actions, inputs, examples, and cautions.

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 — provider presets consumed by launcherConfigKey
• pm_health — pm_generate_ulid for idempotency keys