[potiuk]

Summary

Follow-up to #1814. It was merged at its third commit, so the fixes from its review round never reached main:

• ensure waits on the wrong signal. The gateway takes its pid lock before it discovers backends, probes egress and binds its sockets. Waiting on status's running therefore lets the triggering docker / podman command race the bind, the race the wait exists to prevent. ensure now waits for status to report a serving backend (serving non-empty).
• No-backend stall. With Docker or Podman stopped, the gateway logs "no backend" and exits, so running never became true and every container command polled for the full five seconds. The wait now ends once the gateway has come up and gone again, or never came up within the first second.
• FIFO hang. Settings files were opened after only a -r test. A FIFO planted by sandboxed code where a settings file would be (in a subdirectory the agent cds into, which Claude Code does not write-protect) blocked jq until the 30 s hook timeout, before every container command. A settings path that exists but is not a regular file now refuses the start without being opened.
• if filters miss commands. Bash(docker *) / Bash(podman *) cannot match docker-compose, podman-compose or /usr/local/bin/docker. The documented PreToolUse wiring drops them; the script's own check leaves within about 10 ms for any other command.
• Docs:
  • The spec's sample wiring uses absolute per-machine paths. A ~ there is expanded from $HOME, which the setup guide already rules out.
  • The agent-isolation README no longer says the hook uses an .apache-magpie/ snapshot. It never does.

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

• New tests in tools/agent-isolation/tests/test_container_gateway_hook.py, run for real (not dry-run) against a fake gateway package:
  • a serving gateway is left alone (one status call);
  • a slow one is waited for until it serves;
  • the wait stops within a second or so when the gateway dies or never starts.
• A FIFO in place of a settings file refuses without blocking.
• Three of the new tests fail against main's hook.
• uv run pytest tests/test_container_gateway_hook.py in tools/agent-isolation: all 118 pass, outside the sandbox.
• Live on macOS with Docker Desktop:
  • with the gateway stopped, ensure for docker-compose ps brought it up and serving in 0.63 s;
  • ensure for ls exited in 8 ms;
  • a sandboxed docker run succeeded straight after.
• prek run --all-files passes locally
• prek run --all-files in CI

RFC-AI-0004 compliance

• Sandbox — no new host access. The hook runs the same trust checks before executing anything; it now also refuses rather than blocks on a non-regular settings file.

Linked issues

Follows #1814.

Notes for reviewers (optional)

These came from the second reads on #1814: codex via adversarial-review, and an independent review. Neither found a sandbox escape. A microseconds-wide pid-file race in the gateway (probe_pid_lock unlocks before it unlinks) predates both PRs and is left for a separate change.

🤖 Generated with Claude Code