agent-guard — хук для Claude Code: что делает и как установить
Хук agent-guard проверяет действия агента на утечки секретов в Claude Code и Codex. Он пригодится, если нужна локальная проверка с дополнительными барьерами в Git и CI.
MIT ★ 1 596 обновлён 2026-10-29
.claude/settings.jsonЧто делает agent-guard
agent-guard блокирует или маскирует секреты при работе инструментов Claude Code и Codex. Хуки запускаются до и после вызова инструмента, а также при отправке запроса, старте сессии и её завершении. По умолчанию проверки работают локально, без телеметрии. Фильтрацию персональных данных можно включить отдельно.
В наборе есть проверки для Git и CI. Хук реагирует на вызовы Bash, apply_patch, субагентов и MCP-инструментов. Если исполняемый файл проверки не найден, режим open по умолчанию пропускает действие; режим closed блокирует его. Это важно учесть при выборе поведения на случай сбоя проверки.
Для Claude Code настройка подключается через .claude/settings.json. Хук также заявлен для Codex, но приведённый способ установки относится к Claude Code.
Какие задачи решает
- блокировать утечку секретов при вызове инструментов
- маскировать секретные значения в действиях агента
- включать фильтрацию персональных данных
- проверять утечки на этапах Git и CI
Примеры запросов агенту
- Перед запуском команд проверь, не содержат ли они секреты.
- Проверь изменения через
apply_patchна утечки ключей. - Включи фильтрацию персональных данных при проверке действий агента.
Как установить agent-guard
Вручную: положить файлы
.claude/settings.jsonБлок hooks: событие (PreToolUse, PostToolUse, Stop…) → команда. Личные — ~/.claude/settings.json
По шагам, с командами для каждой платформы: Хуки Claude Code: что это, где настраивать и как запретить опасную команду
Вопросы об agent-guard
Как установить agent-guard в Claude Code?
Подключите хук через файл .claude/settings.json.
Что делает хук agent-guard?
Он блокирует или маскирует утечки секретов при работе инструментов Claude Code и Codex. Фильтрацию персональных данных можно включить отдельно.
Что произойдёт, если проверочный файл не найден?
В режиме open, который используется по умолчанию, действие продолжается. При AGENT_GUARD_INFRA_FAILURE_MODE=closed хук блокирует его.
Исходный текст
hooks.json · MIT
Hooks bundle shipped with the agent-guard plugin for Claude Code.
Local-by-default, no-telemetry hooks block or mask secret leaks in Claude Code and Codex, with opt-in PII filtering and Git/CI backstops.
Triggers on: PreToolUse, PostToolUse, UserPromptSubmit, SessionStart, Stop.
```json
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash|apply_patch|Agent|Task|mcp__.*",
"hooks": [
{
"type": "command",
"command": "sh -c 'r=${PLUGIN_ROOT:-}; b=${r%/*}; x=; semver() { case ${1:-} in \"\"|*[!0-9.]*) return 1 ;; esac; o=$IFS; IFS=.; set -- $1; IFS=$o; [ \"$#\" -eq 3 ] && [ -n \"$1\" ] && [ -n \"$2\" ] && [ -n \"$3\" ]; }; root_ok() { q=$1; e=${2:-}; z=\"$q/bin/agent-guard\"; [ -x \"$z\" ] && [ -r \"$q/config/gitleaks.toml\" ] && [ -r \"$q/config/deny-read-paths.txt\" ] && [ -r \"$q/config/deny-bash-patterns.txt\" ] || return 1; u=; while IFS= read -r l; do case \"$l\" in VERSION=*) u=${l#VERSION=}; break ;; esac; done <\"$z\"; [ -n \"$u\" ] && { [ -z \"$e\" ] || [ \"$u\" = \"$e\" ]; }; }; if [ -n \"$r\" ]; then v=${r##*/}; semver \"$v\" || v=; if root_ok \"$r\" \"$v\"; then x=\"$r/bin/agent-guard\"; elif [ ! -e \"$r\" ]; then c=\"$b/current\"; t=; [ -L \"$c\" ] && t=$(readlink \"$c\" 2>/dev/null) || :; if semver \"$t\" && root_ok \"$c\" \"$t\"; then x=\"$c/bin/agent-guard\"; else x=$(for z in \"$b\"/*/bin/agent-guard; do [ -x \"$z\" ] || continue; q=${z%/bin/agent-guard}; v=${q##*/}; semver \"$v\" || continue; root_ok \"$q\" \"$v\" || continue; printf \"%s\\\\t%s\\\\n\" \"$v\" \"$z\"; done | sort -t. -k1,1n -k2,2n -k3,3n | tail -n 1 | cut -f 2-); fi; fi; fi; if [ ! -x \"$x\" ]; then mode=${AGENT_GUARD_INFRA_FAILURE_MODE:-open}; case \"$mode\" in closed) action=blocking ;; *) mode=open; action=continuing ;; esac; d=${AGENT_GUARD_WARNING_DIR:-${TMPDIR:-/tmp}/agent-guard-warnings-${UID:-user}}; p=; while IFS= read -r line || [ -n \"$line\" ]; do p=$p$line; done; i=${AGENT_GUARD_SESSION_ID:-}; if [ -z \"$i\" ] && command -v jq >/dev/null 2>&1; then i=$(printf %s \"$p\" | jq -r \".session_id // empty\" 2>/dev/null); fi; if [ -z \"$i\" ]; then case \"$p\" in *\\\"session_id\\\":\\\"*) i=${p#*\\\"session_id\\\":\\\"}; i=${i%%\\\"*}; case \"$i\" in \"\"|*[!A-Za-z0-9._:-]*) i= ;; esac ;; esac; fi; if [ -n \"$i\" ]; then i=$(printf %s \"$i\" | cksum); else i=ppid-${PPID:-0}; fi; k=\"$d/manifest-codex-$i-$mode\"; warn=1; if [ \"$mode\" = open ] && mkdir -p \"$d\" 2>/dev/null; then (umask 077; set -C; : >\"$k\") 2>/dev/null || { [ -e \"$k\" ] && warn=0; }; fi; [ \"$warn\" -eq 0 ] || echo \"agent-guard: PLUGIN_ROOT env not set, selected root was incomplete, or no installed binary was found; $action because AGENT_GUARD_INFRA_FAILURE_MODE=$mode\" >&2; [ \"$mode\" = closed ] && exit 2; exit 0; fi; AGENT_GUARD_HOOK_HOST=codex \"$x\" hook-pre-tool'",
"timeout": 60
}
]
}
],
"PostToolUse": [
{
"matcher": "Bash|apply_patch|Agent|Task|mcp__.*",
"hooks": [
{
"type": "command",
"command": "sh -c 'r=${PLUGIN_ROOT:-}; b=${r%/*}; x=; semver() { case ${1:-} in \"\"|*[!0-9.]*) return 1 ;; esac; o=$IFS; IFS=.; set -- $1; IFS=$o; [ \"$#\" -eq 3 ] && [ -n \"$1\" ] && [ -n \"$2\" ] && [ -n \"$3\" ]; }; root_ok() { q=$1; e=${2:-}; z=\"$q/bin/agent-guard\"; [ -x \"$z\" ] && [ -r \"$q/config/gitleaks.toml\" ] && [ -r \"$q/config/deny-read-paths.txt\" ] && [ -r \"$q/config/deny-bash-patterns.txt\" ] || return 1; u=; while IFS= read -r l; do case \"$l\" in VERSION=*) u=${l#VERSION=}; break ;; esac; done <\"$z\"; [ -n \"$u\" ] && { [ -z \"$e\" ] || [ \"$u\" = \"$e\" ]; }; }; if [ -n \"$r\" ]; then v=${r##*/}; semver \"$v\" || v=; if root_ok \"$r\" \"$v\"; then x=\"$r/bin/agent-guard\"; elif [ ! -e \"$r\" ]; then c=\"$b/current\"; t=; [ -L \"$c\" ] && t=$(readlink \"$c\" 2>/dev/null) || :; if semver \"$t\" && root_ok \"$c\" \"$t\"; then x=\"$c/bin/agent-guard\"; else x=$(for z in \"$b\"/*/bin/agent-guard; do [ -x \"$z\" ] || continue; q=${z%/bin/agent-guard}; v=${q##*/}; semver \"$v\" || continue; root_ok \"$q\" \"$v\" || continue; printf \"%s\\\\t%s\\\\n\" \"$v\" \"$z\"; done | sort -t. -k1,1n -k2,2n -k3,3n | tail -n 1 | cut -f 2-); fi; fi; fi; if [ ! -x \"$x\" ]; then mode=${AGENT_GUARD_INFRA_FAILURE_MODE:-open}; case \"$mode\" in closed) action=blocking ;; *) mode=open; action=continuing ;; esac; d=${AGENT_GUARD_WARNING_DIR:-${TMPDIR:-/tmp}/agent-guard-warnings-${UID:-user}}; p=; while IFS= read -r line || [ -n \"$line\" ]; do p=$p$line; done; i=${AGENT_GUARD_SESSION_ID:-}; if [ -z \"$i\" ] && command -v jq >/dev/null 2>&1; then i=$(printf %s \"$p\" | jq -r \".session_id // empty\" 2>/dev/null); fi; if [ -z \"$i\" ]; then case \"$p\" in *\\\"session_id\\\":\\\"*) i=${p#*\\\"session_id\\\":\\\"}; i=${i%%\\\"*}; case \"$i\" in \"\"|*[!A-Za-z0-9._:-]*) i= ;; esac ;; esac; fi; if [ -n \"$i\" ]; then i=$(printf %s \"$i\" | cksum); else i=ppid-${PPID:-0}; fi; k=\"$d/manifest-codex-$i-$mode\"; warn=1; if [ \"$mode\" = open ] && mkdir -p \"$d\" 2>/dev/null; then (umask 077; set -C; : >\"$k\") 2>/dev/null || { [ -e \"$k\" ] && warn=0; }; fi; [ \"$warn\" -eq 0 ] || echo \"agent-guard: PLUGIN_ROOT env not set, selected root was incomplete, or no installed binary was found; $action because AGENT_GUARD_INFRA_FAILURE_MODE=$mode\" >&2; [ \"$mode\" = closed ] && exit 2; exit 0; fi; AGENT_GUARD_HOOK_HOST=codex \"$x\" hook-post-tool'",
"timeout": 20
}
]
}
],
"Stop": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "sh -c 'r=${PLUGIN_ROOT:-}; b=${r%/*}; x=; semver() { case ${1:-} in \"\"|*[!0-9.]*) return 1 ;; esac; o=$IFS; IFS=.; set -- $1; IFS=$o; [ \"$#\" -eq 3 ] && [ -n \"$1\" ] && [ -n \"$2\" ] && [ -n \"$3\" ]; }; root_ok() { q=$1; e=${2:-}; z=\"$q/bin/agent-guard\"; [ -x \"$z\" ] && [ -r \"$q/config/gitleaks.toml\" ] && [ -r \"$q/config/deny-read-paths.txt\" ] && [ -r \"$q/config/deny-bash-patterns.txt\" ] || return 1; u=; while IFS= read -r l; do case \"$l\" in VERSION=*) u=${l#VERSION=}; break ;; esac; done <\"$z\"; [ -n \"$u\" ] && { [ -z \"$e\" ] || [ \"$u\" = \"$e\" ]; }; }; if [ -n \"$r\" ]; then v=${r##*/}; semver \"$v\" || v=; if root_ok \"$r\" \"$v\"; then x=\"$r/bin/agent-guard\"; elif [ ! -e \"$r\" ]; then c=\"$b/current\"; t=; [ -L \"$c\" ] && t=$(readlink \"$c\" 2>/dev/null) || :; if semver \"$t\" && root_ok \"$c\" \"$t\"; then x=\"$c/bin/agent-guard\"; else x=$(for z in \"$b\"/*/bin/agent-guard; do [ -x \"$z\" ] || continue; q=${z%/bin/agent-guard}; v=${q##*/}; semver \"$v\" || continue; root_ok \"$q\" \"$v\" || continue; printf \"%s\\\\t%s\\\\n\" \"$v\" \"$z\"; done | sort -t. -k1,1n -k2,2n -k3,3n | tail -n 1 | cut -f 2-); fi; fi; fi; if [ ! -x \"$x\" ]; then mode=${AGENT_GUARD_INFRA_FAILURE_MODE:-open}; case \"$mode\" in closed) action=blocking ;; *) mode=open; action=continuing ;; esac; d=${AGENT_GUARD_WARNING_DIR:-${TMPDIR:-/tmp}/agent-guard-warnings-${UID:-user}}; p=; while IFS= read -r line || [ -n \"$line\" ]; do p=$p$line; done; i=${AGENT_GUARD_SESSION_ID:-}; if [ -z \"$i\" ] && command -v jq >/dev/null 2>&1; then i=$(printf %s \"$p\" | jq -r \".session_id // empty\" 2>/dev/null); fi; if [ -z \"$i\" ]; then case \"$p\" in *\\\"session_id\\\":\\\"*) i=${p#*\\\"session_id\\\":\\\"}; i=${i%%\\\"*}; case \"$i\" in \"\"|*[!A-Za-z0-9._:-]*) i= ;; esac ;; esac; fi; if [ -n \"$i\" ]; then i=$(printf %s \"$i\" | cksum); else i=ppid-${PPID:-0}; fi; k=\"$d/manifest-codex-$i-$mode\"; warn=1; if [ \"$mode\" = open ] && mkdir -p \"$d\" 2>/dev/null; then (umask 077; set -C; : >\"$k\") 2>/dev/null || { [ -e \"$k\" ] && warn=0; }; fi; [ \"$warn\" -eq 0 ] || echo \"agent-guard: PLUGIN_ROOT env not set, selected root was incomplete, or no installed binary was found; $action because AGENT_GUARD_INFRA_FAILURE_MODE=$mode\" >&2; [ \"$mode\" = closed ] && exit 2; exit 0; fi; AGENT_GUARD_HOOK_HOST=codex \"$x\" hook-stop'",
"timeout": 20
}
]
}
],
"SessionStart": [
{
"matcher": "startup|resume|clear|compact",
"hooks": [
{
"type": "command",
"command": "sh -c 'r=${PLUGIN_ROOT:-}; b=${r%/*}; x=; semver() { case ${1:-} in \"\"|
```
© Agent Guard contributors · MIT · hashgraph-online/awesome-codex-plugins