Skip to content

2.0 Agent Control Plane: Authorization, Approval, Audit

Status: IN PROGRESS - MCP Stages 1-4 are shipped for local MCP and A2A operation, including supervised worker ownership. MCP report-read scope separation and A2A skill-scope, skill-audit, compact-resource, report-read, research approval, and runtime-budget parity are shipped. Hosted worker convergence and remaining output negotiation are still planned (independent of 1.x quality work; unblocks unattended/enterprise consumption). ROADMAP anchors: Active Queue #21; SECURITY.md threat T8; cost-cap policy (mcp_server/cost_caps.py, v1.30.0); write guard (#11, shipped).

Motivation

Today MCP has per-tool scopes, server-issued approval tokens, structured tool-call and resource-read audit trails, and runtime budget propagation for fast optional stages and non-fast optional strategy documents. A2A now shares the authenticated bearer-token context and enforces skill scopes for the read and research capabilities. A2A skill calls now write the same privacy-preserving audit event shape as MCP tool calls. A2A research execution now uses the same estimate-issued approval-token and runtime-budget path as MCP. MCP also separates status and compact metadata reads from explicit report-body reads through the report scope, and A2A now exposes the same explicit report-read boundary through read_report_by_job. Local MCP and A2A research now share a supervised Python worker boundary, so terminal cancelled is published only after worker exit is observed. Provider work remains separate when its API cannot confirm cancellation. The remaining gaps are hosted-worker convergence, additional output-consumption negotiation, and better visibility around required provider tasks that expose no live cost state. The shape of the work is narrow by design: harden the control plane for Primr's actual surface, not build generic agent middleware.

Shipped local execution boundary

Local MCP and A2A use one packaged execution system:

  • one supervised Python child process owns each long local job;
  • a registry retains the job-id to worker handle mapping;
  • cancellation requests cooperative stop, waits for a bounded interval, then terminates the worker when required;
  • terminal cancelled is persisted only after the owned worker exits;
  • the worker-exit manifest records termination method and any provider work that may continue without raw request bodies;
  • partial artifacts are preserved and remain discoverable when present; and
  • runtime budget state belongs to the job process rather than leaking through process-global state.

This is process isolation, not a scheduler or a Go rewrite. The older hosted deployment runner and one-job containers have not yet converged on the packaged worker protocol. A remote provider task is described as non-interruptible unless the provider confirms its own cancellation.

The completed control-plane slice is job-scoped artifact consumption plus A2A parity. MCP already has scopes, approval tokens, structured audit, runtime budget propagation for the shipped paths, and seven compact artifact resources: primr://output/artifacts/by_job/{job_id} returns owned-job file metadata, and primr://output/qa_summary/by_job/{job_id} returns compact QA score/status and count metadata, and primr://output/usage_summary/by_job/{job_id} returns compact cost, timing, approval, execution, and artifact-count metadata, and primr://output/source_summary/by_job/{job_id} returns compact citation and source appendix metadata, and primr://output/trace_summary/by_job/{job_id} returns compact scrape trace metadata, and primr://output/verification_summary/by_job/{job_id} returns compact claim verification metadata, and primr://output/calibration_summary/by_job/{job_id} returns compact label-calibration metadata, including inference source-copy counts. None of these resources returns report body content; trace summaries omit raw trace entries, URLs, and page content, and verification summaries omit raw claims, source URLs, search queries, and explanations, and calibration summaries omit raw claims, source URLs, evidence reviews, and rationales. A2A now binds authenticated HTTP bearer tokens into the shared MCP auth context and enforces the same read/research split for estimate, status, health, research, QA, and cancellation. Authenticated A2A jobs are owned by the token client_id. A2A skill calls and task cancellation now write privacy-preserving audit events with hashed message/result payloads, hashed caller ids, granted scopes, duration, outcome, and job id when present. A2A estimate_research now returns approval-token fields, and A2A research_company enforces max_estimated_cost_usd plus a matching token by default before job creation, then propagates the accepted cap into the supervised worker's PipelineRunner as the runtime budget. A2A read_report_by_job now reuses the same ownership-gated report reader and requires report scope for authenticated callers. Local no-auth A2A is loopback-only and uses an internal marker that can read only local a2a jobs; a caller-controlled JWT subject cannot select it. A2A tasks/get applies exact request ownership and hides cross-owner task ids like missing ids. The remaining safety gap is output negotiation that is not specific to report-body reads.

Shipped artifact-resource slices

primr://output/artifacts/by_job/{job_id} is the first read-only handoff resource for completed-job consumption:

  • It is job-scoped and ownership-gated for HTTP callers.
  • It returns artifact type, file name, file path, existence, size, modified timestamp, and SHA-256 hash.
  • It sets full_content_included to false and never returns report text.
  • Missing and unowned jobs return the same job_not_found payload.

primr://output/qa_summary/by_job/{job_id} follows the same boundary for QA sidecars and current text QA reports:

  • It is job-scoped and ownership-gated for HTTP callers.
  • It reads only attached QA JSON artifacts or text QA reports and returns score, status, count, parse, hash, timestamp, and top-level-key metadata where available.
  • It sets full_content_included to false and never returns detailed issue, recommendation, or report text.
  • Malformed QA JSON returns metadata plus parse_error without echoing the malformed body.

primr://output/usage_summary/by_job/{job_id} follows the same boundary for run manifests:

  • It is job-scoped and ownership-gated for HTTP callers.
  • It reads only run_manifest.json files adjacent to owned job output paths.
  • It returns compact cost, timing, approval, budget-enforcement, execution, parse, hash, timestamp, and artifact-count metadata, including the approved ceiling, active runtime-budget flag, checkpointed stages, and non-interruptible required provider tasks.
  • It never returns company URLs, approval tokens, manifest artifact lists, or full manifest content.
  • Malformed manifests return metadata plus parse_error without echoing the malformed body.

primr://output/source_summary/by_job/{job_id} follows the same boundary for report source appendices:

  • It is job-scoped and ownership-gated for HTTP callers.
  • It reads owned markdown and text report artifacts.
  • It returns citation counts, source definition counts, missing and unused citation numbers, duplicate URL counts, domains, and source URLs.
  • It sets full_content_included to false and never returns report body content.
  • Missing report artifacts return source_summary_not_found; unowned jobs remain indistinguishable from missing jobs.

primr://output/trace_summary/by_job/{job_id} follows the same boundary for same-run scrape traces:

  • It is job-scoped and ownership-gated for HTTP callers.
  • Same-run trace JSONL files are attached to job metadata when present, bounded by the job company slug and run window.
  • It returns tier attempts, success rates, latency summaries, block counts, HTTP status counts, and validation health.
  • It sets full_content_included, raw_entries_included, and urls_included to false.
  • It never returns URLs, final URLs, raw trace entries, or page content.
  • Missing trace artifacts return trace_summary_not_found; unowned jobs remain indistinguishable from missing jobs.

primr://output/verification_summary/by_job/{job_id} follows the same boundary for claim verification artifacts:

  • It is job-scoped and ownership-gated for HTTP callers.
  • Same-run verification.json files are attached to job metadata when MCP verification runs, including fast-mode MCP runs.
  • It returns trust score, claim counts, status counts, first-party downgrade counts, and source-reference counts.
  • It sets full_content_included, raw_claim_results_included, source_urls_included, and search_queries_included to false.
  • It never returns raw claims, source URLs, search queries, explanations, or report body content.
  • Missing verification artifacts return verification_summary_not_found; unowned jobs remain indistinguishable from missing jobs.

primr://output/calibration_summary/by_job/{job_id} follows the same boundary for label-calibration sidecars:

  • It is job-scoped and ownership-gated for HTTP callers.
  • It reads attached .calibration.json artifacts and the standard <report filename>.calibration.json sidecar next to owned report artifacts.
  • It returns per-label traceability counts, inference source-copy counts, evidence-review count buckets, judge provenance, and judge-agreement metadata.
  • It sets full_content_included, raw_claims_included, claim_text_included, source_urls_included, evidence_reviews_included, and rationales_included to false.
  • It never returns raw claims, source URLs, evidence reviews, rationales, or report body content.
  • Missing calibration sidecars return calibration_summary_not_found; unowned jobs remain indistinguishable from missing jobs.

primr://output/report/by_job/{job_id} is the explicit report-body path:

  • It is job-scoped and ownership-gated for HTTP callers.
  • It requires report scope for authenticated HTTP callers; legacy write does not satisfy this scope.
  • It supports content_mode=metadata|preview|full, artifact_type=report|strategy|all, and bounded max_chars negotiation.
  • check_jobs, primr://output/latest, and primr://output/by_job/{job_id} no longer return report bodies or previews to authenticated HTTP callers, even when they hold report; authenticated callers use the explicit report resource for body consumption. Local stdio retains backwards-compatible inline artifact behavior.

Future resources should follow this pattern: compact first, report bodies only on an explicit report-read path, and no raw report or raw resource persistence in audit records.

Planned ledger summary and explainability boundary

If the run-scoped epistemic ledger is implemented after v1.45, the artifact inventory remains the first read. A compact owned-job findings summary may add only body-free schema, hash, record-count, confidence-count, anchor-coverage, review-status, relation-count, and temporal-coverage metadata. It excludes statements, source URLs, evidence excerpts, exact locator values, assumptions, rationales, and validation questions.

Full traversal such as report section -> strategic inference -> finding -> source receipt -> exact evidence anchor is a content read. It requires an explicit report/body-equivalent scope, bounded output, owned-job checks, and the same privacy-preserving audit behavior as report reads. A2A delegates to the shared resource reader rather than implementing another parser. Recorded external rationale and counterevidence may be returned; hidden model reasoning is never stored or exposed. See run-epistemic-ledger.md.

Design: four stages, each building on the previous

Stage 1 - per-tool, capability-scoped authorization (T8)

Status: SHIPPED for MCP tool dispatch and A2A skill dispatch.

  • The JWT role claim already exists and maps to scopes; enforce it per tool. Scope vocabulary stays small and capability-shaped: read (estimates, status, compact resources, qa), report (report-body resource reads), research (research_company, generate_strategy, skill packs), delegate (delegate_to_agent), admin (job clearing)
  • Tool registry annotates each tool with its required scope; the central call_tool dispatcher checks before handler dispatch (one seam - same pattern as the cost-cap check)
  • Default deny for unknown tools/scopes; stdio (host-mediated) keeps current behavior unless scopes are configured - mirrors the cost-cap transport-default precedent
  • A2A co-host inherits the same bearer-token context and enforces read for estimate_research, check_jobs, system_health, and compact resources, report for read_report_by_job, plus research for research_company, run_qa, and cancellation

Stage 2 - server-issued approval tokens for cost-incurring operations

Status: SHIPPED for MCP cost-cap-governed execution tools (research_company, generate_strategy, and generate_skill_pack) and A2A research_company.

  • Flow: estimate_run (or estimate_skill_pack, or A2A estimate_research) returns, alongside the estimate, a short-lived single-use approval_token bound to {process instance, tool, args-hash, max-cost, expiry}
  • Cost-incurring tools accept the token; with enforcement on, a valid token is required in addition to the cap, and the args-hash binding stops approve-A-execute-B swaps
  • Tokens are HMAC-signed with a server secret (no storage needed beyond a process-local replay set with TTL); single-use is enforced before execution starts. A restart changes the process-instance binding and invalidates every outstanding token even when the signing secret is shared.
  • The packaged OpenClaw workflows and the Claude skill adopt the flow so the estimate-first pattern becomes cryptographically checkable, not just documented

Stage 3 - structured agent audit log

Status: SHIPPED for MCP tool calls, MCP resource reads, and A2A skill calls.

  • Tool-call events use append-only JSONL: timestamp, transport, tool name, hashed caller id, granted scopes, args hash and result hash (never raw args or raw results), approval token id, estimated/max cost, job id, duration, and outcome
  • Resource-read events use the same JSONL file with event_type: "resource_read", tool_name: "resources/read", normalized resource kind, hashed URI, hashed result body, job id when present, granted scopes, duration, and outcome. Raw URI query values, raw resource bodies, and raw caller ids are not persisted.
  • A2A skill-call events use the same JSONL file with transport: "a2a", tool_name: "a2a/<skill>", hashed message arguments, hashed result payloads, hashed caller ids, granted scopes, duration, outcome, and job id when present. Raw A2A message text, task ids, report paths, company URLs, raw results, and caller ids are not persisted.
  • Every audit event carries a stable request_id and a body-free otel_span projection with span name plus attributes such as request id, event type, transport, tool name, status, duration, and job id when present. This gives structured logs enough information to become OpenTelemetry spans without storing raw prompts, report bodies, resource bodies, URLs, or caller ids.
  • primr://agent/audit/recent exposes recent events to local stdio callers and admin-scoped HTTP callers
  • The fields already designed for App Insights (#22: request_id, job_id, tool_name, duration_ms) reuse this record.
  • Future CLI rendering and OTLP export can read this same JSONL surface without changing the tool dispatcher or resource dispatcher

Runtime budget propagation

Status: SHIPPED for MCP research_company fast-path runs, non-fast optional strategy documents, A2A research_company execution, and compact post-run budget visibility through run manifests and usage summaries.

  • research_company passes the approved max_estimated_cost_usd into PipelineRunner after the cost cap and approval token checks succeed
  • PipelineRunner activates utils.run_budget.RunBudget, so optional-spend checkpoints behave the same way as CLI --budget
  • The process-global budget is cleared in a finally to avoid leaking state into later jobs in the long-lived MCP server process
  • estimate_run and CLI --dry-run --json expose the same budget_enforcement payload, so agent clients can distinguish fast optional checkpoints, non-fast optional strategy checkpoints, and estimate-gated-only modes before asking for approval
  • A2A estimate_research returns the same budget_enforcement payload, and accepted A2A research calls pass the approved cap to PipelineRunner through the same budget_usd argument as MCP.
  • Run manifests persist the same budget-enforcement payload plus the approved ceiling and active runtime-budget flag. primr://output/usage_summary/by_job/{job_id} exposes a sanitized projection of that metadata, including non_interruptible_required_tasks, without returning company URLs, approval tokens, manifest bodies, or artifact lists.
  • Remaining: scrape is still estimate-gated only, and required Deep Research tasks cannot be stopped mid-flight because the provider exposes cost at task completion rather than at live checkpoints

Stage 4 - truthful cancellation and execution isolation

Status: SHIPPED for local MCP and A2A jobs. Hosted container convergence and provider-confirmed remote cancellation remain planned.

  • mcp_server.worker_protocol defines the packaged versioned child-process lifecycle; the older deployment runner should converge on it.
  • One shared supervisor retains an execution handle per active local job.
  • Repeated cancellation is idempotent and terminal states are immutable.
  • The worker stops launching stages after cooperative cancellation, and the parent escalates through bounded process-tree termination when needed.
  • The parent observes worker exit before publishing terminal cancelled.
  • For failed or cancelled exits with a retained supervisor handle, the worker-exit manifest records remote provider state as unknown when it cannot be confirmed. Spawn failures and restart reconciliation remain journal-only.
  • Partial artifacts are preserved, and any worker-exit manifest is committed only after lifecycle truth is known.
  • Active journals recovered without a retained worker reconcile to failed/server_restart instead of remaining ghost jobs.
  • Research logic remains Python and scheduling stays outside the single-job worker.

Order of operations

Stage 1 -> 2 -> 3 strictly (2 needs 1's identity enforcement to mean anything; 3 logs what 1+2 decided). Runtime budget propagation follows those stages because it depends on an approved cap being meaningful. Stage 4 gives local MCP/A2A cancellation an owned execution boundary. All four stages are shipped locally. Remaining work converges hosted workers and improves request/job telemetry and post-hoc visibility for non-interruptible provider tasks.

Validation cost

Entirely free: all four stages are deterministic and fully testable with the existing JWT/test-server harnesses plus subprocess fixtures. Red-team style tests to pin: scope escalation attempts, token replay, token args-swap, audit-log injection via crafted company names, repeated cancellation, worker refusal to exit, server shutdown, and crash reconciliation.

Exit criteria

  • A low-trust agent can hold an read-only credential that cannot start paid work; a research credential cannot delegate
  • A cost-incurring call without a valid, matching approval token is refused by default on every transport; legacy opt-out is explicit and unsafe
  • Every tool invocation and resource read appears in the audit log with identity metadata, hashes, and outcome; the log survives crashes uncorrupted
  • Artifact-resource reads are compact, job-scoped, and ownership-gated before any full report content is requested
  • Report-body reads require an explicit report path and report scope for authenticated HTTP callers
  • No Primr-owned worker remains after a job becomes terminally cancelled
  • Cancellation is idempotent, crash and shutdown reconciliation are tested, and remote provider cancellation is never promised without provider support

Explicitly not

  • No user database, no OAuth server, no session management - identity stays JWT-claims-in, decisions-out
  • No generic policy engine (OPA etc.); the scope table is a dict in code
  • No multi-tenant isolation guarantees beyond per-credential scoping - primr remains a single-operator tool whose callers may be many agents
  • No generic scheduler or daemon inside Primr's single-job core
  • No Go rewrite for process ownership that the packaged Python worker protocol already provides locally
  • No claim that a client disconnect or local worker exit cancelled remote provider work