skills/README.md

# ctx-tools — как пользоваться

**Маркетплейс плагинов для Claude Code.** Сейчас в нём один плагин:

**`ctxguard`** — санитизация контекста: вырезает креденшлы, подменяет имена компаний,
людей и PII на стабильные обратимые алиасы до того, как они попадут в модель.
Принуждение живёт в хуках, поэтому агент не может это выключить.

Этот файл — про то, как этим пользоваться. Раздача плагина коллегам и процесс
релизов — в [README.en.md](README.en.md).

---

## Установка

### Вариант 1. Через маркетплейс (рекомендуется)

```
/plugin marketplace add /path/to/skills
/plugin install ctxguard@ctx-tools
```

Вместо локального пути можно указать `<owner>/<repo>` на GitHub, git-URL или любой
путь в файловой системе. Ничего не тянется из сети во время работы, зависимостей кроме
`python3` нет.

Для всей команды — объявить на уровне **проекта** и закоммитить результат, чтобы
клонирования репозитория было достаточно:

```
claude plugin marketplace add <owner>/<repo> --scope project
claude plugin install ctxguard@ctx-tools --scope project
```

### Вариант 2. Копированием папки

```
cp -r plugins/ctxguard ~/.claude/skills/ctxguard
```

Загрузится в следующей сессии как `ctxguard@skills-dir`, **вместе с хуками**. Два
нюанса:

- **Имя должно быть свободно.** Установленный плагин с тем же именем побеждает, и
  просто *отключить* его недостаточно — имя остаётся занятым до
  `claude plugin uninstall`.
- Копируйте каталог, а не симлинк на репозиторий, который потом переедет.

Этот способ — для одной машины или одного коллеги. Маркетплейс — когда одну и ту же
версию нужно раздать нескольким людям и обновление должно быть командой, а не
перекопированием.

---

## ctxguard: повседневное использование

Ниже `ctxguard` — сокращение для вызова скрипта. Сам путь зависит от того, как
инструмент установлен, и это первое, обо что спотыкаются:

| Откуда запускаете | Путь к скрипту |
|---|---|
| Клон этого репозитория | `python3 plugins/ctxguard/scripts/ctxguard.py` |
| Распакованный ZIP из реестра скиллов | `python3 plugin/scripts/ctxguard.py` |
| Внутри сессии Claude Code | `python3 "${CLAUDE_PLUGIN_ROOT}/scripts/ctxguard.py"` |

В ZIP-поставке каталог называется `plugin` в единственном числе и лежит в корне
архива — там нет промежуточного `plugins/ctxguard/`, потому что архив содержит ровно
один плагин.

Удобно завести алиас под свой случай, например для распакованного архива:

```
alias ctxguard='python3 ~/.local/share/ctxguard/plugin/scripts/ctxguard.py'
```

Все примеры ниже записаны через это сокращение, подставьте свой путь.

### Что он делает

- **Креденшлы удаляются безвозвратно** — на их месте остаётся маркер вида
  `SECRET:правило:хэш` в угловых скобках. Восстановить значение нельзя, и это
  осознанно: отредактированный приватный ключ бесполезен.
- **Имена и PII превращаются в стабильные алиасы** (`CTXG_COMPANY_A`,
  `CTXG_PERSON_B`, `CTXG_EMAIL_7F3A`) — и переводятся обратно в реальные значения по
  пути на диск и в шелл. Поэтому агент продолжает делать реальную работу: код и
  команды, ссылающиеся на алиасы, работают.
- **Принуждение живёт в хуках, а не в скилле.** Агент не может это выключить, а то,
  что он забыл правила, безвредно — решение принимает хук.

Хуки: `SessionStart`, `UserPromptSubmit`, `PreToolUse` (перехват до запуска
инструмента), `PostToolUse` (обратный перевод при записи), `SessionEnd`.

### Первый запуск в новом проекте

```
ctxguard init            # создать состояние, показать что активно
ctxguard scan .          # что реально лежит в этом репозитории (только счётчики)
ctxguard entity add "Acme Corp" --type company --hint "розничный клиент"
ctxguard verify          # 43 канареечных кейса через настоящие точки входа хуков
ctxguard scan-transcript # что реально дошло до модели
```

**Словарь стартует пустым.** Детект креденшлов и PII работает сразу; имена компаний,
людей и хостов защищены только после регистрации — поэтому `scan`, а затем
`entity add` — первая работа в новом репозитории.

Словарь привязан к **корню git-репозитория**, а не к текущему каталогу, так что
сессия, начатая в `src/`, использует тот же словарь.

### Как выбрать `--match` — от этого зависит, скрывает ли алиас хоть что-то

| Режим | Когда | Что ловит |
|---|---|---|
| `exact` (по умолчанию) | имя встречается только в прозе | целые слова, терпит гомоглифы (кириллическая `с` вместо латинской `c`) и разные разделители: `Acme Corp` / `acme-corp` / `AcmeCorp` |
| `stem` | всё, что склоняется — в первую очередь русские фамилии | плюс до четырёх символов окончания на слово: `Петров / Петрова / Петровым`. Перебирает по замыслу: `Петров` поймает и `Петровский` |
| `ident` | **любое имя, встречающееся в коде** | без границ слова, так что значение находится внутри идентификаторов: `ContosoClient`, `CONTOSO_API_KEY`, `contoso.rs`. С `exact` все три утекут в реальном написании, выглядя защищёнными. Нужно ≥4 символов |
| `regex` | точная настройка | используется как есть, без именованных групп |

Побеждает самый длинный шаблон, так что регистрировать и `Acme`, и
`Acme Corporation` безопасно.

Ещё два флага:

- `--hint` вставляется в контекст модели **буквально**, поэтому описывайте сущность,
  не называя её («розничный клиент», а не «Globex — наш клиент»). Хинт, содержащий
  само значение, отвергается.
- `--variant` (можно повторять) — дополнительные написания: транслитерации,
  аббревиатуры.

Если у значения несколько слов, а режим `ident`, — зарегистрируйте отдельно и
отличительное слово: код обычно пишет `GlobexClient` для `Globex Retail`.

### Слэш-команды в сессии

| Команда | Зачем |
|---|---|
| `/ctx-entity <значение> [тип]` | Защитить название компании, человека, хост или кодовое имя за стабильным алиасом |
| `/ctx-sanitize` | Превратить текст (тикет, лог, письмо) в версию с алиасами, которую можно куда-то вставить |
| `/ctx-audit` | Показать, что ctxguard блокировал и подменял |
| `/ctx-verify` | Доказать, что защита действительно блокирует заявленное, и измерить реальную утечку |

Промпт нельзя перезаписать хуком — только заблокировать. Поэтому если ваш промпт
отклонён, штатный путь — `/ctx-sanitize` на текст, ручная подстановка алиасов или
регистрация значения через `/ctx-entity`.

### CLI

| Команда | Что делает |
|---|---|
| `ctxguard init [--force]` | создать каталог состояния и политику по умолчанию |
| `ctxguard status` | режим, префикс алиасов, число сущностей, правил, записей аудита |
| `ctxguard mode enforce\|observe` | `observe` только логирует находки и ничего не блокирует — средство калибровки, не режим эксплуатации |
| `ctxguard entity add <значение> --type <тип> [--match …] [--hint …] [--variant …]` | защитить значение. Типы: `company`, `person`, `host`, `project`, `email`, `phone`, `custom` |
| `ctxguard entity list` | алиасы, типы, режимы совпадения, хинты — **значения не печатаются никогда** |
| `ctxguard entity remove <алиас>` | снять защиту |
| `ctxguard entity export --out <файл>` | выгрузить словарь для коллеги (откажется писать внутрь git-репозитория) |
| `ctxguard entity import <файл>` | влить словарь, выгруженный на другой машине |
| `ctxguard sanitize < <файл>` | stdin → текст с алиасами на stdout, сводка по правилам на stderr |
| `ctxguard scan [путь…]` | какие файлы содержат чувствительные значения (только счётчики и id правил) |
| `ctxguard scan-transcript [--limit N] [--verbose] [--all-projects]` | что реально дошло до модели |
| `ctxguard audit -n 40` | последние решения: id правил, имена инструментов, алиасы — без плейнтекста |
| `ctxguard verify [--adversarial]` | канареечный корпус через настоящие точки входа хуков |
| `ctxguard run -- <команда>` | выполнить команду с фильтрацией вывода |

Ни одна подкоманда не печатает реальное значение сущности или секрета — именно это
делает сам инструмент безопасным для запуска изнутри сессии агента.

### Через Makefile

```
make test        # юнит-тесты движка
make verify      # канареечный корпус через настоящие точки входа хуков
make leaks       # поиск в транскриптах значений, которые реально дошли до модели
make scan        # чувствительные значения в этом репозитории (только счётчики)
make status      # что у ctxguard активно
make lint        # байт-компиляция всех скриптов + валидация JSON
make all         # lint + test + verify
```

---

## Что видит агент — и что делать, когда вызов отклонён

Пять правил, которые агент получает в контекст:

1. `CTXG_*` — алиасы реальных значений, использовать **буквально**.
2. Никогда не восстанавливать реальное значение и не просить пользователя его
   вставить.
3. Маркер секрета необратим; записывать его в файл нельзя — это затрёт настоящий
   креденшл заглушкой, и хук такую запись отклонит. Нужно целиться в более узкий
   участок через Edit.
4. Некоторые пути ведут в санитизированный кэш («twin»). Читать и править как
   обычно — изменение прописывается в настоящий файл за вас. Незнакомый путь — это
   ожидаемо и само по себе сигнал, что в файле что-то было.
5. Отказ — это информация, а не препятствие. В причине названо правило и штатный
   путь; попытки обойти сами попадают в аудит.

| Отказ | Штатный путь |
|---|---|
| Чтение `.env`, `*.pem`, `~/.ssh/…` | Читать `.env.example` или задокументированную схему. Проверить, что переменная задана, не печатая её: `test -n "$VAR" && echo set` |
| Команды, чья задача — напечатать креденшл (дамп окружения, выдача токена, чтение секрета кластера) | Проверять наличие, не печатая значение |
| `Grep` с `output_mode: content` | `Bash` + `grep` (этот путь фильтруется), либо `Grep` с `files_with_matches`, а затем `Read` |
| Поиск реального защищённого значения | Искать по алиасу — в санитизированных копиях лежат алиасы, а не реальные значения |
| Креденшл в командной строке | Передать через переменную окружения или файл, который команда читает сама |
| `cd` / `export` / `source` с алиасом | Они выполняются в постоянном шелле и не могут быть обёрнуты фильтром; перестроить команду или выполнить шаг вручную |
| Аргумент MCP-инструмента с защищённым значением | Использовать алиас; если инструменту нужно реальное значение — этот шаг выполняет пользователь |

Отдельно про изменение файлов: если правка не появилась в настоящем файле —
write-through упал и сообщил об этом (`PostToolUse` выходит с кодом 2 и печатает
`write-through to <path> FAILED`). Проверьте права на целевой файл и
`ctxguard audit -n 20`. Подготовленное содержимое цело в twin-копии.

---

## Проверка, что защита работает

Два разных вопроса — две разные команды, и путать их нельзя:

```
ctxguard verify            # работает ли механика?      -> измеряет замысел
ctxguard scan-transcript   # утекло ли что-то реально?  -> измеряет результат
```

Доказательство — только второе: оно ищет реальные значения из словаря в
транскриптах, то есть буквально в том, что было отправлено модели. Ненулевой
результат означает, что данные дошли до модели несмотря на хуки — тогда сначала
смотрите файлы инструкций (`CLAUDE.md` / `AGENTS.md` грузит харнесс, их не видит ни
один хук), затем `ctxguard audit`.

По умолчанию сканируются транскрипты **только этого проекта**: сессии других
проектов оцениваются против словаря, который им не принадлежит. Расширить —
`--all-projects`.

Часть находок может быть помечена как **структурные**: значение входит в собственный
путь проекта, поэтому появляется в каждом абсолютном пути и в метаданных транскрипта.
Никаким хуком это не лечится — только переименованием каталога.

---

## Передача словаря другой машине или коллеге

Плагин путешествует через маркетплейс. Словарь — нет, и не должен.
`~/.claude/ctx-guard/` живёт на машине и намеренно вне любого репозитория. Передавать
его нужно явно, потому что **алиасы невозможно воспроизвести**:

- они выдаются в порядке регистрации, так что добавивший две компании в другом
  порядке получит перевёрнутое соответствие — два человека будут понимать под
  `CTXG_COMPANY_A` *разные компании*;
- соль генерируется на хранилище, поэтому маркеры секретов и PII-алиасы тоже не
  совпадут, и находки нельзя сопоставить между людьми.

На это есть тест, так что рекомендация не может тихо устареть.

```
ctxguard entity export --out ~/team-dict.json   # откажется писать внутрь git-репозитория
# передавать по каналу, по которому вы отправили бы сами реальные значения — файл содержит их
ctxguard entity import team-dict.json           # запускать из каталога проекта
# удалить файл выгрузки сразу после импорта
```

После импорта обе машины дают побайтово одинаковый вывод — включая маркеры и
PII-алиасы. Если в проекте уже есть словарь с другой солью, импорт откажется:
принять чужую соль (`--adopt-salt`) значит поменять все уже используемые PII-алиасы и
маркеры секретов.

---

## Чего ctxguard не покрывает

- `CLAUDE.md` и `AGENTS.md` грузит сам харнесс — **ни один хук их не видит**.
  Санитизировать вручную; `SessionStart` предупредит, если в них найдены реальные
  имена.
- Структурные утечки: имя, входящее в путь проекта, защитить нельзя.
- Пока сущности не зарегистрированы или не импортированы, живы только детект
  креденшлов и PII — имена компаний, людей и хостов не защищены.

Подробнее — `plugins/ctxguard/skills/context-sanitization/references/threat-model.md`.
Прочитайте его прежде, чем обещать кому-либо, что данные в безопасности.

Необязательно, но полезно — чтобы ожидание пережило отключение плагина, добавьте в
свой `CLAUDE.md`:

```markdown
Чувствительные данные в этом проекте заменены алиасами (`CTXG_*`), это обеспечивают
хуки ctxguard. Используй алиасы буквально, никогда не восстанавливай реальные
значения, а причину отказа читай вместо того, чтобы его обходить. См. скилл
context-sanitization.
```

---

## Настройка и отладка

Политика: `~/.claude/ctx-guard/policy.json`. Отсутствует или битая — применяются
строгие значения по умолчанию, потому что умолчания и есть безопасный откат.
Хранится как diff от умолчаний, чтобы исправления правил доходили до установленных
копий.

Ключевые поля: `mode` (`enforce` / `observe`), `fail_closed` (ошибка санитайзера
отклоняет вызов инструмента), `alias_prefix`, `entropy_threshold`, `max_scan_bytes`,
`bash_wrap` (выключение убирает фильтрацию вывода шелла целиком — не отключайте ради
скорости), `deny_read_paths`, `deny_command_patterns`, `allowlist`,
`disabled_secret_rules`. Полный список — `references/policy.md`.

**Ложные срабатывания** — в порядке предпочтения: точное значение в `allowlist` →
конкретный маркер в `allowlist_substrings` → сужение правила в `detect.py` с тестом →
id правила в `disabled_secret_rules`. Сначала посмотрите `ctxguard audit`: правило,
которое постоянно срабатывает на безобидном, — это причина, по которой защиту в итоге
выключают.

**Стоимость:** порядка 134 мс на решение по Bash и 155 мс на Read, который должен
просканировать файл и материализовать twin. На задачу из 50 вызовов инструментов —
примерно 6–7 секунд. Twin-копии кэшируются и инвалидируются по mtime+size, так что
повторные чтения дешёвые.

**Правка плагина не подействовала.** Хуки исполняют **установленную копию**, а не
рабочее дерево, и `plugin.json` сравнивается по версии, а не по коммиту — релиз без
бампа версии не доедет до установленной копии молча. После каждого изменения:

```
claude plugin marketplace update ctx-tools
claude plugin update ctxguard@ctx-tools        # нужен рестарт сессии
```

Убедиться:
`diff -rq ~/.claude/plugins/cache/ctx-tools/ctxguard/<версия>/scripts plugins/ctxguard/scripts`.

**Выключить.** `/plugin uninstall ctxguard@ctx-tools`. `mode observe` оставляет детекторы
и аудит, но ничего не блокирует — это калибровка, а не способ работать защищённо.
Состояние в `~/.claude/ctx-guard/` в обоих случаях остаётся; удалите этот каталог,
чтобы убрать и словарь.

---

## Структура репозитория

```
.claude-plugin/marketplace.json     манифест маркетплейса
plugins/ctxguard/                   санитизация контекста: скилл + хуки + CLI
docs/specs/                         проектный документ (исторический)
Makefile                            единственный вход в проверки
```

### Куда положить новый скилл

| Скиллу нужны… | Куда |
|---|---|
| хуки, слэш-команды, MCP-серверы, скрипты | отдельный плагин в `plugins/<имя>/` + запись в `marketplace.json` |
| ничего, кроме инструкций | плагин-«ведро»: `plugins/<bucket>/skills/<имя>/SKILL.md` |

Хуки не могут ехать внутри голого скилла — именно поэтому репозиторий сделан
маркетплейсом, а не плоским каталогом `SKILL.md`. Скиллы «только инструкции» стоит
собирать в один плагин-ведро: одна установка покрывает все, тогда как плагины,
ставящие хуки, добавляются осознанно и по одному. Такого ведра здесь пока нет —
создайте его вместе с первым таким скиллом, а не заранее.

Конвенции, вслед за экосистемой установленных плагинов:

- frontmatter в `SKILL.md` — `name` + `description`, третье лицо, много триггеров
- детали уходят в `references/*.md`, не в `SKILL.md`
- скрипты — Python 3 **только stdlib**, вызов через
  `python3 "${CLAUDE_PLUGIN_ROOT}/..."`

Начать чтение стоит с `plugins/ctxguard/skills/context-sanitization/SKILL.md`.