dsh-tool-underseal

English | 中文

The one-breath pitch: chat is transport, not authorization. Authority is a hash-sealed assignment file; evidence is append-only and re-derivable by any third party; and every boundary fails closed — sealed tools, a worker check-in lock, and byte-pinned supply-chain sentinels — behind a single dsh plugin add dsh-tool-underseal.

Tested on DSH 0.1.0-rc.5 — runtime mounting smoke test passed: dsh plugin add + dsh --dump-config mounts both layers (underseal and underseal-guard), and the full ceremony chain (doctor → seal → start → event → audit → retire) ran end to end through the vendored adapter in a real Git repository. Two field notes: when dsh plugin add takes a local path containing spaces, wrap it in literal double quotes (dsh plugin --profile p add '"D:\Project Hyperion\A_Deepseek Harness Workspace\underseal-dsh"') — the CLI joins pnpm args through a shell without quoting; and after sealing, commit the lead plane (.underseal/, .underseal-runs/) before the worker starts — the normative scope audit fails closed on uncommitted control-plane files (see the bundled skill).

Model-facing typed tools that wrap the frozen, reviewed underseal adapter for the DeepSeek Harness.

Underseal is a hash-sealed, file-authorization protocol for delegating bounded work between AI agents. Its frozen Python verifier is the only authority; this package is a process shell only — it never reimplements validation. Each tool spawns the vendored adapter through the ctx.subprocess seam, requires the adapter's canonical UNDERSEAL_ADAPTER_* marker, and throws with the adapter's E_* diagnostic on failure.

The package also ships a DSH skill (skills/underseal-delegation/SKILL.md) that documents the delegation workflow in DSH terms (subagent / subagent_fork / workflow / goal), and reference files under skills/underseal-delegation/references/.

Field record: the ceremony's shape in production

A three-day production run of the original underseal workflow (Codex as lead, DeepSeek workers, August 2026) left OpenAI-side metering worth reading as a design signal — with two caveats: it predates this DSH plugin, and it mixes Codex's own context with underseal's, so no clean per-part attribution exists.

Metric (3 days, weighted)	Value
Input cache hit rate	99.164%
Total input	289,510,152 tokens
Total output	1,669,568 tokens
Input/output ratio	≈ 173:1
Effective input cost at 0.1× cached reads	≈ 31.1M tokens (≈ 89% saved)

Two honest readings:

1. The 99% cache hit rate is a property to keep. Sealed assignments, receipts, dispatch bindings, and ceremony rules are stable, hash-bound text, so long prompt prefixes cache almost perfectly. Protocol stability is cache-friendliness.
2. The 173:1 ratio is the tax of carrying the ceremony inside the chat. The same roughly 100K-token prefix was re-read thousands of times; caching made it cheap but did not make it light — rate limits, latency, and the exposed prompt surface all paid for it.

This plugin is the correction: authority lives in files, not in the prompt. A steady-state turn carries the 8 tool schemas (~1–2K tokens) plus bounded tool results ({marker, payload, exitCode, stdout, stderr}); the assignment is read exactly once by the worker that must obey it, and evidence never re-enters the context. A normalized per-task benchmark (sealed vs. unsealed, same task) is in BENCHMARK.md — run it and fill in a real Δ.

Measured on DSH 0.1.0-rc.5 with deepseek-v4-flash, the seal overhead is a flat ~10.4K-uncached-token per-task constant — not a percentage tax (plus tens of seconds of wall clock, +10s trivial / +54s real task): on a trivial one-file task it was 42% of total input; on a real coding task (a Python module plus a 16-test suite) it dropped to 14% — and it keeps shrinking as the task grows. Full tables and caveats in BENCHMARK.md.

Benchmark: what sealing actually costs

Measured end-to-end on DSH 0.1.0-rc.5 with deepseek-v4-flash, same task run twice — unsealed (A) vs. the full sealed ceremony (B):

Task (A → B)	uncached Δ	wall-clock Δ	overhead as % of total input
Trivial: create one file	+10,420 tokens	+10.2s	41.7%
Real: Python module + 16-test suite	+10,282 tokens	+54.3s	13.8%

The seal is a flat ~10.4K-uncached-token per-task constant — not a percentage tax. The token bill barely moves as the task grows (+10,420 → +10,282), so its share of a task's input falls from 42% on a trivial one-file job to 14% on a real coding task and keeps shrinking. (Wall clock grows a little more, since the ceremony adds model round-trips whose latency scales with reasoning.) Full per-run tables, method, and caveats: BENCHMARK.md.

Status: out-of-tree bundle

This directory is an out-of-tree plugin package that doubles as an installable DSH bundle: package.json declares dsh.bundle = { patch: "./cordis.patch.yml" }, so dsh plugin add activates its layer automatically. It compiles with a plain tsc -p . (see tsconfig.json) and is not yet registered in the monorepo's tsconfig.host.json / knip.json / root workspaces. See Inlining.

Install

Three official forms (publish guide):

# 1. npm (preferred): prebuilt lib/ ships in the published package
dsh plugin --profile <name> add dsh-tool-underseal

# 2. Git checkout: pnpm runs this package's `prepare` (tsc -p .) after fetch;
#    the first add fails until you allowlist the build in the profile's
#    pnpm-workspace.yaml (copy the exact key pnpm printed):
#      allowBuilds:
#        dsh-tool-underseal: true
#    then re-run, pinning a commit:
dsh plugin --profile <name> add github:you/dsh-tool-underseal#<sha>

# 3. Tarball: no build permission needed at all
pnpm pack
dsh plugin --profile <name> add ./dsh-tool-underseal-0.1.0.tgz

Verify the layer without booting, then boot:

dsh --profile <name> --dump-config   # shows a "# == dsh-tool-underseal" layer
dsh --profile <name>

Uninstall: dsh plugin --profile <name> remove dsh-tool-underseal removes both the dependency and its layer.

Treat allowBuilds as what it is: permission to execute this package's code at install time, outside any agent sandbox. Prefer the npm or tarball forms when you do not want to grant it.

Service API

Two plugins ship in this package:

• Plugin name: tool-underseal

• inject: ['tools', 'subprocess'] — the plugin loads only when both the tool registry (ctx.tools) and a subprocess provider (ctx.subprocess) exist.

• Contribution: registers eight model-facing tools on ctx.tools.

• Plugin name: underseal-guard (subpath dsh-tool-underseal/guard)

• inject: ['tools']

• Contribution: registers one monotonic execution guard on ctx.tools — the worker check-in lock (see Worker check-in lock).

Config

tool-underseal:

Field	Type	Default	Meaning
adapterPath	string	vendored python/underseal_adapter.py (absolute, resolved at load)	Adapter script; when pythonPath is empty, an executable name or absolute path instead.
pythonPath	string	python (Windows) / python3 (POSIX)	Interpreter prefix for the .py adapter script. Empty string spawns adapterPath directly as an executable.
cwd	string	process.cwd()	Child working directory. The adapter resolves its workspace from --workspace-root, so this only affects PATH-relative tooling.
graceMs	number	30000	Grace period (ms) for the subprocess terminate escalation.
outputMaxBytes	number	65536	In-memory cap per output stream before tail retention.
spillMaxBytes	number	4194304	Whole-stream spill cap per output stream.

underseal-guard:

Field	Type	Default	Meaning
blockedTools	string[]	['write', 'edit', 'pwsh', 'bash']	Tool names whose mutations are denied while READY evidence is missing.
cacheTtlMs	number	2000	Verdict cache lifetime (ms) per repository; the small underseal state files are re-read when stale.

Defaults are self-contained: the reviewed adapter is vendored inside the package, so a bare dsh plugin add needs only a Python interpreter on the host. Override pythonPath: '' + adapterPath: underseal-adapter to use a separately provisioned console-script install instead.

Vendored verifier

python/ carries the exact reviewed bytes, not a moving branch:

• Upstream: https://github.com/Hyperionjust/underseal
• Reviewed upstream commit: 18f85a6b3bc89a8b3325a9bd665ee51a8ab3d225
• The underseal.py bytes match python/underseal.pin.json (SHA-256 130c86e0…); python/.gitattributes forces LF so checkout-time CRLF rewriting cannot drift the pinned bytes.
• Apache-2.0: LICENSE and NOTICE ship alongside.

Treat every vendored-verifier update as a new supply-chain review (skills/underseal-delegation/references/maintenance.md).

Supply-chain sentinels

The plugin runs three byte-level anti-forgery checks inside apply() before registering any tool, so a tampered package cannot activate silently:

• E1 — vendored verifier bytes. SHA-256 of python/underseal.py must equal the pin in python/underseal.pin.json; python/underseal_adapter.py must exist. On any mismatch the plugin logs error and registers nothing (the whole package goes silent rather than run a drifted verifier).
• E2 — skill body pin. Every byte of the skills/underseal-delegation/SKILL.md body (the range after the closing frontmatter --- line) is hashed and compared with the metadata.pin value in its frontmatter. Drift logs a warn and still loads the skill — the skill is guidance, not authority, so E2 never blocks tool registration.
• E3 — bundle patch bytes. SHA-256 of cordis.patch.yml must equal the pin in cordis.pin.json. A mismatch logs error and registers nothing, preventing a supply-chain-rewritten layer from activating.

Pin file locations: python/underseal.pin.json (E1), the metadata.pin frontmatter line of skills/underseal-delegation/SKILL.md (E2), and cordis.pin.json (E3). The expected hash always comes from the pin document itself, so a missing, corrupt, or malformed pin is itself a fail-closed condition.

Re-pinning is a new review action. After a reviewed change to the verifier, the skill body, or the bundle patch, recompute the pins with:

powershell -ExecutionPolicy Bypass -File scripts\repin.ps1

The script prints the three new SHA-256 values, rewrites the two pin JSON files, and updates the SKILL.md frontmatter metadata.pin line (body bytes are never touched). It is idempotent: re-running it with nothing changed leaves every file byte-identical. Inspect the printed values and commit the changed pin files as a new supply-chain review.

Tools

Every tool returns the same canonical value on success (output.schema, additionalProperties: false):

{ marker: string, payload: JsonValue, exitCode: 0, stdout: string, stderr: string }

marker is the adapter's exact success token; payload is the parsed JSON the adapter emitted after it. On any failure (non-zero exit, or missing the expected marker) the tool throws with the adapter's E_* code and stderr — there is no success value with a failure marker. No tool runs acceptance commands, performs Git commits, or performs network operations; each mirrors exactly one adapter subcommand.

Tool	Adapter subcommand	Required marker	Args	Lead / Worker
underseal_doctor	doctor	UNDERSEAL_ADAPTER_OK	workspaceRoot	read-only, either
underseal_pin	pin	UNDERSEAL_ADAPTER_PIN_OK	workspaceRoot, replace?	lead
underseal_seal	seal	UNDERSEAL_ADAPTER_SEALED	workspaceRoot, taskName, expectedMode (owner|mechanical), expectedRole, dispatchId?	lead
underseal_start	start	UNDERSEAL_ADAPTER_READY	workspaceRoot, taskName, expectedMode, expectedRole, summary?	worker
underseal_event	event	UNDERSEAL_ADAPTER_EVENT_OK	workspaceRoot, taskName, expectedMode, expectedRole, state, summary	worker
underseal_resume	resume	UNDERSEAL_ADAPTER_RESUMED	workspaceRoot, expectedRole, hostSameAgentConfirmed	lead
underseal_audit	audit	UNDERSEAL_ADAPTER_AUDIT_OK	workspaceRoot, taskName, expectedMode, expectedRole	lead
underseal_retire	retire	UNDERSEAL_ADAPTER_RETIRED	workspaceRoot, expectedRole	lead

Notes that are load-bearing for the protocol:

• expectedRole is a free string, validated against the Underseal role grammar [a-z][a-z0-9_]{0,63} (the adapter's --expected-role is type=_role_name, not a fixed enum). deepseek_owner / deepseek_coder are this skill's convention, not the adapter's closed set.
• underseal_event.state is the adapter's PROGRESS_STATES minus READY. The CLI accepts READY as a legal choice, but READY is the activation boundary that underseal_start owns; the enum excludes it so workers cannot emit a second activation event through the generic event path.
• underseal_resume.hostSameAgentConfirmed is a required boolean; the tool refuses false without invoking the adapter, and only passes --host-same-agent-confirmed when true.
• underseal_seal.dispatchId is required for a full-ceremony assignment and must be omitted for lite (the adapter enforces both directions).

Skill

The bundled skill documents the whole ceremony in DSH terms. DSH's filesystem skill provider does not scan npm package directories, so link it into a scanned root once per machine or project:

# project-scoped (committed to the repo):
mkdir -p .dsh/skills
cp -r node_modules/dsh-tool-underseal/skills/underseal-delegation .dsh/skills/

# or user-scoped:
cp -r node_modules/dsh-tool-underseal/skills/underseal-delegation ~/.agents/skills/

The session skill catalog then lists underseal-delegation; loading it (the skill tool or a /underseal-delegation gesture) injects the workflow whose steps name these tools.

Worker check-in lock (guard)

The second plugin (dsh-tool-underseal/guard, plugin name underseal-guard) turns "call underseal_start before touching project files" from skill guidance into a machine rule in the tool pipeline.

Enforcement seam

The guard registers through ctx.tools.guard(), not the reorderable tools/pre-execute waterfall. The contract (packages/core/tools README, "Public API") makes the difference explicit:

ctx.tools.guard(guard: ToolGuard): () => void — Register a monotonic synchronous execution guard after tools/pre-execute: returning a reason denies the call, while undefined leaves it unchanged. A plain-context guard applies globally … Later waterfall listeners cannot turn a guard denial back into permission.

and ToolGuard is (execution) => string | undefined, evaluated "after the reorderable pre-execute waterfall and before dispatch". A machine rule must not be reversible by reordering a waterfall, so the monotonic guard API is the enforcement point. The guard receives the full identity-protected Readonly<ToolExecution> (name, arguments, agent), which supplies the caller agent's session.header.cwd for the repository lookup.

Decision (v1, full ceremony only)

For each dispatch, when the tool name is in blockedTools (default write, edit, pwsh, bash):

1. Walk up from session.header.cwd to the Git repository root (any .git entry). No .git (or no usable cwd) → allow.
2. Scan <repo>/.underseal/assignments/*.assignment.json; require at least one assignment with ceremony == "full" and gate.status == "OPEN". None → allow. lite ceremonies are out of scope for v1.
3. That assignment's role must have an INITIAL-generation current dispatch at .underseal/dispatch/<role>.current.json (a resume dispatch — non-INITIAL activation kind or generation > 1 — does not satisfy this).
4. .underseal-runs/<task>.events.jsonl must contain no READY event line.

All three hold → the tool call is denied with a reason naming the assignment and pointing at underseal_start (including the workspaceRoot/taskName/ expectedRole/expectedMode arguments it needs). Fail-closed: any read error that is not an explicitly classified "absent" answer (no assignments directory → allow; no current dispatch → allow; no events log → deny) rejects the call, as does any malformed JSON. The decision core is a pure function (src/guard-core.ts) over a minimal injected read interface, so it runs without a DSH runtime in tests/run-guard-tests.mjs.

Caching

Verdicts are cached per repository root so the dispatch path is O(1) while fresh. The cache is invalidated (a) by fs/observed events under the repository (the fs tools emit them after reads/writes), (b) immediately after any successful underseal_* tool result — underseal_start's READY append goes through the subprocess seam and emits no fs/observed, so this is what makes the block→allow transition immediate — and (c) by a short TTL (cacheTtlMs, default 2000 ms) as a staleness bound for subprocess-driven changes that emit neither signal. Cache misses re-read the small state files synchronously, as the synchronous ToolGuard contract requires.

Known limitations of the seam

This is a program gate inside the tool pipeline, not an OS sandbox:

• It only sees tool dispatches that flow through the DSH registry. A model that reaches the host outside the tool layer, a host-level subprocess the tool layer does not mediate, or a remote backend reached through ACP bypasses it entirely.
• It blocks by tool name, not by target path: v1 denies write/edit/ pwsh/bash everywhere while the evidence is missing, even for writes outside the repository.
• The authoritative acceptance review remains underseal_audit; the guard is a hygiene gate, not evidence.

Model Experience

Tool schemas

What the model sees

Eight tool schemas named underseal_doctor, underseal_pin, underseal_seal, underseal_start, underseal_event, underseal_resume, underseal_audit, underseal_retire, each with the parameters and the shared canonical result schema described under Tools. Schemas flow into prompt assembly automatically via ctx.tools.

Token effect

Fixed schema cost per request where each tool is visible, plus the tool's description prose.

KV Cache effect

Prefix-stable while tool definitions and visibility are unchanged; restriction, shadowing, or plugin lifecycle changes may invalidate reuse from that schema.

Tool result

What the model sees

On success, output.render emits one text block:

underseal <label> succeeded (<marker>, exit 0)
<payload as indented JSON>

On failure the tool throws; the model sees an Error: underseal <label> failed [E_*] (exit N): <stderr> message rather than a success card.

Token effect

Data-dependent tool-result tokens; failures add only the bounded error message (the adapter already truncates its own git stderr to 500 chars).

KV Cache effect

Append-only; newly visible content follows the reusable request prefix.

Skill catalog

What the model sees

When the bundled skills/underseal-delegation/SKILL.md is linked into a scanned root (see Skill), the session catalog lists underseal-delegation with its description summary. Loading it injects the DSH-first delegation workflow, whose steps name these tools.

Token effect

One catalog summary line when available; the full skill body is loaded only on demand via the skill tool or a direct /underseal-delegation gesture.

KV Cache effect

Append-only; catalog replacement republishes the whole <available_skills> list.

Inlining into the monorepo

When this package is moved under packages/:

1. Replace tsconfig.json with the package template shape (extends: "../../../tsconfig.base.json", rootDir: "src", outDir: "lib/types", project references to vendor/cordis, vendor/schemastery, core/tools, subprocess/subprocess).
2. Register the package in tsconfig.host.json references (one aggregate only — Host), and in knip.json if discovery needs it.
3. Re-add the workspace-constraint invariants (private: true, root-version match, the full files gate). The current package.json omits private on purpose because this is a distributable out-of-tree package.

Known Limitations and Deferred Work

• Not built inside the monorepo toolchain — the package is verified with a standalone overlay (tsconfig.verify.json maps the four @deepseek-ai/* specifiers onto the checkout's built type entries): strict tsc exits 0, the guard/sentinel suites pass (54 + 39 assertions), and a runtime smoke test on DSH 0.1.0-rc.5 mounted both layers and ran the full ceremony chain. It has not been compiled through the monorepo's tsdown/tsc project-reference build.
• Published-line drift — peer ranges are pinned against the npm registry: @deepseek-ai/cordis@^4.0.1 and @deepseek-ai/schemastery@^3.18.1 match the vendored build sources exactly; @deepseek-ai/dsh-tools/@deepseek-ai/dsh-subprocess@^0.1.0-rc.0 admit the published 0.1.0-rc.6 line, which is newer than the locally tested 0.1.0-rc.5. Re-run the smoke test after the first real install resolves versions, and tighten the range if rc.6 changes the seams this package uses.
• Windows subprocess capture — the plugin deliberately routes every spawn through ctx.subprocess rather than node:child_process, because the harness sandbox denies piped-stdio capture from a bare Node spawn (EPERM on named pipes); ctx.subprocess collect mode is the sanctioned path and the only one exercised here.
• Python interpreter required — the vendored adapter runs under the host's python/python3; the package does not ship or install an interpreter.
• graceMs upper bound — the subprocess seam caps grace at MAX_TIMER_DELAY_MS; the plugin asserts only positive-integer, leaving the upper bound to the seam and documenting it here.
• resume host-same-agent — hostSameAgentConfirmed is an assertion the human/model makes, not a fact the plugin can verify; the plugin only refuses false and forwards true to the adapter.
• No UI cards — tools fall back to the generic card; terminal/diff presentation and a presentationMeta projector are deferred.
• Guard is a pipeline gate, not an OS sandbox — the worker check-in lock (Worker check-in lock) denies change-shaped tool dispatches while READY evidence is missing, but it cannot see host-level processes the tool layer does not mediate or remote ACP backends, and it blocks by tool name rather than target path (v1). The authoritative review remains underseal_audit; the adapter's fail-closed verifier and the human workflow still own the final boundary.
• No resident watcher — the sentinels (Supply-chain sentinels) run once at plugin apply(). A resident watcher that raises an immediate alarm on fs/observed mutations under python/ (or the bundle patch / skill file) is not yet implemented; drift surfaces at the next plugin load or repin.