pm_audit
{"content":"{{\u003c tier level=\"vanguard\" \u003e}}\n\nThe `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.\n\nUse `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.\n\n## Actions\n\n`launch`, `context`, `events`, `score`, `score_list`, `help`\n\n---\n\n## launch\n\nLaunch an auditor session attached to an existing task and source session.\n\n### Parameters\n\n| Field | Type | Required | Notes |\n|-------|------|----------|-------|\n| `clientRequestId` | string | Yes | Idempotency key |\n| `taskKey` | string | Yes | Task the audit is attached to |\n| `sourceSessionUlid` | string | Yes | The session being audited |\n| `actor` | string | No | Who is launching |\n| `agentId` / `agentHandle` | string | No | Specific auditor agent |\n| `provider` | string | No | Provider type |\n| `launcherConfigKey` | string | No | Preset to use |\n| `prompt` | string | No | Initial user message override |\n| `systemPrompt` | string | No | System prompt override |\n| `config` | object | No | Provider configuration overrides |\n| `role` | string | No | Agent role |\n| `capabilityKeys` | string[] | No | Hot-loaded capabilities |\n| `additionalInstructions` | string | No | Extra context |\n| `maxRuntimeSeconds` | number | No | Runtime cap |\n| `run` | boolean | No | Auto-run after launch |\n\n### Example\n\n```text\npm_audit {\n action: \"launch\",\n clientRequestId: \"\u003cgenerated-request-id\u003e\",\n taskKey: \"MYAPI-42\",\n sourceSessionUlid: \"01HXYZ...\",\n agentHandle: \"tyr-v2\",\n launcherConfigKey: \"auditor-claude\"\n}\n```\n\n---\n\n## context\n\nFetch compact audit metadata for a session. Returns everything an auditor needs to get oriented without loading the full transcript.\n\n### Parameters\n\n| Field | Type | Required |\n|-------|------|----------|\n| `sessionUlid` | string | Yes |\n\n### Returns\n\n| Field | Description |\n|-------|-------------|\n| `capabilitiesAttached` | Capabilities that were attached to the audited session |\n| `capabilitiesDeclared` | Capabilities the agent declared using |\n| `promptCapabilitiesParsed` | Parsed capability references from the prompt |\n| `scoreTemplate` | The scoring template the auditor should apply |\n\n---\n\n## events\n\nFetch 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.\n\n### Parameters\n\n| Field | Type | Required | Notes |\n|-------|------|----------|-------|\n| `sessionUlid` | string | Yes | |\n| `sinceSeq` | number | No | Cursor (default `-1`) |\n| `limit` | number | No | Default `50` |\n| `textMaxLength` | number | No | Truncate long text fields |\n| `includePayloadJson` | boolean | No | Include raw payloads |\n\nUse `textMaxLength` and `includePayloadJson: false` to keep auditor context compact. Pass the returned `structuredContent.nextSinceSeq` as `sinceSeq` on the next page; do not use array indexes as cursors.\n\n---\n\n## score\n\nIngest a complete score-audit payload.\n\n### Parameters\n\n| Field | Type | Required |\n|-------|------|----------|\n| `scorePayload` | object | Yes |\n\nStart from the `scoreTemplate` returned by `context`, which provides the required `findings[]` and `criteria[]` structure. Fill it from the inspected evidence before submitting it as `scorePayload`. Valdr validates and saves the seven-dimension scorecard so it appears in dashboards and review history.\n\n---\n\n## score_list\n\nList stored score runs with optional filters.\n\n### Parameters\n\n| Field | Type | Required | Notes |\n|-------|------|----------|-------|\n| `taskKey` | string | No | |\n| `scoredSessionUlid` | string | No | The audited session |\n| `scoredAgentHandle` | string | No | Who was scored |\n| `auditorAgentHandle` | string | No | Who scored |\n| `limit` | number | No | Default `50` |\n\n---\n\n## help\n\nReturn the structured action reference from the running MCP server.\n\n```text\npm_audit { action: \"help\" }\n```\n\nThe help payload is a read-only contract for audit-specific orchestration:\n\n| Field | Contents |\n|-------|----------|\n| `actions` | Every accepted `pm_audit` action: `launch`, `context`, `events`, `score`, `score_list`, and `help` |\n| `whenToUse` | Action-by-action guidance for launching auditors, loading compact context, paging evidence events, ingesting score payloads, and listing score runs |\n| `examples` | Representative calls such as fetching audit context, paging compact events, and listing recent score runs for a task |\n| `cautions` | Guardrails for paginating large sessions, carrying `nextSinceSeq`, validating score payloads, and tying launches to a `sourceSessionUlid` |\n| `compatibility` | Compatibility notes for supported calls |\n\nUse `help` when building auditor agents or score dashboards that need to check audit actions and inputs.\n\n## Related\n\n- [Reviewable AI Agent Workflows](/valdr/docs/features/reviewable-workflows/) — product-level overview of evidence-backed review, audit, and approval gates\n- [pm_review](../reviews/) — review lifecycle management, reviewer launches, and lightweight review scores\n- [pm_session](../sessions/) — lower-level session mechanics","description":"Auditor launch surface — dedicated workflow for launching auditors, fetching audit evidence, and ingesting score runs.","title":"pm_audit"}
Vanguard
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 |
prompt | string | No | Initial user message override |
systemPrompt | string | No | System prompt override |
config | object | No | Provider configuration overrides |
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
pm_audit {
action: "launch",
clientRequestId: "<generated-request-id>",
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. Pass the returned structuredContent.nextSinceSeq as sinceSeq on the next page; do not use array indexes as cursors.
score
Ingest a complete score-audit payload.
Parameters
| Field | Type | Required |
|---|---|---|
scorePayload | object | Yes |
Start from the scoreTemplate returned by context, which provides the required findings[] and criteria[] structure. Fill it from the inspected evidence before submitting it as scorePayload. Valdr validates and saves the seven-dimension scorecard so it appears 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
Return the structured action reference from the running MCP server.
pm_audit { action: "help" }The help payload is a read-only contract for audit-specific orchestration:
| Field | Contents |
|---|---|
actions | Every accepted pm_audit action: launch, context, events, score, score_list, and help |
whenToUse | Action-by-action guidance for launching auditors, loading compact context, paging evidence events, ingesting score payloads, and listing score runs |
examples | Representative calls such as fetching audit context, paging compact events, and listing recent score runs for a task |
cautions | Guardrails for paginating large sessions, carrying nextSinceSeq, validating score payloads, and tying launches to a sourceSessionUlid |
compatibility | Compatibility notes for supported calls |
Use help when building auditor agents or score dashboards that need to check audit actions and inputs.
Related
- Reviewable AI Agent Workflows — product-level overview of evidence-backed review, audit, and approval gates
- pm_review — review lifecycle management, reviewer launches, and lightweight review scores
- pm_session — lower-level session mechanics