Skip to main content
Narya checks one gate in front of every tool call. Two things decide the answer: whether you trust the directory, and what the rules say.

​
The trust question

The client asks Trust this repository? one round trip after it opens. It asks only when the directory carries something governed: an instruction file, a resource directory, or a .narya/config.toml. The question names what reaches the model and what runs on this machine. You have four answers:
  • y trusts this folder.
  • p trusts this folder and its parent. The host computes the parent, so no client can widen the scope past what it showed you.
  • n is a durable no.
  • esc continues untrusted. Narya stores nothing and asks again at the next launch.
Narya stores one row per canonical path. A lookup walks up the tree, and the nearest trusted or refused ancestor decides. Type /trust to reopen the question.

​
What trust unlocks

Trust decides which rule set runs. A directory nobody trusts runs under a stricter set, and only where a person can answer. A one-shot run keeps the shipped set. Reads inside the directory stay free, and reads outside it ask. Shell, write, network and tool actions ask. Trust swaps in the shipped set. Trust also gates the repository’s own material: its instruction files, its .claude/settings.json hooks, and its .claude and .narya commands, skills and agents. Narya ignores all of it in an untrusted repository, in any mode.

​
How a rule reads

A rule is a TOML table with three keys.
Five actions exist, and no more: shell, read, write, network and tool. The action decides what Narya matches. A path glob matches read and write. Command text matches shell, after Narya decomposes the line into the commands it really runs. A host matches network. A tool name matches tool. Three effects exist: allow, ask and deny. There is no ordinal field. Position in the file is the precedence. Narya concatenates four scopes in this order: its shipped set, your global rules, the project rules, and the session. The last match wins. An answer you remember becomes a rule: a global one for everywhere, or a project one for this repository. A repository you trust also contributes project rules through the [[rule]] blocks of its .narya/config.toml. Set permission_mode = "custom" in config.toml to replace the shipped set with permissions.toml in your Narya home.

​
The shipped posture

Shell commands run. Tool calls run. Reads inside the session’s directory run, and reads outside it ask. More than forty shell rules ask first, among them rm -r, sudo, git push --force, chmod, dd and kill -9. Writes inside the repository run, and writes outside it ask. Network actions ask, except the supplier’s own web search, which deny network ** turns off. The read tool refuses .env files, such as prod.env and .env.local, and reads .env.example inside the directory. These rules govern the read tool alone. A grep of the directory returns their contents. A shell command reads them under the shell rules. A write to one is allowed. Narya judges a shell line on the strictest verdict across everything it really runs. A line Narya cannot parse asks, and Narya remembers nothing from it.
A non-interactive run turns every ask into a recorded refusal. It never hangs. narya -p always runs in that mode.

​
Audit

Narya writes one row per ask and per refusal that belongs to a session, including refusals that reached no person. A refusal outside a session, or a row the store fails to write, leaves no row. The refusal still stands. Each row carries:
  • the action and the resource
  • which rules matched, and what a remembered allow would grant
  • the status and who decided
  • the reason
  • the scope of the answer
Rule-derived allows carry no row. Read the rows back with narya permissions denied. Add --session <id>, --since <time> or --until <time> to narrow the range. One page holds 100 rows, and Narya says so when it truncates. Retention is opt-in per class and keeps everything by default. The [retention] permission_asks setting sweeps decided rows and keeps the pending ones.

​
Attended and detached sessions

Every session records a posture, attended or detached. A detached session refuses and records the next prompt rather than blocking forever. Run narya session promote <session-id> to hand a session to the host as detached. A second run changes nothing. The host refuses it in a directory nobody trusts. A session recorded detached in a directory nobody trusts drops back to attended at its next gate check. The trust read fails closed.