potiuk opened a new pull request, #293:
URL: https://github.com/apache/airflow-steward/pull/293
## Summary
New PostToolUse hook
[`tools/agent-isolation/sandbox-error-hint.sh`](tools/agent-isolation/sandbox-error-hint.sh)
that runs after every Bash tool call, pattern-matches the result
for the three known sandbox-shaped error signatures catalogued in
[#291's
`docs/setup/sandbox-troubleshooting.md`](docs/setup/sandbox-troubleshooting.md),
and prints a `[sandbox-hint] …` line pointing at the matching
catalog entry.
Closes the discoverability loop on the catalog: the user no
longer has to remember the catalog exists when a mid-flow
failure looks sandbox-shaped — the catalog reference appears
next to the error automatically.
### How the three discoverability surfaces work together
| Surface | When it fires | What it does |
|---|---|---|
| [Catalog](docs/setup/sandbox-troubleshooting.md) (#291, merged) |
Reference resource | Single source of truth: symptom → root cause →
settings.json fix per failure mode. |
| [Doctor skill](.claude/skills/setup-isolated-setup-doctor/SKILL.md) (#292,
open) | User-invoked | Live probes against all three failure modes; reports
✓/✗/⊘ per probe, links each ✗ back to the catalog. |
| **Hint hook (this PR)** | After every Bash call, automatically |
Pattern-matches tool output for the catalog's failure-mode signatures; prints
`[sandbox-hint] …` annotation when matched. |
The three together form a *catalog → on-demand diagnostic →
just-in-time annotation* loop. New failure modes land in the
catalog first; the doctor skill and the hint hook then grow a
matching probe / pattern in the same change.
### The three pattern matches
| Signature in tool stderr/stdout | Catalog anchor |
|---|---|
| `Could not open a connection to your authentication agent`, `agent refused
operation`, `ssh-add: error fetching identities`, `Permission denied
(publickey)` | [SSH agent / Yubikey
unreachable](docs/setup/sandbox-troubleshooting.md#ssh-agent--yubikey-appears-unreachable-from-inside-the-sandbox)
|
| `Cannot connect to the Docker daemon`, `open /var/run/docker.sock:
operation not permitted`, `Cannot connect to Podman`, podman `connect:
permission denied` | [Docker / Podman socket
denied](docs/setup/sandbox-troubleshooting.md#docker--podman-command-fails-with-a-socket-error)
|
| `127.0.0.1 … [Pp]ermission denied`, `[Oo]peration not permitted … bind`,
`Errno 49 … assign requested address`, `Connection refused … 127.0.0.1` |
[Localhost port-bind
blocked](docs/setup/sandbox-troubleshooting.md#test-cannot-bind-to-a-localhost-port)
|
Each hint also nudges the user to run
`/setup-isolated-setup-doctor` for a structured probe of all
three failure modes.
### Fail-open by design
The hook exits 0 silently when:
- The tool isn't `Bash` (the signatures are Bash-stderr-shaped).
- `tool_response` is missing or has an unexpected shape.
- `jq` isn't installed.
- The JSON envelope is malformed.
- No signature matches.
A broken hint must never break a legitimate tool call. Cost: a
future Claude Code hook-schema change can silently stop the
hook from firing; re-run the verification snippet in
`secure-agent-setup.md` after every Claude Code upgrade.
### Files touched
| File | What |
|---|---|
| `tools/agent-isolation/sandbox-error-hint.sh` (new) | The script. ~120
lines. Same shape as `sandbox-bypass-warn.sh`. |
| `tools/agent-isolation/README.md` | New table row for the script +
relationship to the doctor skill (#292). |
| `docs/setup/secure-agent-setup.md` | New "Sandbox-error hint hook" section
between the existing "Sandbox-bypass visibility hook" and "Sandbox-state status
line" sections — install / verify / trade-offs in the same shape. Quick-start
step 4 and sync-repo table updated to include the new hook. |
| `docs/setup/sandbox-troubleshooting.md` | Short intro section explaining
the two discoverability surfaces (doctor + hook) and the lock-step rule. |
| `.claude/skills/setup-isolated-setup-verify/SKILL.md` | Checks 2 + 3
updated to include the new hook script + its `PostToolUse` wiring. ⚠ (not ✗) on
absence — the hook is a discoverability aid, not a security guard. |
The install skill (`setup-isolated-setup-install`) needs no edit
— it defers the install walkthrough to `secure-agent-setup.md`,
and the doc's quick-start + the new section together cover the
new hook's install steps.
### Sequencing
This is **PR-3 of 3** addressing sandbox friction:
- **PR-1 (#291, merged)** — `docs/setup/sandbox-troubleshooting.md`
catalog + cross-links.
- **PR-2 (#292, open)** — `setup-isolated-setup-doctor` skill:
structured probe of all three failure modes.
- **PR-3 (this PR)** — `sandbox-error-hint.sh` hook: just-in-time
annotation of sandbox-shaped tool output.
Cross-references in this PR's docs that point at the doctor
skill will resolve once #292 merges. The hook itself works
independently of #292.
## Test plan
- [x] `bash -n tools/agent-isolation/sandbox-error-hint.sh` —
shell syntax OK.
- [x] Smoke-tested six envelope shapes locally against the
script:
- SSH-signature stderr → hint fires, rc=1, anchor correct.
- Docker-signature stderr → hint fires, rc=1, anchor correct.
- Loopback-signature stderr → hint fires, rc=1, anchor correct.
- Benign Bash stderr → no output, rc=0.
- Non-Bash tool (`Read`) → no output, rc=0.
- Malformed JSON → no output, rc=0.
- [x] `prek run --files <all-touched-files>` — markdownlint /
doctoc / typos / skill-validate / placeholder all pass.
- [ ] After install on a fresh machine: a real `git push` that
fails due to missing SSH agent reachability surfaces the
`[sandbox-hint] SSH agent / Yubikey appears unreachable …`
line automatically.
- [ ] After install: a real `docker info` that fails due to
socket denial surfaces the docker hint.
- [ ] After install: a real test that fails due to loopback
block surfaces the loopback hint.
- [ ] Pattern set robustness on Linux (the patterns are written
primarily against macOS Seatbelt; bubblewrap may produce
slightly different stderr signatures). Refine the regex set
as real data comes in.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
