[shahar1]

Summary

• A sandboxed agent in an Apache Airflow checkout ran breeze. The container gateway correctly refused BuildKit POST /grpc and label-checked an untyped docker inspect of the CI image, but the agent never saw why: breeze captures docker inspect output, and buildx prints only unable to upgrade to h2c, received 403. It then routed around the gateway by building a host virtualenv, which the project forbids.
• sandbox-error-hint.sh gains a branch for gateway policy refusals: the gateway's 403 body (container-gateway: …; see docs/setup/sandbox-troubleshooting.md…) and the bare unable to upgrade to h2c, received 403. The hint says the request was refused by policy, points at the deny lines in container-gateway.log, and tells the agent to report to the user instead of routing around it. Gateway 502 backend errors don't match.
• The "403 container-gateway" troubleshooting entry now lists the workflows that can never pass the gateway: BuildKit sessions, bind-mounting the gateway socket, and untyped docker inspect, with breeze as the example. It also says that excludedCommands doesn't get past the gateway and what the agent should do.

Type of change

• Skill change (.claude/skills/<name>/) — eval fixtures updated below
• Tool / bridge contract (tools/<system>/*.md)
• Python package (tools/*/ with pyproject.toml)
• Groovy reference impl
• Cross-cutting (RFC, AGENTS.md, sandbox, privacy-LLM)
• Documentation (docs/, README.md, CONTRIBUTING.md)
• Project template (projects/_template/)
• CI / dev loop (prek, workflows, validators)
• Other:

Test plan

• prek run --from-ref upstream/main --to-ref HEAD passes, including markdownlint, lychee, isolated-setup-fingerprint (re-stamped by the hook) and workspace pytest. prek run lychee --all-files passes too.
• tools/agent-isolation/tests/test_sandbox_error_hint.py: 23 passed. Both new positive cases exit 0 under the pre-change hook and 1 with it. The 502 negative case stays silent.
• Not run: shellcheck (not installed; bash -n OK), the sandbox-lint CLI, and anything against a live gateway or Docker daemon.
• Seen once, unrelated: test_gpg_touch_overlay.py::test_signing_in_flight_matches_the_whole_process_name failed under -n auto and passes alone. It looks like a system-wide pgrep racing a parallel ssh-keygen.

RFC-AI-0004 compliance

• Sandbox — no gateway, policy or sandbox settings change. The hook only adds a note to the tool result and never allows or blocks anything.
• Vendor neutrality — breeze appears only as an example of a tool that hits the refusals.

Linked issues

Refs apache/airflow#75599 (the Airflow-side AGENTS.md change: stop and report when breeze can't run).

Notes for reviewers (optional)

Considered and left out:

• BuildKit support in the gateway. It needs an h2c/protobuf inspector and a privileged builder.
• A 404 instead of 403 for missing or foreign containers. It would reverse the no-detection decision in relay.py and still not unblock breeze.

Known stale counts not touched here: "Five classes of failure" in secure-agent-setup.md, the hook header comment, and tools/agent-isolation/README.md "four known … signatures".

Generated-by: Claude Code (Opus 5.5, Sonnet 5.5)