# pm_session
{{< badge content="Sovereign" color="purple" class="tier-badge" >}}

{{< callout type="info" >}}
**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.
{{< /callout >}}

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

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `limit` | number | No | Default 200 |
| `contextRef` | string | No | Filter by context ref (e.g., task key) |

---

## get

Fetch a session by ULID.

### Parameters

| Field | Type | Required |
|-------|------|----------|
| `sessionUlid` | string | Yes |

---

## events

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

### Parameters

| Field | Type | Required |
|-------|------|----------|
| `sessionUlid` | string | Yes |

---

## prompt

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

### Parameters

| Field | Type | Required |
|-------|------|----------|
| `sessionUlid` | string | Yes |

---

## config

Fetch the parsed launcher config used for this session.

### Parameters

| Field | Type | Required |
|-------|------|----------|
| `sessionUlid` | string | Yes |

---

## spec

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

### Parameters

| Field | Type | Required |
|-------|------|----------|
| `sessionUlid` | string | Yes |

---

## live_deltas

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

### Parameters

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `sessionUlid` | string | Yes | |
| `sinceSeq` | number | No | Cursor for incremental streaming |

---

## input

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

### Parameters

| Field | Type | Required |
|-------|------|----------|
| `sessionUlid` | string | Yes |
| `prompt` | string | Yes |

### Example

```text
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`](#launch_task) instead.

### Parameters

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `clientRequestId` | string | Yes | Idempotency key — use [`pm_generate_ulid`](../health/#pm_generate_ulid) |
| `actor` | string | Yes | Who is launching |
| `contextRef` | string | Yes | Context reference (e.g., task key) |
| `role` | string | Yes | Session role |
| `provider` | string | Yes | Provider key |
| `systemPrompt` | string | Yes | System prompt |
| `launcherConfigKey` | string | No | Preset to apply |
| `worktree` | object | No | `{ baseRef, branchPrefix, templateRef, projectKey, disabled }` |
| `env` | array | No | Array of `{ name, valueRef }` |
| `bootstrapCommands` | string[] | No | Commands to run before first turn |
| `tools` | string[] | No | Tool IDs to attach |
| `config` | object | No | Provider config object |

---

## run

Execute a turn for a session.

### Parameters

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `sessionUlid` | string | Yes | |
| `prompt` | string | No | Optional prompt for this turn |
| `configuration` | object | No | Config override |
| `dbPath` | string | No | DB path override |

---

## abort

Abort an in-flight run.

### Parameters

| Field | Type | Required |
|-------|------|----------|
| `sessionUlid` | string | Yes |

---

## restart

Restart a closed session using its prior thread/worktree.

### Parameters

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `clientRequestId` | string | Yes | Idempotency key |
| `actor` | string | Yes | Actor string |
| `sessionUlid` | string | Conditional | One of `sessionUlid` / `providerSessionId` required |
| `providerSessionId` | string | Conditional | Existing provider thread id |
| `prompt` | string | No | Optional prompt for the restart run |
| `run` | boolean | No | Dispatch run immediately (default `true`) |

---

## purge

Delete a session and optionally its artifacts. **Destructive.**

### Parameters

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `sessionUlid` | string | Yes | |
| `deleteFiles` | boolean | No | Delete transcript/worktree files (default `true`) |
| `dryRun` | boolean | No | Preview without deleting |

{{< callout type="warning" >}}
`deleteFiles` defaults to **`true`** — if you want to preserve worktree files and transcripts, pass `deleteFiles: false` explicitly.
{{< /callout >}}

---

## launch_task

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

### Parameters

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `clientRequestId` | string | Yes | Idempotency key |
| `actor` | string | Yes | Actor string (e.g., `"@pm"`) |
| `taskKey` | string | Yes | Task key (e.g., `"PROJ-123"`) |
| `launcherConfigKey` | string | Yes | Launcher preset key |
| `agentId` | string | No | Specific agent ID |
| `agentHandle` | string | No | Agent handle |
| `provider` | string | No | Provider override (must match launcher config) |
| `role` | string | No | Role (default `executor`) |
| `prompt` | string | No | Optional initial user message override. When provided, launch uses a minimal generated system prompt instead of the built task/capability prompt. |
| `capabilityKeys` | string[] | No | Capability keys to load |
| `additionalInstructions` | string | No | Extra context for this run |
| `sessionUlidToAudit` | string | No | Session to audit (for `auditor` role) |
| `worktree` | object | No | `{ baseRef, branchPrefix, templateRef, disabled }` |
| `config` | object | No | Config overrides |
| `maxRuntimeSeconds` | number | No | Runtime cap |
| `run` | boolean | No | Run immediately (default `true`) |

### Example

```text
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

```text
pm_session { action: "help" }
```

## Related

- [Agent Sessions feature guide](/valdr/docs/features/agent-sessions/) — product-level overview of MCP launches, chained execution, and session inspection
- [pm_task](../tasks/) — sessions launch against tasks
- [pm_review](../reviews/) — `launch_reviewer` wraps session start with review context
- [pm_audit](../audits/) — `launch` wraps session start with audit context
- [pm_provider](../providers/) — launcher presets consumed by `launcherConfigKey`
- [pm_health](../health/) — `pm_generate_ulid` for idempotency keys