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
cancelledis 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_includedtofalseand never returns report text. - Missing and unowned jobs return the same
job_not_foundpayload.
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_includedtofalseand never returns detailed issue, recommendation, or report text. - Malformed QA JSON returns metadata plus
parse_errorwithout 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.jsonfiles 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_errorwithout 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_includedtofalseand 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, andurls_includedtofalse. - 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.jsonfiles 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, andsearch_queries_includedtofalse. - 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.jsonartifacts and the standard<report filename>.calibration.jsonsidecar 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, andrationales_includedtofalse. - 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
reportscope for authenticated HTTP callers; legacywritedoes not satisfy this scope. - It supports
content_mode=metadata|preview|full,artifact_type=report|strategy|all, and boundedmax_charsnegotiation. check_jobs,primr://output/latest, andprimr://output/by_job/{job_id}no longer return report bodies or previews to authenticated HTTP callers, even when they holdreport; 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
roleclaim 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_tooldispatcher 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
readforestimate_research,check_jobs,system_health, and compact resources,reportforread_report_by_job, plusresearchforresearch_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(orestimate_skill_pack, or A2Aestimate_research) returns, alongside the estimate, a short-lived single-useapproval_tokenbound 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_idand a body-freeotel_spanprojection 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/recentexposes 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_companypasses the approvedmax_estimated_cost_usdintoPipelineRunnerafter the cost cap and approval token checks succeedPipelineRunneractivatesutils.run_budget.RunBudget, so optional-spend checkpoints behave the same way as CLI--budget- The process-global budget is cleared in a
finallyto avoid leaking state into later jobs in the long-lived MCP server process estimate_runand CLI--dry-run --jsonexpose the samebudget_enforcementpayload, so agent clients can distinguish fast optional checkpoints, non-fast optional strategy checkpoints, and estimate-gated-only modes before asking for approval- A2A
estimate_researchreturns the samebudget_enforcementpayload, and accepted A2A research calls pass the approved cap toPipelineRunnerthrough the samebudget_usdargument 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, includingnon_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_protocoldefines 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
unknownwhen 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_restartinstead 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; aresearchcredential 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
reportscope 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