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
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\0header, 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.fromCharCodeandchr()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) orbinary(any binary reason).- binaries: NUL bytes, a high ratio of non-text characters, magic numbers
(ELF, Mach-O, PE with a
Semantic review for
suspicioustext, and forcleantext 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 intostateasuntrustedFields, bounded to 8,000 characters. The provider answers one fixed choice:none,code,binary,injectionorunknown. Ifnonecomes back with confidence below 0.6, it is treated asunknown. A user on a multi-user server needs the Decisions API resource published to them; otherwise the reviewer is unavailable. - Control Room:
suspiciousrequests are held in the Control Room queue. The Control Room agent reviews them throughcontrol_request. codeandbinarypre-screen results skip the reviewer. A deterministic finding is final; the reviewer cannot clear it.
- Decisions API: the configured Decisions provider, through the same
owner, budget and history path as permission risk review (Decisions
history kind
Policy for a final
code,binaryorinjectionverdict:- 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.
- Block: the tool call fails with HTTP 422 (
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
systemmessage in its own inbox saying whether the request was approved and delivered, rejected, failed or expired. - Holds in the
control-roomqueue (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 thehumanqueue, 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
humanqueue, 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.
- Automatic approval requires a clean pre-screen and no recorded finding. This
covers ordinary and Danger automation in
mcpAutomaticDecisionPolicy, and a Control Room policy-reviewallow, which is turned intoneeds-human.mcpAutoApprovalHoldReasonexplains why the request is held. - An operator execution outcome whose text is not clean always goes to
administrator review (
admin-reviewstage). It is never routed directly to a Control Room worker. - The Control Room performs the semantic analysis as part of its review. Its
instructions (
control-room-instructions.ts, thedevctl-control-roomskill and the policy reviewer prompt) tell it to treat approval content as untrusted. It checks for embedded code, binaries, obfuscation, encoded payloads and prompt injection, refuses or escalates when it finds any, and records a verdict withPOST /v1/peer-payload/approvals/:id/verdict. A Control Room verdict can only escalate; it cannot clear a deterministiccodeorbinaryfinding. - One history row is recorded per approval and content hash, with channel
approvaland actionannotated. Findings raise the same alarm.
History
Every check is a row in peer_payload_checks. A row holds:
- channel and tool;
- sender session and label, and recipient;
- pre-screen verdict, score, reason codes, the fields that carried them and the detected languages;
- reviewer, reviewer verdict and model;
- final verdict and action;
- risk class of the entry point (absent on older rows);
- latency;
- the SHA-256 of the canonical field list and the payload size;
- links to the hold, alarm and approval.
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:
- a stricter policy or timeout action applies;
- Off is ignored when the server reviewer is on;
- a user may switch between the Decisions API and the Control Room, or enable a reviewer the server leaves off;
- Also review clean text can be turned on but not off.
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
TUI: Settings → Peer payload validation. In Control Room → Chats, press
pfor Payload checks: held requests (approvea, rejectd), history, and alarms (acknowledgek). Payload alarms in Control Room attention open the same view. The MCP approvals screen shows the payload pre-screen on each request.CLI:
devctl payload-checks list [--flagged] [--limit N] [--before ID] devctl payload-checks holds [--all] devctl payload-checks show <hold-id> devctl payload-checks approve|reject <hold-id> [note] devctl payload-checks alarms [--all] devctl payload-checks ack <alarm-id> devctl payload-checks settingsAdd
--jsonfor raw output.HTTP: every route below is classified
userinserver-route-policy.json. Handlers scope rows to the caller's owner; administrators see all owners. Server policy changes require an administrator and cannot be made by the Control Room.Route Purpose GET /v1/peer-payload/settingsRead server policy, user preference and effective settings PUT /v1/peer-payload/settings/serverSet the server policy (administrators) PUT /v1/peer-payload/settings/userSet your tightening preference GET /v1/peer-payload/checksCheck history GET /v1/peer-payload/holds,GET /v1/peer-payload/holds/:idHeld requests POST /v1/peer-payload/holds/:id/approve,POST /v1/peer-payload/holds/:id/rejectDecide a hold GET /v1/peer-payload/alarms,POST /v1/peer-payload/alarms/:id/acknowledgeAlarms POST /v1/peer-payload/approvals/:id/verdictControl Room verdict on an approval
Limitations
- Heuristics. The pre-screen can miss well-obfuscated code and can flag prose that looks like code. Novel encodings and natural-language descriptions of an attack pass the deterministic layer. With the default settings, a clean pre-screen is not sent to the Decisions reviewer.
- Legitimate code. Agents that share snippets are held by default. They can describe a change in prose or point to a file or commit instead.
- Federation. Inbound messages are screened synchronously and
deterministically. Grey-zone text gets the timeout action instead of a
Decisions call. The remote sender sees the per-recipient rejection reason
payload_heldorpayload_blocked, but receives no later notice when a local human approves the hold. - External MCP. External MCP senders have no session, so they get no inbox notice about a decision.
- Replay. An approved hold is replayed with its original arguments. If the
target or sender changed in the meantime, the replay fails and the hold is
marked
failed. - Tenant Control Rooms. A tenant Control Room cannot reach the
/v1/peer-payload/*operations throughcontrol_request. Holds and verdicts for tenants are decided by humans. - Human channels. Text typed by humans (TUI, messengers, the Control Room chat composer) is not screened.