skills/docs/specs/2026-08-26-ctxguard-design.md

ctxguard — санитизация контекста AI-агента

Исторический документ. Это проектный замысел на 2026-08-26, сохранённый как есть: он объясняет, почему система устроена так, а не описывает текущее состояние. Часть запланированного здесь не была реализована в том виде (references/workflows.md, цель make install, tests/corpus/, плагин-«ведро» для простых скиллов). Актуальное состояние — в README.md.

Context

Работая через Claude Code, в контекст модели утекает всё, что агент прочитал: содержимое файлов, вывод команд, вставленные тикеты и письма. Это значит, что провайдеру уходят креды, названия компаний-клиентов, ФИО, внутренние хостнеймы и данные продакшена. Цель — сделать так, чтобы этого не происходило, и чтобы гарантия не зависела от того, помнит ли агент правила.

Главное архитектурное ограничение. Скилл сам по себе защитить не может: скилл — это инструкции для модели, а модель читает их уже внутри контекста, который уже отправлен. Перехват обязан быть вне модели. Единственная такая точка в Claude Code — хуки.

Проверенные возможности хуков (docs.claude.com/hooks, проверено 2026-08-26):

Хук	Может	Не может
PreToolUse	permissionDecision: allow/deny/ask, updatedInput (shallow merge, при нескольких хуках выигрывает последний)	—
PostToolUse	additionalContext, exit 2 = фидбек	переписать/вырезать вывод — поля updatedOutput нет
UserPromptSubmit	additionalContext, exit 2 = блок	переписать текст промпта
SessionStart	additionalContext, матчеры startup/resume/clear/compact/fork	блокировать
PreCompact	запретить компактинг	повлиять на то, что сохранится
egress / транскрипт	—	перехвата на пути к API нет

Следствие: вся санитизация делается на PreToolUse через updatedInput — до запуска инструмента. Вывод чиним, переписывая вход, который его порождает.

Решения, зафиксированные с заказчиком:

• Защищаем все четыре класса: секреты, бизнес-идентификаторы, PII, данные клиентов.
• Обратимые псевдонимы для имён/компаний/PII; секреты гасим безвозвратно (метка <SECRET:type:hash>).
• Периметр: ввод/вывод инструментов и содержимое репозитория.
• Упаковка: плагин Claude Code (скилл + хуки + скрипты).
• Fail-closed везде: скрипт упал, таймаут, непонятный ввод → тул-колл блокируется.

---

Организация репозитория

Репозиторий /path/to/skills пуст. Делаем его marketplace, чтобы будущие скиллы ложились туда же по внятному правилу.

skills/
├── .claude-plugin/marketplace.json     # манифест маркетплейса, name: ctx-tools
├── README.md                           # что тут, как поставить, как добавить скилл
├── .gitignore                           # словари/кеш/аудит НИКОГДА не в git
├── Makefile                            # test | verify | install | lint
├── docs/specs/2026-08-26-ctxguard-design.md
└── plugins/
    ├── ctxguard/                        # нужны хуки → свой плагин
    │   ├── .claude-plugin/plugin.json
    │   ├── hooks/hooks.json
    │   ├── skills/context-sanitization/
    │   │   ├── SKILL.md
    │   │   └── references/{policy.md,threat-model.md,workflows.md,troubleshooting.md}
    │   ├── commands/{ctx-entity.md,ctx-sanitize.md,ctx-verify.md,ctx-audit.md}
    │   ├── scripts/ctxguard/            # Python 3 stdlib-only
    │   └── tests/{unit/,corpus/,run.sh}
    └── <bucket>-skills/                 # «ведро» для простых скиллов без хуков
        ├── .claude-plugin/plugin.json
        └── skills/<name>/SKILL.md

Правило размещения: скиллу нужны хуки, команды или MCP → отдельный плагин в plugins/. Скилл — это чистые инструкции → каталог внутри plugins/<bucket>/skills/. Одна установка покрывает все простые скиллы, хук-плагины ставятся осознанно и по одному.

Установка: /plugin marketplace add /path/to/skills, затем /plugin install ctxguard@ctx-tools.

Конвенции берём из установленных плагинов (это де-факто стандарт здесь):

• Фронтматтер SKILL.md: только name + description в третьем лице со «Use when…» (образец: ~/.claude/plugins/cache/claude-plugins-official/superpowers/6.3.0/skills/writing-skills/SKILL.md).
• Progressive disclosure: детали в references/*.md, не в SKILL.md.
• Скрипты — Python 3 только stdlib, вызов python3 "${CLAUDE_PLUGIN_ROOT}/..." (образцы: ~/.claude/skills/jira/scripts/jira.py, плагин hookify).
• Шаблон hooks.json — ~/.claude/plugins/marketplaces/claude-plugins-official/plugins/hookify/hooks/hooks.json.
• Принцип «нашёл, но не цитирую» уже реализован в ~/.claude/plugins/marketplaces/claude-plugins-official/plugins/claude-security/scripts/lib/secret.py (функция withheld()) — переиспользуем идею как инвариант CLI.

---

Хранилище

Всё вне репозитория, чтобы не попало в git и не попалось агенту под руку. JSON, а не YAML — в stdlib нет парсера YAML, а tomllib умеет только читать.

~/.claude/ctx-guard/
├── policy.json                          # режим, префикс алиасов, правила, deny-списки
├── projects/<slug>/entities.json        # словарь real↔alias, 0600
├── projects/<slug>/index.json           # кеш «в каком файле есть сущности» (по mtime+size)
├── cache/<slug>/…                       # санитизированные двойники файлов, 0700
└── audit.jsonl                          # 0600, только alias/rule_id, без plaintext

Два жёстких инварианта:

1. Весь ~/.claude/ctx-guard/ в deny-read для агента, и Bash с упоминанием этого пути тоже. Иначе агент прочитает словарь и одним чтением сольёт всё сразу.
2. В CLI нет ни одной ветки кода, печатающей реальное значение сущности. Только алиасы, типы и хеши. Это делает утечку через сам инструмент невозможной, а не маловероятной.

---

Матрица перехвата

Всё через PreToolUse, один хук-владелец на инструмент (иначе гонка updatedInput).

Поверхность	Механизм	Enforced
Промпт пользователя	UserPromptSubmit: детект → exit 2 + причина с подсказкой /ctx-sanitize	да, блоком
Строка команды Bash	updatedInput.command — обратная подстановка alias→real	да
Вывод Bash	updatedInput.command → python3 ctxguard run -- <cmd>: обёртка сама запускает команду и стримит отфильтрованный вывод	да
Содержимое Read	updatedInput.file_path → путь санитизированного двойника в кеше	да
Grep/Glob	path → каталог двойников; pattern, совпавший с сущностью, — deny	да
Write/Edit	content / old_string / new_string — обратная подстановка alias→real и twin-path→real-path	да
WebFetch/WebSearch	deny при сущности или секрете в url/query	да
MCP (mcp__.*)	скан всех строковых аргументов, семантика неизвестна → deny при попадании	да
Task (сабагенты)	скан аргумента prompt	да
Скриншоты, изображения	не покрыто	нет
Текст, сгенерированный самой моделью	не покрыто	нет

Ключевой приём — обёртка Bash. Она же бесплатно закрывает git log, git blame, git remote -v и почтовые адреса коммитов, которые иначе текут мимо любой фильтрации файлов.

Симметрия путей обязательна. Read отдаёт двойник → агент дальше правит двойник. Поэтому Write/Edit обязаны отображать twin-path обратно в реальный путь и делать обратную подстановку содержимого. Модуль pathmap двунаправленный; без него правки уходят в кеш и теряются.

Префикс алиасов — CTXG_ (CTXG_COMPANY_A, CTXG_PERSON_3): валидный идентификатор, не ломает код, коллизии с реальным текстом крайне маловероятны.

---

Движок детекции

Три семейства, detect.py:

1. Словарные (детерминированные, из entities.json). Одна скомпилированная альтернация, отсортированная от длинных к коротким. Устойчивость строится прямо в regex, без карт офсетов: классы гомоглифов ([аa], [еe], [оo], [рp], [сc]) против обхода смешанными алфавитами, гибкость по пробелам и дефисам, регистронезависимость. Русская морфология — per-entity режим exact | stem | regex; stem даёт Петров(?:[а-яё]{0,4})?\b, покрывая падежи.
2. Паттерные (секреты). Курируемый набор: AWS AKIA/ASIA, GitHub ghp_/gho_/ghs_/github_pat_, Slack xox[baprs]-, Stripe sk_live/rk_live, Google AIza, OpenAI sk-proj-, Anthropic sk-ant-, JWT eyJ, PEM-блоки, SSH-ключи, postgres://user:pass@, generic (api[_-]?key|secret|token|password)\s*[:=]\s*…{16,}. Плюс Луна для карт и РФ-специфика: ИНН, ОГРН, СНИЛС, паспорт, +7-телефоны, email. FP-фильтры: энтропийный порог (Шеннон > 3.5) для generic-правил и allow-list заведомо фейковых значений (AKIAIOSFODNN7EXAMPLE, example.com, sk-test-*), иначе хук будет блокировать документацию.
3. Структурные. По пути: .env*, *.pem, id_rsa*, credentials, ~/.aws, ~/.ssh, .git-credentials. По команде: env, printenv, aws configure get, gh auth token, kubectl get secret -o yaml, docker inspect, op read, pass show.

Самозащита — отдельная группа deny, без неё всё остальное декоративно: агент не может писать в settings.json, settings.local.json, hooks/hooks.json, scripts/ctxguard/** и ~/.claude/ctx-guard/**. Иначе он выключит собственный контроль.

---

Чтобы агент не забывал

Четыре слоя, по убыванию силы. Порядок принципиален: первый слой делает забывание безвредным, остальные лишь сохраняют агента полезным.

1. Механическое принуждение. Хук блокирует независимо от того, что агент помнит. Память — оптимизация UX, граница безопасности — хук.
2. Переинъекция на SessionStart с матчерами startup|resume|clear|compact|fork: компактный блок правил (цель — ≤400 токенов) плюс глоссарий алиасов. В глоссарий уходит только сторона алиасов и безопасное поле hint («CTXG_COMPANY_A — ритейл-заказчик», «CTXG_PERSON_3 — бэкендер»). Агент получает смысл без значения. Переживает компактинг.
3. Коррекция в момент ошибки. Каждый deny несёт permissionDecisionReason, который повторяет правило и даёт готовое действие: «используй CTXG_COMPANY_A; если это новая сущность — /ctx-entity add». Обучение в точке ошибки работает лучше любого баннера. При подстановке — additionalContext, объясняющий, почему путь изменился.
4. CLAUDE.md — две строки-указатель, чтобы правило выживало, если плагин отключили, плюс триггероёмкий description у скилла.

Напоминания на UserPromptSubmit дозируем: одна строка, только если недавно было нарушение. Баннер в каждом промпте выжигает внимание и токены.

---

Проверяемость (без неё «эффективно» — это вера)

• ctxguard verify — канареечный корпус: подаём на реальные точки входа хуков настоящий hook-JSON на stdin и проверяем решение. Кейсы: фейковый AWS-ключ; компания; русское ФИО в шести падежах; обход гомоглифами; секрет внутри base64; секрет в JSON в выводе Bash; попытка записи в settings.json. Это одновременно регрессионный тест и метрика.
• ctxguard scan-transcript — измерение по факту, а не по замыслу. Транскрипт ~/.claude/projects/<slug>/*.jsonl — это буквально то, что было отправлено. Грепаем его по словарю и паттернам, считаем реальные утечки за сессию. Вешаем на SessionEnd.
• ctxguard audit — jsonl 0600: ts, session, tool, rule_id, alias, action. Без plaintext.
• ctxguard verify --adversarial — сабагент пытается вынести канарейку (приём из superpowers/skills/writing-skills/testing-skills-with-subagents.md).

---

План работ

Фаза 0 — каркас репозитория. marketplace.json, оба plugin.json, .gitignore, Makefile, README.md, скелет плагина-«ведра». Коммит. Риска нет.

Фаза 1 — движок и тесты, без хуков. policy.py, store.py (словарь, 0600), detect.py, morph.py, substitute.py, юнит-тесты, канареечный корпус, verify, scan-transcript. TDD (superpowers:test-driven-development). Хуки не подключены → нулевой риск, но уже появляется базовая метрика утечек на текущих транскриптах.

Фаза 2 — калибровка. Прогон движка в режиме наблюдения по истории транскриптов и репозиторию, чистка false positives, наполнение allow-list. Это шаг разработки, а не режим поставки: в проде — fail-closed, как решено.

Фаза 3 — слой запрета. hooks.json + pretooluse.py: структурные deny (пути, команды), секреты, самозащита, MCP/Task fail-closed. Уже здесь система реально защищает.

Фаза 4 — слой подстановки. ctxguard run (обёртка Bash), двойники для Read/Grep, pathmap, обратная гидратация Write/Edit. Перед реализацией — короткий спайк: обёртка Bash не должна сломать персистентный шелл Claude Code. Проверить проброс кода возврата, cd/export/source (их не оборачиваем — вывода у них нет, но строку команды всё равно сканируем), построчную буферизацию и run_in_background. Это единственное место с неизвестным поведением рантайма.

Фаза 5 — слой памяти. sessionstart.py (инъекция правил + глоссарий алиасов), userpromptsubmit.py (детект + exit 2 + подсказка), тексты permissionDecisionReason, строки для CLAUDE.md.

Фаза 6 — оформление. SKILL.md, четыре references/*.md, слэш-команды (/ctx-entity, /ctx-sanitize, /ctx-verify, /ctx-audit), --adversarial, README.

---

Что эта система честно не закрывает

Пишем это в references/threat-model.md первым разделом, а не мелким шрифтом.

• Псевдонимизация ≠ анонимизация. По структуре проекта, доменам в конфигах и именам пакетов заказчик часто восстанавливается. Если требование юридическое или контрактное, правильный контроль — zero-retention договор или self-hosted развёртывание, а обфускация лишь снижает объём утечки.
• Скриншоты и изображения не фильтруются. Текст на картинке уходит как есть.
• История git не переписывается. Реальные имена остаются в объектах; их ловит фильтр вывода при чтении, но сам репозиторий остаётся «грязным».
• Собственный вывод модели не контролируется: агент может воспроизвести реальное имя, если вывел его из контекста.
• ~/.claude/settings.local.json уже содержит Bash(python3 *) в allow. Хуки это не обходит (они срабатывают всегда), но человек из цикла подтверждения выпадает. Стоит сузить.
• Первый прогон до наполнения словаря защищает слабо. Словарные детекторы знают только то, что в них внесли; секретные и структурные работают сразу.

---

Верификация

1. make test — юнит-тесты движка (детекция, морфология, гомоглифы, подстановка, pathmap).
2. make verify → ctxguard verify: таблица по канареечному корпусу, все кейсы PASS. Отдельно проверить, что запись в settings.json заблокирована.
3. Ручной e2e в отдельном каталоге-песочнице: положить файл с фейковым ключом и фейковой компанией, попросить агента прочитать файл и запустить env, cat .env, git log. Ожидаемо: чтение отдано двойником, секрет — <SECRET:…>, компания — CTXG_COMPANY_A, env и cat .env — deny с внятной причиной.
4. ctxguard scan-transcript по транскрипту этой e2e-сессии → ожидается ноль реальных значений. Это финальная приёмка: она измеряет то, что действительно ушло.
5. Проверка памяти: /compact, затем спросить агента правила — блок правил и глоссарий должны вернуться через SessionStart с матчером compact.
6. ctxguard verify --adversarial — сабагент не смог вынести канарейку.