The permission layer — and the paper trail — for AI agents.

Why it exists

Yesterday’s AI failure was a bad answer: the model got something wrong, you corrected it in chat, and nothing outside the conversation changed. Today’s failure is a bad action: agents use tools. A misread no longer comes back as a wrong paragraph — it goes out as a sent email, a filed ticket, a changed record.

That’s two failures in one incident — an action nobody permitted, and a record nobody could trust — and docket is a layer against both. Before an agent acts, it checks a one-page rule file a human wrote — allow, ask, or deny — and a never written under calm conditions can’t be overridden by in-the-moment panic. After, every check and action lands on a hash-chained record, so “the agent says it rolled back” is checkable, not taken on faith. The default is the point: anything the file doesn’t grant, the agent must ask about. Unlisted means ask. Silence is never permission.

And the rules aren’t only advice. In Claude Code, docket hook claude wires the warrant into the harness itself as a PreToolUse gate — every intercepted tool call gets its allow/ask/deny from your file, whether or not the model read a word of it. Advisory for cooperative agents, mechanical where it counts.

Why I built this

I kept handing agents more of my real work — the follow-ups, the planning, the paperwork nobody loves — and noticed the deal I was actually making: every step of autonomy I granted was a step of visibility I gave up. The tools got better at acting much faster than I got better at knowing what I’d authorized. My rules lived in prompts I’d improvised at 11pm, different in every tool, enforced by hope.

Then came the incidents that wouldn’t leave me alone — a database deleted through a code freeze, an agent that read silence as a yes and sent the thing anyway. What struck me wasn’t that the agents misjudged. It’s that in each case the human had no artifact to point at. Nothing that said here is what it was allowed to do, nothing that proved here is what it did. The permission was a vibe, and the evidence was a chat scroll.

Docket is the tool I wanted on those days: the boundary written down once, calmly, in a file I can diff and commit — and a record I can hand to anyone, including my own future self, that doesn’t depend on trusting the agent’s memory or mine. It’s deliberately small. The problem isn’t that we lack platforms; it’s that the most important question in agent autonomy — what exactly was it allowed to do? — didn’t have a file format. Now it has one, and it’s short enough to read.

— Shah (@shahcolate)

Principles it won’t bend

• Allowlists, not blocklists. Permission is what you wrote down, not everything you forgot to forbid. The author doesn’t have to anticipate every failure to be protected from it.
• Degrade toward the human. Pattern matching is asymmetric by design: a phrasing difference may cause an unnecessary ask; it must never cause an accidental allow. The enforcement hook holds the same line — every failure mode gates to ask, never open.
• Consequences count from where they land. A send with a timer is still a send; a git hook or CI job planted now is not a “local change” — it executes after the session, past every approval. Actions classify by where their consequences eventually land, and the templates pre-decide the common escape vectors as hard stops.
• On the record, not on trust. Every check and every piece of finished work lands in an append-only, hash-chained log. A record that can be edited quietly is not a record.
• Humans decide; the agent never widens its own permissions. Rule changes are proposed from the record and applied only by a human keystroke — and the approval is logged too.
• Plain text you own. Loops are Markdown, the record is JSONL, both live in your repo. Assistant files are build artifacts; a model switch is a recompile, not a re-teach. Deleting docket loses you nothing but the tooling.
• No execution, no secrets, no lock-in. A loop describes and constrains work — it is not a workflow engine, and it is meant to be committed and shared.

The project

Docket is open source under the MIT license, published on npm as docket-agent, and built with zero runtime dependencies — a grammar small enough to audit is part of the security posture. It works with Claude, ChatGPT/Codex, Gemini, Cursor, OpenClaw, Hermes, and any MCP client.

The claims are red-teamed, not asserted: 10,582 checks across six suites run against the shipped templates on every CI build — real-incident scenarios, adversarial phrasing (euphemism, compound intent, injection, homoglyphs), vague-target probes, 10,000 fuzzed targets, 239 record-tampering mutations, and a live hook-gate corpus of hostile tool calls. Zero silent allows, zero fail-open outcomes, zero warranted work blocked. Reproduce it yourself with npm run eval.

Start with the homepage, read the docs or the loop file spec, and contributions are welcome via CONTRIBUTING.md.