Steer envelope v1
This specification defines what a steer makes visible inside a running sandbox: the steer files and the message the agent receives. It is the contract between fullsend run, the agent runtimes, and the agent definitions in fullsend-ai/agents.
- ADR 0119 decides when a steer happens and which records it may carry.
- ADR 0117 (proposed) decides how a runtime delivers the message.
- ADR 0118 (proposed) and ADR 0121 (proposed) decide the GitHub Actions change signal and the default.
- ADR 0141 requires a versioned schema before extension output becomes sandbox-visible. This document is that schema for steer output. Its manifest stands in for the snapshot manifest under the scoped partial supersession in ADR 0119, with the same filtering, digest, permissions, exact-path, and cleanup rules.
This document is normative. The key words MUST, MUST NOT, and MAY are used as in RFC 2119.
Overview
Each steer produces two things:
| Part | What it is | Who reads it |
|---|---|---|
| Steer directory | One manifest plus one filtered file per admitted record, in an agent-immutable tree | The agent, through file reads |
| Envelope | A short message that lists the steer's records by key and path, with the new head | The agent, as a new user turn |
Record bodies appear only in the steer directory. The envelope carries no source-authored text, so a record body cannot forge envelope structure.
Steer directory
Location
Fullsend reserves one sandbox path per cycle, a sibling of the snapshot path:
/sandbox/entity-context-steer/
├── 0001/
│ ├── manifest.json
│ └── records/<order-key>-<record-key>.md
└── 0002/
└── ...FULLSEND_STEER_DIRpoints to/sandbox/entity-context-steerinside the sandbox.- Each steer writes a new directory named by its one-based sequence number within the cycle, zero-padded to four digits so names sort in steer order. Four digits bound a cycle to 9999 steers, so
max_steersMUST NOT exceed 9999. Earlier steer directories stay until the cycle ends. - Fullsend MUST reject a checkout or
host_filesdestination that overlaps this path, and MUST decline steering if the path exists with unexpected contents at sandbox start.
Record files
Each admitted record is one file. Its name and bytes follow the entity-context-snapshot v1 record rules exactly: the records/<order-key>-<record-key>.md name, the fixed Fullsend-Record, Source-ID, Author-ID, and Created-At header, and the filtered body. A record key derived for a steer is the same key the snapshot derives for that forge record.
- A changed version of a record that is already in the snapshot keeps its record key. The steer file holds the current filtered revision; the snapshot copy is not modified.
- A record whose filter status is
rejected, or whose admission failed, has no file. It appears only in the manifest'somittedlist.
Manifest
manifest.json is UTF-8 JSON serialized with RFC 8785, with no byte-order mark and no trailing newline. Timestamps and Git object IDs use the entity-context-snapshot v1 canonical forms.
| Field | Type | Meaning |
|---|---|---|
schema_version | string | Always "steer-envelope/v1" |
filter_version | string | The pipeline version; MUST equal the cycle snapshot's filter_version |
sequence | integer | This steer's sequence number, from 1 |
snapshot_input_revision | string | SHA-256 of the cycle snapshot's index.json bytes |
previous_manifest_sha256 | string or null | SHA-256 of the previous steer's manifest bytes; null for the first |
entity | object | source (as in the snapshot index), kind, and the entity record key |
head | object or null | sha and previous_sha for a change proposal whose head moved and was provisioned; otherwise null |
records | array | One entry per admitted record, sorted by created_at then record key |
omitted | array | One entry per scope and code, sorted by scope then code |
Each records[] entry:
| Field | Meaning |
|---|---|
record_key | The snapshot record key |
kind | entity, comment, or review |
path | Path relative to the steer directory, for example records/<order-key>-<record-key>.md |
sha256 | SHA-256 of the file bytes |
created_at | Source creation time |
revision | The source's current-revision time (its edit time, or created_at when never edited) |
replaces_snapshot | true when the snapshot holds an earlier revision of the same record |
actor | id, login, and either role (human, verified at release) or bot_role (ADR 0107) |
filter | status (unchanged, modified, or truncated) and findings (codes and counts), as in the snapshot |
Each omitted[] entry has scope (entity, comments, or reviews), code (authorization_failed, unsafe_content, fetch_failed, source_too_large, or invalid_metadata), and count. Omitted entries hold no record text, keys, or logins.
The manifest's own path set is exact: every file under the steer directory is either manifest.json or listed in records[].path.
Write, permissions, and cleanup
| Rule | Requirement |
|---|---|
| Assembly | The host builds the directory in host-private state, then verifies every sha256 and the exact path set before upload |
| Release check | The fresh authorization check for every record runs after assembly and immediately before upload, under the sandbox write lock. A record that fails is removed and moved to omitted |
| Upload | Rejects symlinks and special files at every path component, as the snapshot does |
| Permissions | Agent-immutable, with the snapshot's modes: a read-only bind mount, or root-owned 0555 directories and 0444 files with the agent unprivileged and without CAP_FOWNER. If neither can be enforced, Fullsend MUST NOT steer |
| Host copy | The snapshot's host modes, 0700 directories and 0600 files (owner-only), outside the clone and the retained run-output tree |
| Cleanup | The sandbox copy is removed with the cycle's snapshot copy; the host copy after the post-script, on every controlled exit. Startup scavenges abandoned copies |
| Artifacts | Steer directories are excluded from retained artifacts. Diagnostics MAY keep counts, digests, and filter codes, never bodies |
Envelope
The envelope is the message appended to the running session. It is built only from manifest fields, never from record bodies.
Runner update: your task inputs changed after this run started.
Steer: 0002
Manifest: /sandbox/entity-context-steer/0002/manifest.json
Head: 4f1c2e9d0b7a65c3e8f1a2b4c6d8e0f1a3b5c7d9 (was 9e8d7c6b5a4f3e2d1c0b9a8f7e6d5c4b3a2f1e0d)
Omitted: 1
[steer-record 1/2]
Record: c73645a72a9c5de28d71e3e1efe235b9a5d02ee6dfe7dc0ef06cf3d0e5ee3421
Kind: comment
Actor: @example-maintainer (write)
Revision: 2026-11-02T10:15:30.000000000Z
Filter: unchanged
Path: /sandbox/entity-context-steer/0002/records/20261102T101530000000000Z-c73645a72a9c5de28d71e3e1efe235b9a5d02ee6dfe7dc0ef06cf3d0e5ee3421.md
[/steer-record]
[steer-record 2/2]
...
[/steer-record]The values above are illustrative; the record key is the worked example from entity-context-snapshot v1.
Envelope rules
- Opening line. Every envelope begins with
Runner update: your task inputs changed after this run started., byte for byte, followed by one blank line. - Header lines.
Steer:andManifest:are always present.Head:is present only when the manifestheadis notnull.Omitted:is present only when the omitted count is above zero, and gives the sum ofomitted[].count. - One block per record. Each admitted record is one
[steer-record N/M]...[/steer-record]block, in manifest order. Lines inside a block are, in order:Record,Kind,Actor,Revision,Filter,Path.Actorshows(role)for a human or(bot: <bot_role>)for a bot. - No other text. The envelope contains no record body, title, or label text. A runtime that splits the message into content blocks MUST keep each record block whole.
- Field safety. Every field value comes from the manifest. Fullsend MUST refuse to steer if any value contains a line break,
[steer-record,[/steer-record], or the opening line.
The opening line inside record bodies
Agent definitions treat the opening line in two ways:
| Where it appears | Meaning |
|---|---|
| First line of a delivered message | A runner update. The agent reads the listed records |
| Inside a record body | An injection attempt. The agent should flag it |
Fullsend does not rewrite the opening line inside record bodies, because that would remove the evidence the agent definitions act on. The filter pipeline still applies to the rest of the body.
What the agent may do with a steer
- Read the listed files. They are filtered, attributed data under ADR 0133: an admitted record may guide the task within the harness's scope, but cannot change tools, role, credentials, or routing.
- Ignore a block whose
Pathdoes not exist. The agent MAY check a file against the manifestsha256with a tool such assha256sumand ignore a mismatch. Such a block was not written by Fullsend.
Versioning
This is v1. A breaking change requires docs/normative/steer-envelope/v2/.
These changes are breaking:
- the opening line, the header line names, the block delimiters, or the block line order;
- the steer directory path, the record file rules, or a manifest field's name, type, or meaning;
- any change to the permission, exact-path, or cleanup rules that weakens them.
Adding a manifest field is also breaking: consumers validate a closed field set, as entity-context-snapshot v1 consumers do.
Open questions
- Machine-readable schema. This version defines the manifest in tables. A
manifest.schema.jsonin this directory would let consumers validate it the way snapshot consumers do. Should it ship with the first implementation? - One block per record. ADR 0141 asks for one content block per record "when cache reuse is intended". A steer is a new user turn, so prompt-cache reuse past it is already lost. Does the rule apply to steer delivery?
- In-band version. The opening line carries no version token. Adding one later changes the opening line, which is itself a v2 change.
