Skip to content

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:

  1. permissions.deny matches → silent, so the native deny applies
  2. sensitive path touched → silent (disclosure, an axis dippy does not model)
  3. execution-redirecting assignment → silent (PATH=, LD_PRELOAD=, BASH_ENV=, …)
  4. nothing left to judge → grant
  5. dippy classifies → allow / deny / fall through
  6. binary dippy does not know → grant if every segment is that binary or inert plumbing
  7. 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 export rows 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 upgrade changes 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 to permissions.allow would re-grant exactly what dippy just refused.
  • ai-grep needs a separate absolute-path entry because it is not on PATH. Basename matching was rejected: it would let any file named lb anywhere 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 endswith assertion.
  • 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.py already 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 keep baseline.sh runnable.
  • 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.