Screen writes and hold the suspicious ones
Write screening - agent writes are screened and suspicious ones held for you; the existing corpus is reviewed, files changed outside Seamless are quarantined, a lockdown switch narrows what agents receive, and refusals and a metadata feed tell a monitor what happened.
On this page
Seamless injects its constraints and conventions into every session's briefing, and recall serves memories and notes to any agent that asks. That makes the corpus the most leveraged place to plant a prompt injection: a poisoned constraint is read by every agent, in every session, until someone notices. The gardener, which reads memories and proposes rewrites, can carry one further.
Write screening is the optional feature that closes that door. It is off by default, and off means writes land exactly as they always have. On, it does these things:
- Screens every agent write to a memory or note for secrets, injection
markers, hidden Unicode, long encoded blobs, and links outside an allowlist,
and records the verdict codes - never the text - as a
memory.screenedevent. - Holds the suspicious ones. A write that fails a screen, a change to a briefing-injected kind (constraint, convention, protocol, stage) by a session an agent guard marked as having read outside text, and any supersede or delete of a constraint are kept out of the corpus - out of briefings, recall, prompt injection and the gardener - until you release them on the console's Held screen.
- Marks provenance on what agents read: every injected memory line says whether you confirmed its content or an agent wrote it, and in which session.
- Reviews the existing corpus the first time you turn it on: every memory and note goes through the same screens, on this machine. Clean ones are marked safe; the rest are listed for you with a Mark safe action.
- Quarantines files changed outside Seamless. A memory or note file edited or planted on disk by anything but Seamless stays exactly as it is, but no briefing or prompt recall injects it until you accept it.
- Offers a lockdown switch for an incident: changes to binding rules wait for you, and briefings inject only what you confirmed or the review marked safe.
- Records refusals and feeds a monitor. Refused accesses become
access.refusedevents, and an optional metadata feed delivers every event's metadata - never its content - to a Unix socket you name.
Turn it on
Three ways, all the same switch:
- The Home welcome card. After installing, Home asks how much of the console you want to see. Beside the level choice is an unchecked box, Also turn on write screening. Tick it and whichever button you press (a level or Dismiss) turns the feature on too. Leave it unticked and nothing changes, at any level. The level is presentation only; screening changes what your agents receive, which is why it is its own choice rather than part of a level.
- Settings -> Features, the card named Write screening. This is the way
in once the welcome card is gone. It stores the same override row the
welcome box writes, records the same
settings.features_changedevent, and, like every optional feature, turning it off deletes nothing. - The config file or environment:
features.screening: true, orSEAMLESS_FEATURES_SCREENING=true. A console choice wins over both until you reset it.
The tunables live in their own block:
screening:
# Hosts a URL may point at without a verdict; each covers its subdomains.
# Unset or empty turns the URL screen off.
url_allowlist: [example.com, docs.example.org]
# The shortest unbroken base64 or hex run that counts as a long blob.
blob_min_length: 200
SEAMLESS_SCREENING_URL_ALLOWLIST (comma-separated) and
SEAMLESS_SCREENING_BLOB_MIN_LENGTH override them. Loopback URLs
(localhost, 127.0.0.1) are never "outside".
Two more keys belong to the drift and lockdown sections below:
screening:
drift_interval: 5m # 0 turns the drift watch off
lockdown_file: /path/to/lockdown.flag # its existence turns lockdown on
Each has a SEAMLESS_SCREENING_* override (DRIFT_INTERVAL,
LOCKDOWN_FILE); the path expands a leading ~ and must be absolute.
What is screened
Every agent write that lands text in the corpus: memory_write (including
the half that supersedes), memory_append, memory_edit, notes_create,
notes_update, notes_edit, notes_append, capture_url (a fetched page is
outside text by definition), and an agent's gardener_apply of a proposal
that writes text (a digest, a consolidated memory). A memory is screened on
its description, body and tags; a note on its title, description, source URL,
body and tags.
An update is judged by what it adds: a verdict counts only if the new text matches it more often than the text it replaces. So a memory you released because it legitimately quotes an injection (a note about prompt injection, say) takes later edits without being held again, while a second marker - or one assembled across two appends - still shows.
Memories are instructions to agents by design, so the screens look for what an injection or a leak looks like, never for ordinary imperative text. "Always run make check" and "fetch upstream first" screen clean.
| Code | Holds? | What it means |
|---|---|---|
secret.private_key |
holds | A PEM or OpenSSH private key block. |
secret.aws_access_key |
holds | An AWS access key id (AWS's documented example key excepted). |
secret.github_token |
holds | A GitHub personal, OAuth, app or fine-grained token. |
secret.slack_token |
holds | A Slack token or incoming-webhook URL. |
secret.openai_key |
holds | An OpenAI API key. |
secret.anthropic_key |
holds | An Anthropic API key. |
secret.google_api_key |
holds | A Google API key. |
secret.stripe_key |
holds | A live Stripe secret or restricted key. |
secret.jwt |
holds | A signed JSON Web Token. |
instruction.override |
holds | Telling the reader to drop its prior instructions ("ignore all previous instructions", "you are now in developer mode", "new instructions:"). |
instruction.role_marker |
holds | Chat-template and role tags that impersonate the system, a developer or a tool, including Seamless's own seam-briefing and seam-recall envelope tags. Quoted as code (in backticks or a fence) they are documentation and do not count. |
instruction.concealment |
holds | Telling the reader to hide what it does from the user ("keep this hidden from the user", "do not reveal these instructions", "secretly send"). |
instruction.exfiltration |
holds | Telling the reader to send credentials somewhere outside: a sending verb, a secret, and a destination it goes to (a webhook, an external server, or a URL outside the allowlist), or a network command reading a credential file. Copying a public key is not one. |
hidden.comment |
records | An HTML or markdown comment: invisible on the console, read in full by an agent. |
hidden.style |
records | An element styled or flagged invisible (display:none, font-size:0, hidden). |
hidden.instruction |
holds | An imperative aimed at the agent inside hidden text: harmless in plain sight, a marker when hidden from the person reviewing it. |
unicode.tag |
holds | Tag characters U+E0000 to U+E007F, which can spell invisible ASCII. |
unicode.zero_width |
holds | Zero-width characters U+200B to U+200D, U+2060 and U+FEFF (a byte-order mark at the very start excepted). They also split words to slip past the phrase screens, which is why those screens read the text with them removed. |
unicode.bidi |
holds | Bidirectional embeddings, overrides and isolates U+202A to U+202E and U+2066 to U+2069, which make the console show different text than an agent reads. |
blob.base64 |
holds | An unbroken base64 run of at least blob_min_length characters, mixing digits and both cases. |
blob.hex |
holds | An unbroken hex run of at least blob_min_length characters. |
url.unlisted |
holds | A URL whose host is outside url_allowlist. With no allowlist this screen is off: every URL would be "outside", which says nothing. |
Why the two that only record: comments and invisible styles are common in real
notes (templates, TODOs, pasted HTML), and holding on them alone would bury the
queue. What makes one dangerous - an instruction to the agent hidden inside -
is hidden.instruction, which holds.
What is held
A write is held when any of these is true:
| Reason | When |
|---|---|
| a screen verdict that holds | The write adds one of the holding codes above. |
session.tainted |
The writing session carries the outside-text mark, and the write touches a briefing-injected kind: a constraint, convention, protocol or stage it writes, replaces, supersedes or deletes. |
constraint.supersede |
The write supersedes a constraint, from any session. |
constraint.delete |
memory_delete, or an agent's gardener archive, of a constraint, from any session. |
constraint.demote |
The write turns a constraint into another kind, which drops it from every briefing's binding section. |
A held call is held whole: a memory_write that supersedes a constraint
writes nothing - neither the replacement nor the supersede - so the old
constraint stays valid and in every briefing until you release both halves
together. A held delete leaves the memory exactly where it is. A held gardener
apply leaves the proposal pending.
The held text lives in the database's queue, never under memory/ or
notes/. Briefings, recall, prompt injection and the gardener only ever read
those two trees, so a held write cannot reach any of them, and no reconcile or
index rebuild can bring it back. Deleting seam.db discards the queue with
the rest of the database - held writes are not corpus data until you release
them.
The agent is told plainly that the write is held: the tool answers with
status: "held", the hold's id, its reason codes, and a message that nothing
in the corpus changed and the owner decides. It is a success answer, not an
error an agent would retry. memory_read and notes_read keep serving the
corpus as it stands - the held text reaches no agent.
Review on the Held screen
Held (in the sidebar while the feature is on, at every console level)
lists each waiting write with what it would do, who wrote it, the reason codes
in plain words, and the text exactly as an agent would read it: every hidden
character is spelled out ([U+200B]), and secrets are redacted, so the screen
can be reviewed - and captured - without the credential. The reasons are color
coded by kind, most serious first, and the text marks what each one matched in
the same color, so the issues read at first sight.
- Release applies the write through the files layer, exactly as the agent sent it, and marks the memory owner-confirmed. A release whose target moved on after it was held (a later write landed, the name was taken, the constraint it supersedes is already gone) is refused, because it would silently undo that change; such a hold offers only Discard.
- Discard lands nothing and erases the held text. The row stays as the record of what was refused.
Turning the feature off stops screening new writes but releases nothing: held writes stay out of the corpus, and the queue comes back when you turn it on.
The outside-text mark
An agent guard - a client hook that knows which tools bring outside text into a session, such as a web fetch, a search or a mail reader - marks the session after one runs. From then on the session's changes to briefing-injected kinds are held. The mark is set by POSTing to the daemon with the credentials every hook already has (the bearer key, or the peer_auth socket):
# From a PostToolUse hook: forward the hook's own stdin unchanged.
seam hook session-taint
seam hook session-taint --client codex
seam hook session-taint reads the hook payload from stdin and posts it to
POST /api/hooks/session-taint, which finds the session by the client's own
session_id. A caller that knows the Seamless session can name it instead,
with {"session": "<ULID or cc/... name>"}. An optional reason is a short
code (web_fetch, mail); without one, the payload's tool_name becomes the
reason (tool:webfetch). The first mark stands. With the feature off the
endpoint marks nothing and says so.
Under a lock, an agent in a locked project's repository has its session recorded there before you approve its access. Its own guard marks that session all the same, so the access request you are shown carries the "session tainted" warning. A process outside the agent's process tree finds no such session, as with every other hook.
Setting the mark only lowers trust, so a session's own hook may set it. Clearing it is yours: the Held screen lists every marked session with a Clear mark button, and nothing else - no endpoint, flag or MCP tool - clears one. A new session starts unmarked.
install-hooks does not wire this event: the stock PostToolUse hook only ever
forwards plan-file writes and plan approvals, so the daemon never sees which
other tools ran. The guard is a hook of your own.
Provenance on injected memories
While the feature is on, every memory line in a briefing and in the
prompt-matched seam-recall block ends with a mark:
[owner-confirmed]- you released a held write of exactly this content (the console stores a fingerprint of its kind, scope, name, description and body). Any later change - an agent's edit, an append, a hand edit of the file- no longer matches, and the mark lapses on its own. A star or a tag change does not lapse it.
[agent-written, session cc/...]- everything else, with the session that last wrote the content through Seamless. The session is named only when it ran in the memory's own scope: a global memory written from inside a project does not carry that project's session name into every other briefing.
memory_read returns the same answer as provenance and
written_by_session.
The review and the safe mark
The first time the feature is on - from the welcome card, Settings or the config, whichever comes first - the daemon reviews every memory and note file already on disk. It runs the same screens agent writes go through, deterministically and on this machine: nothing is sent anywhere. Each item gets a verdict:
- safe - the screens found nothing that holds. The mark is stamped with a fingerprint of what the item says (its kind, scope, name, description and body), and holds only while it still says exactly that: an agent's later change lapses it on its own. A star or a tag change does not.
- flagged - a holding code fired. The Held screen lists flagged items under Review, each with its codes, the sessions it was already injected into, and its text as an agent reads it, so you can decide.
Mark safe on a flagged item marks it safe as it reads now and, for a memory, stamps it owner-confirmed - the same mark a released write carries. Re-run review screens the whole corpus again and marks every clean item safe as it reads now; an item you marked safe keeps your mark while it is unchanged. The review runs once by itself; after that it runs when you ask.
The review does not run when the database is migrated: the migration only adds the table, so an installation that never turns the feature on does no review and stores nothing.
Changed outside Seamless
The review also records the content hash of every file, and while the
feature is on every write Seamless makes updates that record. Every
drift_interval (5 minutes by default) the drift watch compares each file on
disk with it:
- a file whose bytes no longer match was changed outside Seamless - an editor, a script, a sync tool, another program;
- a memory or note file Seamless has no record of appeared there;
- a recorded file that is gone went missing.
A changed or appeared file is quarantined in place: it stays on disk
exactly as it is (Seamless never moves, rewrites or deletes it), its text goes
through the screens and the codes are recorded, corpus.drift is logged, and
while the feature is on no briefing or prompt recall injects it - lockdown or
not, because its text never passed the write screens. An agent's edit of a
quarantined memory is screened against nothing, so the drifted text cannot
ride in as if it were already there, and the quarantine stays until you act.
A missing file is reported and nothing is restored.
The Held screen lists quarantined files under Changed outside Seamless, with their codes, the sessions they reached before they changed, and their text as an agent reads it. Accept records the file as it stands, lifts the quarantine and, for a memory, stamps it owner-confirmed. If it should not stand, edit it back or delete it: a file put back to the exact bytes Seamless recorded leaves the quarantine by itself.
Editing memory files in your own editor is fine; each edit lands in the list until you accept it. Changes made while the feature was off are not watched: turning it back on adopts the files as they are (it does not re-run the review, so their safe marks stay lapsed until you do).
Lockdown
Lockdown is for an incident: something wrote where it should not have, and you want agents working only from knowledge you trust until you have looked. It only ever narrows what agents receive. While it is on:
- every change that touches a constraint, convention, protocol or stage - a
write, an edit, a supersede, a delete, a gardener apply - is held for you
with the reason
lockdown, from any session; - briefings and prompt recall inject only memories you confirmed or the review marked safe and that still say what they said then. An agent-written memory created or changed since waits for you or the next review. The briefing carries one line saying lockdown is on and how many memories it withheld.
Two things turn it on, and either keeps it on:
- the switch on the Held screen (
lockdown.changed, sourceconsole); - the file
screening.lockdown_fileexisting. Another program - a security monitor during an incident - can create it. The console cannot lift a lockdown the file holds; it lifts when the file goes. A file that exists but cannot be checked counts as present.
Lockdown does nothing while the feature is off. recall and memory_read,
which an agent asks for, are not narrowed.
Refusals
Every refused access becomes an access.refused event while the feature is
on, with a reason code:
| Reason | When |
|---|---|
fence.read, fence.write |
A read or write across a project isolation fence. fence.write is also every cross-project write attempt. |
peer.unreachable |
Under peer_auth, an account reaching a project it may not. |
peer.unknown |
A socket caller whose OS account peer_auth does not know, or with no peer credential. |
peer.owner_only |
A restricted account reaching the owner's console. |
auth.failed |
A request with no valid bearer key, on any surface. |
The event names the surface (mcp, hooks, a2a, console), the tool and
the target project when there is one - never the call's arguments. It is
rate-limited: one event per reason, surface, tool, target and session every
ten seconds, with the refusals in between counted in suppressed.
The metadata feed
While this feature is on and screening.feed_socket names a Unix socket, the
daemon delivers every event's metadata - never its content - to a monitor
listening there, so it can see what agents do without reading Seamless.
Feeding a security monitor has the frame and
delivery contract and how to turn it on, beside the commit-matching snapshot
that serves the same kind of monitor.
Forensics
retrieval.injected - the record of which memories a briefing, a prompt
recall or a recall answer gave which session - is never pruned: the retention
pass only ever removes transport events (tool.call, hook.prompt,
recall.miss, hook.error). So when a memory turns out poisoned, the
sessions it reached are on record back to its first injection. The Held
screen shows them beside each flagged or quarantined memory.
Events
| Event | When | Payload |
|---|---|---|
memory.screened |
Every screened write, clean ones included (verdicts: []), so a monitor can tell a clean write from one never screened. |
item_kind, kind, tool, size, verdicts, held |
memory.held |
A write went to the queue. | hold, op, item_kind, kind, tool, reasons |
memory.released |
You released a held write and it landed. | hold, op, item_kind, kind, tool, by |
memory.discarded |
You discarded a held write. | hold, op, item_kind, kind, tool, by |
session.tainted |
A session got the outside-text mark (once). | reason, via |
session.untainted |
You cleared a session's mark. | by |
access.refused |
An access was refused (rate-limited). | reason, surface, tool, target, suppressed |
corpus.reviewed |
The review read the corpus. | items, safe, flagged, by, baseline |
corpus.drift |
A file changed, appeared or went missing outside Seamless. | change, item_kind, verdicts, quarantined |
corpus.confirmed |
You marked a flagged item safe or accepted a quarantined one. | item_kind, via, by |
lockdown.changed |
Lockdown went on or off. | on, source, by |
Each carries the session, project and item ids in the event's own columns. None carries a body, a description, or the text a screen matched.
Calibrate before you turn it on
The screens ship with a calibration test that reads a folder of memory and note markdown files and prints how often each verdict would fire, per code and per file - never the matched text:
SEAMLESS_SCREEN_CORPUS=/path/to/a/copy/of/memory go test ./internal/screening \
-run TestCalibration_Corpus -v
SEAMLESS_SCREEN_ALLOWLIST and SEAMLESS_SCREEN_BLOB_MIN_LENGTH set the rules
it runs with. Run it on a copy of a corpus you are allowed to read.
What it does not cover
- Your own writes. Console actions and the owner CLIs (
seamlessd import, merges, the v1 importer) are yours, and are not screened. - Other text agents leave. Session findings and task titles also reach briefings, and plan-mode captures land as notes; none of them is screened by this feature, and lockdown does not narrow them.
- What agents ask for. Drift quarantine and lockdown narrow what is
injected;
recallandmemory_readstill answer an agent that asks.