Skip to content

feat(vetted-ops): run SSH push and worktree moves without leaving them to the user - #2161

Merged
potiuk merged 12 commits into
apache:mainfrom
potiuk:vetted-ops-git-operations
Nov 18, 2026
Merged

potiuk merged 12 commits into
apache:mainfrom
potiuk:vetted-ops-git-operations

Conversation

@potiuk

@potiuk potiuk commented Nov 17, 2026 •

Copy link
Copy Markdown
Member

Summary

  • A sandboxed agent cannot push over SSH (the proxy carries no TCP for it, and a hardware key's touch prompt never reaches the user), and cannot write a linked worktree's administrative directory it did not create. Each of those steps ended in a command the user pasted into their own terminal, or in a sandbox bypass.
  • New entry point vetted-op-git runs exactly those steps as closed shapes, outside the sandbox and behind the same ask confirmation as vetted-op, bounded by the approved policy's new [git] table:
    • git-push-branch: a push to the policy's fork or upstream repository, with --force-with-lease on the full SHA the caller expects (or new). Built-in protected branches are refused, and upstream accepts only the upstream_push globs.
    • git-worktree-sync, git-worktree-add, git-worktree-remove: move, create or remove a clean linked worktree (reset --keep, never --force).
  • A push never runs a hook: --no-verify always, and the pre-push checks run inside the sandbox before it. A pre-push hook is code the agent can write, and the confirmation shows the push, not what the hook would run.
  • Wired into expected.json, .claude/settings.json, sandbox-lint, the agent-guard spelling guard, the Codex rules, the touch-overlay matcher and the secure-setup docs.

What keeps git safe to run unsandboxed, all in tools/vetted-ops/src/vetted_ops/git_ops.py:

  • Repository configuration. Every key outside a short list of inert ones is refused (SAFE_LOCAL_KEY; a remote name may not look like a URL). This is checked in every working tree git runs in, and again right before the acting command.
  • Pinned on every call:
    • core.fsmonitor, gc and maintenance off;
    • only https and ssh transports (protocol.allow=never plus GIT_ALLOW_PROTOCOL);
    • core.sshCommand set to the user's global value;
    • GIT_ATTR_SOURCE set to the empty tree (git 2.42+ required);
    • --no-follow-tags on push;
    • hooks off, and --no-verify on push.
  • Environment. GIT_* is dropped, HOME comes from the password database and XDG_CONFIG_HOME is dropped.
  • Directories. Validated directories are opened without following a symlink, and git runs inside them by descriptor. A linked worktree must be registered with the checkout, and its validated git directory is passed explicitly, so its agent-writable .git file is never read again. A new worktree is created through its root's descriptor.
  • Final re-check. Right before the acting command, the worktree's common and own git directory are asked for again and must match the validated ones (a linked worktree's commondir file can be rewritten in between).
  • Unapproved policy. A dry run against a policy that is not an approved copy checks the parameters and runs no git command.

Type of change

  • Python package (tools/*/ with pyproject.toml)
  • Cross-cutting (RFC, AGENTS.md, sandbox, privacy-LLM)
  • Documentation (docs/, README.md, CONTRIBUTING.md)

Test plan

  • tools/vetted-ops: 61 new tests in tests/test_git_ops.py. They run against real repositories in a temp directory, with bare repositories standing in for the forge. Every guard above has a test that fails without it, including a root swapped for a symlink mid-operation, a repointed .git file, a rewritten commondir, a planted filter, core.sshCommand, url.*.insteadOf, a pre-push hook that must not run, and a dry run against an unapproved policy that must not start git.
  • ruff check, ruff format --check and mypy pass for tools/vetted-ops.
  • sandbox-lint passes on the new .claude/settings.json against the new expected.json. The old settings fail only on the four missing vetted-op-git entries.
  • agent-guard tests pass, as do the touch-overlay matcher tests for both launcher forms.
  • The full prek run --all-files and the rest of the vetted-ops, sandbox-lint and overlay suites were run in a sandboxed session. That sandbox denies writes to .apache-magpie-overrides/tools/vetted-ops and .claude/** paths and blocks pgrep, so the tests that create those paths fail there before and after this change. CI runs them.

RFC-AI-0004 compliance

  • HITL: both dispatcher spellings are in permissions.ask and never in allow, and sandbox-lint enforces the pairing.
  • Sandbox: this removes the reason for a bypass. The unsandboxed surface is four closed shapes, with destinations taken from the approved policy, and no repository code runs in it.

Notes for reviewers (optional)

  • Pre-push hooks. An earlier revision ran the pre-push hook by default. It no longer does: that hook was the one place agent-writable code ran outside the sandbox. Callers run prek run --hook-stage pre-push in the sandbox first.
  • Residual race. Git finds a repository's .git and its config by name. Identity and config are re-checked right before the acting command, but closing the last instant relies on the harness keeping the git directory write-protected, as Claude Code's sandbox does for .git/config and .git/worktrees. /dev/fd/N as --git-dir does not work on macOS git.
  • Admin directory name. A new worktree is added as . from inside its own directory, so git names its administrative directory - (-1, …).

Was generative AI tooling used to co-author this PR?
  • Yes — Claude Code (Claude Opus 5)

Generated-by: Claude Code (Claude Opus 5)

🤖 Generated with Claude Code

https://claude.ai/code/session_01NyQq9U7i5HhjDgrQ9qd3gq

@potiuk
potiuk force-pushed the vetted-ops-git-operations branch from 7993e8e to 22a4373 Compare November 18, 2026 01:08
@potiuk
potiuk enabled auto-merge (squash) November 18, 2026 01:09
@github-actions github-actions Bot added family:setup setup-* skills family:tools tools/* family:docs Docs, MISSION.md, READMEs capability:platform Framework / agent substrate skills (install, verify, doctor, override, status, setup bootstrap) substrate:sandbox Tool substrate: agent isolation, egress control, settings audit substrate:action-guard Tool substrate: deterministic pre-tool-use command guards family:dev Repo dev: .asf.yaml, spec-loop specs, Node manifests, .claude/settings.json labels Nov 18, 2026
@potiuk
potiuk force-pushed the vetted-ops-git-operations branch from 22a4373 to 6cb35c3 Compare November 18, 2026 03:03
@potiuk
potiuk disabled auto-merge November 18, 2026 03:09
…m to the user

A sandboxed session cannot push over SSH (the proxy gives it no TCP, and a
hardware key's touch prompt never reaches the user) and cannot write the
administrative directory of a linked worktree it did not create. Each of those
steps ended in a command the user had to paste into their own terminal, or in a
sandbox bypass, which is the wider and worse door.

vetted-op-git runs exactly those steps as closed shapes behind the same
confirmation as vetted-op, bounded by the approved policy's [git] table: a
leased push to the policy's fork or upstream repository, and adding, moving or
removing a clean linked worktree. Repository configuration and GIT_*
environment that could steer git are refused or dropped. The push keeps the
user's pre-push checks; skipping them is an explicit parameter for a hook that
cannot run in this environment.

Generated-by: Claude Opus 5
…before the git command acts

The config check ran once, in one working tree, before several more git calls.
A linked worktree's commands also read the main checkout's worktree config, and
a key added between the check and the final command would have taken effect.

Generated-by: Claude Opus 5
…t calls

The repository check alone left gaps outside the sandbox: a .gitattributes
could switch on a globally configured filter during a checkout, the caller's
HOME or XDG_CONFIG_HOME could stand in a different global config, a key added
right after the check could still take effect, and push.followTags would
publish tags beside the one ref. The same pins the local tracker's git uses now
apply here.

Generated-by: Claude Opus 5
…quire git 2.42

A remote named exactly like the push URL would have applied its own pushurl
to the push, and a git older than 2.42 ignores GIT_ATTR_SOURCE, so attributes
could still switch on a filter. A failing pre-push hook's explanation on
stdout was also dropped from the error.

Generated-by: Claude Opus 5
…scriptor

A directory the agent can write, such as a worktree root inside the checkout,
could be swapped for a symlink between the checks and the command, sending
git to write a new worktree somewhere outside the sandbox. A per-protocol
setting in the repository could also override protocol.allow.

Generated-by: Claude Opus 5
… git directory

A copy of the main checkout whose .git file points at the main git directory
passed as a linked worktree, so worktree-sync could reset the main branch
through it. Git also finds .git by name, so the checkout's git directory could
be swapped between validation and the command.

Generated-by: Claude Opus 5
…ectory

A linked worktree's .git file lives in the tree the agent can write, so it
could be repointed after validation; git is now told the validated directory
instead of reading that file. The checkout's .git is also looked up by name
again before acting, so a swapped parent directory shows. And the touch
overlay did not recognise a vetted-op-git push, so a push waiting for a key
touch showed no window.

Generated-by: Claude Opus 5
…ed-op-git

agent-guard's empty-rebase guard stops a plain force-push of a branch with no
commits over its base, because that push closes the pull request it heads.
A push through vetted-op-git did not pass that guard.

Generated-by: Claude Opus 5
The vetted-op-git permissions in .claude/settings.json and the agent-guard
change are inputs to the secure-setup fingerprint, so the constant in
setup_preflight needs regenerating (prek's isolated-setup-fingerprint hook).

Generated-by: Claude Opus 5
…unapproved dry runs

Three gaps in vetted-op-git, each a way to run or steer code outside the
sandbox:

- git-push-branch drops its hooks parameter and always pushes with
  --no-verify. A pre-push hook (.git/hooks/pre-push, or a hook manager
  reading its config from the working tree) is code the agent can write,
  and the confirmation shows the push, not what the hook executes. The
  pre-push checks run in the sandbox before the push instead.
- The final check before the command re-reads the worktree's common and
  own git directory and refuses if either moved since validation: a
  linked worktree's commondir file can be rewritten in between.
- A dry run against a policy that is not an approved copy validates the
  parameters and runs no git command at all.

Generated-by: Claude Opus 5
@potiuk
potiuk force-pushed the vetted-ops-git-operations branch from 3beed20 to 0d9ea56 Compare November 18, 2026 05:06
…t holds

Git.anchor ignored a passed descriptor when the path already had one,
and that descriptor was never closed. It now takes ownership: a passed
descriptor is kept until Git.close, or closed at once when the path is
already anchored. Tests cover both cases.

Generated-by: Claude Opus 5
@potiuk
potiuk merged commit 226ca2d into apache:main Nov 18, 2026
5 checks passed
def test_anchor_closes_a_passed_descriptor_for_a_path_it_already_holds(git: Git, tmp_path: Path) -> None:
path = Path(os.path.realpath(tmp_path))
first = git.anchor(path)
second = os.open(path, os.O_RDONLY | os.O_DIRECTORY)

def test_anchor_keeps_a_passed_descriptor_for_a_new_path_until_close(git: Git, tmp_path: Path) -> None:
path = Path(os.path.realpath(tmp_path))
fd = os.open(path, os.O_RDONLY | os.O_DIRECTORY)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

capability:platform Framework / agent substrate skills (install, verify, doctor, override, status, setup bootstrap) family:dev Repo dev: .asf.yaml, spec-loop specs, Node manifests, .claude/settings.json family:docs Docs, MISSION.md, READMEs family:setup setup-* skills family:tools tools/* substrate:action-guard Tool substrate: deterministic pre-tool-use command guards substrate:sandbox Tool substrate: agent isolation, egress control, settings audit

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants