One Bash grant authority, replacing three that could not see each other¶
- Date: 2026-08-25
- Status: Accepted
- Tags:
tooling
Context¶
Bash permissions were decided by three independent grant authorities with no knowledge of
each other: native permissions.allow prefix matching, chain-aware-allow.py, and dippy.
They were composed by hook ordering and a || in a shell command, so the effective decision
order existed nowhere in writing.
The composition let the bluntest rule silence the sharpest judgement. Bash(aws *) matched
every AWS command, so chain-aware-allow.py granted, so dippy was never consulted — even
though dippy correctly separates describe-alarms from terminate-instances. Measured on
the live stack before any change:
silent | aws iam delete-user --user-name admin
silent | aws ec2 terminate-instances --instance-ids i-123
silent | aws s3 rm s3://prod-bucket/ --recursive
silent | cat ~/.ssh/id_rsa
silent | echo hi > /etc/passwd
silent | git push --force origin main
PROMPT | export AWS_PROFILE=knox-east AWS_REGION=us-east-1
The prompts and the risk were uncorrelated. Setting an environment variable cost a confirmation; deleting an IAM user did not. Prompt fatigue and genuine exposure came from the same defect, so tuning either one in isolation would have made the other worse.
Decision¶
A single ~/.claude/hooks/bash-arbiter.py is the sole Bash grant authority, and its
decision order is stated in one place:
permissions.denymatches → silent, so the native deny applies- sensitive path touched → silent (disclosure, an axis dippy does not model)
- execution-redirecting assignment → silent (
PATH=,LD_PRELOAD=,BASH_ENV=, …) - nothing left to judge → grant
- dippy classifies → allow / deny / fall through
- binary dippy does not know → grant if every segment is that binary or inert plumbing
- otherwise → silent
chain-aware-allow.py and the || dippy shell glue are removed. terraform-scope-guard.py
and enforce-pbcopy-spacing.py are untouched — they only ever deny, so they compose safely.
permissions.allow drops from 66 Bash rules to 5; permissions.deny grows from 5 to 13.
Silence means "no opinion" and the normal prompt happens. That is the failure direction: a
bug in the arbiter costs a prompt, never an unreviewed mutation. The arbiter never emits
ask, because a hook ask does not override permissions.allow and would be
indistinguishable from silence while looking like it did something.
Alternatives Considered¶
| Option | Why Rejected |
|---|---|
| Tune the existing three authorities | The defect is the composition, not any one rule. Nothing readable states the order, so every fix is a guess about what the other two will do. |
Delete permissions.allow and rely on dippy alone |
dippy has no opinion on lb, tflint, pre-commit, vault-search, mempalace, ai-grep — every invocation would prompt, which is the friction this removes. |
| Keep prefix rules, add deny rules for the dangerous forms | Works where the dangerous space is enumerable (git push --force*) and is kept for exactly those. It does not generalise: aws has thousands of subcommands and no flag distinguishes them. |
| Re-probe dippy per segment when a chain is unknown | Built in round 1, deleted in round 2 for cause. Segmentation drops operator characters, so it asked dippy about a string the user never typed and honoured the more permissive answer. A guard was tried and blocked none of the laundering it was written for. |
Consequences¶
Positive:
- The decision order is readable in one file instead of emerging from four hook entries.
- Prompts now correlate with risk: 7 previously-silent mutating commands prompt, 1 is denied,
and the two
exportrows that always prompted are silent. - dippy is consulted on every command rather than being short-circuited by a prefix rule.
Negative / Trade-offs:
- dippy is now a hard dependency of the grant path, pinned at 0.2.7. A
brew upgradechanges classification independently of anything in this repo. - The long-tail set (
UNKNOWN_TO_DIPPY) is hardcoded. A new local tool prompts until it is added — deliberately, since falling back topermissions.allowwould re-grant exactly what dippy just refused. ai-grepneeds a separate absolute-path entry because it is not onPATH. Basename matching was rejected: it would let any file namedlbanywhere on disk inherit the grant.
Ongoing obligations:
- Never restore the per-segment dippy re-probe. The one sound way to give dippy a smaller
input is a byte-identical contiguous suffix, enforced by an explicit
endswithassertion. - Prefer positive allowlists over denylists of known-bad shapes. Six plan defects and one
post-ship Critical were all denylists beaten by something unenumerated — the same lesson
terraform-scope-guard.pyalready records ("beaten 20 times out of 21"). - The rollback point at
~/.claude/backups/2026-08-24-pre-arbiter/is what makes reverting provable rather than assumed. Do not delete it, and keepbaseline.shrunnable. - A review of this file found two Criticals in code that had passed mutation testing, a 49-row acceptance suite and 199 vectors. Test-suite green is not evidence here — the suite and the code share an author and encoded the same wrong assumption. Future rounds want an independent reviewer.
ADRs are immutable. If this decision changes, create a new ADR with status "Superseded by" pointing here, and update this record's status.