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 shows two disclosure lines: 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 stay free. 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 file, the project file, and the session. The last match wins. Narya reads permissions.toml in your Narya home only when config.toml sets permission_mode = "custom". A repository you trust contributes [[rule]] blocks through its .narya/config.toml.

​
The shipped posture

Shell commands run. Tool calls run. 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 only deny network ** turns off. The read tool refuses a .env file and reads everything else. That rule governs the read tool alone. A grep of the directory returns the file’s contents. A shell command reads it under the shell rules. A write to it 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 mark a session attended. It repeats the client’s exit prompt, and a second run changes nothing. A session recorded detached in a directory nobody trusts drops back to attended at its next gate check. The trust read fails closed.