Metadata-Version: 2.4
Name: custodian-claude-guard
Version: 0.1.0
Summary: Fail-closed Custodian policy guard for Claude Code, with unstrippable managed-hook enforcement
Author-email: InovinLabs <hello@inovinlabs.com>
License-Expression: MIT
Project-URL: Homepage, https://getcustodian.xyz
Project-URL: Repository, https://github.com/KeyArgo/custodian-claude-guard
Project-URL: Documentation, https://getcustodian.xyz/docs
Project-URL: Issues, https://github.com/KeyArgo/custodian-claude-guard/issues
Project-URL: Security, https://github.com/KeyArgo/custodian-claude-guard/blob/main/SECURITY.md
Keywords: claude,claude-code,guard,policy,agent,custodian
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: custodian-kernel<0.5,>=0.4.3
Dynamic: license-file

# 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:

```bash
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:

```bash
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:

```bash
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

```text
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.

```bash
custodian gates protect
```

turns that class of action into a required approval instead.

## Operator commands

```bash
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:

```bash
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](https://github.com/KeyArgo/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:

```bash
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](SECURITY.md) before using it for consequential actions.

## Links

- [Source](https://github.com/KeyArgo/custodian-claude-guard)
- [Custodian Kernel](https://github.com/KeyArgo/custodian-kernel)
- [Custodian Codex Guard](https://github.com/KeyArgo/custodian-codex-guard)
- [Documentation](https://getcustodian.xyz/docs)
- [Security policy](SECURITY.md)
- [Contributing](CONTRIBUTING.md)
