# pm_audit
{{< badge content="Vanguard" color="blue" class="tier-badge" >}}

The `pm_audit` tool is the dedicated auditor workflow surface. It's thinner than `pm_review` — focused specifically on launching auditor agents, fetching the context they need, and ingesting the seven-dimension score payloads they produce.

Use `pm_audit` when you're building audit-specific orchestration. Auditor launch and score-run workflows live here; `pm_review` stays focused on review lifecycle management and lightweight review scores.

## Actions

`launch`, `context`, `events`, `score`, `score_list`, `help`

---

## launch

Launch an auditor session attached to an existing task and source session.

### Parameters

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `clientRequestId` | string | Yes | Idempotency key |
| `taskKey` | string | Yes | Task the audit is attached to |
| `sourceSessionUlid` | string | Yes | The session being audited |
| `actor` | string | No | Who is launching |
| `agentId` / `agentHandle` | string | No | Specific auditor agent |
| `provider` | string | No | Provider type |
| `launcherConfigKey` | string | No | Preset to use |
| `role` | string | No | Agent role |
| `capabilityKeys` | string[] | No | Hot-loaded capabilities |
| `additionalInstructions` | string | No | Extra context |
| `maxRuntimeSeconds` | number | No | Runtime cap |
| `run` | boolean | No | Auto-run after launch |

### Example

```text
pm_audit {
  action: "launch",
  clientRequestId: "audit-myapi-42-abc",
  taskKey: "MYAPI-42",
  sourceSessionUlid: "01HXYZ...",
  agentHandle: "tyr-v2",
  launcherConfigKey: "auditor-claude"
}
```

---

## context

Fetch compact audit metadata for a session. Returns everything an auditor needs to get oriented without loading the full transcript.

### Parameters

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

### Returns

| Field | Description |
|-------|-------------|
| `capabilitiesAttached` | Capabilities that were attached to the audited session |
| `capabilitiesDeclared` | Capabilities the agent declared using |
| `promptCapabilitiesParsed` | Parsed capability references from the prompt |
| `scoreTemplate` | The scoring template the auditor should apply |

---

## events

Fetch paged audit evidence for a session. Unlike `pm_session.events`, this is shaped for audit consumption — paged, text-length-limited, optionally excluding raw payload JSON.

### Parameters

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `sessionUlid` | string | Yes | |
| `sinceSeq` | number | No | Cursor (default `-1`) |
| `limit` | number | No | Default `50` |
| `textMaxLength` | number | No | Truncate long text fields |
| `includePayloadJson` | boolean | No | Include raw payloads |

Use `textMaxLength` and `includePayloadJson: false` to keep auditor context compact.

---

## score

Ingest a complete score-audit payload.

### Parameters

| Field | Type | Required |
|-------|------|----------|
| `scorePayload` | object | Yes |

The payload is the full seven-dimension scorecard structure the auditor produces. Valdr validates and persists it so it shows up in dashboards and review history.

---

## score_list

List stored score runs with optional filters.

### Parameters

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `taskKey` | string | No | |
| `scoredSessionUlid` | string | No | The audited session |
| `scoredAgentHandle` | string | No | Who was scored |
| `auditorAgentHandle` | string | No | Who scored |
| `limit` | number | No | Default `50` |

---

## help

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

## Related

- [Reviewable AI Agent Workflows](/valdr/docs/features/reviewable-workflows/) — product-level overview of evidence-backed review, audit, and approval gates
- [pm_review](../reviews/) — review lifecycle management, reviewer launches, and lightweight review scores
- [pm_session](../sessions/) — lower-level session mechanics