Tenuo for Claude Code

Claude Code can read files, run shell commands, fetch URLs, and call MCP tools. Tenuo lets you write a tenuo.yaml policy for which of those calls are allowed, then checks every model-invoked tool call before it runs.

That policy is compiled into a signed, expiring credential called a warrant. A local authorizer checks each tool call against it and logs the decision. The same policy is applied no matter why the model tried the call: prompt injection, hallucination, poisoned tool output, or an unsafe request.

Start with the local quickstart below. Optional Cloud control-plane setup is in Cloud mode.

Quickstart

Requires Python 3.10+. Uses Docker if it's running; otherwise a native authorizer binary, installed automatically. On Windows, run these commands from WSL.

pip install tenuo-claude-code
mkdir my-project && cd my-project
tenuo-claude bootstrap

bootstrap writes a starter tenuo.yaml, starts the authorizer, and runs a self-test (verify). It runs non-interactively, ideal for a fresh folder. For a guided wizard with prompts, run tenuo-claude onboard instead; it's the same flow with a preflight check. The starter policy is deliberately strict:

name: my-project
sandbox: ./workspace
mode: enforce
enforce:
  Read: "subpath:{sandbox}"          # Read only files under ./workspace
  Bash: "shlex:ls,pwd,echo,date"     # Bash only these commands
default: deny                        # every other tool call is denied

Now open Claude Code in my-project/:

claude

The agent is governed: Read ./workspace/notes.txt is allowed; Read /etc/passwd, Bash(curl …), or any tool not listed is denied and logged. After Claude runs a few tools, run tenuo-claude audit to see the decisions. Edit tenuo.yaml to fit your project (see Policy), then tenuo-claude refresh.

For an example with MCP and subagents, see the reference demo.

Policy

tenuo.yaml is the whole configuration: it drives the warrant, the authorizer, the hooks, and the MCP proxy. You list tools under enforce: and give each a constraint on its key argument.

name: acme-backend
sandbox: ./workspace        # a directory; {sandbox} expands to its absolute path
ttl_seconds: 3600           # optional: session warrant lifetime (default 3600 = 1h)
mode: enforce               # block out-of-scope calls. 'dry-run' = log only, don't block

enforce:
  Read:  "subpath:{sandbox}"
  Write: "subpath:{sandbox}"
  Bash:  "shlex:ls,pwd,echo,cat,grep"
  WebFetch:
    domains: ["api.github.com", "*.githubusercontent.com"]

default: deny               # anything not listed above is denied

subagents:                  # optional: each role runs under a narrower warrant
  analyst:
    tools: [Read, Grep, Glob]

mcp:                        # optional: govern a downstream MCP server's tools
  downstream: ./your_mcp_server.py
  enforce:
    read_file: "subpath:{sandbox}"          # bare string constrains the `path` arg
    run_query:                              # constrain a differently-named arg
      arg: sql
      constraint: "regex:^SELECT "
    http_call:                              # constrain several args at once
      args:
        url:    "urlpattern:https://api.example.com/*"
        method: "oneof:GET,HEAD"

Constraints

The keys above are the tenuo.yaml DSL's convenient subset. The underlying tenuo engine supports more (set operations, numeric ranges, negation, boolean composition, and CEL expressions) for programmatic policies — see tenuo.

{sandbox} is a convenience variable for the directory in sandbox:; you can point subpath: at any path. Tools you don't list aren't governed individually; they're caught by default.

For internal egress, WebFetch also accepts cidrs: to allow hosts by IP range (e.g. cidrs: ["10.0.0.0/8"] alongside domains:). It's off by default and reaches past public domains and SSRF private-network defaults, so add it deliberately.

Command-execution tools. Bash, PowerShell, and Monitor all execute commands and are each governed independently (their own constraint on the command argument). Monitor runs the same shell commands as Bash in the background; PowerShell is a different dialect, so prefer oneof/pattern/regex over shlex (which parses POSIX syntax) for it. If your team enables PowerShell or Monitor in Claude Code, list them under enforce: too. Left unlisted they fall to default: deny and are blocked. Never put a shell in allow: — that grants it unconstrained; governed shells belong under enforce:.

MCP tool arguments. Under mcp.enforce:, a bare constraint string targets the path argument. To constrain a differently-named argument use arg: NAME + constraint:, and to constrain several at once use args: {NAME: constraint, …}. This works for any downstream MCP tool and any constraint kind, locally and on Cloud. Tools you don't list are still allowed/denied by default and can be human-approval gated (approval:); they just aren't argument-constrained.

• mode: enforce blocks denied calls. mode: dry-run computes and logs the same decisions but blocks nothing; use it to roll out a policy, then switch to enforce. (mode: audit is a deprecated alias for dry-run.)
• allow: lists extra tools permitted without constraints. Inert Claude harness tools (plan mode, TodoWrite, AskUserQuestion, …) are bundled in by default; set allow_bundled: false to opt out.
• default: is the fallback for any tool in neither enforce nor allow: deny blocks it (recommended) or approve requires human sign-off (Tenuo Cloud). There is no allow-everything fallback — enforce never fails open; use mode: dry-run to observe instead.
• subagents: declares roles; spawning is gated to those roles, and each runs under the session warrant attenuated to its tools (it can only ever do less than the session). Details.
• ttl_seconds: sets the session warrant lifetime in seconds (positive integer; default 3600 = 1h). up re-mints before expiry. Enterprise rollouts pin it centrally through Claude Code managed settings / MDM (the policy file is what managed settings pins); local dev sets it directly. A shorter TTL shrinks the blast radius of a leaked warrant.

Ready-made policies: examples/policies/. After any edit, run tenuo-claude refresh.

Commands

Day to day, you mostly need up (start), audit (review), and refresh (after editing policy).

The warrant is short-lived (1h TTL by default, configurable via ttl_seconds: in tenuo.yaml); up refreshes it. The authorizer listens on 127.0.0.1:9090; change it with TENUO_AUTHORIZER_PORT before bootstrap. Generated files (don't commit): .state/ (keys, warrant, credentials), .claude/settings.json (hooks), .mcp.json (MCP wiring).

Working from a git clone instead of PyPI? See Build from source.

How enforcement works

init compiles tenuo.yaml into a signed warrant and wires two interception points; both check the same warrant against the same local authorizer:

• Native tools (Read, Bash, WebFetch, …) → a Claude Code PreToolUse hook intercepts the call, signs a proof-of-possession with the session key, and asks the authorizer.
• MCP tools → Claude is pointed at a proxy that stands in for the downstream MCP server; the proxy authorizes, then forwards only if allowed.

The authorizer (a small local service, ~1–3 ms/call) verifies the warrant's signature, proof-of-possession, and expiry, then checks the call's arguments against the warrant's constraints → allow, deny, or (Cloud) approval-required. Full detail in docs/DETAILS.md.

Cloud mode

Local mode is enough to evaluate Tenuo on one project. Connect cloud.tenuo.ai for organization-scale governance:

• Tenant-root warrants: sessions chain to your org root, not a key on the laptop.
• Signed receipts: one verifiable allow/deny/approval audit stream (Ed25519 over CBOR).
• Fleet revocation: revoke a warrant id; authorizers pick it up within ~30s.
• Human approval gates: specific calls pause for a person instead of allow/deny (below).
• Managed rollout: push hook/MCP wiring through Claude Code managed settings instead of per-project local settings.

Setup

Two keys, kept apart; the runtime never sees the admin key:

mkdir my-project && cd my-project
tenuo-claude bootstrap --cloud      # runtime token from --connect-token/env, or prompts if missing; then sets up + verifies

Every session after that:

tenuo-claude check && tenuo-claude up

If check reports a cloud bindings failure, run tenuo-admin setup and retry.

tenuo-claude up refuses to start if a tenant-admin key is in the environment; keep it only in ~/.tenuo/admin.env. And once a project is on Cloud, don't re-run plain bootstrap: it reverts the project to local mode and moves your Cloud files aside. Use check && up.

CI / non-interactive and manual step-by-step setup: docs/DETAILS.md § Tenuo Cloud. After changing enforce/mcp/subagents/approvals on Cloud, re-run tenuo-admin setup; for mode-only changes, refresh suffices.

Human approval (Cloud)

A gated capability returns a third outcome, approval-required, instead of allow/deny. The hook opens a Cloud approval request, waits for an approver on their notification channel (Slack, Telegram, console, …), then re-authorizes with their signed, identity-bound approval — so the receipt records who approved. Add an approval: block to any enforced native tool (e.g. Bash), any mcp.enforce tool, or WebFetch; an optional exempt: lets safe argument values skip the gate. default: approve gates every unlisted tool.

Human approval requires Tenuo Cloud — anywhere (native hook, MCP proxy, or catch-all). The gate lives in the Cloud-issued warrant, so without Cloud an approval-gated tool falls back to deny (fail-closed); tenuo-claude check warns when a gate is configured but Cloud isn't. Setup and policy shape: docs/DETAILS.md § Human approval.

Security

Tenuo runs alongside Claude Code permissions; it doesn't replace managed settings. The difference is where and how policy is enforced:

Admins can also block the bypass flag entirely in managed settings (disableBypassPermissionsMode).

What's in scope. Tenuo governs model-invoked tool calls (Read, Bash, WebFetch, MCP tools, subagent spawns) on the PreToolUse path, including the agent's own Bash. The TUI ! shell (a command the operator types) is not a tool call and is out of scope; the model can't invoke it. (details)

Fail-closed. A missing or broken tenuo.yaml denies every governed call until it's restored. Keys under .state/ must be owner-only (0600).

Receipts. Every governed call carries a proof-of-possession signature the authorizer verifies. Locally, the hook appends a JSON line to .state/receipts.jsonl (read with tenuo-claude audit; in mode: dry-run, denials show as WOULD-DENY):

{"phase":"pre","decision":"deny","claude_tool":"Read","governed":true,
 "args":{"file_path":"/etc/passwd"},"reason":"Constraint not satisfied"}

Connected to Cloud, the authorizer also emits signed receipts to your tenant, the verifiable record for compliance and fleet audit.

Rolling out to a team. Keep tenuo.yaml in version control, push the hook/MCP wiring through Claude Code managed settings (not per-developer settings.local.json), and use Cloud for org-root warrants, central audit, and revocation. Start in mode: dry-run, review the WOULD-DENY rows, then switch to enforce. Talk to us about managed-settings rollout. Report issues: SECURITY.md.

Build from source

For development, running the demo from a checkout, or using ./bin/tenuo-claude:

git clone https://github.com/tenuo-ai/claude-governance.git
cd claude-governance
uv venv && uv sync && source .venv/bin/activate     # Windows: .venv\Scripts\activate
chmod +x bin/tenuo-claude
uv run tenuo-claude install-authorizer              # only if you don't use Docker

Run via ./bin/tenuo-claude --help, uv run tenuo-claude --help, or pip install -e .. Re-run tenuo-claude init (or refresh) after moving the repo or reinstalling. The hooks pin the launcher path at wiring time. Contributors: CONTRIBUTING.md.

Performance

Authorization is ~1–3 ms per call; the command hook adds ~100–200 ms (mostly process startup). Measure on your machine with tenuo-claude bench after up.

This repo

GitHub: tenuo-ai/claude-governance · PyPI: tenuo-claude-code