How the poison0 agent protects
The poison0 agent runs on the same machine as your agent and acts on the change to a file, not the file at rest. Every change to a protected memory file is checked before it takes effect, and the result is one of three outcomes. This page is the behavior, not the model internals.
Where the protection sits
The unit of protection is the change, not the file:
- On the change: a file is only read, diffed and scored when it changes; nothing is judged at rest.
- Before it takes effect: the check runs at the moment of the write, not once at install.
- Local: the watcher and the evaluation run on the same machine as your agent.
Scope is an allowlist: only an agent's memory, instruction and configuration files are watched, and everything else on the machine is never opened. See what the poison0 agent watches. Tool calls are checked with exec0 before they run.
What triggers a check
The watcher listens for filesystem events on the protected paths and evaluates only content that is created or written:
| Event | What happens |
|---|---|
| File created | Evaluated as a new change |
| File written or modified | The added content is diffed against the last clean state and evaluated |
| File removed or renamed | Not evaluated: removing content is not a poisoning vector |
Directory events and the daemon's own runtime files are filtered out before evaluation; only in-scope memory files reach the model.
The three outcomes
Every evaluated change ends in exactly one of three outcomes:
| Outcome | When | What the poison0 agent does |
|---|---|---|
| Allow | The change is evaluated as harmless | The change is accepted and becomes the new clean state |
| Ask | The change is neither clearly safe nor a proven attack | The file is held in its last safe state and you are asked before it takes effect. For a file that is being created for the first time there is no earlier state, so declining moves the whole file into quarantine - reversibly |
| Roll back | The change is evaluated as a proven attack | The change is undone automatically and the file returns to its last clean state |
The exact scoring is not exposed here; the behavior is what matters: safe passes, uncertain asks, dangerous rolls back. The uncertain middle band is covered in user confirmation prompts.
Rolling back is reversible
A roll-back never destroys content. The dangerous change is undone by restoring the last known-clean version, and the displaced content is kept, not deleted:
- Restore, not delete: the file is rewritten to its last clean state; the change is quarantined, held aside rather than erased.
- Recoverable: the displaced content is preserved verbatim, so a decision can always be undone.
- Logged: every outcome is written to the local audit trail - what changed, when, and why.
Because a roll-back is a reversible quarantine, an entry the poison0 agent could not clear never quietly becomes one of your agent's beliefs, and a false alarm costs you nothing but a click to keep.
Fail-closed: if the evaluator is unavailable or returns nothing usable, the change is held in its safe state, never waved through. Safety is the default. See fail-closed by design.
Read next
The exact set of watched files: what the poison0 agent watches. The uncertain middle band: user confirmation prompts. The safe-by-default stance: fail-closed.
Notice when a threat is blocked: the window after a quarantine
Optionally, the poison0 agent shows a window on the device after an automatic rollback. Default: off.
| Item | Behavior |
|---|---|
| Turning it on | Console: profile, setting Notice when a threat is blocked. Private devices: sudo poisonzero notify on; the local setting takes precedence over the profile |
| Content | File, removed content and reason for each case |
| Frequency | Cases in quick succession share one window, at most one window every 10 minutes |
| Headless devices | No desktop session, no window; the cases are listed in sudo poisonzero status and in the audit log |
| OK | The case stays in quarantine. Closing the window or 5 minutes without an answer count as OK |
| False alarm, restore | Administrators only. The operating system asks for an administrator sign-in for each case; only after that sign-in does the service restore exactly the content shown |
| Report as false alarm | For users without administrator rights. The case is recorded as a false alarm and stays in quarantine; the window shows the command to restore it |
| Note in the console | Cloud devices with verdict sharing on only; the case then shows in the audit view that the device reported it as a false alarm. Private devices never report |
| Claude Code | A hook shows new cases as a note for the human, without the removed content. poisonzero setup-claude installs it |
Notice when a threat is blocked: commands
| Command | Effect |
|---|---|
poisonzero notify | Shows whether the window is on and where the setting comes from (local, profile, default) |
sudo poisonzero notify on / off | Local switch, takes precedence over the profile |
sudo poisonzero notify clear | Remove the local switch; the profile applies again |
sudo poisonzero quarantine false-alarm <id> | Record the case as a false alarm; it stays in quarantine |
sudo poisonzero quarantine restore <id> | Restore the case |
poisonzero setup-claude --notice-off | Remove the hook from ~/.claude/settings.json again; other entries stay |
Windows: run the commands marked
sudo in an administrator terminal, without sudo.