[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)

[potiuk]

Approving. The hint pattern matches the body the gateway actually sends (policy_shape.py builds it as container-gateway: <reason>; see <catalog anchor>), the 502 case stays silent, and the troubleshooting entry reads well. Today's volume-driver refusal reaches the agent through the same 403 body, so it gets the hint too.

I pushed one merge commit to your branch (479de3a):

• merged main, which had moved the stamped files, and re-stamped FRAMEWORK_FINGERPRINT in isolated_fingerprint.py with the hook — that was the only conflict;
• docs/setup/secure-agent-setup.md: the lead-in to the hint table now says seven classes of failure (it said five, with six rows before your new one).

---

This review was drafted by an AI-assisted tool and
confirmed by an Apache Magpie maintainer. The maintainer
approving this PR has read the findings and signed off. If
something feels off, please reply on the PR and a maintainer
will follow up.

More on how Apache Magpie handles maintainer review:
Contributing guide.