paratia

paratia exists because a deny list is a list of paths somebody thought of, and an agent runs as your own user, holding your read bit on every file you own: a path left off the list, or reached by a command it was not written to catch, is just as readable as everything else. It answers two separate problems: keeping a secret out of an agent’s reach at all, and stopping a restriction that holds for one agent from being laundered through a second agent it is bridged to, since restrictions are enforced per agent while capabilities compose across the pair.

What it does not do

• It does not hide secrets by hiding their path. Secrets live encrypted in an AES-256 sparsebundle; the passphrase is in your head and in no file, and unlock refuses to run inside an agent session.
• It is not a lock and it inspects nothing at the file level. paratia gate, the PreToolUse hook, asks the kernel one coarse question, whether the volume is mounted, and denies every tool call while it is. It does not look at which path a command names.
• On a Mac with one account it cannot be tamper-proof, only tamper-evident: there is no file an agent running as you cannot rewrite, including the hook itself. paratia attest reports whether it changed since it was sealed; it does not prevent the change.
• An open zone does not stop the session. The gate ignores zone mountpoints on purpose, because an agent that cannot read the repository cannot work on it.
• Losing the passphrase loses the contents. That is stated as the mechanism, not as a caveat: nothing outside your memory can open the compartment.

Install

pip install git+https://github.com/nerln/paratia.git
paratia doctor

Or, if you also want the hooks and the scripts under strumenti/:

git clone https://github.com/nerln/paratia.git ~/dev/paratia
ln -s ~/dev/paratia/paratia.py ~/.local/bin/paratia
paratia doctor

Python 3.11 or newer, macOS, no third-party packages. pip install gives you the command only; the hooks are not placed by pip and are wired into ~/.claude by hand. First, in your own terminal, never in an agent session:

paratia init

The passphrase is asked once and stored nowhere

paratia init asks for a passphrase twice and writes it to no file. There is no recovery path: losing it loses everything the compartment holds. That property, not a bug, is what makes the compartment something an agent running as you cannot open.

Then add the hook to ~/.claude/settings.json under PreToolUse with matcher *, pointing at hooks/paratia-gate.py, and seal it:

paratia unlock && paratia seal ~/dev/paratia/hooks/paratia-gate.py ~/.claude/settings.json && paratia lock

Use

paratia unlock            # your terminal, asks for the passphrase, auto-locks in 15 min
paratia put OPENAI_KEY    # value typed, not echoed, never on a command line
paratia ls
paratia lock
paratia attest            # did anything that enforces this change since you sealed it?

A verb lets an agent use a key it cannot read, declared in verbi.json inside the open compartment:

{
  "deploy": {"comando": ["curl", "-sS", "-H", "Authorization: Bearer <OPENAI_KEY>", "{}"]}
}

<NAME> is replaced by the stored secret, {} by whatever the agent passed; paratia broker deploy <url> runs it without the key ever appearing in the transcript.

How it works

The gate does not read a path. It reads the mounted state of the compartment volume and, while it is mounted, denies every agent tool call for that reason alone. The same hook also reads the transcript written by the harness, finds who actually spoke last, and if that is another agent rather than you, takes a further set of tools, computer use, the browser, the simulator, sudo, off the table for the turn: the composite of two agents bridged together should not have a capability neither had enforced against alone.

python3 tests/test_gate.py runs sixteen cases against a fake mountpoint and a synthetic transcript, including a base64’d path, a compound command hiding behind an allowed one, and a tool result that must not be mistaken for the human retaking the turn.

paratia on GitHub, GPL-3.0 licensed.