dsh-zcode-git
English | 中文
First-class Git tools for DeepSeek Harness agents.
DeepSeek Harness ships no git tooling, so an agent drives git through bash.
This plugin registers six structured tools instead, and fixes the three things
that makes bash a bad fit:
Problem with bash | What this plugin does |
|---|
Output shape follows the user's config (color.ui, core.pager, core.quotepath, diff.external, status.relativePaths, aliases) | Pins every one of those settings per invocation and parses porcelain / NUL / %x1f formats |
git commit -m "..." must survive cmd.exe, PowerShell, and POSIX sh — each with different escaping, and none of them preserving %PATH%, $(...), or a newline by accident | Builds an argv array: no shell ever sees an argument |
In bash, git status and git push --force are equally privileged | Splits reading from mutating, and routes mutations through the harness approval service |
Requirements
- DeepSeek Harness
>=0.1.5-rc.2 <0.1.6-0 || >=0.1.6-alpha.1 <0.2.0-0 — the same range is declared in engines.dsh
- Node
>=20, which the harness's own bundled runtime satisfies
- A
git binary on PATH
Install
dsh plugin --profile web add dsh-zcode-git
The bundle declares its own patch, so the profile's bundles list is updated
automatically. Restart Harness afterwards — bundle-layer changes are read at
boot.
To mount it by hand instead:
# cordis.patch.yml
- insert:
- id: tool-git
name: dsh-zcode-git
Tools
| Tool | Kind | What it does |
|---|
git_status | read | Branch, upstream, ahead/behind, and the staged / modified / conflicted / untracked / ignored lists |
git_diff | read | Per-file line counts plus the unified diff, scoped by paths, staged, or contextLines |
git_log | read | Commits as {hash, shortHash, author, date, subject}, bounded by limit, narrowable by paths or revision |
git_branch | read + write | list / create / switch / delete; mutations are approved |
git_commit | write | Optionally stages paths, then commits message; approved |
git_stash | read + write | list / push / pop / apply / drop; mutations are approved |
Every tool takes an optional path selecting the repository; it defaults to
the session working directory, and a relative value resolves against it.
Status codes
git_status renders git's own two-column code — index state, then worktree
state — so .M is an unstaged edit and M. is a staged one. The words are
also returned as fields (index, worktree) for callers that prefer them.
Safety
No shell, ever. Every invocation goes through ctx.subprocess.spawn with
an argv array. The harness's other seam, ctx.shell, takes a single command
line; using it would push every argument back through a shell parser. There is
no escaping routine that is correct for cmd.exe, PowerShell, and POSIX sh at
once — cmd.exe still expands %VAR% inside double quotes — so the argument
never reaches a shell in the first place. A commit message containing ",
`, $(...), %PATH%, a newline, or CJK text is stored byte-for-byte.
Output is pinned. These are forced on every call, immediately after git,
because each one changes the bytes this plugin parses:
color.ui=false core.pager=cat
core.quotepath=false status.relativePaths=false
log.showSignature=false log.date=default
diff.noprefix=false diff.mnemonicPrefix=false
diff.external= advice.detachedHead=false
Behavioural settings are deliberately not pinned: user.name,
user.email, core.autocrlf, hooks, and core.sshCommand are the user's
intent, not noise. The child environment adds GIT_TERMINAL_PROMPT=0 so a
credential-needing operation fails immediately instead of blocking on a prompt
nobody can answer, and GIT_OPTIONAL_LOCKS=0 so a read cannot fail because
another window holds index.lock.
Mutations are approved. git_commit, and the mutating actions of
git_branch and git_stash, call ctx.approval.request() before running. If
no approval service is mounted the mutation is refused, not allowed — a
silently unguarded git commit is the outcome this plugin exists to prevent.
Set requireApprovalForWrites: false only if you are knowingly accepting that.
Paths are validated. Absolute paths, .. traversal, UNC paths,
drive-relative forms (C:foo), NTFS alternate data streams, Windows reserved
device names, and control characters are all rejected before any process
starts. git would refuse most of these anyway; checking first produces a
precise message and keeps hostile input away from a process entirely.
Not provided — on purpose. push, fetch, pull, reset, clean,
rebase, remote, and config writes. In bash these are at least visible in
a command line a human can read; as a tool they become a one-call destroyer
guarded only by a prompt. Fetch and push need credential and host-key handling
that deserves its own design, not a checkbox here.
Configuration
| Key | Default | Meaning |
|---|
timeoutMs | 30000 | Per-invocation timeout |
maxDiffLines | 500 | Default patch line ceiling (clamped to 10–5000) |
maxLogEntries | 50 | Default git_log limit (clamped to 1–500) |
requireApprovalForWrites | true | Whether mutations need an approval decision |
A patch entry replaces the whole config map rather than merging into it,
so restate anything you want to keep:
- insert:
- id: tool-git
name: dsh-zcode-git
config:
timeoutMs: 60000
requireApprovalForWrites: true
Development
npm test # node --test
95 tests, no dependencies beyond the harness peers. They split into six
layers:
test/parse.test.js — the pure parsers, against recorded git outputtest/validate.test.js — path, message, ref-name, and revision validationtest/exec.test.js — the spawn spec, against a recording faketest/tools.test.js — tool behaviour, against a fake subprocess servicetest/e2e.test.js — a real git binary against real temporary repositoriestest/schema.test.js — schema compatibility with the harness and providers
Notes for plugin authors
Three things in this plugin exist because the obvious approach fails, and none
of them fail loudly at the point of the mistake. They are worth knowing before
writing another tool plugin.
ctx.tools.register() does not compile anything. It validates
output.schema, then stores the definition verbatim. The parameters authoring
DSL is not converted — so registering a raw definition object sends a bare
property map with no top-level type to the model provider, which rejects the
entire request. Wrap it: ctx.tools.register(defineTool(definition)). The
provider names only the alphabetically first tool, so the error points at a
tool that is not at fault.
parameters and output.schema use different DSLs. parameters is a flat
property map ({ path: { type: "string" } }); output.schema is raw JSON
Schema ({ type: "object", properties: { ... } }). Passing the JSON Schema form
to parameters throws parameters.type must be a value schema object; passing
the flat map to output.schema throws schema.type must be string/….
Schema keywords are version-sensitive. required: true inside a property
is accepted by dsh-tools 0.1.5-rc.2 and rejected by 0.1.6-alpha.2
(UNSUPPORTED_SCHEMA). A top-level required: [...] array is rejected by both.
enum in a tool schema caused a provider to reject the whole function schema
with must be a JSON Schema of 'type: "object"', got 'type: null'. This plugin
therefore declares none of them and enforces the same constraints in code,
which also produces better messages — unsupported action "x"; expected one of list, create, switch, delete.
The returned value must match the schema exactly. A null where the schema
says string fails the turn with INVALID_TOOL_OUTPUT after git has already
succeeded. Omit the field instead of sending null.
Renderers run after the work is done. A renderer that reads a field its
execute never returned throws inside the harness and fails an otherwise
successful turn. test/tools.test.js drives every tool's output through its
own renderer for this reason.
Licence
MIT
