dsh-tool-git
Structured, safe Git tool family for DeepSeek Harness (dsh).
Coding agents reach for git constantly, but the stock runtime only offers raw bash.
dsh-tool-git gives the model eight structured tools that run git through a
shell-free subprocess runner and return canonical JSON values — plus a
tools/pre-execute safety gate that stops destructive git operations
(force push, hard reset, rebase, amend, branch deletion, …) before they happen,
whether the model calls them through these tools or through a shell tool.
- No shell injection: every command goes through
execFile with an explicit
argument array. Model-supplied paths and messages are never string-interpolated.
- Machine output: porcelain v2,
--numstat, and --format records are parsed
into structured JSON, not prose.
- Safety by default: destructive operations are denied with an explanation
unless you opt into
ask (approval prompt) or allow.
Tools
| Tool | What it does |
|---|
git_status | Working tree state: branch, ahead/behind, staged / unstaged / untracked files |
git_diff | Per-file insertion/deletion stats, optional unified patch, --cached / rev bases |
git_log | Commit history: hash, author, date, subject, body; maxCount, rev range, path filter |
git_branch | Branches with upstream and ahead/behind tracking state |
git_stage | Stage explicit paths, or all / tracked-only changes |
git_commit | Create a commit with a message; returns hash and statistics |
git_stash | list / push / pop stashes, with conflict-safe pop |
git_show | One commit: metadata, per-file stats, optional patch |
git_fetch | Download refs from a remote without touching the worktree |
git_pull | Fast-forward-only by default; reports not-fast-forward / conflict outcomes |
git_remote | List configured remotes with fetch/push URLs |
git_checkout | Switch branches, or create and switch (-b); never discards changes |
Every tool accepts an optional repoDir argument and reports the resolved
repository root in its result.
Safety gate
The gate listens on tools/pre-execute and inspects every tool call:
-
The plugin's own tools — e.g. git_commit with amend: true.
-
Shell tools — bash, tool:bash, bash_persistent, terminal,
tool:terminal, pwsh — scanning their command text for destructive git
invocations such as:
push --force / --force-with-lease · push --delete · reset --hard ·
clean -f · branch -d/-D · tag -d · rebase · pull --rebase ·
commit --amend · checkout -- / checkout . / checkout -f ·
switch -f · restore (discarding worktree) · rm -r ·
update-ref -d · filter-branch
Pattern matching is per-command: it never crosses |, ;, or newline
boundaries, so git add . && git push --force is still caught but innocent
compound commands are not misread.
This is a policy guardrail, not a sandbox. An agent that can run arbitrary
code can always route around a string matcher (aliases, -c rewrites,
scripting). The gate exists to make accidental destructive calls fail loudly
with an explanation — deliberate destructive work is authorized through the
configured policy, not by bypassing the gate.
Install
npm (recommended) — from any directory:
dsh plugin --profile web add dsh-tool-git
From GitHub (or a local checkout / tarball):
dsh plugin --profile web add github:lxj808624/dsh-tool-git#v0.1.3
Then restart dsh --profile web. For GitHub installs, pnpm asks you to
allowlist the prepare build script once (see the
official packaging guide).
Configuration
All options are optional; the defaults are shown below:
# profile-level or bundle patch config for the tool-git row
- id: tool-git
name: dsh-tool-git
config:
workDir: '' # repo discovery start dir (default: process cwd)
gitPath: git # git executable
destructivePolicy: deny # deny | ask | allow
extraDestructivePatterns: [] # extra case-insensitive regexes for the gate
logMaxCommits: 20 # git_log default count (cap 100)
diffContextLines: 3 # patch context lines for git_diff / git_show
deny (default) — destructive calls are rejected with the pattern name and
an explanation.ask — destructive calls go through the runtime's approval seam
(ctx.approval); without a mounted approval service they degrade to deny.allow — the gate passes everything through.
Development
Prerequisites: Node.js ≥ 22.19 and pnpm. The project is self-contained — all
@deepseek-ai/* types resolve from the published public API (0.0.1-rc.5 line)
installed as devDependencies, so no deepseek-harness checkout is required.
pnpm install
pnpm run typecheck # tsc against the public @deepseek-ai/* API
pnpm test # vitest: boots the plugin, runs real git in temp repos
pnpm run build # tsc declarations + tsdown bundle (lib/index.mjs)
The tests create a disposable repository, register the plugin on a Cordis
context with the real dsh-tools runtime, and execute every tool through the
full pipeline (tools/pre-execute → dispatch → tools/result).
Publish
dsh.bundle.patch in package.json points at cordis.patch.yml, so
dsh plugin add activates the plugin as a profile layer.prepare runs tsdown --config tsdown.prepare.config.ts, which transpiles
src/ without project references — so GitHub installs build cleanly without
a sibling harness checkout. Prefer publishing prebuilt tarballs / npm
packages to avoid pnpm's build-script allowlist.
License
MIT
Contributors
- taonokenshin — found and fixed the
dsh-tools peer-resolution issue that crashed the host tool dispatcher on
DeepSeek Harness 0.1.0-rc.6 (#1, #2).
