One-Line Description

Place a YAML-written allow/deny/ask gate before each tool call in DeepSeek Harness, matching by tool name, parameters, paths, Agent identity, and network targets; overlay a local HTTP/CONNECT proxy to uniformly control subprocess outbound network, all hits write read-only audit logs, but the model cannot see them and is not disturbed by side effects other than blocking.

Core Capabilities

• Ordered Rule Chain: Each tool call is evaluated using a "first match wins" approach in file order, with matched rules producing one of three actions: allow/deny/ask; deny/ask truncate subsequent rules, while allow and no-match strictly next() pass through without ever blocking downstream.
• Rich Matching Dimensions: Tool name glob (supports mcp__*), Agent identity selectors (main/subagent/preset:<name>, unknown identity never matches—fail-safe fallback), parameter key-value glob or regex (including !pattern negation and absent missing dimension), workspace-relative paths with arbitrary nesting, when host conditions (environment variables + platform allowlist).
• Process-Level Network Policy: Built-in local HTTP/CONNECT proxy uniformly controls shell subprocess outbound network; rules can use match.network with domains/ips/ports/schemes (glob, wildcard, CIDR, port range) for target matching; three network modes automatically follow official sandbox presets (readonly→deny-all, workspace-write→whitelist, danger-full-access→allow-all).
• Hot Reload with Hierarchical Files: Chokidar watches rule file changes with debounce; broken edits preserve old rules without crashing; optional searchUp merges parent directory .dsh/rules.yaml together (closer takes precedence).
• Complete Read-Only Audit: Every hit and every pass writes permissionRules/decision session event (with ignorable flag), proxy intercepts also write permissionRules/network; logs don't enter model context, only for post-hoc traceback.
• Visual Settings Panel: Web profile adds a "Permission Rules" settings page showing network mode summary, intercept count, recent intercept list and rule editor, all data fetched via Typert remote API.

Technical Implementation

• Language: TypeScript (ESM, strict mode; client React 18)
• Key Dependencies: @deepseek-ai/cordis + @deepseek-ai/schemastery (plugin loading & Config validation), chokidar (rule file watching), yaml (rule file parsing), react (Web settings panel)
• Architecture Pattern: Functional cordis plugin (name/inject/Config/apply, no default export); apply registers tools/pre-execute listener, /rules command, settings section, local proxy; Web half-package communicates with host via Typert remote API. Rule matching is pure function (no I/O, replayable, unit-testable).
• Entry Files: src/index.ts (host entry), src/client/index.ts (Web settings panel entry), src/runtime.ts (core assembly & apply), cordis.patch.yml (profile bundle patch)

Use Cases

Suitable for projects that need to add "allowlist/blocklist/graylist" to AI Agent tool calls: for example, protecting secrets/ and .env from arbitrary editing, restricting network outbound to only hit trusted APIs, requiring sensitive operations to go through secondary approval. Typical users are individuals or teams who want to add an auditable, hot-reloadable, traceable rule source security fence to a session or entire organization using pure YAML config files without writing code.

Prerequisites & Compatibility

Installation

dsh plugin --profile web add github:PerryLink/dsh-permission-rules

Configuration Options

FAQ

Q: Rules not effective after installation?

A: Installing only mounts the plugin to the profile; you must restart the profile for id: permission-rules line to appear; then you also need a .dsh/rules.yaml in your working directory (or configure a fallback file via fallbackPath), having no rules equals "allow all".

Q: Is it a replacement or complement to dsh-auto-review?

A: Complementary. This plugin produces ask going through approval channel, dsh-auto-review attaches a second AI model for judgment on the approval channel; when only this plugin is installed, ask goes through human or host default behavior, only when both are installed does it form a closed loop of "rule filtering + model review".

Q: How to observe if new policy will accidentally block legitimate calls?

A: In cordis.yml temporarily set enforce to false to enter dry-run: all deny/ask hits only write audit logs with dryRun flag, don't block calls, events flow normally to downstream; after observation switch back to true.

Q: What happens with malformed YAML?

A: With default badFilePolicy: 'fail', the tool call waiting to execute errors directly; in HMR reload scenarios, the last successfully loaded rules are preserved, never crash; to be more forgiving, change to ignore-with-warning to warn and continue with empty rules.

Q: How does network policy work by default? How to change?

A: Default is network.enabled: true and network.mode: 'auto', following official sandbox presets (readonly→deny-all, workspace-write→whitelist, danger-full-access→allow-all), falls back to autoFallback when host has no sandbox service (default allow-all). To fix it, explicitly set mode to one of deny-all/whitelist/allow-all.

Q: Why can't I see audit events on old hosts?

A: Host 0.1.0-rc.6 and earlier discard the ignorable flag, causing audit events without the flag and breaking session recovery on new hosts. The plugin actively downgrades to not write session log audit and prints a one-time warning; to keep audit, set allowUnmarkedAudit: true, but old logs may need running scripts/repair-session-logs.mjs repair.

Q: How to view currently effective rules and recent decisions?

A: Run /rules in session to list all rules and source files, /rules reload to force-reload current workspace rule chain, /rules decisions [n] to see last n decisions in this session (default 10), /rules test <tool> <json> can dry-run rule matching without actually triggering tool call.

Q: How to uninstall?

A: One line dsh plugin --profile web remove dsh-permission-rules does it, transactional uninstall, doesn't affect other plugins or session state outside the profile.

Learning Curve

Beginner — configuration is primarily pure YAML, placing config file in workspace root takes effect immediately; refer back to docs when encountering complex matching dimensions (agent selector, CIDR, backtracking protection).

Known Issues & Limitations

• Audit downgrade on old hosts: Session.append in 0.1.0-rc.1–0.1.0-rc.7 series doesn't recognize ignorable flag, plugin actively downgrades to not write session log audit and prints one-time warning; to keep audit set allowUnmarkedAudit: true, and accept that old sessions may need scripts/repair-session-logs.mjs repair on new host.
• Path candidates are heuristic: Only document-listed parameter keys (url/path/file_path etc.) participate in path matching, and only match workspace-relative paths; non-convention keys and references outside absolute paths won't be covered by rules.
• Glob is a conservative subset: No brace expansion support, need to write two rules or switch to regex mode; maxGlobStars (default 2) rejects globs with too many unbounded stars to prevent backtracking.
• Regex backtracking protection is structural not exhaustive: Can block common disaster patterns (nested unbounded quantifiers, overlapping quantified literals), but not complete ReDoS detection, untrusted files should stay in glob mode.
• Proxy layer ask cannot enter interactive approval channel: Local proxy has no session context, when encountering targets requiring approval can only intercept with structured message and write permissionRules/network audit, model sees reason via shell tool error output; only Web tool ask goes through real interactive approval.

---

Compatibility

What you get

dsh-permission-rules puts an ordered allow / deny / ask rule list in front of every tool call on the tools/pre-execute waterfall — deterministic, instant, auditable, and written by you in plain YAML:

• deny blocks the call; the rule's reason becomes the model-visible error.
• ask rides the official approval seam (mount dsh-auto-review for a second-model answerer, or a human answers; with neither, the harness fails closed).
• allow (and no-match) strictly delegates via next() — downstream listeners are never short-circuited.

Every hit and every passthrough is audit-logged as a permissionRules/decision session event (log-only — nothing extra is injected into the model context).

• Rich matching — tool-name globs (including mcp__*), agent-identity selectors (main / subagent / preset:*), argument key/value globs or regexes (with !pattern negation and an absent key dimension), workspace-relative path globs at any nesting depth, and when host conditions (env vars, platform).
• Hierarchical rule files — optional searchUp merges every .dsh/rules.yaml from the session cwd to the filesystem root, nearest first.
• Dry-run rollout — enforce: false audits what the policy would do while passing every call through.
• Hot reload — Chokidar watch with debounce; a broken edit keeps the previous rules, never crashes.
• Fail loud — invalid YAML, unknown actions/fields, bad globs/regexes, backtracking-prone patterns, or more than maxRules rules fail the load.

Rule syntax

# <project>/.dsh/rules.yaml
rules:
  - match: { tools: [bash, pwsh], params: { command: "git push*" }, paths: ["**/secrets/**"] }
    action: deny
    reason: "No pushes from protected paths"

  - match: { tools: [edit, write] }
    action: ask
    reason: "File writes need confirmation"

• Match dimensions — tools (globs, incl. mcp__*), agents (main / subagent / preset:<name>; unknown identity never matches — fail closed), params (key/value globs or regexes, !pattern negation, absent key dimension), paths (workspace-relative globs extracted at any nesting depth), when (env var globs/regexes + a closed platform list), and network (domains / ips / ports / schemes — globs, wildcards, CIDRs, port ranges).
• Actions — allow / deny / ask, evaluated in file order, first match wins.
• Rule metadata — enabled: false (visible but inert), description, tags; unknown fields fail the load.
• Schema — a JSON Schema ships at docs/rules-format.schema.json (editor completion via # yaml-language-server: $schema=...); the full vocabulary and a 5-rule security baseline live in docs/rules-format.en.md.

Network policy

A Codex-style process-level network policy: shell subprocess traffic flows through a built-in local HTTP/CONNECT proxy, and every connection is decided by ordered network rules or by three modes mapped onto the official sandbox presets:

• deny-all — the read-only sandbox preset: block all outbound.

• whitelist — the workspace-write preset: allow listed targets, unlisted: ask (or deny) for the rest.

• allow-all — the danger-full-access preset: allow everything.

• auto (default) — follows the sandbox preset; on hosts without the sandbox-policy service it resolves to autoFallback (allow-all).

• Matching — match.network with domains / ips / ports / schemes (globs, wildcards, CIDRs, port ranges; numeric YAML ports are accepted). URL-candidate extraction on the tools/pre-execute hot path fires on web-tool arguments and URLs embedded in bash/pwsh command text; loopback targets can short-circuit rules per loopback policy.

• Audit — denied connections append permissionRules/network to the owning session (same adaptive ignorable gate), with block counters and recent interceptions in /rules network and the settings page.

Quick start

# 1. install the bundle into your profile
dsh plugin --profile web add "github:PerryLink/dsh-permission-rules#main"

# or from npm (published releases)
dsh plugin --profile web add dsh-permission-rules

# 2. restart and verify the row
dsh --profile web --dump-config | grep -A4 'id: permission-rules'

Install & uninstall

• git channel (latest main): dsh plugin --profile web add "github:PerryLink/dsh-permission-rules#main" — the prepare script builds with production dependencies only.
• npm channel (published releases): dsh plugin --profile web add dsh-permission-rules.
• tarball channel: pnpm pack in this repo, then dsh plugin --profile web add ./dsh-permission-rules-<version>.tgz.
• uninstall: dsh plugin --profile web remove dsh-permission-rules.

Configuration

All tunables are Schemastery Config fields (changeable from cordis.yml). An id-targeted override replaces the whole row — restate every key you need.

Tools & surfaces

/rules                        list the active rules, their source files, and any last-reload error
/rules list                   explicit alias for the bare listing
/rules reload                 re-read the rule-file chain for this workspace
/rules decisions [n]          show the last n permission decisions of this session (default 10)
/rules test <tool> <json>     dry-evaluate the rules against a hypothetical call

/rules test also accepts leading flags: --cwd <dir>, --env KEY=VALUE (repeatable), --agent <selector> (repeatable), and --platform <name>. In multi-file chains (e.g. searchUp), every listed rule line is attributed to its own source file.

Permissions & data

• Permissions: declares files:read, files:watch, files:write, session:append, and network:outbound in its workshop manifest. ask decisions ride the official approval seam — nothing is re-implemented or bypassed.
• Data: rule files are read from disk; no rule data is written. No model calls, no reviewer subagents.
• Session log: permissionRules/decision is never injected into the model context and is appended with the envelope's ignorable: true marker so any harness build loads the log.

Security boundaries

• Policy, not a kernel. paths candidates come only from a documented set of argument keys (at any nesting depth, depth-capped), and only workspace-relative paths match.
• No reviewer here. The plugin never spawns subagents or calls models — producing an ask decision is the end of its work.
• No sandbox changes. OS-level sandbox policy belongs to the sandbox seam, not this plugin.
• Loud misconfiguration. Unknown YAML fields, unknown actions, and bad patterns are rejected at load.
• Backtracking bounds. Glob patterns are capped at maxGlobStars unbounded star expansions; regex-mode patterns reject nested unbounded quantifiers and quantified overlapping literal alternations.

Known limitations

• Audit marker on pre-marker hosts. permissionRules/decision is appended with ignorable: true; hosts whose Session.append predates the marker (the 0.1.0-rc.6 line) silently drop it, so the runtime disables session-log audit with a one-time warning. Set allowUnmarkedAudit: true to opt back in; repair already-written logs with scripts/repair-session-logs.mjs.
• Path candidates are heuristic. Only the documented argument keys feed path matching, and workspace-relative matching is ASCII-case-insensitive only when caseInsensitivePaths is on.
• Globs are a conservative subset. No brace expansion — write two patterns, or use regex mode.
• The regex backtracking guard is structural, not exhaustive. Prefer glob mode for untrusted files.

Collaborating with dsh-auto-review

• dsh-permission-rules produces ask; dsh-auto-review answers on the approval/request waterfall with a read-only second-model verdict (or delegates to humans). Mount both for the full closed loop.
• Integration-tested: permissionRules/decision → approval/asked → autoReview/verdict → approval/decided, with the reviewer replaced by a scripted mock.
• The never approval policy and every fail-closed guarantee of the official harness stay untouched.

Session log repair

Session logs written before the ignorable marker existed can be refused by newer harness builds (SessionFormatUnsupportedError). The shipped scripts/repair-session-logs.mjs rewrites only the targeted audit rows to carry ignorable: true, frame-preserving, with backups:

node scripts/repair-session-logs.mjs scan [--home DIR]      # report foreign rows, change nothing
node scripts/repair-session-logs.mjs repair [--home DIR] [--dry-run]

--home defaults to $DSH_HOME/sessions (or ~/.dsh/sessions).

Development

pnpm install            # node ^22.19 || >=24
pnpm run typecheck      # tsc, src + tests
pnpm run lint           # eslint, src + tests + scripts
pnpm test               # vitest: 139 tests, 9 suites
pnpm run test:coverage  # coverage gate (90/80/90/90)
pnpm run build          # tsc declarations + tsdown bundles (lib/)
pnpm run pack:check     # build + pack (the published artifact)
node scripts/check-readme-sync.mjs   # five-language README sync gate (also in CI)

See VERIFICATION.md for the headless end-to-end verification record.

Topics

dsh, dsh-plugin, deepseek-harness, permission, policy, allow-deny-ask, approval, safety, network, network-policy, proxy

Contributors

• @PerryLink — creator and maintainer: rule vocabulary and evaluation, runtime, HMR watch, session-log audit, network policy + proxy, and the five-language docs.
• @22xuan — the detailed report on rc.6 hosts silently dropping the audit event's ignorable marker (#2) and the upstream harness discussion; the v0.4.1 runtime host-capability detection and the documentation correction drew directly from that analysis.

PerryLink DSH Plugin Family

This project is one of the 15 DeepSeek Harness plugins maintained by PerryLink. If this one helps you, the others likely will too:

License

Apache License 2.0 © 2026 dsh-permission-rules contributors