Claude Code agent governance: practical guardrails, logs, and rule packs

Claude Code agent governance matters as soon as an agent can run shell commands, edit files, or call tools on your machine. The problem is not abstract: once an agent has enough autonomy to be useful, it also has enough autonomy to make a bad assumption at scale. A workable governance layer needs to do three things well: constrain behavior before execution, record actions after execution, and stay simple enough that developers will actually keep it enabled.

AgentCheck is one approach aimed specifically at this gap. It wraps each Claude process with hook-based guardrails, logs tool calls to JSONL, and enforces rule packs defined in YAML. That design is useful because it does not require you to rewrite the agent, build a separate proxy service, or depend on a UI dashboard just to understand what happened.

This post walks through Claude Code agent governance from a practical perspective: what should be governed, how AgentCheck fits into the execution path, what configuration looks like, and where the limits are. The goal is not to present a perfect safety story. The goal is to give you a technical pattern that is auditable, inspectable, and good enough to use in real development workflows.

Why Claude Code agent governance is an engineering problem, not a policy document

Most teams start with written rules such as “don’t modify production credentials” or “don’t run destructive commands without approval.” Those rules are fine for humans, but they are weak controls for agents. If the only enforcement point is the prompt, governance is effectively advisory.

For developers, useful Claude Code agent governance typically covers four surfaces:

• Tool execution: which commands, file operations, or integrations are allowed.
• Scope boundaries: which directories, repos, or file patterns are writable.
• Auditability: whether every tool call is captured with enough context to reconstruct the session.
• Policy portability: whether rules can be versioned in Git and reviewed like code.

That last point is easy to underestimate. If your governance logic only lives in a local shell alias or undocumented wrapper script, nobody can review changes to it. YAML rule packs are not magical, but they are easy to diff, test, and distribute across environments.

How AgentCheck implements Claude Code agent governance

AgentCheck sits around the Claude process rather than inside the model. In practice, that means you keep using Claude Code, but the session runs with a behavioral governance layer attached. Hooks observe tool activity, JSONL provides a durable event stream, and rule packs define the policy.

The basic install path is straightforward:

npm install -g github:paprika-org/agentcheck

# Example invocation pattern
agentcheck --rules ./rules/dev-safe.yaml --log ./logs/agentcheck.jsonl -- claude

A minimal rule pack might look like this:

version: 1
name: dev-safe
rules:
  - id: deny-destructive-shell
    match:
      tool: shell
      commandRegex: '(^|[;&|[:space:]])(rm -rf /|mkfs|shutdown|reboot)([;&|[:space:]]|$)'
    action: deny
    message: "Destructive system commands are blocked."

  - id: restrict-env-files
    match:
      tool: write_file
      pathRegex: '(^|/)\.env(\..+)?$'
    action: deny
    message: "Direct edits to environment files are not allowed."

  - id: allow-project-work
    match:
      tool: write_file
      pathRegex: '^/workspace/project/'
    action: allow

The value in this pattern is operational clarity. If a session is blocked, you can inspect the matching rule. If a session succeeds, you can inspect the emitted log. You do not need to infer everything from agent chat transcripts.

JSONL is a strong choice for logging because it is append-only, grep-friendly, and easy to forward into existing systems. A typical event stream might include timestamps, tool names, arguments, decision outcomes, and rule identifiers. That is enough to answer the questions developers usually have after the fact: what command actually ran, which rule allowed it, and what happened immediately before it?

Setting up rule packs that developers will keep using

The failure mode for many governance systems is overreach. If rules are too broad, developers disable them. If rules are too vague, they do not protect anything. In practice, Claude Code agent governance works best when rules are narrow, explicit, and tied to concrete risks.

A useful starting set usually includes:

• Deny destructive shell commands outright.
• Block writes to secrets, SSH material, and deployment manifests.
• Limit file writes to the current repo or workspace subtree.
• Require explicit allow rules for high-risk tools.
• Keep logs on by default for every session, including local development.

It is also worth separating rules by context. A local prototype, a CI verification run, and a documentation-only agent should not share the same policy file. Smaller rule packs are easier to reason about, and context-specific packs reduce the temptation to add sprawling exceptions.

One practical workflow is to store policies under a directory such as ./agentcheck/, review them in pull requests, and couple changes to incidents or new classes of agent behavior. If an agent was allowed to modify a file it should not have touched, the remediation should include a rule update and a regression test around that policy.

$ tail -n 3 ./logs/agentcheck.jsonl
{"ts":"2026-05-02T10:14:11Z","tool":"shell","args":{"command":"git status --short"},"decision":"allow","ruleId":"allow-readonly-shell"}
{"ts":"2026-05-02T10:14:16Z","tool":"write_file","args":{"path":"/workspace/project/src/config.ts"},"decision":"allow","ruleId":"allow-project-work"}
{"ts":"2026-05-02T10:14:22Z","tool":"write_file","args":{"path":"/workspace/project/.env"},"decision":"deny","ruleId":"restrict-env-files"}

This kind of output is enough for incident review without requiring a heavyweight platform. You can diff policy changes, grep logs, and answer whether a behavior was blocked by design or merely happened not to occur.

Limitations and honest tradeoffs of Claude Code agent governance

Claude Code agent governance reduces risk, but it does not eliminate it. There are at least four limits developers should plan around.

First, governance at the process layer is not a replacement for sandboxing. If the wrapped process can already reach sensitive paths, networks, or credentials, then your rule pack is enforcing behavior inside a trusted boundary. That is useful, but it is not the same thing as hard isolation.

Second, pattern-based policy can miss intent. Denying rm -rf / is easy. Identifying a subtle but dangerous repository-specific command is harder. Good policies evolve from observed usage, not from trying to predict every possible bad action up front.

Third, audit logs create their own operational responsibility. If you log command arguments, file paths, or snippets of content, you need to think about retention and sensitivity. JSONL is easy to process, which is exactly why you should decide where those files live and who can read them.

Fourth, policy friction is real. If your rules block common refactors or produce noisy false positives, developers will route around them. The design goal should be “safe by default, boring to operate,” not “maximally restrictive at all times.”

In other words, the best Claude Code agent governance setup is layered: AgentCheck for behavioral controls and auditability, sandboxing for system boundaries, and repository practices such as branch protection or CI checks for downstream verification.

Common mistakes and troubleshooting

1. Rules only deny obvious shell commands. Teams often focus on a short list of destructive commands and ignore file-level operations. That leaves gaps where an agent can still alter lockfiles, deployment configs, or secrets through other tools. Add path-based rules, not just command regexes.

2. Log files are enabled but never reviewed. Logging without review is just storage. At minimum, validate that denied actions show up as expected and that allowed actions include enough context for debugging. Run a few controlled violations during setup so you know the pipeline is working.

3. The policy is too global. A single monolithic rule pack for all workflows usually becomes unreadable. Split policies by mode, such as docs-only, repo-write, or ci-verify, and keep each one small.

4. Governance is expected to replace code review. It does not. Agent governance can stop certain classes of bad behavior and produce a better audit trail, but it will not tell you whether a migration is logically correct or whether a refactor introduced a race condition.

If troubleshooting a blocked session, check three things in order: the exact tool call emitted, the rule that matched, and whether the path or command normalization in your rule pack reflects real runtime values. Many policy bugs turn out to be mismatched paths or an overly broad regex.

Operational advice for teams adopting Claude Code agent governance

Start in report-first mode if needed, but do not stay there forever. Logging-only rollout helps you see what agents actually attempt, which is valuable input for building sane policies. After a short observation period, promote the obvious high-risk cases to deny rules.

Keep rule changes in the same repository review process as application code. A governance layer that can silently change outside normal engineering workflows is hard to trust. Pair each nontrivial policy change with a short rationale in the commit message or a neighboring README.

Finally, measure governance quality by developer outcomes: fewer accidental file touches, faster incident reconstruction, and clearer boundaries for autonomous tasks. If a policy system cannot explain why it blocked or allowed an action, it will not hold up under real operational pressure.

Frequently Asked Questions

What is Claude Code agent governance?

Claude Code agent governance is the practice of defining technical controls around an agent session, including tool restrictions, execution logging, approval boundaries, and machine-readable rules that limit risky behavior.

Can AgentCheck block dangerous Claude Code commands?

Yes. AgentCheck can wrap Claude Code processes, inspect tool calls through hooks, and enforce YAML rule packs that deny or constrain commands, file access patterns, and other actions before they execute.

Where are AgentCheck audit logs stored?

AgentCheck logs tool activity to JSONL so each event is appended as a structured line. The exact path depends on your configuration, but the format is designed for local review and downstream ingestion into log pipelines.

Is Claude Code agent governance the same as sandboxing?

No. Sandboxing isolates runtime capabilities at the operating system or container level, while agent governance adds behavioral policy, auditability, and higher-level rules about what the agent should and should not attempt.