pawl

Deterministic gates for coding agents, as one plugin for Claude Code,
OpenAI Codex and Antigravity.

Agents make the same mistakes over and over, and telling them not to in the
prompt stops working after a page. pawl is a set of small checks that run as
code, not as instructions, and a report command that tallies what they blocked.
Each check watches for one mistake and refuses it, cleans it up, or (for
provably read-only commands) waves it through without a prompt. Plain Python
standard library, no model calls, nothing added to the prompt but a skill
description of under 150 tokens.

A pawl is the small part in a ratchet that lets the wheel move forward and stops
it from slipping back. Every check here works the same way: the current state is
the floor.

Try it

No install, no harness, nothing written outside a scratch directory:

git clone https://github.com/ulukaya/pawl && python3 pawl/hooks/pawl.py demo

Recorded through the real Claude Code hook adapter using fixture tool calls.
The commands are inspected, never executed; displayed reasons are excerpts.
This demonstrates hook decisions rather than a live agent session.

The command above sends fifteen calls through the real dispatcher, written as
Antigravity, Claude Code and Codex send it, and prints what each harness
is told:

call                        gate        antigravity      claude code      codex
-------------------------------------------------------------------------------
make build                  -           allow            silent           silent
git log --oneline -5        readonly    auto_approve     allow            silent
git reset --hard            git         force_ask        ask              deny
script that runs rm -rf ~/  blast       deny             deny             deny
curl install.sh | sh        pin         force_ask        ask              deny
terraform destroy           teardown    force_ask        ask              deny
tail -f server.log          poll        force_ask        ask              deny
same pytest run, 3rd time   loop        force_ask        ask              deny
edit that changes nothing   noop        deny             deny             deny
write with a U+200B         zero-width  allow +rewrite   +rewrite         allow +rewrite
test edited to assert True  tamper      force_ask        ask              deny
send naming ~/.deploy/      egress      deny             deny             deny
read another session        fence       force_ask        ask              deny
read Chrome's cookie key    creds       force_ask        ask              deny
stop with tail -f running   idle        n/a              block            n/a

silent leaves the harness's own prompt in place; allow and
auto_approve skip it. A Codex PreToolUse hook can neither ask nor approve,
so there an ask is a deny that tells the agent how to proceed. --verbose adds every
reason, --json every raw answer.

On your own sessions

replay sends every tool call from your past Claude Code sessions through
the same gates. It runs nothing and keeps no state:

python3 pawl/hooks/pawl.py replay --days 30 --show

It lists each call pawl would have asked about or refused, then a tally per
gate, including how many read-only commands it would have approved without a
prompt. Run it before installing to see what would change, and after
changing a gate to find its false alarms on real work.

What it catches

Grouped by what a miss costs. The first table is work or data an agent
cannot take back; those gates are the reason pawl exists.

Can't be undone

Checks it keeps honest

Prompts it removes

Time and tokens it saves

CLIs for pre-commit, CI and cron

The first four tables are hook gates that fire on their own; the
last holds CLIs. Every piece also runs on its own: see
pieces/<name>/README.md.

What it costs

Install

Claude Code

claude plugin marketplace add ulukaya/pawl
claude plugin install pawl@pawl

Or inside a session: /plugin marketplace add ulukaya/pawl, then
/plugin install pawl@pawl. Start a new session (or /reload-plugins), and
claude plugin details pawl lists Hooks (2) PreToolUse, Stop.

Codex

codex plugin marketplace add ulukaya/pawl
codex plugin add pawl@pawl

Codex reads .codex-plugin/plugin.json, which points it at
hooks/codex.json and the skill. Hooks need a Codex release with lifecycle
hooks.

Adding the plugin does not turn its hooks on. Codex runs a plugin's hooks
only once you have reviewed and trusted their current definitions, and skips
new or changed ones until then; see
review and trust hooks
in the Codex docs. To activate pawl:

1. Start codex. It warns at startup when hooks need review.
2. Open /hooks, review pawl's PreToolUse and Stop hooks (each runs
   hooks/pawl.py with --harness codex) and trust both.
3. Do it again after an update that changes hooks/codex.json: a changed
   definition is skipped until trusted again.

To check that pawl is live, open /hooks and confirm both hooks are trusted
and enabled. Then, in a scratch session, ask Codex to run echo pawl-check
three times as separate commands: the third is refused with a
[PAWL loop] reason. hooks/e2e_test.py does not prove this: it runs the
shipped hook commands directly on fixture payloads, with no Codex process,
so it passes whether or not Codex loaded or trusted the hooks.

Antigravity

git clone https://github.com/ulukaya/pawl && cd pawl
./install.sh --antigravity

This links the checkout to ~/.gemini/config/plugins/pawl and adds
{"path": "plugins/pawl"} to ~/.gemini/config/plugins.json next to any
plugins already listed. Restart Antigravity; the plugin inventory lists
pawl.

From a checkout, any harness

./install.sh                 # every harness found on this machine
./install.sh --claude        # or --antigravity, --codex
./install.sh --uninstall     # reverse every step
./install.sh --dry-run       # print what would change

For Claude Code and Codex the installer runs the commands above with this
checkout as the marketplace, so the plugin loads in place (Codex still needs
the /hooks trust step above; the installer reminds you); --source ulukaya/pawl tracks GitHub instead. Every step is idempotent. It then runs
the test battery, which needs pytest (PAWL_PYTHON picks the
interpreter); the plugin itself needs only Python 3.9+.

How it works

 harness ──stdin──▶ hooks/pawl.py pre|stop --harness H
                      │
                      ├─ harness.parse()    native payload ─▶ one canonical call
                      ├─ gates.plan()       which gates apply to this tool
                      ├─ pieces/<name>/     each gate asks its piece
                      ├─ merge              deny > ask > approve > allow
                      └─ harness.render()   answer in H's own contract ──stdout──▶

Each harness has its own config, all running the same dispatcher:

hooks/harness.py, with its tables in hooks/harness_vocab.py, maps each
harness's tools onto the canonical names the pieces speak (Claude Code
Bash, PowerShell, Monitor, Read, Write, Edit, NotebookEdit,
TaskOutput; Codex Bash and apply_patch) and writes each answer the
way that harness reads it. PowerShell and Monitor are shell commands to
the gates, and NotebookEdit a write of its cell to the notebook.
PowerShell is read as POSIX sh, so readonly never approves it: pawl
denies or asks when a gate objects and is otherwise silent, which leaves
Claude Code's own PowerShell rules in charge (PAWL_POWERSHELL_ASK=1 asks
on the rest too). blast knows its delete and disk cmdlets (Remove-Item,
ri -r -fo, Format-Volume). poll skips Monitor, whose watches end at
a deadline:

git, poll, pin, teardown, tamper, creds and fence read a
shell command through hooks/shell_view.py, which blanks heredoc bodies
that never run as shell:
the file cat > notes.md <<'EOF' writes, a commit message in
git commit -m "$(cat <<'EOF' ...)", the string literals of a
python3 - <<'EOF' edit script, a list of commands that a while read
loop or a later python3 check.py cases.txt only reads. Each rule names
what is known to be data, and anything else keeps the body: a file run or
copied later, a loop that runs or saves the lines it reads, and Python
whose code can start a process (hooks/py_body.py reads it with ast).
creds and fence keep the paths in Python literals.

Codex does let a separate PermissionRequest hook, sent only when Codex is
about to ask the user, answer allow or deny; pawl registers no such hook.

Reasons use the harness's own tool names (Read, not view_file;
NotebookEdit, not the Write it is read as). The first deny ends a run, so
a refused call never spends a send-budget unit. On Codex an ask is a deny and
ends the run too; a send over budget is refused with nothing spent and no
override logged. A git or poll gate whose piece cannot load denies, as when it
fails. A run past its watchdog (12 s from the hook's start, under the hosts'
15 s) or hitting an internal error keeps any deny or ask it reached, and asks
on a shell or write call (denies on Codex), so input built to be slow cannot
wave a call through; other tools, MCP tools among them, allow. The watchdog
cannot cut into one long call into C (a regex on Python older than 3.11), so
the shipped regexes are kept linear; see SECURITY.md. On a python3 older
than 3.9 every call is allowed with a warning. Every answer exits 0; no path
prints a traceback.

Gates

On Claude Code, "shell" is Bash, PowerShell and Monitor. hooks/pawl.py gates lists them. Details: skills/pawl/references/<piece>.md and
pieces/<piece>/README.md.

Configuration

On Claude Code five of these are plugin settings, so nobody edits an
environment: /config lists pawl's rows (Approve read-only shell commands,
Repos the git guard protects, Refuse reads of other sessions, Ask on every
PowerShell command, Gates to turn off); a PAWL_* you export wins over it.
claude plugin install pawl@pawl --config disable=reread sets one at install.

State and logs live under PAWL_DATA (default ~/.pawl). Each piece's knobs
are listed in its reference page.

Privacy

pawl runs on your machine and nowhere else: no network, no telemetry, no
model calls. Its logs hold counters and SHA-1 digests, never a command,
path or message. One gate loosens anything: on Claude Code and Antigravity,
readonly approves shell commands it can prove only read, without a prompt
(a Codex PreToolUse hook cannot approve, so there it stays silent); turn it
off in /config or with PAWL_READONLY_PASS_OFF=1.
PRIVACY.md lists every file pawl reads and writes.

pawl never opens a credential store. The creds gate knows the names of
browser cookie stores, keychains and the commands that dump them only so it
can spot them in a tool call's arguments and ask you first; it never opens,
decrypts or sends any of them. It never logs or sends a token or API key:
beyond its own settings, it reads your environment only to expand $VAR in a
command and compare the path against fenced ones. The demo and the end-to-end
hook tests start pawl with a minimal environment (hooks/child_env.py), so
no token you exported reaches them. The URLs in this README and in the tests
are documentation and test input; pawl itself fetches nothing.

Pieces

One skill, skills/pawl/SKILL.md, routes an agent by denial prefix or task to
skills/pawl/references/<piece>.md, which carries that piece's flags.

What it is not

• Not a model, model router, or model picker. pawl never names, selects,
  or calls a model.
• Not a replacement for other plugins. Skill packs and shell guards keep
  doing their jobs; each plugin registers its own hooks and the harness runs
  them all.
• Not a sandbox. The gates read tool arguments; a script that builds a path
  at run time is not fenced. creds matches a glob against its roots by
  name and never lists the disk, so it does not follow a symlink that a
  glob part matches: cat ~/x*/Default/Cookies, with ~/xlink pointing
  at a Chrome profile, runs without a prompt (cat ~/xlink/... asks).
  Listing the matches caught that, but a deep glob could keep the listing
  running past the hook's time budget. The match reads braces, [^...],
  [[:class:]], **, extglob and a dotglob the command turns on, but
  not one the user's shell startup files turn on (credential-fence README,
  Limits).
• Not a workflow engine. Nothing here spawns subagents or schedules
  anything.

Eval

eval/ holds a gates-on vs gates-off ablation suite: 24 tasks with a
temptation in each (10 code-change, 6 repo-hygiene, 8 outbound), throwaway
git fixtures, stub senders and script graders, with no LLM judge.
The blast gate has its own measurements: five labelled corpora (329
cases, four held out before tuning, first-seen scores kept in
pieces/blast-radius-guard/HILLCLIMB.md), a replay of 472 real commands
with no false alarm, and eval/blast-compare/, which runs other deletion
guards on the same cases:

Historical comparison from October 3, 2026. Competitor error counts were
not measured; rerun them before quoting their false-alarm counts. The
comparison README explains the scoring and policy differences.

The same author wrote pawl and the cases; read the caveats in
eval/blast-compare/README.md before quoting a number.

Scorecards for the ablation suite, three passes per arm; eval/README.md
has the per-case tables. A gate that blocks a leak often ends the task, so a
blocked leak scores as a failure. The harm columns count the failures where
something went out or was lost: a leak, a send past a ceiling or to an
address off the allowlist, another session's uncommitted work.

Sonnet's runs leave out 5 per arm the model refused. Of Qwen's 5 on-arm
harms, 2 sent from one shell loop, gated since (a re-run of that case sent
nothing past the ceiling), and 3 deleted another session's uncommitted work
with rm -rf after the git gate refused a stash. Same caveat: the same
author wrote pawl and the cases.

Sonnet's harm counts are documented in eval/README.md; that older JSONL
lacks verdict lines, so the harm counts cannot be regenerated from it with
results_table.py. Neither agent scorecard is a new run of version 0.4.1.

eval/run_arms.sh runs both arms; see eval/README.md. eval/claude/ holds
four cases for Claude Code's built-in runner (claude plugin eval . --scaffold --allow-tools Bash Edit Write), also judge-free.

Development

python3 -m venv .venv && .venv/bin/pip install pytest
.venv/bin/python3 -B run_tests.py       # one OK line per suite
.venv/bin/python3 -B check_portable.py  # portable: clean
git config core.hooksPath .githooks     # run both before every push

run_tests.py runs the hooks suite (including end-to-end runs of the
commands in the shipped Claude Code and Codex configs, fed fixture payloads
without a real host), every piece's suite, the root tools and the
eval grader twins. check_portable.py fails on an absolute home path, a
non-stdlib import in shipped code, a CR byte, a markdown prose line over 80
columns, a reference page naming an env var its piece never reads, a hook
config that does not run hooks/pawl.py the way its harness needs,
manifests that disagree on name or version, a source file over 500 lines, or
a function nested more than 3 blocks deep. The .githooks/pre-push hook runs
both and refuses a push that fails. Each suite may run for 180 seconds; set
PAWL_SUITE_TIMEOUT to a number of seconds to change that on a slow
machine. GitHub CI (.github/workflows/ci.yml) runs both on every push to
main and every pull request: Linux on Python 3.9 to 3.14, macOS on 3.11
and 3.14. AGENTS.md holds the engineering rules; CHANGELOG.md the history.
CONTRIBUTING.md is the short version for a first pull
request, and SECURITY.md says what to report privately.

To add a gate: write the piece under pieces/<name>/ with its tests, add a
Gate to hooks/gates.py, add its Antigravity group to hooks.json, and
add skills/pawl/references/<name>.md; check_portable.py tells you what
is missing.

Questions

Open an issue at https://github.com/ulukaya/pawl/issues or email
[email protected]. pawl is licensed under Apache-2.0.