dsh-desktop-kit 2.2.1 → 2.7.2

package/plugins/dsh-guardrails/README.md

@@ -0,0 +1,264 @@
+# dsh-guardrails
+
+Host guardrails for DSH: a small, inspectable policy layer plus a bounded
+read-only security scan.
+
+The plugin is local-only (Node built-ins, no network, no LLM) and has three
+parts:
+
+1. the model-facing `guardrails` tool — `status`, `check`, `policy`;
+2. a `tools/pre-execute` hook — denies or asks before dangerous shell
+   commands, and denies writes/edits to protected paths requested through
+   file-mutating tools;
+3. `fs/write-intent`, `fs/edit-intent`, `fs/delete-intent` hooks — refuse
+   filesystem mutations that target protected paths.
+
+The package is a child plugin of the desktop kit (`export const inject =
+["tools"]`): the kit entry mounts it via `ctx.plugin()` next to the other
+bundled plugins. The kit passes no services to it beyond `tools`; the
+`fs/*` hooks are event-only, which is why no `fs` injection is declared
+(the shipped `dsh-fs-observation-policy` also injects nothing).
+
+## Tool `guardrails`
+
+Read-only. The canonical value is lossless JSON; the rendered text is a
+bounded human summary.
+
+| Action | What it returns |
+|---|---|
+| `status` | Effective command rules (id, severity, description, default/policy source), protected paths, registered/missing hooks, `DSH_GUARDRAILS` kill-switch state, policy file state (loaded / invalid / defaults), limits, bypass list. |
+| `check` | Bounded worktree scan: secrets, `.env` files, protected paths present in the tree, oversized files, dangerous commands in shell scripts, and `git diff --check`. Optional `root` (default: Session cwd), `maxFiles`, `maxFileSizeBytes`, `maxFindings` overrides (clamped). |
+| `policy` | The effective JSON policy (defaults merged with the user file), plus the policy path, load error and warnings. |
+
+Example calls:
+
+```json
+{ "action": "status" }
+{ "action": "check", "root": "C:\\work\\project", "maxFiles": 400 }
+{ "action": "policy" }
+```
+
+`check` never executes a scanned file: the only subprocess is `git` with fixed
+read-only arguments (`rev-parse`, `diff --check`). It is bounded by
+`maxFiles` (default 800), `maxFileSizeBytes` (default 256 KiB),
+`maxTotalBytes` (default 8 MiB), `maxDepth` (default 12), `maxFindings`
+(default 200) and a git subprocess timeout (default 5 s). Symlinks are not
+followed; binaries, oversized and skipped directories are counted in `stats`.
+
+The scan is cooperative with cancellation: an aborted tool call returns a
+partial report marked `aborted: true`.
+
+## What is blocked
+
+Default command rules (`deny` blocks the call, `ask` routes through the DSH
+approval seam and degrades to a denial when no approval channel exists):
+
+| Rule | Severity | Matches |
+|---|---|---|
+| `rm-rf-root` | deny | `rm -rf /`, `rm -rf /*`, `sudo rm -fr ~`, `$HOME`, drive roots — but not `rm -rf ./build` |
+| `pwsh-remove-root` | deny | `Remove-Item -Recurse -Force C:\`, `rd /s /q C:\`, `del /f /s /q C:\*` |
+| `drop-database` | deny | `DROP DATABASE`, `DROP SCHEMA` |
+| `disk-format` | deny | `mkfs*`, `wipefs`, `diskpart`, `dd … of=/dev/…`, `format C:`, `Format-Volume`, `Clear-Disk`, `Initialize-Disk` |
+| `shell-overwrite-credentials` | deny | shell redirect/overwrite/truncation/removal of `.credentials*`, `id_rsa`, `id_ed25519`, `id_ecdsa`, `.pem`, `.p12`, `.pfx`, `.ssh/` |
+| `shell-copy-credentials` | ask | shell copy/move of the same credential paths (`cp cert.pem /etc/ssl/`) |
+| `git-push-force` | ask | `git push --force`, `git push -f`; `--force-with-lease` stays allowed |
+| `git-reset-hard` | ask | `git reset --hard` |
+| `truncate-table` | ask | `TRUNCATE TABLE …` / `TRUNCATE …` |
+| `shell-write-dotenv` | ask | shell write/removal of `.env` (redirect, `Set-Content`, `rm`, `cp`, `tee`, …); `.env.example`/`.sample`/`.template`/`.dist` are allowed |
+| `sed-inplace-protected` | ask | `sed -i` / `perl -pi` over `.env`, credentials or key files |
+
+Rules are applied to the `command` argument of `bash`, `pwsh`, `powershell`,
+`shell`, `sh`, `zsh`, `cmd` and `terminal` tools. The decision shape is the
+event's own `PreToolDecision`: `{ kind: "deny", reason, info }` or
+`{ kind: "ask", reason, displayReason: { en, ru } }`. Every other call
+delegates with `next()` and is untouched.
+
+Default protected paths (denied for `write`, `edit`, `apply_patch` arguments
+and enforced authoritatively by the `fs/*-intent` hooks):
+
+| Entry | Match |
+|---|---|
+| `git-metadata` | any path segment equal to `.git` (but not `.gitignore`, `.github`) |
+| `ssh-directory` | any path segment equal to `.ssh` |
+| `env-file` | basename `.env` or `.env.*`, except `.env.example`, `.env.sample`, `.env.template`, `.env.dist` |
+| `dsh-credentials` | `…/.dsh/.credentials.yaml` |
+| `private-key-name` | `id_rsa`, `id_dsa`, `id_ecdsa`, `id_ed25519` |
+| `private-key-ext` | `.pem`, `.key`, `.p12`, `.pfx`, `.jks` |
+
+Reads are never blocked.
+
+## Permission presets
+
+DSH already owns the picker (`Read Only`, `Workspace Write`, `Full access`,
+`Auto review`) and the approval card. Guardrails does **not** add a second
+picker; it reads the effective `permissionPresets` mode and enforces hard
+limits through the same `tools/pre-execute` hook:
+
+| Mode | Files | Mutating shell | Outside workspace |
+|---|---|---|---|
+| `read-only` | deny write/edit/apply_patch/delete/move | deny | deny |
+| `workspace-write` | allow inside cwd | allow | ask |
+| `danger-full-access` | allow | allow | allow |
+
+The kit's own policy rules still apply in every mode: `rm -rf /`, prod
+database destruction, protected paths and secrets are denied even in Full
+access. `ask` decisions use the shipped approval UI (`Allow once` / `Always
+allow` / `Reject`).
+
+## Policy file
+
+Path: `<DSH_HOME>/guardrails.json` (default `~/.dsh/guardrails.json`; the
+`DSH_HOME` environment variable is honoured). The file is read with an
+mtime/size cache and is never loaded unbounded. Invalid JSON or an invalid
+entry never takes the plugin down: the problem is reported by `status` /
+`policy` and safe defaults stay in force.
+
+Merge rules: objects merge recursively; `rules` and `protectedPaths` merge by
+`id` (so one entry can be adjusted or disabled without restating the policy);
+all other arrays replace the default value.
+
+Example — disable the force-push ask, tighten `truncate`, add a path:
+
+```json
+{
+  "version": 1,
+  "enabled": true,
+  "askBehavior": "ask",
+  "limits": { "maxFiles": 400, "gitTimeoutMs": 3000 },
+  "hooks": { "toolsPreExecute": true, "fsIntents": true },
+  "rules": [
+    { "id": "git-push-force", "enabled": false },
+    { "id": "truncate-table", "severity": "deny" },
+    { "id": "team-danger", "severity": "deny", "pattern": "deploy\\s+--production", "description": "custom rule" }
+  ],
+  "protectedPaths": [
+    { "id": "team-secrets", "match": "segment", "pattern": "^\\.secrets$", "description": "team secret dir" }
+  ]
+}
+```
+
+`askBehavior: "deny"` turns every `ask` rule into a hard denial (useful on
+unattended machines). `enabled: false` disables the hooks and `check` while
+keeping the tool available for inspection.
+
+## Bypass (kill switch)
+
+- `DSH_GUARDRAILS=off` — process environment; read on every hook and every
+  `check`, so no restart of the plugin is needed. `0`, `false` and `disabled`
+  are accepted as well.
+- `guardrails.json` → `enabled: false`, or
+  `hooks: { toolsPreExecute: false }` / `hooks: { fsIntents: false }`.
+- one rule or protected-path entry: `{ "id": "…", "enabled": false }`.
+
+The tool itself is always readable, so `status` shows exactly what is active.
+
+## Event contracts (verified against the live DSH Event inspect API)
+
+```text
+tools/pre-execute (waterfall)
+  'tools/pre-execute'(this: Scoped<ToolsService>, exec: ToolExecution,
+                      next: () => Promise<PreToolDecision>): Promise<PreToolDecision>
+  PreToolDecision = { kind: 'allow' }
+                  | { kind: 'deny'; reason: string; info?: ToolErrorInfo }
+                  | { kind: 'cancel' }
+                  | { kind: 'ask'; reason?: string; displayReason?: { en; [locale]: string } }
+
+fs/write-intent (waterfall, single slot)
+  'fs/write-intent'(target: FsTarget, actor: object | undefined,
+                    next: () => FsWriteIntent | undefined | Promise<FsWriteIntent | undefined>)
+                    : Promise<FsWriteIntent | undefined>
+  FsTarget = { targetKey: FsTargetKey; displayPath: string }
+
+fs/edit-intent / fs/delete-intent (waterfall, single slot)
+  (target, actor, next) => Promise<{ version: FsVersion } | undefined>
+```
+
+Used exactly:
+
+- `tools/pre-execute` returns only `allow` (via `next()`), `deny` or `ask`
+  decisions. `next()` is always preferred for the allow path so later policy
+  listeners still run.
+- `fs/write-intent` / `fs/edit-intent` / `fs/delete-intent` return `next()`
+  for paths that are not protected. **Ambiguity:** the `fs/*-intent`
+  contracts have no `deny` decision — their return value is a guard or
+  `undefined`, and the "first returned guard wins" slot has no refusal
+  variant. The shipped `dsh-fs-observation-policy` refuses by throwing a
+  coded `FsError` from the listener, and `dsh-tool-fs` dispatches the
+  waterfall so that a throw aborts the mutation. This plugin follows the
+  same mechanism with a plain `Error` (`.name =
+  "GuardrailsProtectedPathError"`, `.code = "GUARDRAILS_PROTECTED_PATH"`,
+  `.ruleId`) only when a path matches the policy and **delegates with
+  `next()` otherwise** — the documented conservative-allow fallback. If a
+  future DSH contract gains a real deny shape it should replace this throw.
+- `tools/pre-execute` also performs a belt-and-braces check of `write` /
+  `edit` / `apply_patch` path arguments, because a first-wins `fs` policy
+  mounted before this plugin could own an intent slot (e.g. the shipped
+  observation policy). The `fs` hook remains the authoritative check for
+  resolved paths.
+
+## Security properties
+
+- Secret values never leave `lib/secrets.js` raw: findings carry a masked
+  placeholder (`AKIA…[redacted 20 chars]`), a line/column and a rule id.
+  `redactText()` is applied to command previews and git output. Tool results
+  and debug logs contain no raw token values.
+- Hook logs contain only the event/tool name and the rule id — never command
+  text, target paths or secret values.
+- Scanned files are never executed; the scanner performs no network I/O and
+  no writes. `git diff --check` is invoked with fixed arguments and a timeout.
+- All matches are bounded by policy limits; the scanner skips symlinks and
+  binary content.
+
+## Limitations
+
+- These are heuristics, not a security boundary. Obfuscated commands
+  (base64, variable indirection, `python -c`, alternative shells), tools that
+  are not in the shell-name list, and PTC/`run_code` compositions can evade
+  the pre-execute rules. The plugin is a guardrail for a cooperative model,
+  not a sandbox — use the process sandbox/kernel isolation for untrusted code.
+- `fs/*-intent` is a single-slot waterfall: another first-wins policy mounted
+  before this plugin can own the slot. The pre-execute path check is the
+  fallback for `write`/`edit`/`apply_patch`; a path protection that must be
+  absolute belongs in a provider-level fence.
+- `ask` rules degrade to a denial when the DSH approval channel is missing or
+  the call has no agent.
+- The command rules intentionally accept some false positives (`TRUNCATE` in
+  prose, `echo`/`copy` mentioning key files in scripts). Adjust or disable a
+  rule in `guardrails.json` when a project needs an exception. `.env.example`,
+  `.env.sample`, `.env.template` and `.env.dist` stay writable by default.
+- `check` reports a protected path per file found in the tree, not per
+  directory; an empty `.ssh/` directory is not reported.
+- Windows path matching is case-insensitive; POSIX matching uses the same
+  case-insensitive regexes (conservative over-matching, not under-matching).
+- Scan limits are caps, not coverage guarantees: skipped/oversized/binary
+  counts are reported, and a truncated result is marked.
+
+## Tests
+
+```powershell
+cd plugins/dsh-guardrails
+node tools/guardrails-tests.mjs
+```
+
+The suite has no kit dependency. It covers the pure policy functions (kill
+switch, defaults, merge, clamping, protected paths, command verdicts),
+secret detection/redaction, the bounded scan (including `git diff --check`
+when `git` is available) and the exact event decision shapes with a fake
+Cordis context. Expected result: `guardrails tests: OK (39 tests)`.
+
+## Files
+
+```text
+dsh-guardrails/
+├── package.json          # package manifest + dsh bundle patch
+├── cordis.patch.yml      # Host row inserted by the kit
+├── index.js              # inject, guardrails tool, apply()
+├── lib/
+│   ├── hooks.js          # tools/pre-execute + fs/*-intent listeners
+│   ├── policy.js         # defaults, JSON merge, matching, kill switch
+│   ├── scan.js           # bounded worktree scan + git diff --check
+│   └── secrets.js        # secret regexes, findings, redaction
+├── tools/
+│   └── guardrails-tests.mjs
+└── README.md
+```

package/plugins/dsh-guardrails/cordis.patch.yml

@@ -0,0 +1,5 @@
+# Host guardrails: shell-command policy, protected-path hooks and a
+# read-only guardrails tool. Mounts as a child plugin of the kit entry.
+- insert:
+    - id: guardrails
+      name: dsh-guardrails

package/plugins/dsh-guardrails/index.js

@@ -0,0 +1,389 @@
+/**
+ * dsh-guardrails — Host half.
+ *
+ * Three capabilities, all local and read-only except for the mutations it
+ * refuses:
+ *
+ *  - `guardrails` tool: `status` (effective rules, protected paths, hook
+ *    state), `check` (bounded worktree scan for secrets, .env files,
+ *    protected paths, oversized files, dangerous script commands and
+ *    `git diff --check`) and `policy` (effective JSON policy).
+ *  - `tools/pre-execute` hook: deny/ask dangerous shell commands and protect
+ *    file-mutating tool arguments before dispatch.
+ *  - `fs/write-intent`, `fs/edit-intent`, `fs/delete-intent` hooks: refuse
+ *    writes, edits and deletions of protected paths at the filesystem seam.
+ *
+ * No network, no LLM, Node built-ins only. The documented bypass is the
+ * `DSH_GUARDRAILS=off` environment variable or the user policy file
+ * `<DSH_HOME>/guardrails.json`.
+ */
+import fs from "node:fs";
+import path from "node:path";
+
+import { createGuard, createHookState, registerHooks } from "./lib/hooks.js";
+import { resolveMode } from "./lib/modes.js";
+import {
+  DEFAULT_COMMAND_RULES,
+  DEFAULT_PROTECTED_PATHS,
+  KILL_SWITCH_ENV,
+  credentialsPath,
+  loadPolicy,
+  policyPath,
+} from "./lib/policy.js";
+import { scanProject } from "./lib/scan.js";
+
+/** Tool and hook plugin depends on the tool registry only. */
+export const inject = ["tools"];
+
+const PLUGIN_NAME = "dsh-guardrails";
+const PLUGIN_VERSION = "1.0.0";
+const ACTIONS = ["status", "check", "policy"];
+const DEFAULT_ACTION = "status";
+const TEXT_LIMIT = 24_000;
+
+const DEFAULT_RULE_IDS = new Set(DEFAULT_COMMAND_RULES.map((rule) => rule.id));
+const DEFAULT_PROTECTED_IDS = new Set(DEFAULT_PROTECTED_PATHS.map((entry) => entry.id));
+
+function messageOf(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function truncate(text, maximum = TEXT_LIMIT) {
+  const value = String(text ?? "");
+  return value.length <= maximum ? value : `${value.slice(0, Math.max(0, maximum - 1))}…`;
+}
+
+function rootOf(args, exec) {
+  const explicit = typeof args?.root === "string" ? args.root.trim() : "";
+  const sessionCwd = exec?.agent?.session?.header?.cwd;
+  return path.resolve(explicit.length > 0 ? explicit : typeof sessionCwd === "string" && sessionCwd.length > 0 ? sessionCwd : process.cwd());
+}
+
+function finiteOverride(value) {
+  const number = Number(value);
+  return Number.isFinite(number) ? number : undefined;
+}
+
+/* ------------------------------------------------------------------ */
+/* status                                                              */
+/* ------------------------------------------------------------------ */
+
+function statusValue(loaded, hookState) {
+  const ruleList = loaded.policy.rules.map((rule) => ({
+    id: rule.id,
+    severity: rule.severity,
+    enabled: rule.enabled !== false,
+    description: rule.description,
+    source: DEFAULT_RULE_IDS.has(rule.id) ? "default" : "policy",
+  }));
+  const enabledRules = ruleList.filter((rule) => rule.enabled);
+  const protectedList = loaded.policy.protectedPaths.map((entry) => ({
+    id: entry.id,
+    enabled: entry.enabled !== false,
+    match: entry.match,
+    pattern: entry.pattern,
+    description: entry.description,
+    source: DEFAULT_PROTECTED_IDS.has(entry.id) ? "default" : "policy",
+  }));
+  const enabledProtected = protectedList.filter((entry) => entry.enabled);
+  const hooks = {
+    toolsPreExecute: hookState.toolsPreExecute,
+    fsWriteIntent: hookState.fsWriteIntent,
+    fsEditIntent: hookState.fsEditIntent,
+    fsDeleteIntent: hookState.fsDeleteIntent,
+    allRegistered:
+      hookState.toolsPreExecute && hookState.fsWriteIntent && hookState.fsEditIntent && hookState.fsDeleteIntent,
+    configured: { ...loaded.policy.hooks },
+    errors: hookState.errors,
+  };
+  const value = {
+    ok: true,
+    enabled: loaded.enabled,
+    plugin: { name: PLUGIN_NAME, version: PLUGIN_VERSION },
+    killSwitch: {
+      active: loaded.killSwitch,
+      variable: KILL_SWITCH_ENV,
+      acceptedValues: ["off", "0", "false", "disabled"],
+    },
+    policy: {
+      path: loaded.path,
+      exists: loaded.exists,
+      loadedFromFile: loaded.loadedFromFile,
+      version: loaded.policy.version,
+      error: loaded.error,
+      warnings: loaded.warnings,
+      askBehavior: loaded.policy.askBehavior,
+    },
+    hooks,
+    rules: {
+      total: ruleList.length,
+      enabled: enabledRules.length,
+      list: enabledRules,
+      disabled: ruleList.filter((rule) => !rule.enabled).map((rule) => rule.id),
+    },
+    protectedPaths: {
+      total: protectedList.length,
+      enabled: enabledProtected.length,
+      list: enabledProtected,
+      disabled: protectedList.filter((entry) => !entry.enabled).map((entry) => entry.id),
+    },
+    credentialsPath: credentialsPath(process.env),
+    limits: loaded.policy.limits,
+    bypass: [
+      `${KILL_SWITCH_ENV}=off (process environment)`,
+      "policy.enabled=false or policy.hooks.{toolsPreExecute,fsIntents}=false",
+      "a rule or protected path entry with enabled=false",
+    ],
+    text: "",
+  };
+  value.text = renderStatus(value);
+  return value;
+}
+
+function renderStatus(value) {
+  const lines = [];
+  const policyState = value.policy.loadedFromFile
+    ? `loaded from ${value.policy.path}`
+    : value.policy.exists
+      ? `${value.policy.path} is invalid, defaults in force`
+      : `defaults (no ${value.policy.path})`;
+  lines.push(`${PLUGIN_NAME} ${PLUGIN_VERSION} — ${value.enabled ? "ENABLED" : "DISABLED"} (${policyState})`);
+  if (value.policy.error) lines.push(`Policy error: ${value.policy.error}`);
+  for (const warning of value.policy.warnings.slice(0, 10)) lines.push(`Policy warning: ${truncate(warning, 300)}`);
+  lines.push(
+    `Kill switch: ${value.killSwitch.variable}=off disables every hook (currently ${value.killSwitch.active ? "ACTIVE" : "inactive"})`,
+  );
+  lines.push(
+    `Hooks: tools/pre-execute=${value.hooks.toolsPreExecute ? "on" : "off"} · fs/write-intent=${value.hooks.fsWriteIntent ? "on" : "off"} · fs/edit-intent=${value.hooks.fsEditIntent ? "on" : "off"} · fs/delete-intent=${value.hooks.fsDeleteIntent ? "on" : "off"}`,
+  );
+  if (value.hooks.errors.length > 0) {
+    for (const error of value.hooks.errors.slice(0, 5)) lines.push(`Hook error: ${error.event}: ${truncate(error.message, 200)}`);
+  }
+  const denyCount = value.rules.list.filter((rule) => rule.severity === "deny").length;
+  const askCount = value.rules.list.filter((rule) => rule.severity === "ask").length;
+  lines.push(`Command rules: ${value.rules.enabled}/${value.rules.total} enabled (deny ${denyCount}, ask ${askCount})`);
+  for (const rule of value.rules.list) lines.push(`- ${rule.severity.toUpperCase().padEnd(4)} ${rule.id} — ${truncate(rule.description, 160)}`);
+  if (value.rules.disabled.length > 0) lines.push(`Disabled rules: ${value.rules.disabled.join(", ")}`);
+  lines.push(`Protected paths: ${value.protectedPaths.enabled}/${value.protectedPaths.total} enabled`);
+  for (const entry of value.protectedPaths.list) {
+    lines.push(`- ${entry.id} (${entry.match} /${truncate(entry.pattern, 120)}/) — ${truncate(entry.description, 120)}`);
+  }
+  if (value.protectedPaths.disabled.length > 0) {
+    lines.push(`Disabled protected paths: ${value.protectedPaths.disabled.join(", ")}`);
+  }
+  lines.push(`DSH credentials file: ${value.credentialsPath}`);
+  lines.push(
+    `Limits: maxFiles=${value.limits.maxFiles}, maxFileSizeBytes=${value.limits.maxFileSizeBytes}, maxTotalBytes=${value.limits.maxTotalBytes}, maxFindings=${value.limits.maxFindings}, maxDepth=${value.limits.maxDepth}`,
+  );
+  lines.push("Bypass: DSH_GUARDRAILS=off · policy.enabled=false · policy hooks off · individual rule disabled");
+  return lines.join("\n");
+}
+
+/* ------------------------------------------------------------------ */
+/* policy                                                              */
+/* ------------------------------------------------------------------ */
+
+function policyValue(loaded) {
+  const value = {
+    ok: true,
+    path: loaded.path,
+    exists: loaded.exists,
+    loadedFromFile: loaded.loadedFromFile,
+    error: loaded.error,
+    warnings: loaded.warnings,
+    killSwitch: loaded.killSwitch,
+    enabled: loaded.enabled,
+    policy: loaded.policy,
+    text: "",
+  };
+  value.text = truncate(JSON.stringify({
+    path: value.path,
+    loadedFromFile: value.loadedFromFile,
+    error: value.error,
+    warnings: value.warnings,
+    killSwitch: value.killSwitch,
+    enabled: value.enabled,
+    policy: value.policy,
+  }, null, 2));
+  return value;
+}
+
+/* ------------------------------------------------------------------ */
+/* check                                                               */
+/* ------------------------------------------------------------------ */
+
+async function checkValue(loaded, args, exec, logger) {
+  const root = rootOf(args, exec);
+  if (!loaded.enabled) {
+    return {
+      ok: true,
+      enabled: false,
+      root,
+      skipped: true,
+      reason: loaded.killSwitch
+        ? `kill switch ${KILL_SWITCH_ENV} is active`
+        : `guardrails policy is disabled (${loaded.path})`,
+      findings: [],
+      text: "Guardrails are disabled; nothing was scanned. Re-enable by unsetting DSH_GUARDRAILS or setting policy.enabled=true.",
+    };
+  }
+  let rootStat;
+  try {
+    rootStat = fs.statSync(root);
+  } catch {
+    return { ok: false, enabled: true, root, error: `root does not exist: ${root}`, findings: [], text: `guardrails check: root does not exist: ${root}` };
+  }
+  if (!rootStat.isDirectory()) {
+    return { ok: false, enabled: true, root, error: `root is not a directory: ${root}`, findings: [], text: `guardrails check: not a directory: ${root}` };
+  }
+  const overrides = {};
+  const maxFiles = finiteOverride(args?.maxFiles);
+  if (maxFiles !== undefined) overrides.maxFiles = maxFiles;
+  const maxFileSizeBytes = finiteOverride(args?.maxFileSizeBytes);
+  if (maxFileSizeBytes !== undefined) overrides.maxFileSizeBytes = maxFileSizeBytes;
+  const maxFindings = finiteOverride(args?.maxFindings);
+  if (maxFindings !== undefined) overrides.maxFindings = maxFindings;
+  const report = await scanProject({ root, policy: loaded.policy, env: process.env, signal: exec?.signal, overrides, logger });
+  const value = {
+    enabled: true,
+    policy: {
+      path: loaded.path,
+      loadedFromFile: loaded.loadedFromFile,
+      error: loaded.error,
+      warnings: loaded.warnings,
+    },
+    ...report,
+    text: "",
+  };
+  value.text = renderScanReport(value);
+  return value;
+}
+
+function severityCounts(findings) {
+  const counts = { critical: 0, high: 0, medium: 0, low: 0 };
+  for (const finding of findings) {
+    if (Object.hasOwn(counts, finding.severity)) counts[finding.severity] += 1;
+  }
+  return counts;
+}
+
+function renderScanReport(value) {
+  if (value.ok === false) return `guardrails check: ${value.error ?? "scan failed"}`;
+  const stats = value.stats;
+  const lines = [];
+  lines.push(`Guardrails scan (read-only, no network): ${value.root}`);
+  lines.push(
+    `Files: scanned ${stats.filesScanned}, considered ${stats.filesConsidered}, bytes ${stats.bytesRead}, directories ${stats.directoriesVisited}`,
+  );
+  lines.push(
+    `Skipped: binary ${stats.skipped.binary}, oversized ${stats.skipped.oversized}, symlinks ${stats.skipped.symlinks}, depth-limit ${stats.skipped.depthLimit}, unreadable ${stats.skipped.unreadable}`,
+  );
+  const limitsHit = Object.entries(stats.limitsHit).filter(([, hit]) => hit === true).map(([key]) => key);
+  if (limitsHit.length > 0) lines.push(`Limits hit: ${limitsHit.join(", ")} (results are partial)`);
+  const findings = value.findings ?? [];
+  if (findings.length === 0) {
+    lines.push("Findings: none");
+  } else {
+    const counts = severityCounts(findings);
+    lines.push(
+      `Findings: ${findings.length}${value.findingsTruncated ? " (truncated)" : ""} — critical ${counts.critical}, high ${counts.high}, medium ${counts.medium}, low ${counts.low}`,
+    );
+    for (const finding of findings.slice(0, 40)) {
+      const location = finding.line !== undefined ? `${finding.path}:${finding.line}` : String(finding.path ?? "?");
+      const masked = typeof finding.masked === "string" ? ` [masked: ${finding.masked}]` : "";
+      lines.push(`- ${String(finding.severity).toUpperCase()} ${finding.kind}/${finding.rule} — ${location} — ${truncate(finding.message, 200)}${masked}`);
+    }
+    if (findings.length > 40) lines.push(`… ${findings.length - 40} more finding(s) are in the JSON value`);
+  }
+  if (value.gitDiffCheck != null) {
+    lines.push(
+      `git diff --check: ${value.gitDiffCheck.available ? value.gitDiffCheck.message : `unavailable (${value.gitDiffCheck.message})`}`,
+    );
+  }
+  if (value.aborted) lines.push("Scan aborted by cancellation; partial results only.");
+  lines.push("Scanned files are never executed; secret values are redacted in this result.");
+  return lines.join("\n");
+}
+
+/* ------------------------------------------------------------------ */
+/* Plugin entry                                                        */
+/* ------------------------------------------------------------------ */
+
+export function apply(ctx) {
+  const env = process.env;
+  const logger = ctx?.logger;
+  const hookState = createHookState();
+  const guard = createGuard({ env, logger, modeFor: (agent) => resolveMode(ctx, agent) });
+  try {
+    registerHooks(ctx, guard, hookState);
+  } catch (error) {
+    hookState.errors.push({ event: "registration", message: messageOf(error) });
+    logger?.warn?.(`[guardrails] hook registration failed: ${messageOf(error)}`);
+  }
+
+  const tool = {
+    name: "guardrails",
+    description:
+      "Read-only guardrails control and security scan. `status` shows effective command rules, protected paths, hook registration and the DSH_GUARDRAILS kill switch. `check` scans a project or worktree with strict limits (no network) for secrets, .env files, protected paths, oversized files, dangerous commands in shell scripts and `git diff --check`; token values are redacted. `policy` prints the effective JSON policy. Scanning never executes files and never writes.",
+    parameters: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        action: {
+          type: "string",
+          enum: ACTIONS,
+          description: "status (rules, protected paths, hooks) | check (bounded read-only scan) | policy (effective JSON policy).",
+        },
+        root: {
+          type: "string",
+          description: "Absolute project/worktree root for check; defaults to the current Session cwd.",
+        },
+        maxFiles: {
+          type: "integer",
+          description: "Override the check file cap (1..5000, default from policy 800).",
+        },
+        maxFileSizeBytes: {
+          type: "integer",
+          description: "Override the per-file byte cap for check (256..16777216, default 262144). Larger files are reported, not read.",
+        },
+        maxFindings: {
+          type: "integer",
+          description: "Override the findings cap for check (1..2000, default 200).",
+        },
+      },
+      required: ["action"],
+    },
+    timeoutMs: 30_000,
+    output: {
+      schema: { type: "object", additionalProperties: true },
+      render(_args, value) {
+        const text = typeof value?.text === "string" ? value.text : JSON.stringify(value);
+        return [{ type: "text", text: truncate(text) }];
+      },
+    },
+    async execute(args, exec) {
+      try {
+        const action = typeof args?.action === "string" ? args.action : DEFAULT_ACTION;
+        const loaded = loadPolicy({ env });
+        if (action === "policy") return policyValue(loaded);
+        if (action === "status") return statusValue(loaded, hookState);
+        if (action === "check") return await checkValue(loaded, args, exec, logger);
+        return {
+          ok: false,
+          enabled: loaded.enabled,
+          error: `unknown action: ${action}`,
+          text: `guardrails: unknown action "${action}". Available actions: ${ACTIONS.join(", ")}.`,
+        };
+      } catch (error) {
+        return {
+          ok: false,
+          error: messageOf(error),
+          text: `guardrails: ${messageOf(error)}`,
+        };
+      }
+    },
+  };
+
+  ctx.tools.register(tool);
+  logger?.info?.(`[guardrails] tool ready (policy: ${policyPath(env)})`);
+}