/setup-agent-guard

name: setup-agent-guard
description: Diagnose, install, and verify Agent Guard's plugin-local binary, jq and gitleaks dependencies, the active host integration, and live hook protection. Use when Agent Guard reports degraded protection, a SessionStart warning asks for setup, plugin hooks fail or appear bypassed, or a user asks to finish or repair Agent Guard installation.
disable-model-invocation: true

Setup Agent Guard

Make Agent Guard operational without silently changing the machine. Diagnose first, request approval before package-manager or download actions, and finish with a real smoke test.

Workflow

1. Resolve the Agent Guard executable without confusing the plugin with a standalone install.

• First use the plugin binary two directories above this skill: `../../bin/agent-guard` relative to this `SKILL.md` directory.
• Resolve the path from the skill directory, confirm that it is executable, and use it for every plugin diagnosis and smoke test.
• Separately inspect `command -v agent-guard`, if present. Compare its `version` with the plugin binary and report version drift, but do not substitute it for the plugin binary or modify the standalone installation without explicit approval.
• Only fall back to `command -v agent-guard` when the plugin-relative binary is unavailable, and clearly state that plugin-local verification could not be completed.
• Do not install a second copy of Agent Guard merely to get a command on `PATH`.

2. Run the read-only diagnosis:

   "<agent-guard-bin>" setup

`setup` and `doctor` report only local dependencies. Their `host hook protection: unverified` notice is expected even when they exit `0`; do not call that result runtime protection.

3. If `jq` is missing, identify the available system package manager and show the exact install command. Ask for explicit user approval before running it. Do not use `sudo` unless the user explicitly approves elevated installation.

4. `setup`이 gitleaks 자체의 누락이 아니라 `gitleaks version isolation requires setsid or perl`을 보고하면 gitleaks를 다시 설치하지 마세요. Linux에서는 `setsid`를 제공하는 `util-linux`를, Homebrew 환경에서는 Perl을 설치하는 정확한 명령을 보여 주고 실행 전 명시적 승인을 받으세요. `setup --install`도 이 보조 도구를 자동 설치하지 않으며, 보조 도구가 없으면 gitleaks 다운로드 전에 중단하고 복구 전까지 nonzero 상태를 유지합니다.

5. If `gitleaks` is missing, prefer Agent Guard's private, checksum-pinned installer:

• Determine the target OS and architecture.
• Fetch the official checksum list for the version reported by `agent-guard setup`.
• Select the checksum for the exact archive name and show the version, archive, source URL, checksum, and destination.
• Ask for explicit approval before downloading or installing.
• After approval, run:

   "<agent-guard-bin>" setup --install \
     --gitleaks-version "<version>" \
     --gitleaks-checksum "<published-sha256>"

Never substitute an unverified checksum and never bypass TLS verification.

6. If an approved dependency installation is blocked by the host sandbox:

• Relay the exact error. Do not retry the same blocked write, change the

install destination, or bypass the sandbox silently.

• Show the exact command for the user to run in a separate terminal. For the

private gitleaks installer, preserve the plugin-local binary path, version, and published checksum from the approved command above.

• Wait for the user to confirm that the command finished, rerun the read-only

`"<agent-guard-bin>" setup` diagnosis, and continue only when the dependency reports `ok`.

7. Verify the plugin-local installation:

   "<agent-guard-bin>" check
   "<agent-guard-bin>" smoke-test

Treat `check` as dependency/config validation and `smoke-test` as proof of the binary's own behavior. They do not prove that the host is dispatching plugin hooks.

8. Identify the active host and verify its plugin boundary before claiming that protection is active.

• In Codex, confirm that the Agent Guard plugin is installed and enabled. In **Settings > Hooks**, inspect Agent Guard's `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, and `Stop` hooks. Every hook must be enabled and trusted. Treat `Untrusted` and `Modified` as inactive; an updated hook must be reviewed and trusted again.
• In Codex, do not edit `hooks.state` or copy trust hashes into `config.toml`. Hook trust is a user security decision and must go through the Codex trust UI. If `SessionStart` itself is untrusted, explain that it cannot emit the setup warning or invoke this skill automatically.
• In Claude Code, confirm that the Agent Guard plugin is installed and enabled, then reload plugins after an install or update. Do not direct Claude Code users to Codex **Settings > Hooks**; Claude Code does not use that trust workflow. `/agent-guard:verify` can check the working tree, but it does not prove live hook dispatch.
• If the active host is unclear, infer it from the current product and invocation (`$setup-agent-guard` in Codex or `/agent-guard:setup-agent-guard` in Claude Code). Do not apply one host's setup steps to the other.

9. Run live host probes through the normal command tool selected by the active host for the current task. Do not read a real sensitive file.

• Pre-tool probe:

     printf '%s\n' 'AGENT_GUARD_LIVE_PRE_TOOL_PROBE'

The expected result is an Agent Guard block before the marker is printed. If the marker appears, the live command boundary is not protected.

• Post-tool probe:

     printf '%s\n' 'AGENT_GUARD_LIVE_POST_TOOL_PROBE'

The raw marker must not reach the model; expect `[REDACTED]` in a masked or sanitized replacement. While local diagnostic logging is on the replacement also names the hook invocation that produced it, as `[REDACTED] agent-guard live probe run_id=<run id>`; report that id so the user can resolve it with `agent-guard logs export` instead of taking the probe