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

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).