dsh-decision-layer 0.4.0

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Decision Layer",
+    "description": "A structured decision layer for the DeepSeek Harness agent loop: a danger-call gate, output self-check, and loop guard backed by a pluggable adjudication model."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "决策层",
+    "description": "为 DeepSeek Harness agent 循环提供的结构化决策层：危险调用门控、产出自检与防循环，由可插拔的裁决模型驱动。"
+  }
+}

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "dsh-decision-layer",
+  "version": "0.4.0",
+  "description": "A structured decision layer for the DeepSeek Harness agent loop: a danger-call gate, output self-check, tool narrowing, and loop guard backed by a pluggable adjudication model.",
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "deepseek-harness-plugin",
+    "decision-layer",
+    "ai-agents"
+  ],
+  "author": "xbzbing",
+  "license": "MIT",
+  "type": "module",
+  "icon": "./icon.svg",
+  "main": "./service/dsh.mjs",
+  "files": [
+    "service",
+    "skills",
+    "lib/client.js",
+    "locale/*.json",
+    "icon.svg",
+    "cordis.patch.yml",
+    "README.md",
+    "README.en.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20.11"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/xbzbing/dsh-decision-layer.git"
+  },
+  "scripts": {
+    "test": "node --test tests/*.test.mjs",
+    "build:client": "tsc -p tsconfig.client.json && node scripts/build-client.mjs"
+  },
+  "exports": {
+    ".": "./service/dsh.mjs",
+    "./client": "./lib/client.js",
+    "./locale/*.json": "./locale/*.json",
+    "./package.json": "./package.json"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "~4.0.4",
+    "@deepseek-ai/dsh": ">=0.1.7-rc.2"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-client-locale": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-client-ui-plugin-manager": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-client-ui-renderer": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-client-ui-slots": "0.1.7-rc.2",
+    "@testing-library/react": "^16.3.3",
+    "@types/react": "~18.3.1",
+    "@types/react-dom": "~18.3.0",
+    "esbuild": "^0.25.12",
+    "jsdom": "^26.1.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.3.1",
+    "typescript": "~5.9.3"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-renderer",
+        "@deepseek-ai/dsh-client-ui-slots",
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-plugin-manager"
+      ],
+      "platform": "web"
+    }
+  }
+}

package/service/backend.mjs

@@ -0,0 +1,127 @@
+import { setTimeout as wait } from 'node:timers/promises';
+import { DEFAULT_MODEL } from './config-store.mjs';
+
+const REQUEST_LIMIT = 256 * 1024;
+const RESPONSE_LIMIT = 1024 * 1024;
+const isObject = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+const isContent = value => typeof value === 'string' ? value.trim().length > 0 : isObject(value) || Array.isArray(value);
+const probability = value => typeof value === 'number' && Number.isFinite(value) && value >= 0 && value <= 1;
+
+// A backend failure carries a stable `reason` code so callers can surface the
+// specific cause (unreachable / http-error / invalid-response / config) instead
+// of a single generic error.
+function backendError(reason, message) {
+  const error = new Error(message);
+  error.reason = reason;
+  return error;
+}
+
+export function validateRequest(input) {
+  if (!isObject(input) || !isContent(input.state) || !isObject(input.questions)) throw new Error('Invalid state or questions');
+  const questions = Object.entries(input.questions);
+  if (questions.length < 1 || questions.length > 64) throw new Error('Invalid question count');
+  for (const [id, question] of questions) {
+    if (!id.trim() || id.length > 160 || !isObject(question) || !isContent(question.instructions)) throw new Error('Invalid question');
+    if (question.type === 'choice') {
+      if (!isObject(question.criteria) || Object.keys(question.criteria).length < 2 || Object.keys(question.criteria).length > 255 ||
+        Object.entries(question.criteria).some(([key, value]) => !key.trim() || (value !== null && !isContent(value)))) throw new Error('Invalid choice criteria');
+    } else if (question.type === 'score') {
+      if (!Array.isArray(question.criteria) || question.criteria.length < 2 || question.criteria.length > 10 || !question.criteria.every(isContent)) throw new Error('Invalid score criteria');
+    } else if (question.type !== 'noul' || (question.criteria !== undefined && (!isObject(question.criteria) || Object.keys(question.criteria).some(key => !['true', 'false'].includes(key))))) {
+      throw new Error('Invalid question type or criteria');
+    }
+  }
+  let encoded;
+  try {
+    encoded = JSON.stringify(input, (key, value) => {
+      if (typeof value === 'function' || typeof value === 'symbol' || typeof value === 'bigint' || (typeof value === 'number' && !Number.isFinite(value))) throw new Error('Invalid JSON');
+      return value;
+    });
+  } catch { throw new Error('Invalid JSON payload'); }
+  if (Buffer.byteLength(encoded) > REQUEST_LIMIT) throw new Error('Request too large');
+  return { state: input.state, questions: input.questions };
+}
+
+function validateAnswer(value, question) {
+  if (!isObject(value) || value.type !== question.type) throw backendError('invalid-response', 'Invalid response answer');
+  if (question.type === 'noul') {
+    if (!probability(value.noul)) throw backendError('invalid-response', 'Invalid response probability');
+    return { type: 'noul', noul: value.noul };
+  }
+  const keys = question.type === 'choice' ? Object.keys(question.criteria) : question.criteria.map((_, i) => String(i));
+  if (!isObject(value.probabilities) || !probability(value.confidence) ||
+    Object.keys(value.probabilities).length !== keys.length || keys.some(key => !probability(value.probabilities[key])) ||
+    Math.abs(keys.reduce((sum, key) => sum + value.probabilities[key], 0) - 1) > 0.02) throw backendError('invalid-response', 'Invalid response probabilities');
+  const common = { type: value.type, confidence: value.confidence, probabilities: Object.fromEntries(keys.map(key => [key, value.probabilities[key]])) };
+  if (question.type === 'choice') {
+    if (typeof value.choice !== 'string' || !keys.includes(value.choice)) throw backendError('invalid-response', 'Invalid response choice');
+    return { ...common, choice: value.choice };
+  }
+  if (typeof value.score !== 'number' || !Number.isFinite(value.score) || value.score < 0 || value.score > keys.length - 1) throw backendError('invalid-response', 'Invalid response score');
+  return { ...common, score: value.score };
+}
+
+function validateResponse(value, questions) {
+  if (!isObject(value) || !isObject(value.answers) || typeof value.model !== 'string') throw backendError('invalid-response', 'Invalid response');
+  const answers = Object.create(null);
+  for (const [id, question] of Object.entries(questions)) answers[id] = validateAnswer(value.answers[id], question);
+  return { model: value.model, answers, usage: isObject(value.usage) ? {
+    input_tokens: Number.isSafeInteger(value.usage.input_tokens) ? value.usage.input_tokens : 0,
+    output_tokens: Number.isSafeInteger(value.usage.output_tokens) ? value.usage.output_tokens : 0,
+  } : undefined };
+}
+
+async function boundedJson(response) {
+  const reader = response.body?.getReader();
+  if (!reader) throw backendError('invalid-response', 'Invalid response body');
+  const chunks = [];
+  let size = 0;
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      size += value.byteLength;
+      if (size > RESPONSE_LIMIT) throw backendError('invalid-response', 'Invalid response size');
+      chunks.push(value);
+    }
+  } finally { await reader.cancel().catch(() => {}); }
+  try { return JSON.parse(Buffer.concat(chunks).toString('utf8')); } catch { throw backendError('invalid-response', 'Invalid response JSON'); }
+}
+
+export function createBackend({ config, fetcher = globalThis.fetch, timeoutMs = 20_000, retryDelayMs = 200 }) {
+  if (typeof config !== 'function' || typeof fetcher !== 'function' ||
+    !Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || !Number.isSafeInteger(retryDelayMs) || retryDelayMs < 0 || retryDelayMs > 5000) {
+    throw new Error('Invalid backend dependencies');
+  }
+  return {
+    async evaluate(input, { signal } = {}) {
+      const { state, questions } = validateRequest(input);
+      const settings = await config();
+      const key = settings.apiKey?.trim();
+      if (!key || /[\r\n]/.test(key)) throw backendError('config', 'API key is required');
+      let url;
+      try { url = new URL(settings.url); } catch { throw backendError('config', 'Invalid backend URL'); }
+      if (!['https:', 'http:'].includes(url.protocol) || url.username || url.password || url.search || url.hash) throw backendError('config', 'Invalid backend URL');
+      if (url.protocol === 'http:' && settings.httpApprovedUrl !== settings.url) throw backendError('config', 'HTTP URL requires confirmation');
+      const model = settings.model || DEFAULT_MODEL;
+      if (typeof model !== 'string' || !model.trim() || /[\r\n]/.test(model)) throw backendError('config', 'Invalid model');
+      const endpoint = new URL(url.href);
+      endpoint.pathname = `${url.pathname.replace(/\/+$/, '')}/v1/systemone`;
+      if (endpoint.origin !== url.origin) throw backendError('config', 'Invalid backend endpoint');
+      const timeout = AbortSignal.timeout(timeoutMs);
+      const combined = signal ? AbortSignal.any([signal, timeout]) : timeout;
+      for (let attempt = 0; attempt < 3; attempt++) {
+        let reply;
+        try {
+          reply = await fetcher(endpoint.href, { method: 'POST', redirect: 'error', signal: combined,
+            headers: { authorization: `Bearer ${key}`, 'content-type': 'application/json' }, body: JSON.stringify({ state, questions, model }) });
+        } catch { throw backendError('unreachable', 'Backend request failed or timed out'); }
+        if (reply.ok) return validateResponse(await boundedJson(reply), questions);
+        await reply.body?.cancel().catch(() => {});
+        if (![429, 529].includes(reply.status) || attempt === 2) throw backendError('http-error', `Backend HTTP ${reply.status}`);
+        try { await wait(retryDelayMs * (attempt + 1), undefined, { signal: combined }); }
+        catch { throw backendError('unreachable', 'Backend request failed or timed out'); }
+      }
+    },
+  };
+}

package/service/config-store.mjs

@@ -0,0 +1,203 @@
+import { chmod, mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+export const DEFAULT_URL = 'https://api.typesafe.ai';
+export const DEFAULT_MODEL = 'jev-latest';
+
+export function configPath(env = process.env) {
+  return env.DSH_DECISION_CONFIG_PATH?.trim() || join(homedir(), '.config', 'dsh-decision-layer', 'config.json');
+}
+
+function safeObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+async function readStored(path) {
+  try {
+    const value = JSON.parse(await readFile(path, 'utf8'));
+    if (!safeObject(value)) throw new Error('Invalid decision configuration');
+    return value;
+  } catch (error) {
+    if (error?.code === 'ENOENT') return {};
+    throw error;
+  }
+}
+
+function safeText(value) {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+function checkedUrl(value) {
+  if (!value) return '';
+  let url;
+  try { url = new URL(value); } catch { throw new Error('Invalid URL'); }
+  if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.search || url.hash) {
+    throw new Error('Invalid URL: expected an HTTP(S) address without credentials, query or fragment');
+  }
+  return `${url.origin}${url.pathname.replace(/\/+$/, '')}`;
+}
+
+function validRules(value) {
+  if (!safeObject(value)) return undefined;
+  const fields = ['addToolNames', 'removeToolNames', 'addCommandPatterns', 'addPathPatterns'];
+  if (Object.keys(value).some(key => !fields.includes(key))) throw new Error('Invalid danger rules');
+  const rules = {};
+  for (const field of fields) {
+    if (value[field] !== undefined && (!Array.isArray(value[field]) || value[field].length > 64 || value[field].some(item => typeof item !== 'string' || !item.trim() || item.length > 128))) {
+      throw new Error('Invalid danger rules');
+    }
+    if (value[field] !== undefined) rules[field] = value[field].map(item => item.trim());
+  }
+  return rules;
+}
+
+function validCheck(value) {
+  if (!safeObject(value)) return undefined;
+  if (Object.keys(value).some(key => !['mode', 'rubric', 'lowScoreThreshold'].includes(key))) throw new Error('Invalid self-check settings');
+  const check = {};
+  if (value.mode !== undefined) {
+    if (value.mode !== 'observe' && value.mode !== 'steer') throw new Error('Invalid self-check settings');
+    check.mode = value.mode;
+  }
+  if (value.rubric !== undefined) {
+    if (!Array.isArray(value.rubric) || value.rubric.length > 10 || value.rubric.some(item => typeof item !== 'string' || !item.trim() || item.length > 256)) {
+      throw new Error('Invalid self-check settings');
+    }
+    check.rubric = value.rubric.map(item => item.trim());
+  }
+  if (value.lowScoreThreshold !== undefined) {
+    if (!Number.isSafeInteger(value.lowScoreThreshold) || value.lowScoreThreshold < 0 || value.lowScoreThreshold > 9) throw new Error('Invalid self-check settings');
+    check.lowScoreThreshold = value.lowScoreThreshold;
+  }
+  return check;
+}
+
+function validNarrow(value) {
+  if (!safeObject(value)) return undefined;
+  if (Object.keys(value).some(key => !['mode', 'threshold', 'keepPrefixes', 'maxCandidates'].includes(key))) throw new Error('Invalid narrowing settings');
+  const narrow = {};
+  if (value.mode !== undefined) {
+    if (value.mode !== 'observe' && value.mode !== 'enforce') throw new Error('Invalid narrowing settings');
+    narrow.mode = value.mode;
+  }
+  if (value.threshold !== undefined) {
+    if (typeof value.threshold !== 'number' || !Number.isFinite(value.threshold) || value.threshold < 0 || value.threshold > 1) throw new Error('Invalid narrowing settings');
+    narrow.threshold = value.threshold;
+  }
+  // Tool name prefixes that are always kept and never judged for relevance, on
+  // top of the built-in core tools. An explicit empty array clears the list; an
+  // absent field lets narrowing fall back to its own default (mcp__openviking).
+  if (value.keepPrefixes !== undefined) {
+    if (!Array.isArray(value.keepPrefixes) || value.keepPrefixes.length > 32 ||
+      value.keepPrefixes.some(item => typeof item !== 'string' || !item.trim() || item.length > 128)) {
+      throw new Error('Invalid narrowing settings');
+    }
+    narrow.keepPrefixes = value.keepPrefixes.map(item => item.trim());
+  }
+  // Optional-candidate ceiling: above this count, enforce is downgraded to
+  // observe so a large tool surface is never mass-pruned. 1–200; unset uses the
+  // narrowing default (20).
+  if (value.maxCandidates !== undefined) {
+    if (!Number.isSafeInteger(value.maxCandidates) || value.maxCandidates < 1 || value.maxCandidates > 200) throw new Error('Invalid narrowing settings');
+    narrow.maxCandidates = value.maxCandidates;
+  }
+  return narrow;
+}
+
+// Per-feature enable flags for the three decision points. Every flag defaults to
+// enabled; only an explicit `false` disables its decision point.
+export const FEATURE_KEYS = Object.freeze(['gate', 'check', 'narrow']);
+
+function validFeatures(value) {
+  if (!safeObject(value)) return undefined;
+  if (Object.keys(value).some(key => !FEATURE_KEYS.includes(key))) throw new Error('Invalid feature settings');
+  const features = {};
+  for (const key of FEATURE_KEYS) {
+    if (value[key] !== undefined) {
+      if (typeof value[key] !== 'boolean') throw new Error('Invalid feature settings');
+      features[key] = value[key];
+    }
+  }
+  return features;
+}
+
+// Resolve one decision point's enablement, defaulting to enabled when unset.
+export function featureEnabled(features, key) {
+  return !(safeObject(features) && features[key] === false);
+}
+
+function view(stored) {
+  const result = {
+    url: safeText(stored.url),
+    model: safeText(stored.model),
+    apiKeySet: Boolean(safeText(stored.apiKey)),
+    httpApprovedUrl: safeText(stored.httpApprovedUrl),
+  };
+  if (stored.dangerRules !== undefined) result.dangerRules = validRules(stored.dangerRules);
+  if (stored.checkSettings !== undefined) result.checkSettings = validCheck(stored.checkSettings);
+  if (stored.narrowSettings !== undefined) result.narrowSettings = validNarrow(stored.narrowSettings);
+  if (stored.features !== undefined) result.features = validFeatures(stored.features);
+  return result;
+}
+
+export async function loadConfig(path = configPath()) {
+  return view(await readStored(path));
+}
+
+export async function resolveConfig({ path = configPath(), env = process.env } = {}) {
+  const stored = await readStored(path);
+  const url = checkedUrl(safeText(stored.url) || safeText(env.DSH_DECISION_BASE_URL) || safeText(env.TYPESAFE_BASE_URL) || DEFAULT_URL);
+  const resolved = {
+    url,
+    apiKey: safeText(stored.apiKey) || safeText(env.DSH_DECISION_API_KEY) || safeText(env.TYPESAFE_API_KEY),
+    model: safeText(stored.model) || safeText(env.DSH_DECISION_MODEL) || DEFAULT_MODEL,
+    httpApprovedUrl: safeText(stored.httpApprovedUrl),
+  };
+  if (stored.dangerRules !== undefined) resolved.dangerRules = validRules(stored.dangerRules);
+  if (stored.checkSettings !== undefined) resolved.checkSettings = validCheck(stored.checkSettings);
+  if (stored.narrowSettings !== undefined) resolved.narrowSettings = validNarrow(stored.narrowSettings);
+  if (stored.features !== undefined) resolved.features = validFeatures(stored.features);
+  return resolved;
+}
+
+export async function saveConfig(input, path = configPath()) {
+  if (!safeObject(input) || Object.keys(input).some(key => !['url', 'apiKey', 'model', 'confirmHttpUrl', 'dangerRules', 'checkSettings', 'narrowSettings', 'features'].includes(key))) {
+    throw new Error('Invalid configuration fields');
+  }
+  for (const key of ['url', 'apiKey', 'model', 'confirmHttpUrl']) {
+    if (input[key] !== undefined && typeof input[key] !== 'string') throw new Error(`Invalid ${key}`);
+  }
+  const previous = await readStored(path);
+  const url = checkedUrl(safeText(input.url === undefined ? previous.url : input.url));
+  const apiKey = safeText(input.apiKey === undefined ? previous.apiKey : input.apiKey);
+  const model = safeText(input.model === undefined ? previous.model : input.model);
+  if (model.length > 128 || /[\r\n]/.test(input.model ?? '') || /[\r\n]/.test(input.apiKey ?? '')) {
+    throw new Error('Invalid model or API key');
+  }
+  const dangerRules = input.dangerRules === undefined ? previous.dangerRules : validRules(input.dangerRules);
+  const checkSettings = input.checkSettings === undefined ? previous.checkSettings : validCheck(input.checkSettings);
+  const narrowSettings = input.narrowSettings === undefined ? previous.narrowSettings : validNarrow(input.narrowSettings);
+  const features = input.features === undefined ? previous.features : validFeatures(input.features);
+  const confirmed = url.startsWith('http://') && input.confirmHttpUrl !== undefined &&
+    checkedUrl(safeText(input.confirmHttpUrl)) === url;
+  if (url.startsWith('http://') && !confirmed && previous.httpApprovedUrl !== url) {
+    throw new Error('HTTP URL requires explicit confirmation');
+  }
+  const next = { url, apiKey, model, httpApprovedUrl: url.startsWith('http://') ? url : '' };
+  if (dangerRules !== undefined) next.dangerRules = dangerRules;
+  if (checkSettings !== undefined) next.checkSettings = checkSettings;
+  if (narrowSettings !== undefined) next.narrowSettings = narrowSettings;
+  if (features !== undefined) next.features = features;
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+  const temporary = `${path}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(temporary, `${JSON.stringify(next)}\n`, { mode: 0o600, flag: 'wx' });
+    await chmod(temporary, 0o600);
+    await rename(temporary, path);
+  } finally {
+    await rm(temporary, { force: true });
+  }
+  return view(next);
+}

package/service/danger-gate.mjs

@@ -0,0 +1,143 @@
+const DEFAULT_COMMAND_PATTERNS = Object.freeze([
+  /\brm\b(?=[^\n]*(?:\s-r(?:f|fr)?\b|\s--recursive\b|\s--force\b))/i,
+  /\bgit\s+push\b[^\n]*(?:\s-f\b|\s--force(?:-with-lease)?\b)/i,
+  /\b(?:drop|truncate)\s+(?:table|database)\b/i,
+  /\bkubectl\s+delete\b/i,
+  /\b(?:prod|production)\b[^\n]*\b(?:write|deploy|config|secret)\b/i,
+]);
+const DEFAULT_PATH_PATTERNS = Object.freeze([/(?:^|[\\/])(?:etc|production|prod)[\\/]/i, /(?:^|[\\/])\.env(?:$|\.)/i]);
+const COMMAND_KEYS = new Set(['command', 'cmd', 'script', 'query']);
+const PATH_KEYS = new Set(['path', 'file_path', 'filePath', 'target', 'file', 'filename', 'directory']);
+const MAX_RULES = 64;
+const MAX_PATTERN_LENGTH = 128;
+const MAX_METADATA_LENGTH = 2048;
+export const MIN_CONFIDENCE = 0.7;
+
+export const DEFAULT_DANGEROUS_RULES = Object.freeze({
+  toolNames: Object.freeze(['bash', 'pwsh', 'shell', 'exec', 'terminal', 'run_command', 'write', 'edit', 'str_replace_editor', 'file_write', 'write_file']),
+  commandPatterns: DEFAULT_COMMAND_PATTERNS,
+  pathPatterns: DEFAULT_PATH_PATTERNS,
+});
+
+const redact = value => value.slice(0, MAX_METADATA_LENGTH)
+  .replace(/(password|passwd|secret|token|api[_-]?key)\s*[:=]\s*\S+/gi, '$1=[redacted]')
+  .replace(/(password|passwd|secret|token|api[_-]?key)\s+\S+/gi, '$1 [redacted]');
+const literalPattern = value => new RegExp(value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'i');
+const boundedList = value => Array.isArray(value) ? value.filter(item => typeof item === 'string' && item.trim() && item.length <= MAX_PATTERN_LENGTH).slice(0, MAX_RULES) : [];
+
+function collectMetadata(value, depth = 0, commands = [], paths = []) {
+  if (depth > 4 || value === null || typeof value !== 'object') return;
+  for (const [key, item] of Object.entries(value)) {
+    const normalized = key.toLowerCase();
+    if (typeof item === 'string' && COMMAND_KEYS.has(normalized)) commands.push(redact(item));
+    else if (typeof item === 'string' && PATH_KEYS.has(normalized)) paths.push(redact(item));
+    else if (item && typeof item === 'object' && !['content', 'body', 'data', 'metadata', 'headers', 'env', 'value'].includes(normalized)) {
+      collectMetadata(item, depth + 1, commands, paths);
+    }
+  }
+  return { commands, paths };
+}
+
+export function summarizeExecution(exec) {
+  const commands = [];
+  const paths = [];
+  const collected = collectMetadata(exec?.arguments, 0, commands, paths);
+  return { tool: typeof exec?.name === 'string' ? exec.name.slice(0, 128) : '',
+    command: commands.join('\n').slice(0, MAX_METADATA_LENGTH), path: paths.join('\n').slice(0, MAX_METADATA_LENGTH),
+    inspectable: Boolean(collected) };
+}
+
+export function normalizeDangerRules(input = {}) {
+  const addTools = boundedList(input.addToolNames);
+  const removeTools = new Set(boundedList(input.removeToolNames));
+  const tools = [...new Set([...DEFAULT_DANGEROUS_RULES.toolNames, ...addTools])].filter(tool => !removeTools.has(tool));
+  const commands = [...DEFAULT_COMMAND_PATTERNS, ...boundedList(input.addCommandPatterns).map(literalPattern)];
+  const paths = [...DEFAULT_PATH_PATTERNS, ...boundedList(input.addPathPatterns).map(literalPattern)];
+  return { toolNames: tools, commandPatterns: commands, pathPatterns: paths };
+}
+
+export function classifyDangerous(exec, rules = DEFAULT_DANGEROUS_RULES) {
+  const normalized = Array.isArray(rules.toolNames) ? rules : normalizeDangerRules(rules);
+  const summary = summarizeExecution(exec);
+  if (!normalized.toolNames.includes(summary.tool)) return { dangerous: false, reason: 'Tool is outside the dangerous-call rules' };
+  if (!summary.inspectable) return { dangerous: true, reason: 'Dangerous call arguments could not be inspected' };
+  const byCommand = normalized.commandPatterns.some(pattern => pattern.test(summary.command));
+  const byPath = normalized.pathPatterns.some(pattern => pattern.test(summary.path));
+  return { dangerous: byCommand || byPath || (!summary.command && !summary.path), reason: 'Dangerous tool call requires a host decision' };
+}
+
+function suggestionQuestion(exec) {
+  return {
+    state: summarizeExecution(exec),
+    questions: { verdict: {
+      type: 'choice', instructions: 'Classify this dangerous tool call. Never grant a permission the host has not already granted.',
+      criteria: { allow: 'No additional intervention is recommended', ask: 'Ask the host user for approval', deny: 'Reject this dangerous call' },
+    } },
+  };
+}
+
+export function createDangerGate({ evaluate, sessions, rules = DEFAULT_DANGEROUS_RULES, minConfidence = MIN_CONFIDENCE } = {}) {
+  if (typeof evaluate !== 'function') throw new Error('Danger gate requires an evaluator');
+  const resolveRules = async () => {
+    if (typeof rules !== 'function') return rules;
+    try { return (await rules()) ?? DEFAULT_DANGEROUS_RULES; } catch { return DEFAULT_DANGEROUS_RULES; }
+  };
+  const deniedCalls = new WeakSet();
+  const evaluatedCalls = new WeakSet();
+  const record = (exec, outcome, detail = {}) => {
+    const id = exec?.agent?.session?.id;
+    if (!sessions || typeof id !== 'string') return;
+    try { sessions.record(id, 'gate', outcome); } catch { /* metrics cannot change the security decision */ }
+    if (typeof sessions.log !== 'function') return;
+    try { sessions.log(id, { kind: 'gate', outcome, tool: exec?.name, ...detail }); }
+    catch { /* logging is best effort */ }
+  };
+  const fallback = (exec, reason = 'unavailable', detail = {}) => {
+    record(exec, 'error', { action: 'ask', reason, ...detail });
+    if (exec && typeof exec === 'object') evaluatedCalls.add(exec);
+    return { kind: 'ask', reason: 'Dangerous call requires host approval' };
+  };
+  return {
+    classify: exec => classifyDangerous(exec, typeof rules === 'function' ? DEFAULT_DANGEROUS_RULES : rules),
+    guardReason(exec) {
+      if (!exec || !deniedCalls.has(exec)) return undefined;
+      deniedCalls.delete(exec);
+      return 'Dangerous call rejected by decision policy';
+    },
+    observeResult(exec, result) {
+      if (!evaluatedCalls.has(exec) || !sessions || typeof sessions.recordActual !== 'function') return;
+      const id = exec?.agent?.session?.id;
+      if (typeof id !== 'string') return;
+      try { sessions.recordActual(id, result?.isError ? 'deny' : 'allow'); } catch { /* telemetry is best effort */ }
+      evaluatedCalls.delete(exec);
+    },
+    async evaluate(exec) {
+      if (exec && typeof exec === 'object') evaluatedCalls.add(exec);
+      let result;
+      try {
+        result = await evaluate(suggestionQuestion(exec), { signal: exec.signal });
+      } catch (error) { return fallback(exec, typeof error?.reason === 'string' ? error.reason : 'unreachable'); }
+      const answer = result?.answers?.verdict;
+      const choice = answer?.choice;
+      if (!['allow', 'ask', 'deny'].includes(choice)) return fallback(exec, 'invalid-response');
+      if (typeof answer.confidence !== 'number' || answer.confidence < minConfidence) return fallback(exec, 'low-confidence', typeof answer.confidence === 'number' && Number.isFinite(answer.confidence) ? { confidence: answer.confidence } : {});
+      if (choice === 'deny') { record(exec, 'deny', { suggestion: 'deny', action: 'deny' }); if (exec && typeof exec === 'object') deniedCalls.add(exec); return { kind: 'deny', reason: 'Dangerous call rejected by decision policy', modelSuggestion: choice }; }
+      record(exec, choice, { suggestion: choice, action: 'ask' });
+      return { kind: 'ask', reason: 'Dangerous call requires host approval', modelSuggestion: choice };
+    },
+    async preExecute(exec, next) {
+      const classification = classifyDangerous(exec, await resolveRules());
+      if (!classification.dangerous) return next();
+      const id = exec?.agent?.session?.id;
+      if (sessions && typeof id === 'string') {
+        try {
+          const snapshot = sessions.snapshot(id);
+          // A deliberate user toggle bypasses the gate; involuntary capacity overflow must not fail-open.
+          if (snapshot.enabled === false && !snapshot.capacityExceeded) return next();
+          if (snapshot.capacityExceeded) return fallback(exec, 'capacity');
+        } catch { return fallback(exec, 'unreachable'); }
+      }
+      return this.evaluate(exec);
+    },
+  };
+}