agentdetox 0.2.0__tar.gz

agentdetox-0.2.0/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+__pycache__/
+*.egg-info/
+.pytest_cache/
+dist/
+bench/data/

agentdetox-0.2.0/CHANGELOG.md

@@ -0,0 +1,64 @@
+# Changelog
+
+Notable changes to AgentDetox. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
+before 1.0, a minor version may change commands, settings or the snapshot store.
+
+## [0.2.0] - 2026-10-28
+
+The first release on PyPI. 0.1.0 was a knowledge-base scanner published on GitHub as `ragscan`;
+0.2.0 renames it AgentDetox and extends it to what agents trust and reload: memory, rules,
+instruction and skill files, and config.
+
+### Added
+
+- **Claude Code protection** (`agentdetox install claude-code`). Hooks check every write to
+  memory, CLAUDE.md, rules, skills and config, including shell redirects, `tee`, `sed -i`, `cp`,
+  `mv` and `rm`. Planted instructions are denied, unless you typed or pasted the text yourself,
+  in which case you are asked. Changes to hooks, MCP servers or permissions (the prompt says what
+  is added or removed), suspicious writes, and memory that points package installs at a
+  non-default registry need your approval. At session start, files changed outside
+  the agent since the last snapshot are reported with the command that restores each one.
+  `CLAUDE_CONFIG_DIR` is followed.
+- **Claude Code plugin** (`/plugin install agentdetox --marketplace chriswu727/agentdetox`), as an
+  alternative to `install claude-code`. It runs the installed `agentdetox`, or its own release
+  through `uvx`; `install` and `doctor` notice when both routes register the hooks.
+- **Ledger** (`agentdetox log`, `agentdetox blame <file>`). Every change to a watched file is
+  recorded with where it came from: your own words, the agent, a named web page or tool output it
+  copied, or a change made outside the agent's edit tools. The versions before and after are kept,
+  so `blame` can say where each line came from.
+- **Snapshots, tamper detection and restore** (`agentdetox agent snapshot|verify|restore|scan`).
+  The store in `~/.agentdetox` is private (0700/0600). A restore quarantines the current file
+  instead of deleting it.
+- **`agentdetox demo`**: an attack caught and undone in a throwaway folder, using the real hooks.
+  `install` ends by saying what is now watched.
+- **Contradiction detection** (experimental; optional `nli` extra, then `agentdetox fetch-models`). A
+  multilingual NLI model compares new memory with what the agent already knows. It records
+  conflicts by default and asks only if you set it to. One background model server per store
+  keeps the model loaded, so a write costs the hook about 0.1 s.
+- **Provenance check.** A memory write mostly copied from web pages, MCP data, command output or
+  files the agent just read asks for approval, unless you asked the agent to remember it.
+- **Day-to-day commands.** `agentdetox status`, `events` (each with the command or file it was
+  about), `doctor`, and `allow <id>` to
+  permanently allow a reviewed false positive. `config <check> ask|record|off` sets each check;
+  the settings live in `~/.agentdetox/config.toml`, and `AGENTDETOX_<CHECK>` overrides them.
+- **Guard on AgentDetox's own state.** An agent needs approval to change AgentDetox's settings,
+  allowlist or snapshots, or to run the commands that do.
+- **Experimental hooks for Codex and Cursor.** OpenClaw gets tamper detection only.
+- **Windows support**, tested in CI but not yet on a real machine. Windows has no model server yet.
+- **Benchmarks and an evaluation lab.** An agent memory poisoning benchmark (v0, built from public
+  data only) and a provenance benchmark, in `bench/`. The lab in `lab/` replays attacks and
+  everyday use against real Claude Code sessions, with and without AgentDetox.
+
+### Security
+
+- Background processes and the `python -m` hook fallback start Python with `-I`. Without it, a
+  repository could plant an `agentdetox` package that the hook would import.
+
+## [0.1.0] - 2026-10-27
+
+Released on GitHub as `ragscan`. It scans RAG knowledge bases for hidden prompt injections and
+PoisonedRAG-style poisoning (CleanBase clique detection), and traces wrong answers back to the
+passages responsible.
+
+[0.2.0]: https://github.com/chriswu727/agentdetox/compare/ba1cc83...main
+[0.1.0]: https://github.com/chriswu727/agentdetox/commit/ba1cc83

agentdetox-0.2.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

agentdetox-0.2.0/PKG-INFO

@@ -0,0 +1,298 @@
+Metadata-Version: 2.5
+Name: agentdetox
+Version: 0.2.0
+Summary: Protection for what AI coding agents remember and obey: checks what they write to memory, rules, skills and config, records where each change came from, and puts back what was tampered with.
+Project-URL: Homepage, https://github.com/chriswu727/agentdetox
+Project-URL: Issues, https://github.com/chriswu727/agentdetox/issues
+Project-URL: Changelog, https://github.com/chriswu727/agentdetox/blob/main/CHANGELOG.md
+Author: Yichen Wu
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: agent-memory,ai-agents,claude-code,data-poisoning,llm,mcp,prompt-injection,rag,security
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Security
+Requires-Python: >=3.11
+Requires-Dist: numpy>=1.24
+Provides-Extra: dev
+Requires-Dist: mypy>=1.18; extra == 'dev'
+Requires-Dist: pip-audit>=2.7; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff>=0.15; extra == 'dev'
+Provides-Extra: nli
+Requires-Dist: torch>=2.1; extra == 'nli'
+Requires-Dist: transformers>=4.40; extra == 'nli'
+Provides-Extra: st
+Requires-Dist: sentence-transformers>=2.2; extra == 'st'
+Description-Content-Type: text/markdown
+
+# AgentDetox
+
+Protection for what AI coding agents remember and obey. AgentDetox watches an agent's memory,
+instruction and rules files, skills and config: it checks what the agent writes there, notices what
+changes behind its back, and puts things back.
+
+> **Status: preview.** Claude Code is supported. Codex and Cursor hooks are experimental, and
+> OpenClaw gets tamper detection only. Developed on macOS; on Windows the tests run in CI, but it
+> has not yet been used on a real machine. Where it is going:
+> [ROADMAP.md](https://github.com/chriswu727/agentdetox/blob/main/ROADMAP.md).
+
+Agents learn from web pages, files, emails and tool output, and some of it is written into memory
+or rules that every later session trusts. One poisoned write can steer an agent for weeks, as
+[Cisco's persistent-memory compromise of Claude Code](https://blogs.cisco.com/ai/identifying-and-remediating-a-persistent-memory-compromise-in-claude-code)
+(April 2026) and MemGhost (arXiv 2607.05189, July 2026) showed. Today's models refuse much of the
+obvious injected text they read. What they cannot see is a file changed behind their back, by a
+dependency's install script or another program, which they then load as your instructions; and
+smaller models still save planted text when asked to remember "the setup steps".
+
+## See it
+
+```bash
+agentdetox demo
+```
+
+In a throwaway folder, with nothing else read or changed, the demo shows an agent trying to save a
+planted instruction to its memory (blocked), a dependency's install script slipping the same
+instruction into CLAUDE.md (reported to the agent at the next session, with the command that undoes
+it), and the file being restored. It runs the real hooks, so it doubles as a self-test.
+
+## Install
+
+```bash
+uv tool install agentdetox                # or: pipx install agentdetox
+```
+
+To run the latest code from `main` instead:
+`uv tool install git+https://github.com/chriswu727/agentdetox`.
+
+Then install the Claude Code plugin, from inside Claude Code:
+
+```text
+/plugin install agentdetox --marketplace chriswu727/agentdetox
+```
+
+or add the same hooks to your settings directly:
+
+```bash
+agentdetox install claude-code --apply    # adds three hooks to ~/.claude/settings.json, backed up first
+```
+
+Restart Claude Code to load the hooks. Use one route, not both: `install` declines when the plugin
+is enabled, and `agentdetox doctor` warns if the hooks are registered twice. The plugin runs the
+`agentdetox` you installed; without one it runs its own release through `uvx`, and with neither it
+says so at session start instead of failing on every tool call.
+
+A tool install keeps AgentDetox in an environment of its own; `pip install agentdetox` works too.
+If you move Claude Code's folder with `CLAUDE_CONFIG_DIR`, AgentDetox follows it. The first session
+scans what is already there before trusting it; `agentdetox agent scan` does the same at any time.
+
+## What it does in Claude Code
+
+- **Before a write** to memory, CLAUDE.md, rules, skills or config (through Write, Edit or a shell
+  command such as a redirect, `tee`, `sed -i`, `cp`, `mv` or `rm`), the new content is checked.
+  Planted instructions are denied, with the reason sent to the agent. If the flagged text is
+  something you typed or pasted yourself, you are asked instead (hidden text is still denied, since
+  you could not see what you pasted). An agent changing its own hooks,
+  MCP servers or permissions needs your approval, and the prompt says exactly what is added or
+  removed.
+- **After the write**, the file is trusted as it now is, and the change is recorded with where it
+  came from.
+- **At session start**, files changed outside the agent since the last session are compared with
+  the snapshot. Suspicious changes are reported to the agent, which is told not to follow them and
+  to tell you, with the command that restores each file. Edits you made yourself that look benign
+  are accepted silently, and recorded as made outside the agent.
+
+**Where memory came from.** A memory write that is mostly copied from web pages, MCP data, command
+output or files the agent just read asks for approval, unless you asked the agent to remember it.
+This is how text planted in an email or page usually reaches memory. Text the model rewrites in its
+own words is not caught this way.
+
+**What the rules look for** is what a benign memory almost never asks for: running code fetched
+from the network, reverse shells, loosening the agent's own approvals or sandbox, reading
+credentials, acting silently, standing orders to fetch a URL every session, hidden text, and
+injection phrasing. Memory that points package installs at a registry other than the default ones
+and the big public mirrors asks rather than blocks, since teams do run private registries. English
+and Chinese.
+
+**Cleaning up.** `agentdetox agent verify` shows what changed and why it is suspicious;
+`agentdetox agent restore <file>` puts back the last trusted version and moves the current one to
+`~/.agentdetox/quarantine`, never deleting it. Snapshot copies that no longer back any file are
+deleted once a day (`agentdetox agent gc` does it now); quarantined files are kept. If the snapshot
+list itself is damaged, or deleted while its copies remain, AgentDetox says so at every session
+instead of quietly trusting whatever is on disk, until you check and run
+`agentdetox agent snapshot --reset`.
+
+## Day to day
+
+```bash
+agentdetox status                         # health, what is watched, how checks are set, recent activity
+agentdetox events                         # everything blocked, asked, recorded or noticed
+agentdetox log                            # every change to memory, rules and config, and where it came from
+agentdetox blame ~/.claude/CLAUDE.md      # where each line of a file came from
+agentdetox allow 3f9c2a1b7e               # stop flagging something you reviewed
+agentdetox config copied record           # change a check
+agentdetox doctor                         # check the hooks are installed, current and runnable
+```
+
+Each change AgentDetox sees is recorded with its origin: your own words, the agent, a web page or
+tool output the agent copied (named), or a change made outside the agent's edit tools.
+`agentdetox blame <file>` shows that per line; lines from before AgentDetox was installed show as
+"earlier", and lines changed since the last recorded change as "unrecorded".
+
+Every message from AgentDetox carries an id. If what it flagged is fine, `agentdetox allow <id>`
+stops it being flagged again in write checks, session notices and scans alike. An id stands for the
+flagged line, the pair of contradicting entries, or the source text was copied from (that file, page
+or command), not for one occurrence; `agentdetox allow --list` and `--remove` review and undo.
+
+Settings live in `~/.agentdetox/config.toml` (`agentdetox config` shows them). Each check is `ask`,
+`record` (the write goes through and is logged) or `off`; agents without an ask prompt record
+instead of asking. An `AGENTDETOX_<KEY>` environment variable overrides the file.
+
+| Key | Default | Check |
+|---|---|---|
+| `suspicious` | ask | writes that look like planted instructions but are not clear-cut |
+| `copied` | ask | memory copied from untrusted input the agent just read |
+| `contradiction` | record | new memory that contradicts existing memory (experimental, below) |
+
+The settings, the allowlist and the snapshots are guarded like the agent's own config: an agent
+writing under `~/.agentdetox`, deleting it, or running `agentdetox allow`, `config <key> <value>`,
+`install`, `uninstall`, `agent snapshot` or `agent restore` needs your approval, or an injected
+instruction could switch a check off or allow itself.
+
+Hooks fail open: if AgentDetox itself errors, the agent's action proceeds. If an attacker deletes
+the hooks, the session-start check cannot run; `agentdetox agent verify` (by hand or in CI) still
+reports the removal.
+
+## What it does not catch
+
+- Detection is not a security boundary. An adaptive attacker who knows these rules can evade them,
+  and a plausible-looking false fact with nothing to contradict passes.
+- Planted text the model rewrites in its own words before saving it, unless a rule still matches.
+- A change made outside the agent is reported at the next session, not the moment it happens.
+- The ledger knows what the hooks saw. A change the agent makes with a shell command is recorded as
+  made outside the agent, and text it copied in its own words as the agent's.
+- The guard on AgentDetox's own settings recognises plain commands and file writes. An agent that
+  can run arbitrary code can still change them (a script that edits `~/.agentdetox` is not
+  inspected), and nothing stops a person or process outside the agent.
+- On Windows the shell checks understand Git Bash commands (`/c/...` paths, `agentdetox.exe`), not
+  PowerShell or cmd.exe syntax.
+
+## Other agents
+
+| Agent | Files watched | Write checks | Tamper detection |
+|---|---|---|---|
+| Claude Code | CLAUDE.md, CLAUDE.local.md, `.claude/rules`, AGENTS.md, auto memory, skills, subagents, commands, settings, `.mcp.json`, `~/.claude.json` | yes | yes |
+| Codex | AGENTS(.override).md, `~/.codex/memories`, `.agents/skills`, `config.toml`, `hooks.json`, `rules/*.rules` | experimental (`install codex` prints the hook) | yes |
+| Cursor | `.cursor/rules`, `.cursorrules`, AGENTS.md, `.cursor/skills`, `mcp.json`, `hooks.json` | experimental; Tab edits cannot be checked | yes |
+| OpenClaw | AGENTS, SOUL, USER, IDENTITY, BOOT, MEMORY, daily memory, skills, `openclaw.json`, extensions | not yet (needs a plugin) | yes |
+
+Codex and Cursor cannot ask mid-task: checks set to `ask` record instead, and changes to the
+agent's own hooks, MCP servers or permissions are blocked. The provenance check needs Claude Code's
+session transcript.
+
+## Contradiction detection (experimental)
+
+Optional: `uv tool install 'agentdetox[nli]'`, then `agentdetox fetch-models`. A memory write that
+contradicts what the agent already knows is a common sign of a fabricated fact. This uses a
+multilingual NLI model (mDeBERTa-v3, about 560 MB) and **records instead of asking**: after a
+write, the hook hands the check to a background model server and returns (about 0.1 s), and
+conflicts are logged (`agentdetox events`). The server loads the model on first use (about 1 GB of
+memory) and exits after 30 minutes without work; `agentdetox daemon status` shows it. On real memory
+the model still misreads fragments of notes as contradicting each other, which is why it does not
+ask; `agentdetox config contradiction ask` makes it ask. Windows has no model server yet: each
+related write starts a background worker that loads the model (about 6 s). The
+[roadmap](https://github.com/chriswu727/agentdetox/blob/main/ROADMAP.md) replaces this model with
+an LLM judge. Measurements:
+[bench/MEMORY_BENCHMARK.md](https://github.com/chriswu727/agentdetox/blob/main/bench/MEMORY_BENCHMARK.md).
+
+## Also: scanning a RAG knowledge base
+
+```bash
+pip install 'agentdetox[st]'                # drop [st] for a numpy-only install
+agentdetox scan ./knowledge_base            # directory of .txt/.md/.html, or a .jsonl export
+agentdetox trace kb.jsonl -q "Who founded Acme?" -a "Bob Smith"
+```
+
+Try it on the bundled example: `agentdetox scan examples/kb`.
+
+| Detector | What it catches | How |
+|---|---|---|
+| `hidden-unicode` | ASCII smuggled in invisible Unicode tag characters (decoded and shown), zero-width characters splitting words, bidi controls | deterministic |
+| `hidden-html` | Text hidden with `display:none`, `font-size:0`, white text or `hidden`, and HTML comments that carry instructions | deterministic |
+| `injection-phrase` | Instruction overrides, "don't tell the user", chat-template tokens, exfiltration instructions with a destination, text addressed to the AI. English and Chinese | deterministic |
+| `exfil-link` | Markdown images whose URL has a templated query, the zero-click exfiltration channel behind EchoLeak-style attacks | deterministic |
+| `question-template` | Three or more different passages that open with the same question, which is how PoisonedRAG's black-box attack builds its passages | deterministic |
+| `poison-cluster` | Groups of mutually similar passages written to push one false answer, even without the question prefix | CleanBase clique detection |
+| `duplicate-text` | The exact same text repeated many times | deterministic |
+
+`scan` exits with status 1 when any finding is at least `--fail-on` severity (default `high`),
+so it can gate ingestion in CI. A similarity clique on its own is reported as `medium`, because
+legitimately repetitive content (versioned docs, templated pages) also forms cliques; it becomes
+`high` only for members that also open with a question or carry injection markers. Use
+`--fail-on medium` if you want paraphrase-only poisoning to block ingestion too.
+
+`poison-cluster` implements CleanBase (Jin et al., arXiv 2605.00460): a k-nearest-neighbour
+cosine-similarity graph (k=10), edges kept above mu + 2.5 sigma of a 50% edge sample, and every
+passage in a clique of 3 or more flagged; exact duplicates are collapsed first. `trace` takes a
+question and the wrong answer your system gave, ranks the top `4 x top-k` passages by the mean
+z-score of similarity to the question, similarity to the wrong answer and whether the passage
+contains the answer, and splits them with 1-D 2-means. It is a cheap approximation of RAGOrigin
+(Zhang et al., IEEE S&P 2026); treat its output as a ranked lead list.
+
+Limits: `poison-cluster` cannot see an attacker who plants only one or two passages per target
+question or makes them deliberately dissimilar, and needs a few hundred passages to estimate its
+threshold; `injection-phrase` will flag security documentation that quotes attacks; brute-force kNN
+is fine for tens of thousands of passages, not millions. Measurements against PoisonedRAG and
+other scanners:
+[bench/KB_BENCHMARK.md](https://github.com/chriswu727/agentdetox/blob/main/bench/KB_BENCHMARK.md).
+
+## Development
+
+```bash
+./scripts/check.sh       # lint, type checks and tests: what every change must pass
+./scripts/update.sh      # the checks, then update the installed agentdetox, then `agentdetox doctor`
+```
+
+[CONTRIBUTING.md](https://github.com/chriswu727/agentdetox/blob/main/CONTRIBUTING.md) says where
+each kind of change belongs, [docs/architecture.md](https://github.com/chriswu727/agentdetox/blob/main/docs/architecture.md)
+how the pieces fit, and [docs/decisions.md](https://github.com/chriswu727/agentdetox/blob/main/docs/decisions.md)
+why. [SECURITY.md](https://github.com/chriswu727/agentdetox/blob/main/SECURITY.md) covers reporting
+and the threat model, [PRIVACY.md](https://github.com/chriswu727/agentdetox/blob/main/PRIVACY.md)
+what is stored and read.
+
+`lab/` replays attacks and everyday use against real Claude Code sessions, with and without
+AgentDetox ([lab/README.md](https://github.com/chriswu727/agentdetox/blob/main/lab/README.md));
+its latest results are in `lab/results/latest.md`.
+
+How a hook call flows: `adapters.py` turns an agent's event into a planned write or a shell
+command, `engine.py` runs the checks and reports signals, `policy.py` decides from your settings
+and the agent's abilities whether to block, ask or record, and the adapter formats the reply.
+`hooks.py` wires these together, and `session.py` runs the session-start check. The engine knows
+nothing about agents, so a new integration needs only an adapter. The detectors are in
+`hidden.py` and `persistence.py` (rules), `provenance.py` (copied text) and `consistency.py`
+(contradictions). The snapshot store is in `integrity.py`, the ledger in `ledger.py`, and the model
+server in `daemon.py`.
+
+Installed hooks call a fixed executable, so updating it takes effect on the next hook call with
+no reinstall; a model server still running the old build is stopped by `update.sh`, and otherwise
+replaces itself on its next job. Re-run `agentdetox install claude-code --apply` only when
+`agentdetox doctor` says the registered hooks are from an older version. To remove everything:
+`/plugin uninstall agentdetox` or `agentdetox uninstall claude-code`, `agentdetox daemon stop`,
+then `uv tool uninstall agentdetox`, then delete `~/.agentdetox` (this also deletes quarantined
+files).
+
+The Claude Code plugin lives in `plugins/agentdetox` and the marketplace entry in
+`.claude-plugin/marketplace.json`; `claude plugin validate .` checks both. Its version, the version
+its hook script pins, and the package version must match (`tests/test_plugin.py`).
+
+## License
+
+Apache-2.0