custodian-claude-guard 0.1.0

Fail-closed Custodian policy guard for Claude Code, with unstrippable managed-hook enforcement

Custodian Claude Guard

A second opinion before Claude Code touches your machine.

Claude Guard evaluates every tool call Claude Code proposes before it runs, through a fail-closed PreToolUse hook. Reads, writes, shell commands, network calls, credentials, and destructive operations all pass through policy the model cannot rewrite.

When an action needs you, Custodian creates an authenticated, single-use approval bound to the exact tool, arguments, workspace, requester, and policy version. Claude Code's own native permission dialog is the approval step — there is no separate out-of-band approve/deny command to learn.

Why it exists

Tool permissions answer one question: may this run? Custodian asks the questions around it:

• Is the declared workspace a real project rather than a home directory or filesystem root?
• Does this call cross a network, credential, production, or money boundary?
• Can the operator find out afterward what was decided and why, without the receipt itself ever holding a secret or prompt?
• Was this hook actually installed somewhere the user can't just edit away?

Claude Guard supplements Claude Code's own permission system and sandboxing. It does not replace operating-system isolation.

Install

Install from PyPI:

pipx install custodian-claude-guard
custodian-claude setup
custodian-claude doctor

setup merges a fail-closed PreToolUse hook into your Claude Code settings.json, pinned to the exact interpreter that installed it. It's idempotent and never touches unrelated settings.

On Linux distributions that enforce PEP 668, use pipx or a virtual environment. Do not use --break-system-packages.

Two install strengths

The plain install above is user-editable — anyone (or anything) with your file access can remove the hook entry from ~/.claude/settings.json. For enforcement that can't be turned off that way:

sudo custodian-claude setup --managed-lock

This installs into Claude Code's system-level managed settings (a fixed, root/admin-owned path per platform — e.g. /etc/claude-code/managed-settings.json on Linux) and sets allowManagedHooksOnly, which Claude Code enforces as: only managed hooks are loaded, user and project hooks are blocked outright. Removing it requires the same admin access that installing it did:

sudo custodian-claude uninstall --managed

custodian-claude doctor and custodian-claude status always report which of the two states you're actually in — never a bare "OK" for something that can't be verified.

What happens on a tool call

Claude Code proposes a tool call
        |
        v
PreToolUse hook classifies and evaluates it
        |
        +-- autonomous or previously approved --> Claude Code continues
        |         (a systemMessage notes it if it crossed an open gate)
        |
        +-- approval required --> Claude Code's native permission dialog
        |
        +-- denied --> Claude Code receives a hard block with the reason
        |
        v
Custodian appends a value-free, authenticated receipt

The hook fails closed. A malformed event, missing session identity, invalid workspace, or unexpected verdict becomes a denial — never a silent pass-through.

Open-gate notifications

Custodian ships open by default: money, credential, destructive, production, network, and governance actions run automatically rather than blocking. When one does, Claude Guard tells you — a systemMessage on the exact tool call names which open gate it walked through and how to lock it down. This is shown regardless of the allow decision, unlike the reason field Claude Code only surfaces alongside an ask/deny prompt.

custodian gates protect

turns that class of action into a required approval instead.

Operator commands

custodian-claude setup
custodian-claude doctor
custodian-claude status
custodian-claude paladin-git <host> <ref>
custodian-claude uninstall

doctor runs live synthetic probes through the real decision path (a benign call, a forbidden-path call), not just wiring checks, plus Paladin credential status. status reports hook/managed state, receipt-chain health, and a summary of recent open-gate crossings. paladin-git wires one git host's credentials to a Paladin vault ref so tokens resolve at request time instead of living in config, a URL, or argv.

Gate behavior

The shared Custodian control plane supports open monitoring and protected operation:

custodian gates status
custodian gates open
custodian gates protect
custodian gates notifications quiet

Open mode records and announces routed actions. Protected mode requires approval for configured consequential classes. Receipts remain enabled in both modes.

What this does not do

Claude Guard evaluates a call before it runs. It does not currently inspect a tool's output for a leaked secret or PII after the fact — a file that legitimately passes the forbidden-path check but happens to contain a credential is not redacted here. custodian-claude doctor discloses this explicitly. (Of the Custodian adapters, only Hermes Guard's has this today.)

Relationship to Codex Guard

Claude Guard shares its decision engine with Custodian Codex Guard — one policy pipeline, evaluated identically regardless of which harness is asking. Installing custodian-claude-guard pulls in custodian-codex-guard as a dependency for that reason, not because it installs anything Codex-specific.

Data and uninstall behavior

Removing the Python package does not delete policy, approvals, receipts, gate preferences, or vault data. Remove the hook before uninstalling:

custodian-claude uninstall            # and --managed too, if you used it
python -m pip uninstall custodian-claude-guard

Release status

This is a new package (0.1.0), not yet published. Custodian is alpha software and has not received a third-party security audit. Read SECURITY.md before using it for consequential actions.

Links

• Source
• Custodian Kernel
• Custodian Codex Guard
• Documentation
• Security policy
• Contributing