A generated Git executable wrapper receives parsed arguments from normal Bash calls, command git, env git, xargs git, nested Bash, and unqualified child-process PATH lookup.
The first Bash call creates it with fixed Node and Git paths; later calls and reloads reuse it.
It rejects hook-skipping --no-verify options, including accepted abbreviations, short commit -n, and non-shell alias chains.
It resets the editor environment immediately before invoking real Git and delegates ordinary commands unchanged.
Bash git() and git.exe() functions route direct calls to that wrapper, while narrow preflight checks cover simple literal bypasses.
Windows paths are converted for Git Bash, and common git.exe shell forms route through the wrapper.
The layers are defense in depth, not a security boundary; unrestricted Bash can still address or construct alternate executable paths.
On Windows, a non-Bash child process that explicitly launches git.exe can bypass the script wrapper because the extension does not ship a native PE launcher.
git_clone_safe clones a repository with checks around hook execution,
symlinks, LFS filters, disk use, and credential prompts.
Operational behavior:
rejects root, home, paths with depth less than 2, exact /tmp, /var,
/etc, /usr, and paths starting with /sys or /proc
refuses an existing target dir unless it contains .pi-git-safe
removes and replaces prior .pi-git-safe clone dirs
recovers marked clone dirs on demand by checking ancestors of each read
path
wraps text read results from tracked clone dirs in <untrusted_external_data marker="..."> markers with a git-specific warning preamble
warns when .git/config contains include or includeIf
warns when symlinks are present; core.symlinks=false stores them as text
files
Markdown source
# git-safeHardened git clone tool for Pi.
## Install / loadLoaded through the root `pi-ext` package.
See [root README](../../README.md).
## Commands / tools / settings- Commands:
none
- Tools:
- `git_clone_safe(url, path, branch?, sparse?)`
- `url`:
Git repository URL
- `path`:
local target directory, absolute or relative to cwd
- `branch`:
optional branch name
- `sparse`:
optional repository-relative sparse checkout paths
- Hooks:
- `session_start`
- `session_shutdown`
- `tool_call` for agent-issued `bash`
- `tool_result` for `read`
- Settings:
none
## BehaviorAgent-issued Bash commands receive noninteractive Git editor settings:
- `GIT_EDITOR=true`
- `GIT_SEQUENCE_EDITOR=true`
- `GIT_MERGE_AUTOEDIT=no`
A generated Git executable wrapper receives parsed arguments from normal Bash calls, `command git`, `env git`, `xargs git`, nested Bash, and unqualified child-process PATH lookup.
The first Bash call creates it with fixed Node and Git paths; later calls and reloads reuse it.
It rejects hook-skipping `--no-verify` options, including accepted abbreviations, short `commit -n`, and non-shell alias chains.
It resets the editor environment immediately before invoking real Git and delegates ordinary commands unchanged.
Bash `git()` and `git.exe()` functions route direct calls to that wrapper, while narrow preflight checks cover simple literal bypasses.
Windows paths are converted for Git Bash, and common `git.exe` shell forms route through the wrapper.
The layers are defense in depth, not a security boundary; unrestricted Bash can still address or construct alternate executable paths.
On Windows, a non-Bash child process that explicitly launches `git.exe` can bypass the script wrapper because the extension does not ship a native PE launcher.
`git_clone_safe` clones a repository with checks around hook execution,
symlinks, LFS filters, disk use, and credential prompts.
Operational behavior:
- rejects root, home, paths with depth less than 2, exact `/tmp`, `/var`,
`/etc`, `/usr`, and paths starting with `/sys` or `/proc`
- refuses an existing target dir unless it contains `.pi-git-safe`
- removes and replaces prior `.pi-git-safe` clone dirs
- runs `git clone --no-checkout --depth 1 --single-branch -c
core.symlinks=false`
- passes `--branch` when `branch` is provided
- when `sparse` paths are provided, adds `--filter=blob:none` and `--sparse`
to clone args
- rejects unsafe sparse paths: empty paths, absolute paths, `.`, `..`,
traversal, and null bytes
- disables credential prompts with `GIT_TERMINAL_PROMPT=0` and
`GIT_TERMINAL_PROMPT_AUTOCHECK=0`
- sets repo-local `core.hooksPath` to an empty hooks dir
- sets repo-local `lfs.skipSmudge=true`
- writes `.git/info/attributes` with `* -filter`
- removes `.git/hooks`
- estimates checkout size with `git ls-tree -r -l HEAD`
- rejects content over 500 MB
- rejects trees over 10,000 files
- scans `git ls-files -s` for symlinks before checkout
- checks out with the empty hooks dir enforced
- kills clone after 60s and checkout after 30s
- writes `.pi-git-safe` marker after successful checkout
- returns canonical clone path, URL, optional branch, file count, total byte
count, symlink count, symlink paths, warnings, and optional sparse paths
- recovers marked clone dirs on demand by checking ancestors of each `read`
path
- wraps text `read` results from tracked clone dirs in `<untrusted_external_data
marker="...">` markers with a git-specific warning preamble
- warns when `.git/config` contains `include` or `includeIf`
- warns when symlinks are present; `core.symlinks=false` stores them as text
files