@amaster.ai/dsh-policy 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-plugins contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,120 @@
+# @amaster.ai/dsh-policy
+
+![dsh-policy preview](preview.png)
+
+Declarative tool-call policy for [DeepSeek Harness (dsh)](https://github.com/deepseek-ai/deepseek-harness): config-driven `allow` / `deny` / `ask` rules on dsh's `tools/pre-execute` gate — the semantics of Gemini CLI's TOML policy files, expressed as plain plugin config (Schemastery-validated YAML, no code, no rule files).
+
+## Install
+
+```sh
+dsh plugin --profile my-agent add @amaster.ai/dsh-policy
+```
+
+## Configuration
+
+The plugin is **disabled by default**. Rules live in the profile's `cordis.patch.yml` like every other dsh plugin config (edits hot-reload with the config layer):
+
+```yaml
+- name: '@amaster.ai/dsh-policy'
+  config:
+    enabled: true
+    rules:
+      - tool: '*'                      # every tool
+        decision: allow
+        priority: 20
+      - tool: bash                     # dsh's shell tool (pwsh works the same)
+        decision: deny
+        commandPrefix: npm
+        priority: 200
+        message: 'npm is not allowed. Use bun install / bun add / bun test instead.'
+      - tool: bash
+        decision: deny
+        commandPrefix: bun run
+        priority: 200
+      - tool: bash                     # …but one specific subcommand is fine
+        decision: allow
+        commandPrefix: bun run lint
+        priority: 300                  # higher priority overrides the broader deny
+      - tool: bash                     # grep as a pipe filter stays allowed
+        decision: allow
+        commandPrefix: grep
+        priority: 300
+      - tool: write
+        decision: deny
+        argsPattern:
+          file_path: '\.md$'           # matched against the file_path value directly
+        priority: 200
+      - tool: write                    # …except the project contract file
+        decision: allow
+        argsPattern:
+          file_path: 'PRODUCT\.md$'
+        priority: 300
+      - tool: write
+        decision: ask                  # resolved via ctx.approval (human/answerer chain)
+        argsPattern:
+          file_path: '(^|/)etc/'
+        message: 'writes to a system path'
+```
+
+### Rule fields
+
+| Field | Required | Meaning |
+| --- | --- | --- |
+| `tool` | yes | Tool name or list of names; `*` matches every tool |
+| `decision` | yes | `allow` runs the call, `deny` blocks it (the `message` reaches the model as the tool error), `ask` defers to dsh's approval seam |
+| `priority` | no (0) | Higher priority wins among rules competing for the same command segment; ties break fail-closed (deny > ask > allow) |
+| `message` | no | Deny reason / ask explanation (a generated default names the matched rule) |
+| `argsPattern` | no | Regex (or list, any-of) matched against the JSON-stringified arguments — or a map of argument name → regex (or list): each key's pattern is matched against that argument's **value** (non-string values are JSON-stringified first), all keys must hold. Prefer the map form for field-targeted rules — no quote escaping, no key-order or cross-field accidents |
+| `commandPrefix` | no | Anchored prefix match (or list, any-of) on each shell command segment, at a word boundary (`npm` matches `npm install`, never `npmx`) |
+| `commandRegex` | no | Regex (or list, any-of) anchored at each shell command segment's start — Gemini-compatible; use `.*` to match mid-segment |
+
+Plugin-level fields: `enabled` (master switch) and `commandKeys` (argument keys holding a shell command string — default `['command']`, covering dsh's `bash`/`pwsh` tools).
+
+### Matching semantics
+
+- **Every condition on a rule must hold** for the rule to match (AND). A rule with no conditions beyond `tool` matches every call of that tool.
+- **Shell commands are checked segment by segment.** Compound commands (`a && b | c`, newlines, background `&`) are split, quote-aware, and `$( )` / backtick substitutions are extracted as their own segments — `cd /tmp && npm install` and `echo "$(npm install)"` both hit the `npm` rule.
+- **Priority resolves competition within one segment**; across segments the aggregation is conservative: any segment's `deny` denies the whole call, then any `ask` escalates, and `allow` requires every segment decided allow. A broad deny is still overridable by a specific allow because both compete on the same segment (`bun run lint` at 300 vs `bun run` at 200).
+- **No rule matches → the call passes through** to the rest of the `tools/pre-execute` chain (`next()`), so dsh's own gates and other plugins keep their say. Invalid regexes are config errors and fail the plugin load; a runtime evaluation failure is logged with the `[dsh-policy]` prefix and delegates onward — the gate never breaks the agent loop.
+
+### What the gate covers
+
+Everything registered in `ctx.tools` passes `tools/pre-execute` — the gate is tool-agnostic and needs no per-tool support:
+
+- **Official tools** (verified against the 0.1.5-rc.1 sources): `bash`, `pwsh`, `read`, `write`, `edit`, `read_image`, `web_search`, `web_fetch`, `list_subagent_models` and the delegation tool, `run_code`, plus goal/skill/workflow/cordis tools. Match them by `tool` + `argsPattern` (the object form fits their argument shapes: `file_path` for `write`/`edit`, `url` for `web_fetch`, `query` for `web_search`, …).
+- **`commandPrefix`/`commandRegex`** apply to tools whose arguments carry a shell command string — `bash` and `pwsh` both use `command` (covered by the default `commandKeys`).
+- **PTC mode**: `run_code` sub-dispatches re-enter the scheduler's `prepare` stage, which runs the same pre-execute gate — rules apply per sub-call, not just per `run_code`.
+- **MCP tools** bridged by `dsh-mcp-client` register into the same `ctx.tools` pipeline — match them by their registered names like any other tool.
+
+### The `ask` decision
+
+`ask` is resolved by dsh itself: through the composed answerers of `@deepseek-ai/dsh-user-approval` (a UI prompt, an auto-answerer, …), failing closed to deny when no approval service is composed, and short-circuiting to reject under a session's `approval/policy: never`. The model-facing deny reason is the rule's `message` only when no approval service exists at all; a `rejected`/`cancelled`/`unavailable` outcome carries dsh-tools' own reason wording (verified against `dsh-tools@0.1.5-rc.1`). Gemini's `modes` (`default`/`autoEdit`/`yolo`/`plan`) have no dsh counterpart — dsh models that axis as the per-session approval policy (see `dsh-permission-presets` for the user-facing selector), and dsh profiles/`cordis.patch.yml` already scope config per deployment, so the plugin carries no mode axis of its own.
+
+## Gemini CLI policy mapping
+
+| Gemini TOML | dsh-policy config |
+| --- | --- |
+| `toolName = "*" / "name" / ["a", "b"]` | `tool: '*' / name / [a, b]` |
+| `decision = "allow" / "deny" / "ask_user"` | `decision: allow / deny / ask` |
+| `priority = 300` | `priority: 300` (same direction) |
+| `denyMessage` | `message` |
+| `argsPattern` (regex on the serialized args) | `argsPattern` — plus a dsh-native object form `{ file_path: '…' }` matching per-argument values (the string form keeps JSON.stringify key order, not Gemini's sorted-key form — patterns spanning multiple keys may need adjusting; the object form has no such issue) |
+| `commandPrefix` / `commandRegex` (single or list) | same names, matched per command segment; `commandRegex` anchors at the segment start, like Gemini's at the command start |
+| `modes = [...]` | no counterpart — use separate dsh profile patch rows |
+| `allowRedirection` | not supported (dsh has no per-call redirection gate) |
+
+## Security
+
+A policy plugin is advisory gating, not containment: deny rules keep a well-behaved agent off dangerous commands, but the agent process still runs with host privileges. Pair with dsh's sandbox stack (`dsh-sandbox` + a confining executor) for OS-level enforcement, and note that dsh ships no authentication or authorization of its own.
+
+## Compatibility
+
+| @amaster.ai/dsh-policy | dsh | cordis |
+| --- | --- | --- |
+| 0.1.x | `0.1.5-rc.1` | `^4.0.1` |
+
+Peer dependency: `@deepseek-ai/dsh-tools` (the `tools/pre-execute` gate). The approval seam (`@deepseek-ai/dsh-user-approval`) is optional and only involved in `ask` decisions.
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,5 @@
+# Inserts the dsh-policy plugin row; plugin config is the Config schema in
+# src/index.ts (overridable in the profile's own cordis.patch.yml).
+- insert:
+    - id: policy
+      name: '@amaster.ai/dsh-policy'

package/lib/index.js

@@ -0,0 +1,82 @@
+/**
+ * dsh-policy — declarative tool-call policy for DeepSeek Harness.
+ *
+ * Gemini CLI-style policy rules expressed as plain plugin config (no code,
+ * no rule files): each rule matches a tool call by tool name, optional
+ * `argsPattern` (regex over the JSON-stringified arguments) and optional
+ * `commandPrefix`/`commandRegex` (per-segment over shell commands), and
+ * resolves to `allow` / `deny` / `ask` at a priority.
+ *
+ * The decision rides the `tools/pre-execute` gate
+ * (@deepseek-ai/dsh-tools): `allow` runs the call, `deny` materializes the
+ * message as a tool error the model can read, and `ask` is resolved by dsh
+ * itself through the approval seam (ctx.approval, fail-closed to deny when
+ * no answerer is composed). A call no rule matches is delegated onward via
+ * `next()` — the plugin only ever speaks for the calls its rules cover.
+ *
+ * Gate shape verified against @deepseek-ai/dsh-tools@0.1.5-rc.1
+ * (lib/types/index.d.ts: tools/pre-execute + PreToolDecision).
+ *
+ * @module dsh-policy
+ */
+import Schema from '@deepseek-ai/schemastery';
+import { compileRules, describeRule, evaluate } from './rule.js';
+export const name = 'dsh-policy';
+// One waterfall listener only needs the event to exist; no hard service
+// dependency is declared so the plugin still loads in minimal compositions
+// (it simply never gates anything). Add 'tools' to `inject` if you prefer
+// fail-fast wiring.
+export const inject = [];
+/** A match field takes one pattern or an any-of list (Gemini's `field = [...]` form). */
+const stringOrList = Schema.union([Schema.string(), Schema.array(Schema.string())]);
+// Explicit annotation: the nested array/union inference otherwise references
+// cosmokit types that consumers do not have installed (TS2742).
+export const Config = Schema.object({
+    enabled: Schema.boolean().default(false).description('master switch'),
+    commandKeys: Schema.array(Schema.string())
+        .default(['command'])
+        .description('argument keys holding a shell command string (dsh bash/pwsh use `command`)'),
+    rules: Schema.array(Schema.object({
+        tool: stringOrList.required().description('tool name(s), or "*" for every tool'),
+        decision: Schema.union(['allow', 'deny', 'ask'])
+            .required()
+            .description('allow runs, deny blocks with `message`, ask goes through user approval'),
+        priority: Schema.number().default(0),
+        message: Schema.string().description('deny reason / ask explanation, surfaced to the model and the answerer'),
+        argsPattern: Schema.union([stringOrList, Schema.dict(stringOrList)]).description('regex(es) matched against the JSON-stringified arguments (any-of) — or a map of argument name → regex(es) matched against that argument value'),
+        commandPrefix: stringOrList.description('anchored word-boundary prefix match on each shell command segment (any-of)'),
+        commandRegex: stringOrList.description('regex(es) anchored at each shell command segment start (any-of)'),
+    })).default([]),
+});
+export function apply(ctx, config) {
+    if (!config.enabled || config.rules.length === 0)
+        return;
+    // Invalid regexes are config errors — compileRules throws here, at load.
+    const rules = compileRules(config.rules);
+    // Tests apply() directly (no schema defaults), so the fallback stays.
+    const commandKeys = config.commandKeys ?? ['command'];
+    ctx.on('tools/pre-execute', async (exec, next) => {
+        try {
+            const hit = evaluate(rules, exec.name, exec.arguments, commandKeys);
+            if (!hit)
+                return next();
+            switch (hit.decision) {
+                case 'allow':
+                    return { kind: 'allow' };
+                case 'deny':
+                    return {
+                        kind: 'deny',
+                        reason: hit.rule.message ?? `denied by policy: ${describeRule(hit.rule)}`,
+                    };
+                case 'ask':
+                    return { kind: 'ask', reason: hit.rule.message };
+            }
+        }
+        catch (error) {
+            // A policy gate must never break the agent loop: a broken evaluation
+            // delegates to the rest of the chain (dsh's own gates keep their say).
+            console.error('[dsh-policy] evaluation failed:', error);
+            return next();
+        }
+    });
+}

package/lib/rule.js

@@ -0,0 +1,147 @@
+/**
+ * The policy rule model and matching engine (pure — no cordis imports).
+ *
+ * Semantics, mirroring Gemini CLI's policy files:
+ *
+ * - A rule matches a tool call when the tool name matches (a listed name or
+ *   `*`) AND every present condition group holds: `argsPattern` against the
+ *   JSON-stringified arguments, `commandPrefix`/`commandRegex` against each
+ *   shell command segment. Array fields are any-of within the group.
+ * - `commandRegex` is anchored at the segment start (Gemini anchors it at the
+ *   command start) — use `.*` to match mid-segment.
+ * - Shell commands are checked segment by segment (see shell.ts): a compound
+ *   command cannot launder a denied command behind an allowed one.
+ * - Priority resolves rules competing for the SAME segment; ties break
+ *   fail-closed (deny > ask > allow). Across segments deny wins outright,
+ *   then ask; allow only when EVERY segment decided allow.
+ * - No matching rule at all → `undefined` → the plugin delegates to the rest
+ *   of the `tools/pre-execute` chain (dsh's own gates keep their say).
+ */
+import { matchesPrefix, splitSegments } from './shell.js';
+/** Fail-closed tie-break within one priority tier. */
+const SEVERITY = { allow: 0, ask: 1, deny: 2 };
+const prefer = (a, b) => {
+    if (a.priority !== b.priority)
+        return a.priority > b.priority ? a : b;
+    return SEVERITY[a.decision] >= SEVERITY[b.decision] ? a : b;
+};
+const asArray = (value) => value === undefined ? undefined : Array.isArray(value) ? value : [value];
+/** Anchor at the (already trimmed) segment start, Gemini-style. */
+const anchored = (pattern) => new RegExp(`^(?:${pattern})`);
+/** Compile the argsPattern field: string/list → whole-JSON condition; object → per-key conditions. */
+function compileArgsConditions(pattern) {
+    if (pattern === undefined)
+        return undefined;
+    const compile = (value) => (Array.isArray(value) ? value : [value]).map((p) => new RegExp(p));
+    if (typeof pattern === 'string' || Array.isArray(pattern))
+        return [{ res: compile(pattern) }];
+    return Object.entries(pattern).map(([key, value]) => ({ key, res: compile(value) }));
+}
+/** Compile config rules for evaluation. Invalid regexes are config errors: they throw here, at plugin load. */
+export function compileRules(configs) {
+    return configs.map((rule, index) => {
+        const tools = asArray(rule.tool) ?? [];
+        try {
+            return {
+                tools,
+                decision: rule.decision,
+                priority: rule.priority ?? 0,
+                message: rule.message,
+                argsConds: compileArgsConditions(rule.argsPattern),
+                commandPrefixes: asArray(rule.commandPrefix),
+                commandRes: asArray(rule.commandRegex)?.map(anchored),
+            };
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            throw new Error(`[dsh-policy] invalid regex in rule #${index} (tool "${tools.join(', ')}"): ${reason}`);
+        }
+    });
+}
+/** Human-readable rule identity for the default deny reason. */
+export function describeRule(rule) {
+    const quoted = (values) => values.map((v) => `"${v}"`).join(' | ');
+    const parts = [`tool ${quoted(rule.tools)}`];
+    if (rule.commandPrefixes)
+        parts.push(`commandPrefix ${quoted(rule.commandPrefixes)}`);
+    if (rule.commandRes)
+        parts.push(`commandRegex ${rule.commandRes.join(' | ')}`);
+    if (rule.argsConds) {
+        parts.push(`argsPattern ${rule.argsConds
+            .map((cond) => `${cond.key === undefined ? '' : `${cond.key}=`}${cond.res.join(' | ')}`)
+            .join(', ')}`);
+    }
+    return `${parts.join(', ')} (priority ${rule.priority})`;
+}
+/** The first string-valued argument among `keys` — the shell command, for tools that take one. */
+function extractCommand(args, keys) {
+    if (args === null || typeof args !== 'object' || Array.isArray(args))
+        return undefined;
+    for (const key of keys) {
+        const value = args[key];
+        if (typeof value === 'string')
+            return value;
+    }
+    return undefined;
+}
+const anyMatch = (values, test) => values === undefined || values.some(test);
+/** Every args condition holds: whole-JSON sets test the serialized args; keyed sets test that argument's (stringified) value. */
+function argsMatch(rule, args, argsJson) {
+    if (rule.argsConds === undefined)
+        return true;
+    return rule.argsConds.every((cond) => {
+        if (cond.key === undefined)
+            return cond.res.some((re) => re.test(argsJson));
+        if (args === null || typeof args !== 'object' || Array.isArray(args))
+            return false;
+        const value = args[cond.key];
+        if (value === undefined)
+            return false;
+        const text = typeof value === 'string' ? value : JSON.stringify(value);
+        return cond.res.some((re) => re.test(text));
+    });
+}
+function matchesSegment(rule, segment) {
+    const hasCommandCondition = rule.commandPrefixes !== undefined || rule.commandRes !== undefined;
+    // No command string on this call: command conditions cannot be satisfied.
+    if (segment === undefined)
+        return !hasCommandCondition;
+    return (anyMatch(rule.commandPrefixes, (prefix) => matchesPrefix(segment, prefix)) &&
+        anyMatch(rule.commandRes, (re) => re.test(segment)));
+}
+export function evaluate(rules, toolName, args, commandKeys) {
+    const candidates = rules.filter((rule) => rule.tools.includes('*') || rule.tools.includes(toolName));
+    if (candidates.length === 0)
+        return undefined;
+    const argsJson = JSON.stringify(args ?? null);
+    const command = extractCommand(args, commandKeys);
+    // A call without a shell command is one virtual whole-call segment — only
+    // rules without command conditions can match it.
+    const segments = command === undefined ? [undefined] : splitSegments(command);
+    let undecided = false;
+    const best = {};
+    for (const segment of segments) {
+        let winner;
+        for (const rule of candidates) {
+            if (!argsMatch(rule, args, argsJson))
+                continue;
+            if (!matchesSegment(rule, segment))
+                continue;
+            winner = winner === undefined ? rule : prefer(winner, rule);
+        }
+        if (winner === undefined)
+            undecided = true;
+        else {
+            const held = best[winner.decision];
+            best[winner.decision] = held === undefined ? winner : prefer(held, winner);
+        }
+    }
+    // deny anywhere settles the call, then ask anywhere; allow must be unanimous.
+    if (best.deny)
+        return { decision: 'deny', rule: best.deny };
+    if (best.ask)
+        return { decision: 'ask', rule: best.ask };
+    if (!undecided && best.allow)
+        return { decision: 'allow', rule: best.allow };
+    return undefined;
+}

package/lib/shell.js

@@ -0,0 +1,116 @@
+/**
+ * Shell command segmentation for policy matching.
+ *
+ * dsh's bash/pwsh tools receive one raw command string, so a prefix rule that
+ * only examined the whole string would miss `cd /tmp && npm install`. The
+ * splitter is quote-aware and pulls `$( )` / backtick substitutions out as
+ * their own segments (recursively) — `echo "$(npm install)"` must still hit an
+ * npm rule. Over-splitting is safe (every piece is checked on its own);
+ * `commandPrefix` / `commandRegex` rules match against these segments.
+ */
+const isWordBoundary = (ch) => ch === undefined || /\s/.test(ch);
+/**
+ * A prefix matches a segment only at a word boundary: `npm` matches
+ * `npm install` and `npm` itself, never `npmx` or `npm-cache`.
+ */
+export function matchesPrefix(segment, prefix) {
+    const trimmed = segment.trimStart();
+    return trimmed.startsWith(prefix) && isWordBoundary(trimmed[prefix.length]);
+}
+/** Read a `$(`...`)` body starting just after the opening paren. */
+function readParenSubshell(text, start) {
+    let depth = 1;
+    let quote;
+    let i = start;
+    while (i < text.length) {
+        const ch = text[i];
+        if (quote !== undefined) {
+            if (ch === '\\' && quote !== "'")
+                i += 1;
+            else if (ch === quote)
+                quote = undefined;
+        }
+        else if (ch === "'" || ch === '"') {
+            quote = ch;
+        }
+        else if (ch === '(') {
+            depth += 1;
+        }
+        else if (ch === ')') {
+            depth -= 1;
+            if (depth === 0)
+                return { body: text.slice(start, i), end: i + 1 };
+        }
+        i += 1;
+    }
+    return { body: text.slice(start), end: text.length }; // unbalanced: take the rest
+}
+/**
+ * Split a compound command into the segments a shell would run: pipelines,
+ * `&&`/`||`/`;`/newline chains, background `&`, plus the interiors of
+ * `$( )` and backtick substitutions (which execute even inside double
+ * quotes). Quoted operator characters stay literal.
+ */
+export function splitSegments(command) {
+    const segments = [];
+    let buf = '';
+    let quote;
+    const push = () => {
+        const trimmed = buf.trim();
+        if (trimmed !== '')
+            segments.push(trimmed);
+        buf = '';
+    };
+    let i = 0;
+    while (i < command.length) {
+        const ch = command[i];
+        // Substitution contents execute inside double quotes but are literal in
+        // single quotes — extract them from everywhere except '...'.
+        if (quote !== "'") {
+            if (ch === '$' && command[i + 1] === '(') {
+                const { body, end } = readParenSubshell(command, i + 2);
+                segments.push(...splitSegments(body));
+                i = end;
+                continue;
+            }
+            if (ch === '`') {
+                const close = command.indexOf('`', i + 1);
+                segments.push(...splitSegments(close === -1 ? command.slice(i + 1) : command.slice(i + 1, close)));
+                i = close === -1 ? command.length : close + 1;
+                continue;
+            }
+        }
+        if (quote !== undefined) {
+            buf += ch;
+            if (ch === '\\' && quote !== "'" && i + 1 < command.length) {
+                buf += command[i + 1];
+                i += 2;
+                continue;
+            }
+            if (ch === quote)
+                quote = undefined;
+            i += 1;
+            continue;
+        }
+        if (ch === "'" || ch === '"') {
+            quote = ch;
+            buf += ch;
+            i += 1;
+            continue;
+        }
+        if (ch === '\\' && i + 1 < command.length) {
+            buf += ch + command[i + 1];
+            i += 2;
+            continue;
+        }
+        if (ch === ';' || ch === '\n' || ch === '|' || ch === '&') {
+            push();
+            i += command[i + 1] === ch && (ch === '|' || ch === '&') ? 2 : 1;
+            continue;
+        }
+        buf += ch;
+        i += 1;
+    }
+    push();
+    return segments;
+}

package/lib/types/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * dsh-policy — declarative tool-call policy for DeepSeek Harness.
+ *
+ * Gemini CLI-style policy rules expressed as plain plugin config (no code,
+ * no rule files): each rule matches a tool call by tool name, optional
+ * `argsPattern` (regex over the JSON-stringified arguments) and optional
+ * `commandPrefix`/`commandRegex` (per-segment over shell commands), and
+ * resolves to `allow` / `deny` / `ask` at a priority.
+ *
+ * The decision rides the `tools/pre-execute` gate
+ * (@deepseek-ai/dsh-tools): `allow` runs the call, `deny` materializes the
+ * message as a tool error the model can read, and `ask` is resolved by dsh
+ * itself through the approval seam (ctx.approval, fail-closed to deny when
+ * no answerer is composed). A call no rule matches is delegated onward via
+ * `next()` — the plugin only ever speaks for the calls its rules cover.
+ *
+ * Gate shape verified against @deepseek-ai/dsh-tools@0.1.5-rc.1
+ * (lib/types/index.d.ts: tools/pre-execute + PreToolDecision).
+ *
+ * @module dsh-policy
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import Schema from '@deepseek-ai/schemastery';
+import { type PolicyRuleConfig } from './rule.js';
+export declare const name = "dsh-policy";
+export declare const inject: string[];
+export interface PolicyPluginConfig {
+    enabled: boolean;
+    commandKeys?: string[];
+    rules: PolicyRuleConfig[];
+}
+export declare const Config: Schema<PolicyPluginConfig>;
+export declare function apply(ctx: Context, config: PolicyPluginConfig): void;

package/lib/types/rule.d.ts

@@ -0,0 +1,64 @@
+/**
+ * The policy rule model and matching engine (pure — no cordis imports).
+ *
+ * Semantics, mirroring Gemini CLI's policy files:
+ *
+ * - A rule matches a tool call when the tool name matches (a listed name or
+ *   `*`) AND every present condition group holds: `argsPattern` against the
+ *   JSON-stringified arguments, `commandPrefix`/`commandRegex` against each
+ *   shell command segment. Array fields are any-of within the group.
+ * - `commandRegex` is anchored at the segment start (Gemini anchors it at the
+ *   command start) — use `.*` to match mid-segment.
+ * - Shell commands are checked segment by segment (see shell.ts): a compound
+ *   command cannot launder a denied command behind an allowed one.
+ * - Priority resolves rules competing for the SAME segment; ties break
+ *   fail-closed (deny > ask > allow). Across segments deny wins outright,
+ *   then ask; allow only when EVERY segment decided allow.
+ * - No matching rule at all → `undefined` → the plugin delegates to the rest
+ *   of the `tools/pre-execute` chain (dsh's own gates keep their say).
+ */
+export type PolicyDecisionKind = 'allow' | 'deny' | 'ask';
+/** One configured rule (the raw Config shape). */
+export interface PolicyRuleConfig {
+    /** Tool name(s), or `*` for every tool. */
+    tool: string | string[];
+    decision: PolicyDecisionKind;
+    /** Higher wins among rules competing for the same segment; default 0. */
+    priority?: number;
+    /** Deny reason / ask explanation, surfaced to the model and the answerer. */
+    message?: string;
+    /**
+     * Regex(es) matched against the JSON-stringified arguments (any-of) — or a
+     * map of argument name → regex(es) matched against that argument's value
+     * (stringified when not a string; AND across keys, any-of within a list).
+     */
+    argsPattern?: string | string[] | Record<string, string | string[]>;
+    /** Anchored, word-boundary prefix match on each shell command segment (any-of). */
+    commandPrefix?: string | string[];
+    /** Regex(es) anchored at each shell command segment's start (any-of). */
+    commandRegex?: string | string[];
+}
+/** One compiled args condition: a whole-JSON regex set, or one argument key's regex set. */
+interface ArgsCondition {
+    key?: string;
+    res: RegExp[];
+}
+export interface CompiledRule {
+    tools: string[];
+    decision: PolicyDecisionKind;
+    priority: number;
+    message?: string;
+    argsConds?: ArgsCondition[];
+    commandPrefixes?: string[];
+    commandRes?: RegExp[];
+}
+export interface RuleHit {
+    decision: PolicyDecisionKind;
+    rule: CompiledRule;
+}
+/** Compile config rules for evaluation. Invalid regexes are config errors: they throw here, at plugin load. */
+export declare function compileRules(configs: PolicyRuleConfig[]): CompiledRule[];
+/** Human-readable rule identity for the default deny reason. */
+export declare function describeRule(rule: CompiledRule): string;
+export declare function evaluate(rules: CompiledRule[], toolName: string, args: unknown, commandKeys: string[]): RuleHit | undefined;
+export {};

package/lib/types/shell.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Shell command segmentation for policy matching.
+ *
+ * dsh's bash/pwsh tools receive one raw command string, so a prefix rule that
+ * only examined the whole string would miss `cd /tmp && npm install`. The
+ * splitter is quote-aware and pulls `$( )` / backtick substitutions out as
+ * their own segments (recursively) — `echo "$(npm install)"` must still hit an
+ * npm rule. Over-splitting is safe (every piece is checked on its own);
+ * `commandPrefix` / `commandRegex` rules match against these segments.
+ */
+/**
+ * A prefix matches a segment only at a word boundary: `npm` matches
+ * `npm install` and `npm` itself, never `npmx` or `npm-cache`.
+ */
+export declare function matchesPrefix(segment: string, prefix: string): boolean;
+/**
+ * Split a compound command into the segments a shell would run: pipelines,
+ * `&&`/`||`/`;`/newline chains, background `&`, plus the interiors of
+ * `$( )` and backtick substitutions (which execute even inside double
+ * quotes). Quoted operator characters stay literal.
+ */
+export declare function splitSegments(command: string): string[];

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@amaster.ai/dsh-policy",
+  "version": "0.1.1",
+  "description": "Declarative tool-call policy for DeepSeek Harness: config-driven allow/deny/ask rules (tool name, args pattern, shell command prefix/regex, priority) on the tools/pre-execute gate — Gemini CLI-style policy files expressed as plain plugin config.",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "preview.png"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/TGYD-helige/dsh-plugins.git",
+    "directory": "packages/dsh-policy"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-tools": "0.1.5-rc.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-agent": "0.1.5-rc.1",
+    "@deepseek-ai/dsh-home-paths": "0.1.5-rc.1",
+    "@deepseek-ai/dsh-http-proxy": "0.1.5-rc.1",
+    "@deepseek-ai/dsh-invariants": "0.1.5-rc.1",
+    "@deepseek-ai/dsh-jobs": "0.1.5-rc.1",
+    "@deepseek-ai/dsh-llm": "0.1.5-rc.1",
+    "@deepseek-ai/dsh-sandbox": "0.1.5-rc.1",
+    "@deepseek-ai/dsh-sandbox-policy": "0.1.5-rc.1",
+    "@deepseek-ai/dsh-scope": "0.1.5-rc.1",
+    "@deepseek-ai/dsh-shell": "0.1.5-rc.1",
+    "@deepseek-ai/dsh-shell-env": "0.1.5-rc.1",
+    "@deepseek-ai/dsh-subprocess": "0.1.5-rc.1",
+    "@deepseek-ai/dsh-system-prompt": "0.1.5-rc.1",
+    "@deepseek-ai/dsh-tool-bash": "0.1.5-rc.1",
+    "@deepseek-ai/dsh-tools": "0.1.5-rc.1",
+    "@deepseek-ai/dsh-user-approval": "0.1.5-rc.1",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.3",
+    "vitest": "^4.1.11"
+  },
+  "engines": {
+    "node": "^20.19 || ^22.12 || >=24.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
+}