Summary

Fixes #16703. When users configure TERMINAL_ENV=docker and bind-mount /var/run/docker.sock to drive the host's Docker daemon from inside our container ("docker-out-of-docker" / DooD), the supervised hermes user (UID 10000) lacks permission to talk to the socket. Every docker invocation EACCES'es and check_terminal_requirements() returns False.

In messaging-platform mode this has a strictly worse failure mode than the issue title suggests (surfaced by @osheari1 in the issue comments): tools/__init__.py's _check_file_reqs() delegates to check_terminal_requirements(), so when the docker probe fails the entire file toolset (read_file/write_file/patch/search_files/terminal) is silently dropped from the registered tool schema, and the model confidently rationalizes the gaps as a Discord/Telegram sandboxing restriction. model_tools._tool_defs_cache then memoizes that bad result for the rest of the gateway process lifetime.

Why the obvious workaround doesn't work

The "just tell users to docker run --group-add <socket-gid>" answer is broken on our image. s6-setuidgid (and gosu, the older shim) calls initgroups() for the target user, which rebuilds the supplementary group list from /etc/group. Without a matching /etc/group entry, the kernel-granted supp group is wiped between PID 1 and the dropped hermes process. Verified empirically against the published image:

--group-add 998 alone:        PID 1 has Groups: 0 998
                              after s6-setuidgid hermes: Groups: 10000   ← 998 gone
With this fix's /etc/group:   id hermes shows 998
                              after s6-setuidgid hermes: Groups: 998 10000   ← survives

The asymmetry hides the bug from people debugging it: docker exec --user hermes doesn't run initgroups(), so an interactive shell shows the group correctly while the supervised agent process has it wiped.

Fix

In docker/stage2-hook.sh (runs as root before the privilege drop), after the existing UID/GID remap:

1. stat -c '%g' the bind-mounted /var/run/docker.sock (or /run/docker.sock)
2. If a group with that GID already exists in /etc/group, reuse its name; otherwise groupadd -g <gid> hostdocker
3. usermod -aG <group> hermes

Idempotent across container restarts. Silent no-op when no socket is mounted. Non-fatal warnings under rootless containers where groupadd/usermod can fail.

Deliberately a NO-OP on the toolset-stripping side: if the user has explicitly selected terminal.backend: docker and we still can't reach the daemon for some other reason, we must surface that as a failure, not silently fall back to a different backend (per maintainer guidance).

Test plan (all run end-to-end against a freshly-built image and the real host Docker daemon, host socket GID 959)

Stage2 hook output on a successful first boot:

[stage2] Created group hostdocker (GID 959) for Docker socket
[stage2] Added hermes to group hostdocker (GID 959) for /var/run/docker.sock

And the actual Python probe inside the running supervised container:

$ docker exec -e TERMINAL_ENV=docker <cid> /command/s6-setuidgid hermes \
    /opt/hermes/.venv/bin/python -c \
    'from tools.terminal_tool import check_terminal_requirements; \
     print(check_terminal_requirements())'
True

Out of scope (intentional, see issue thread)

• Toolset-stripping side of the bug (_check_file_reqs → entire file toolset disappears with no log line) — not addressed here because it crosses into tools/__init__.py + model_tools.py (cross-lane) and the user has explicitly directed that we never silently fall back from the docker backend to a different one. Worth a follow-up to at least surface the EACCES in logs without changing the fallback behavior, but separate PR.
• Documentation update — the existing website/docs/user-guide/docker.md already says "bind-mount /var/run/docker.sock to opt in"; with this fix that's now sufficient and no further user-facing setup is required.

Fixes #16703