Summary

• Adds workspace-binding guards for gateway-initiated repo side effects.
• Blocks file writes/patches into git repos when a gateway session is unbound or bound to a different repo.
• Blocks detected mutating git terminal commands outside the authoritative workspace binding while preserving read-only git commands and non-repo scratch writes.
• Fails closed on unverifiable Git target-selection forms, including --git-dir, --work-tree, unsafe Git env vars, shell-expanded -C/cd paths, subshell cd, unsafe Git runtime config, include.path, includeIf.*.path, alias.*, and unknown git subcommands that may resolve to aliases/extensions, while allowing quoted parentheses in normal commit messages.

Scope / stacking and rebase note

This branch is stacked after #17711 so the final branch contains both normalized channel identity contextvars and workspace binding contextvars. The latest rebase/integration pass verified that HERMES_SESSION_CHANNEL_IDENTITY, HERMES_WORKSPACE_SLUG, and HERMES_WORKSPACE_REPO_PATH coexist in the session env path.

Until prerequisite context/registry work merges, this PR diff includes the earlier channel identity/workspace registry commits as well as the side-effect guard commits. After #17711 lands, this branch should be rebased again so the final diff excludes unrelated channel-identity commits.

Related reconnaissance

• Searched upstream PRs/issues for workspace registry, workspace binding, and this fork branch head.
• Related prior work found: fix(matrix): preserve named room identity #17702, feat(gateway): expose normalized channel identity #17711, feat(workspace): FTS5 foundation + pluggable indexer + agent tools #11796, feat(skills): add project-manager v2.2 — per-project context isolation #14417, feat(bind): add channel-to-repo binding for Discord gateway #4888. None implement this narrow gateway side-effect guard.

Test plan

Latest verification after the multi-invocation / alias hardening fix:

• RED check before implementation: the new regression tests failed for non-repo git mutation short-circuiting and git -c alias.* shell alias injection before the guard changes.
• python -m pytest tests/tools/test_workspace_safety.py::test_second_git_invocation_wrong_repo_is_blocked tests/tools/test_workspace_safety.py::test_allowed_first_git_then_cd_wrong_repo_git_is_blocked tests/tools/test_workspace_safety.py::test_non_repo_git_mutation_does_not_short_circuit_later_wrong_repo tests/tools/test_workspace_safety.py::test_git_config_alias_shell_fails_closed -q -o 'addopts=' → 4 passed
• python -m pytest tests/tools/test_workspace_safety.py::test_unknown_git_subcommand_alias_fails_closed_from_bound_repo -q -o 'addopts=' → failed before the unknown-subcommand fail-closed patch, then passed after implementation.
• python -m pytest tests/tools/test_workspace_safety.py tests/gateway/test_workspace_registry.py -q -o 'addopts=' → 41 passed
• python -m py_compile tools/workspace_safety.py tools/terminal_tool.py tools/file_tools.py gateway/session_context.py gateway/workspace_registry.py → passed
• git diff --check → passed
• Static added-line scan for obvious shell/secrets hazards → clean
• Independent review after the final hardening pass → passed; no security concerns or logic errors.

Earlier verification on this PR line also covered the #17711 session-env coexistence path (tests/gateway/test_session_env.py) and the Git runtime-config include hardening (include.path / includeIf.*.path).

Security / platform notes

• Credentials/secrets: no changes.
• Shell/subprocess execution: adds a pre-execution guard for detected mutating git commands in gateway sessions.
• Filesystem writes: adds a pre-write guard for file write and patch tools when targeting git repositories from gateway sessions.
• Network/API behavior: no outbound network behavior changes.
• Logging sensitive identifiers: no new logging of room IDs, tokens, private identifiers, workspace repo paths, or private repo URLs.
• Workspace repo path/URL values are session-local operational metadata for safety checks. They may appear in the session prompt/env for the active agent, but should not be logged, quoted, screenshotted, or otherwise disclosed unless the user explicitly asks.

Explicit scope / non-goals

• Guards file-tool writes/patches when the target path is inside a git repository.
• Guards all detected mutating git invocations in a shell command and only returns success after scanning the full command.
• Guards detected mutating git commands when the command targets an existing git repository.
• Fails closed on common unverifiable git target-selection forms, including --git-dir, --work-tree, unsafe Git env vars, shell-expanded -C/cd paths, subshell cd, unsafe git runtime config, include.path, includeIf.*.path, alias.*, and unknown git subcommands that may resolve to aliases/extensions.
• Allows quoted parentheses in normal git arguments such as conventional commit messages.
• Allows non-repo scratch writes and preserves non-repo scratch git behavior while continuing to inspect later git invocations in the same command.
• This is not a full shell sandbox. It handles simple cd / git -C / env-prefix forms and fails closed on common unverifiable git-targeting constructs. It does not attempt to parse or sandbox arbitrary shell programs that themselves write files.
• The guard verifies side effects targeting existing git repositories. It allows non-repo scratch work, including commands run outside a git checkout, unless existing dangerous-command approval blocks them separately.
• Does not prevent creating/cloning new repos from non-repo scratch directories.
• Non-gateway sessions and non-repo paths remain unchanged.

Review feedback remediation (2026-04-30)

Final external-review blocker remediation (2026-04-30)

• Fixed the blocker where an allowed earlier mutating git invocation could stop evaluation before later invocations in the same shell command. The guard now continues across all detected git invocations and only returns success after the loop.

• Added regressions for a wrong-repo second invocation after git add, after read-only git status plus cd, and after a non-repo scratch mutation.

• Blocked alias.* runtime Git config assignments so command-local shell aliases cannot redirect mutations to another repo.

• Added fail-closed handling for unknown git subcommands because they may resolve to repo/global aliases or extensions whose target repo cannot be verified from cwd alone.

• Updated the test plan from stale counts to the fresh 41 passed targeted workspace-safety/registry run.

• Confirmed and retained guard coverage for git -C <path> so the git invocation target repo, not only terminal cwd, is checked.

• Confirmed git fetch is treated as a repo side effect and guarded.

• Confirmed mutating git remote and git branch subcommands/flags are classified as guarded mutations while read-only forms remain allowed.

• Confirmed simple cd <path> && git ... handling so common wrong-repo command chains resolve against the changed cwd.

• Tightened fail-closed behavior for explicit --git-dir / --work-tree git invocations and malformed shell segments containing git.

• Added second-review hardening for absolute git binaries such as /usr/bin/git, unsafe Git env vars (GIT_DIR, GIT_WORK_TREE, related repo redirection vars), shell-expanded cd/git -C paths, and subshell cd ... && git ... chains.

• Added fail-closed hardening for Git config redirection: git -c core.worktree=..., inline git -ccore.worktree=..., GIT_CONFIG_* env assignments, and git --config-env core.worktree=....

• Added final fail-closed hardening for Git config includes: include.path and includeIf.*.path, because included config can set core.worktree or other target-selection config after parsing.

• Fixed the quoted-parentheses false positive so conventional commit scopes like fix(matrix): ... are allowed while unquoted subshell/grouping syntax still fails closed.

• Added regression coverage for all of the above plus the feat(gateway): expose normalized channel identity #17711 coexistence path for channel identity and workspace contextvars.

Relationship to adjacent PRs

This is the enforcement layer. It uses workspace bindings derived from gateway source/channel context to guard repo side effects.

Related:

• fix(matrix): preserve named room identity #17702 fixes Matrix room identity.
• feat(gateway): expose normalized channel identity #17711 exposes normalized channel identity.
• fix(memory): align Honcho routing and memory guidance #17186 is a related memory-routing consistency fix.