Skip to content
Docs menu

Project trust

Decide whether a project's own hooks, MCP servers, allow rules and loosening settings may run, from the TUI dialog or headless with venom trust.

View .md

A repository you clone can carry config that runs code or loosens the rules: Claude Code hooks, .mcp.json servers, allow rules, a permissive mode. Venom ignores all of that until you trust the project. Config that only tightens (ask and deny rules, plan mode) applies untrusted, with nothing to confirm.

Quick start

The first time you start venom in such a project, the TUI shows a trust dialog listing what trusting would turn on and what would run. Without the TUI:

venom trust                    # show what trusting this directory turns on, then ask "Trust <dir>? [y/N]"
venom trust ../api --yes       # no terminal: --yes is required
venom trust --list             # saved decisions and what each trust covers
venom trust --revoke           # forget the decision for this directory; venom asks again
venom -a -p "run the tests"    # trust for this one run only (--approve)
venom --no-approve             # ignore project config for this run

What trust turns on

From Untrusted Trusted
.claude/settings.json, .claude/settings.local.json hooks don't run run
.mcp.json servers, inline MCP servers in project agent files don't start start (subject to the organisation policy's MCP allowlist)
Allow rules in .venom/permissions.json, .claude/settings*.json, the project's venom.yaml ignored apply
A mode past default, Claude's defaultMode ignored applies
"sandbox": false, added sandbox hosts ignored (the network can only narrow) apply
Settings env, additionalDirectories ignored apply
.venom/settings.json, .venom/mcp.json, .venom/extensions/ ignored load
Project-scoped secrets not used used
Ask rules, deny rules, plan mode apply apply

The dialog and venom trust show each item, including the allow rules themselves (2 allow rules from .venom/permissions.json: bash(go test:*), bash(go vet:*)), and under "What would run" each hook command and MCP server command line or URL. Every string from the project is shown with control characters, bidi overrides and invisible characters written out, so a file name can't hide or reorder what you read.

Trust is tied to content

With each "yes", venom records a SHA-256 of every item the trust covered in ~/.venom/trust-content.json (0600, hashes only; a hook command can carry a token). When a trusted project later gains a hook, an MCP server, an allow rule or another loosening item, the trust is suspended until you confirm again:

  • the TUI shows the trust dialog headed "New since you trusted:";
  • print and json mode print once Project config changed since you trusted it … Run venom trust …;
  • venom trust prints the difference and asks; --yes confirms;
  • venom doctor reports the trust as suspended and why.

Removing items needs nothing. A repository cloned into a folder you trusted as a whole (~/work) asks once for itself.

Where decisions are stored

The decision lives in pi's trust store, ~/.venom/agent/trust.json, the same file the TUI dialog and pi's /trust write. It is keyed by the real path and covers the directory and everything below it; the nearest entry wins. "Don't trust" is remembered too: the dialog isn't shown again, and each session says once what it ignored.

A home directory, or one above it, is refused unless you name it (venom trust ~), because that trusts every project below.

Reference

Flag What it does
venom trust [path] Trust the directory (default: the current one) after showing what it turns on
--yes, -y Trust without asking. Required when stdin is not a terminal
--revoke [path] Remove the saved decision for the path, trusted or declined
--list Print saved decisions and what each trust covers
Exit code Meaning
0 trusted, or already trusted
1 declined; no terminal and no --yes; still trusted through a parent (--revoke); config changed while asking
2 usage error, not a directory, or an unnamed home directory

Troubleshooting

  • "not trusted: stdin is not a terminal". Run venom trust --yes in scripts and CI.
  • --revoke exits 1 naming another path. A parent directory's entry still trusts this one. Revoke that path.
  • Hooks stopped running after a pull. The pull added a loosening item; run venom trust to review and confirm.