feat(tools): block git mutations of the running source checkout

[erosika]

Problem

In a source/editable install, changing Hermes's own checkout underneath the live interpreter can mix module versions: already-imported modules stay old while later imports load new code. The resulting failures surface well after the Git command and can discard a completed turn.

The observed failure happened after the agent checked out a PR branch in its running source repo. At turn end, the lazy finalize_turn import loaded the branch version under the old caller and raised a signature TypeError.

Fix

Live source-checkout guard

Local terminal commands now hard-block Git operations that can rewrite the checkout backing the running process. The guard:

• uses the existing quote-aware approval scanner rather than splitting raw shell text;
• resolves the session's actual cwd, git -C, GIT_WORK_TREE/--work-tree, cd chains, wrappers, nested shells, and Git aliases;
• catches gh pr checkout and hub pr checkout as well as direct Git commands;
• keeps subshell/pipeline cwd isolated and distinguishes executable shell heredocs from heredocs used as data;
• remains inert for packaged installs and remote/sandboxed backends.

Read-only and non-worktree operations remain available, including normal status/log/diff workflows, commits, fetch/push, worktree creation, soft/mixed reset, staged-only restore, stash metadata operations, and clean dry-runs. The block cannot be bypassed with force=True; approval cannot make an in-process code swap safe.

Scope: this is a guardrail against the agent accidentally rewriting its own code, not a security boundary. A determined adversarial command can construct shell text the scanner cannot statically resolve; the failure mode it targets — and the one observed — is the model reaching for a plain git checkout/gh pr checkout in the wrong repo, and the block message redirects it to git worktree add or a temp clone.

Shared scanner improvement

tools/approval.py's _iter_shell_command_starts now recurses into nested $( ) and backtick command substitutions instead of only recording the outermost start. The guard reuses this scanner, and existing dangerous-pattern detection benefits from the same nested coverage. No pattern or approval-flow behavior changes otherwise; covered by the approval-parser suite.

Stable turn finalization

finalize_turn is bound when agent.conversation_loop loads instead of being imported for the first time after the agent loop. An out-of-band source change (e.g. the user running git pull in a separate shell mid-session, which no command guard can see) can therefore no longer load a skewed finalizer at the persistence seam.

Validation

• 85 self-repo guard and terminal wiring tests
• 311 approval-parser tests
• 104 terminal cwd/approval and gateway lifecycle tests
• 28 turn-finalizer tests
• Ruff and ty clean for the changed guard code

[tonydwb]

Code Review Summary

Verdict: Approved (read-only token — formal approval requires write access)

Blocks git mutations (checkout, pull, branch, stash, etc.) when the running source checkout is detected. Prevents accidental corruption of the running hermes-agent installation.

• New tools/self_repo_guard.py module with path resolution and git command detection
• Hoists the finalize_turn import to module level to avoid stale-module reads after git operations
• Good test coverage in tests/tools/test_self_repo_guard.py
• No security issues found

---

Reviewed by Hermes Agent