Peer payload validation

Agents send each other free-form text: messages, questions, task prompts, board items, reports and handoffs. Agents also send approval requests that the Control Room acts on with broad authority. Any of this text can carry executable code, an embedded binary or instructions aimed at the reading agent. Peer payload validation screens that text before it is delivered or stored, keeps a hash-only history of every check, holds suspicious requests for a decision and raises a Control Room alarm when it finds code or a binary.

The feature does not sandbox or execute anything. It is a filter in front of delivery. A clean verdict does not prove the text is harmless. Receiving agents must still treat peer text as untrusted data.

Covered entry points

Only free-form fields are screened. Enum, ID, number and boolean fields are excluded by construction: each tool lists the argument paths that carry prose, and identifier-like keys inside them (id, …Id, …Hash, …At, url, kind, status and similar) are skipped. The table lives in apps/controller/src/peer-payload-validation.ts (peerPayloadCoverage).

Session MCP (`POST /v1/mcp/tools/:tool`)

Tool Screened fields Reader
send_session_message subject, body Recipient sessions (local or federated)
ask_session question Target session
reply_to_request reply Asking session
delegate_task goal, context Delegated session
complete_delegated_task result (summary, checks, changed files, structured data) Delegating session
create_board name, description Every session of the Project
create_board_item, update_board_item title, body, labels Board readers; assignee inbox
release_board_item note Board readers
complete_board_item result Board readers
report_agent_task title, summary, detail, stepLabel, agent Peers via the task graph and session list
set_session_title title Approval requester labels, External MCP session list
update_session_plan goal, items Peers via the task graph
record_design_link title, note Other sessions via list_design_links
report_session_handoff goal, nextStep, completed, testResults, knownIssues, changedFiles, quotaCheckpoint Successor session
request_review role, issueRef Review cycle
control_session_input text The target session's terminal prompt
control_request String leaves of body, only for operations that deliver into sessions: POST /v1/scheduled-tasks, POST /v1/scheduled-tasks/normalize, PATCH /v1/scheduled-tasks/:id, POST /v1/sessions/:id/human-instruction, POST /v1/sessions/:id/notices, POST /v1/sessions/:id/handoffs, POST /v1/sessions/:id/input Sessions that receive scheduled prompts, instructions or notices

Other channels

Channel Entry point Screened fields
External MCP send_session_instruction (scope session:write) in ExternalMcpToolbox.call text
Federation inbound Federation.acceptMessage, before local delivery subject, body
Approvals Every persisted mcp-approval (Store.save) Agent-authored text: the permission request (title, resource, actions, purpose, constraints), team policy exception, workspace resource and repository network reasons, operator execution outcome, requester session name

Approvals are covered for request_permission, request_operator_execution, request_policy_exception, request_workspace_resources and request_repository_network_access. Controller-authored parts of an approval, such as command plans, previews and classifications, are not screened.

Pipeline

  1. Deterministic pre-screen (peer-payload-detector.ts). It is bounded (64 KiB per field, 256 KiB per request, 2,000 lines, 8 decoded runs of at most 4 KiB, decode depth 2) and has no dependency that executes anything. Zero-width and soft-hyphen characters are removed and text is NFKC-normalized first, so fullwidth or split keywords match. It detects:

    • binaries: NUL bytes, a high ratio of non-text characters, magic numbers (ELF, Mach-O, PE with a PE\0\0 header, WASM, zip/jar, gzip, bzip2, xz, 7z, Java class);
    • base64 and hex runs of 160 characters or more. These are decoded, checked for magic numbers and binary content, and re-scanned for code. Paths, slugs and commit or SHA-256 digests are not treated as encodings;
    • shebangs, fenced code blocks, escape sequences (\x.., \u00.., octal), String.fromCharCode and chr() chains;
    • strong single-line patterns: curl … | sh, bash -c, python -c, node -e, PowerShell -EncodedCommand/IEX/DownloadString, reverse shells, rm -rf /, fork bombs, base64 -d | sh, eval(atob(…))/exec(b64decode(…)), __import__('os'), <script>, <?php, @echo off, SQL injection;
    • weighted structure for shell, Python, JavaScript/TypeScript, PowerShell, SQL, C-family, Go, Rust, Java, Ruby and PHP. A single stray keyword in prose does not count. Structure must repeat across lines, unless the single line is itself an execution primitive or destructive SQL.

    The verdict is clean, suspicious (score 3–5), code (score 6 or more) or binary (any binary reason).

  2. Semantic review for suspicious text, and for clean text when Also review clean text is on or the entry point is high risk (see Risk classes):

    • Decisions API: the configured Decisions provider, through the same owner, budget and history path as permission risk review (Decisions history kind peer-payload). The payload goes only into state as untrustedFields, bounded to 8,000 characters. The provider answers one fixed choice: none, code, binary, injection or unknown. If none comes back with confidence below 0.6, it is treated as unknown. A user on a multi-user server needs the Decisions API resource published to them; otherwise the reviewer is unavailable.
    • Control Room: suspicious requests are held in the Control Room queue. The Control Room agent reviews them through control_request.
    • code and binary pre-screen results skip the reviewer. A deterministic finding is final; the reviewer cannot clear it.
  3. Policy for a final code, binary or injection verdict:

    • Block: the tool call fails with HTTP 422 (peer_payload_blocked). The message names the reasons and the check ID.
    • Hold for approval (default): nothing is delivered. The tool returns { held: true, holdId, checkId, verdict, reasons, message }. The message says the request has not been delivered and must not be resent.
    • Allow and flag: the request is delivered and the check is recorded as flagged.

    If the reviewer times out or is unavailable, the timeout action applies: allow and flag, hold (default), or block.

  4. Holds. A held request keeps its exact arguments and the authenticated sender identity, so an approval can deliver it. The arguments are discarded when the hold is decided or expires (after 24 hours by default). The bounded preview shown to reviewers is display-only, rendered without control characters, and also discarded with the decision.

    • Approving replays the original call as the same live session. The replay fails if that session is no longer running.
    • The sender always receives a system message in its own inbox saying whether the request was approved and delivered, rejected, failed or expired.
    • Holds in the control-room queue (grey-zone text with the Control Room reviewer) can be decided by the Control Room or a human. Binaries and all Decisions-mode holds are in the human queue, which the Control Room cannot decide.
    • Messages and other covered calls sent by a Control Room session (Main or one of its workers, within the owner's Control Room messaging scope) are screened like any other sender, but their holds always go to the human queue, so a Control Room never approves its own or its workers' held payloads.

Risk classes

Each entry point has a risk class, recorded on its history row as riskClass and shown as "high risk" in the TUI history.

Class Entry points Why
high delegate_task, create_board_item, update_board_item, report_session_handoff, control_session_input, control_request, external send_session_instruction The recipient acts on the text as work or input: a task prompt, a work item, a handoff, typed input or a scheduled prompt.
normal every other covered tool and federation inbound messages Conversational text the recipient reads as untrusted data.

With the Decisions reviewer:

Pre-screen high normal
clean reviewed when Decisions can serve the owner reviewed only with Also review clean text
suspicious reviewed reviewed
code/binary policy applies, no review policy applies, no review

"Can serve the owner" means Decisions is configured and, on a multi-user server, published to that user. Without it, high-risk clean text is decided by the pre-screen alone, as before, so delegations are not held merely because Decisions is absent. Once a review is needed, a failed or timed-out review applies the timeout action; it is never delivered as reviewed. The Control Room reviewer and off are unchanged.

Approvals are not in this table: they are screened by the approval path below and their prose is judged by the permission risk review.

The synchronous screen used inside transactions (federation inbound) never calls a model. Anything that would need a review there, including clean text under Also review clean text and high-risk clean text, is treated as an unavailable review, so the timeout action applies.

Approvals that reach the Control Room

Approval content goes through the same deterministic pre-screen. The verdict and reasons are attached to every approval response as a read projection, payloadScreen, which is recomputed on each read and never trusted from storage.

History

Every check is a row in peer_payload_checks. A row holds:

The payload text itself is never stored in history. Retention defaults to 30 days and can be set from 1 to 365 days. Each table is also capped (20,000 checks, 2,000 holds, 2,000 alarms). A bounded sweep runs every minute.

Alarms

A final code, binary or injection verdict raises an alarm. Alarms for the same sender and tool within 10 minutes fold into one open alarm with a count, so bursts produce one Control Room attention item. Each open alarm appears as Control Room attention reason payload-alarm, with target { type: "payload-check", alarmId } linking to the payload check view. Alarms stay open until a human acknowledges them. The Control Room cannot acknowledge alarms.

Settings and multi-user policy

Settings → Peer payload validation:

Setting Values Default
Reviewer Off / Decisions API / Control Room Decisions API
When code or a binary is found Allow and flag / Hold for approval / Block Hold for approval
When the reviewer times out Allow and flag / Hold for approval / Block Hold for approval
Also review clean text on / off off

Server-only values: timeoutMs (default 4,000 ms), retentionDays and holdHours (PUT /v1/peer-payload/settings/server).

The server policy is set by the owner or administrators. Every other user saves a preference that can only tighten it:

The effective settings of the sender's owner apply to each request.

Approval screening is deterministic and always on, independent of the reviewer setting.

Interfaces

Limitations