---
title: Project trust
description: 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.
section: security
order: 30
audience: [user, operator, agent]
sources: [cli/src/trust.ts, cli/src/trust-text.ts, packages/harness/src/permissions/config.ts, cli/AGENTS.md]
features: [security.trust]
---

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

```bash
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 {#scope}

| 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](/docs/security/policy.md)'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](/docs/security/secrets.md) | 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 {#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 {#storage}

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 {#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 {#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.

## Related {#related}

- [Permission modes and rules](/docs/security/permissions.md#sources): which rule sources need trust.
- [The plugins section](/docs/plugins.md): hooks and MCP servers.
