agent-guard

A generic-purpose cli-guard consumer for repos that take external contributions. Sits between AI agents (or any semi-trusted automation) and the host system, with no maintainer-specific allowlists.

agent-guard is to external contributors what coily is to Kai's own machines: a thin, audited wrapper around the cli-guard primitives. coily ships personal verbs (homelab SSH, vault paths, deploy hooks). agent-guard ships only verbs that make sense to any contributor walking up to a repo cold.

Status

v0. Not yet wired into any downstream. First adopter target is the urfave/cli namespaced repos (cli-mcp, cli-web-docs, cli-web-ops).

What it does

Wraps a small, fixed set of dev verbs (build, test, vet, lint, tidy) behind cli-guard's policy gate. Every invocation:

• validates argv against shell-metacharacter rejection
• writes one append-only JSONL audit row
• binds to a git toplevel via --commit-scope
• refuses repo-shaped verbs on a dirty tree

Downstream repos add an .agent-guard/agent-guard.yaml listing which Makefile targets are exposed. The contract is verified by agent-guard lint.

Install

brew tap coilysiren/agent-guard https://github.com/coilysiren/agent-guard
brew install coilysiren/agent-guard/agent-guard

The explicit-URL brew tap form is required because this repo isn't homebrew-* prefixed.

Usage

agent-guard exec build
agent-guard exec test
agent-guard lint

See docs/ for the full verb list and examples/ for runnable demos.

Claude Code PreToolUse hook

agent-guard hook pre-tool-use is a stdin-driven Claude Code hook that does two things:

1. Binary-path check. Required by default. When the agent invokes agent-guard or coily directly, the hook resolves the binary via command -v and refuses to let it run unless the resolved path is one of the canonical homebrew install paths. This blocks PATH-hijack attacks where a malicious agent-guard or coily earlier on $PATH would otherwise execute. agent-guard ships with maximum-security defaults; this check is on, no flag, no config.
2. Routing-hint surface. Catches bare invocations of wrapped binaries (make, gh, aws, kubectl, ...) and surfaces a recovery hint to the agent before it shops other shell shapes. The hint names the wrapper the agent should use. The active table is picked by whether cwd lives under .agent-guard/agent-guard.yaml or .coily/coily.yaml.

No network, no state. Failure modes (unparseable payload, missing fields, no matching route, binary absent from PATH) pass through silently. Hard denial stays the job of permissions.deny in the consuming repo's .claude/settings.json.

Register the hook with one command (idempotent, safe to re-run, preserves unrelated keys):

agent-guard install-hooks

This writes the PreToolUse entry into <git-toplevel>/.claude/settings.json. Pass --path <file> to target a different settings.json, --dry-run to preview the merged content, or --check (exit non-zero when the hook is not yet registered, for CI).

Or hand-roll the entry:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "agent-guard hook pre-tool-use" }
        ]
      }
    ]
  }
}

Related

• cli-guard - the underlying security-boundary framework
• coily - Kai's personal cli-guard consumer
• Sibling cli-* repos: cli-mcp, cli-web-docs, cli-web-ops

Support

Bug or feature request: create a new issue. Conduct: Code of Conduct. Security: SECURITY.md. License: LICENSE.

See also

• AGENTS.md - agent-facing operating rules.
• docs/FEATURES.md - inventory of what ships today.
• .agent-guard/agent-guard.yaml - allowlisted commands.

Cross-reference convention from coilysiren/agentic-os#59.