git
Run version-control commands with tiered permissions: read always executes, write/destructive/network actions require approval and confirmation, and a cross-session guard prevents unsafe repository changes.
Instructions
Run git through one tiered, policy-gated tool (no shell, no agent-supplied command line). Read subcommands (status, log, diff, show, blame, shortlog, branch/tag/stash listing) always run. Write (add, commit, switch, mv, branch/tag create, stash push/pop) needs [git] allow_writes (default on). Destructive (reset, clean, checkout, restore, rebase, revert, cherry-pick, branch/tag delete, stash drop) needs allow_destructive AND confirm:true. Network (push, fetch, pull) needs allow_push AND confirm:true; force-pushing a protected branch or using an ad-hoc URL/remote is always refused.
add and commit are typed: add stages with -A semantics; commit takes message, plus an optional files list for a path-limited commit. Every other subcommand uses args.
Cross-session guard refuses a write/destructive/network op if a DIFFERENT session moved this repo's HEAD/branch since observed (override with confirm:true). expected_head pins the exact HEAD commit those ops must be at.
Full tier table, the cross-session guard, commit attribution, and the narrower plumb tool to prefer over a destructive git call: the plumb-git skill.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| args | No | Flags and arguments passed directly to git for all subcommands except add and commit. Examples: ["--oneline", "-10"] for log; ["--cached"] or ["--staged"] for diff (shows staged changes ready to commit); ["--staged"] for restore. Ignored when subcommand is "add" (use files) or "commit" (use message). | |
| repo | No | Path to any file or directory inside the repository. Omit to use the attached workspace; if no workspace is attached the call is refused (git never falls back to the daemon's working directory). To operate on a nested git submodule, set this to a path inside the submodule — git resolves to the submodule's own root, so add/commit land there; a command run against the superproject only records the submodule's commit pointer, never its file contents. | |
| files | No | Paths to act on. For subcommand "add": paths to stage (-A semantics — new, modified, and deleted entries all staged). For subcommand "commit": optional path-limited commit — commits ONLY these tracked paths (git commit -m <message> -- <files>), ignoring any unrelated staged changes already in the index; omit to commit the whole index. No glob expansion. Ignored by other subcommands. | |
| confirm | No | Required (true) for destructive and network subcommands. Also required to override the cross-session ref-movement guard: when a DIFFERENT plumb session moved this repo's HEAD/branch since this session last observed it, a write/destructive/network op is refused until re-run with confirm:true. | |
| message | No | Commit message — only used for subcommand "commit". Maps to -m; pre-commit hooks always run. Combine with files to commit only specific paths. Not used by any other subcommand. | |
| subcommand | No | Git subcommand to run. Read (always): diff, log, show, blame, status, shortlog, check-ignore, plus branch/tag/stash listing. Write (needs allow_writes, default on): add, commit, switch, mv, branch/tag create, stash push/pop. Destructive (needs allow_destructive + confirm): reset, clean, checkout, restore, rebase, revert, cherry-pick, branch/tag delete, stash drop. Network (needs allow_push + confirm): push, fetch, pull. | |
| expected_head | No | Optimistic-concurrency guard for write, destructive, and network subcommands (mirrors edit_file's expected_mtime): any git revision (full/short SHA, branch, tag) naming the commit HEAD must be at. When supplied and HEAD resolves elsewhere — or resolves to nothing — the operation is refused before running, regardless of which session (or external tool) moved it. Ignored by read subcommands only. Omit for no check. |