dsh-desktop-kit 2.2.1 → 2.7.2

package/plugins/dsh-agent-extensions/lib/checkpoints.js

@@ -0,0 +1,103 @@
+/**
+ * Safe git checkpoints for agent extensions.
+ *
+ * Unlike a normal `git add`, this builds a tree through a temporary index, so
+ * the user's staged changes and HEAD stay untouched. Restore uses
+ * `git restore --source=<commit> --worktree -- .`: it restores tracked files
+ * from the snapshot but never deletes files created later.
+ */
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+
+function git(cwd, args, env, allowFail = false) {
+  const result = spawnSync("git", args, {
+    cwd,
+    encoding: "utf8",
+    timeout: 30_000,
+    windowsHide: true,
+    env: { ...process.env, ...(env ?? {}) },
+  });
+  if (result.error) throw new Error(`git ${args[0]}: ${result.error.message}`);
+  if (result.status !== 0 && !allowFail) {
+    throw new Error(`git ${args.join(" ")}: ${(result.stderr || result.stdout || "").trim()}`);
+  }
+  return { ok: result.status === 0, stdout: result.stdout ?? "", stderr: result.stderr ?? "" };
+}
+
+export function repoRoot(cwd) {
+  return git(cwd, ["rev-parse", "--show-toplevel"]).stdout.trim();
+}
+
+function homeDirectory(home) {
+  return home || process.env.DSH_HOME || path.join(os.homedir(), ".dsh");
+}
+
+function checkpointDir(root, home) {
+  const digest = crypto.createHash("sha256").update(root.toLowerCase()).digest("hex").slice(0, 16);
+  return path.join(homeDirectory(home), "agent-extensions", "checkpoints", digest);
+}
+
+export function createCheckpoint({ cwd, label = "", home } = {}) {
+  const root = repoRoot(cwd);
+  const id = `cp-${new Date().toISOString().replace(/[-:T.Z]/gu, "").slice(0, 14)}-${crypto.randomBytes(3).toString("hex")}`;
+  const indexPath = path.join(os.tmpdir(), `dsh-agent-extensions-index-${process.pid}-${Date.now()}`);
+  const env = { GIT_INDEX_FILE: indexPath };
+  try {
+    const hasHead = git(root, ["rev-parse", "--verify", "HEAD"], env, true).ok;
+    if (hasHead) git(root, ["read-tree", "HEAD"], env);
+    else git(root, ["read-tree", "--empty"], env);
+    git(root, ["add", "-A"], env);
+    const tree = git(root, ["write-tree"], env).stdout.trim();
+    const message = `dsh agent checkpoint ${id}${label ? `: ${label}` : ""}`;
+    const args = ["commit-tree", tree];
+    if (hasHead) args.push("-p", "HEAD");
+    args.push("-m", message);
+    const commit = git(root, args, env).stdout.trim();
+    git(root, ["update-ref", `refs/dsh-agent-extensions/${id}`, commit], env);
+    const meta = {
+      id,
+      label: String(label ?? ""),
+      createdAt: new Date().toISOString(),
+      repo: root,
+      commit,
+      tree,
+      files: git(root, ["ls-tree", "-r", "--name-only", commit], env).stdout.trim().split(/\r?\n/u).filter(Boolean).length,
+    };
+    const directory = checkpointDir(root, home);
+    fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+    fs.writeFileSync(path.join(directory, `${id}.json`), `${JSON.stringify(meta, null, 2)}\n`, { mode: 0o600 });
+    return meta;
+  } finally {
+    try { fs.rmSync(indexPath, { force: true }); } catch { /* best effort */ }
+  }
+}
+
+export function listCheckpoints({ cwd, home } = {}) {
+  const root = repoRoot(cwd);
+  const directory = checkpointDir(root, home);
+  if (!fs.existsSync(directory)) return [];
+  return fs
+    .readdirSync(directory)
+    .filter((name) => /^cp-.*\.json$/u.test(name))
+    .map((name) => {
+      try {
+        return JSON.parse(fs.readFileSync(path.join(directory, name), "utf8"));
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean)
+    .sort((left, right) => String(right.createdAt).localeCompare(String(left.createdAt)));
+}
+
+export function restoreCheckpoint({ cwd, id, home } = {}) {
+  const root = repoRoot(cwd);
+  const checkpoints = listCheckpoints({ cwd: root, home });
+  const checkpoint = checkpoints.find((item) => item.id === id);
+  if (!checkpoint) throw new Error(`checkpoint not found: ${id}`);
+  git(root, ["restore", "--source", checkpoint.commit, "--worktree", "--", "."]);
+  return checkpoint;
+}

package/plugins/dsh-agent-extensions/lib/commands.js

@@ -0,0 +1,255 @@
+/**
+ * Project commands and the small built-in command set:
+ * /init, /doctor, /verify, /hooks, /checkpoint, /rewind.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { createCheckpoint, listCheckpoints, restoreCheckpoint } from "./checkpoints.js";
+import { loadAgents, loadCommands, loadHooks, loadVerify, projectFor } from "./project.js";
+
+function sessionProject(ctx) {
+  try {
+    const agent = ctx.get("agents")?.currentInitiator?.();
+    const cwd = agent?.session?.header?.cwd;
+    return projectFor(cwd);
+  } catch {
+    return projectFor(process.cwd());
+  }
+}
+
+function listLine(items, empty) {
+  return items.length > 0 ? items.map((item) => `- ${item}`).join("\n") : empty;
+}
+
+function initProject(projectDir, dshDir, force) {
+  fs.mkdirSync(dshDir, { recursive: true });
+  const projectFile = path.join(dshDir, "PROJECT.md");
+  if (fs.existsSync(projectFile) && !force) return `Уже существует: ${projectFile}. Передайте --force для перезаписи.`;
+  let pkg = {};
+  try { pkg = JSON.parse(fs.readFileSync(path.join(projectDir, "package.json"), "utf8")); } catch { /* optional */ }
+  const dirs = [];
+  try {
+    for (const entry of fs.readdirSync(projectDir, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      if (["node_modules", ".git", ".dsh", "dist", "build", "coverage"].includes(entry.name)) continue;
+      dirs.push(entry.name);
+    }
+  } catch { /* ignore */ }
+  const lines = [
+    "# Project",
+    "",
+    `Root: ${projectDir}`,
+    pkg.name ? `Package: ${pkg.name}${pkg.version ? ` ${pkg.version}` : ""}` : "",
+    pkg.scripts?.test ? `Tests: ${pkg.scripts.test}` : "",
+    dirs.length > 0 ? `Directories: ${dirs.slice(0, 20).join(", ")}` : "",
+    "",
+    "## Commands",
+    "```",
+    pkg.scripts?.test ? `npm test` : "# tests not detected",
+    pkg.scripts?.build ? `npm run build` : "",
+    "```",
+    "",
+    "## Agent notes",
+    "- Проверяй изменения тестами и browser_qa для UI.",
+    "- Не коммить секреты и локальные данные.",
+  ].filter((line) => line !== "");
+  fs.writeFileSync(projectFile, `${lines.join("\n")}\n`, "utf8");
+  const rulesDir = path.join(dshDir, "rules");
+  fs.mkdirSync(rulesDir, { recursive: true });
+  const ruleFile = path.join(rulesDir, "project.md");
+  if (!fs.existsSync(ruleFile) || force) {
+    fs.writeFileSync(ruleFile, `---\nalways: true\n---\n# Правила проекта\n\n- Источник истины: ${path.basename(projectFile)}.\n- Перед сдачей — тесты и проверка UI.\n`, "utf8");
+  }
+  return `Создано: ${projectFile} и ${ruleFile}.`;
+}
+
+function runVerify(projectDir, dshDir) {
+  const configured = loadVerify(projectDir, dshDir);
+  let commands = configured.commands;
+  if (commands.length === 0) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(path.join(projectDir, "package.json"), "utf8"));
+      if (typeof pkg.scripts?.test === "string") commands = ["npm test"];
+    } catch { /* optional */ }
+  }
+  if (commands.length === 0) return { text: "Нет .dsh/verify.json и не найден npm test." };
+  const lines = [];
+  for (const command of commands) {
+    const result = spawnSync(command, {
+      cwd: projectDir,
+      shell: true,
+      encoding: "utf8",
+      timeout: 120_000,
+      windowsHide: true,
+    });
+    const output = `${result.stdout ?? ""}\n${result.stderr ?? ""}`.trim().split(/\r?\n/u).slice(-12).join("\n");
+    lines.push(`$ ${command}\nexit ${result.status ?? "?"}${output ? `\n${output}` : ""}`);
+    if (result.status !== 0) break;
+  }
+  return { text: lines.join("\n\n") };
+}
+
+function statusText(ctx) {
+  const project = sessionProject(ctx);
+  const dshDir = project.dsh ?? path.join(project.root, ".dsh");
+  const agents = loadAgents(project.root, dshDir);
+  const commands = loadCommands(project.root, dshDir);
+  const hooks = loadHooks(project.root, dshDir);
+  let checkpoints = [];
+  if (project.dsh) {
+    try { checkpoints = listCheckpoints({ cwd: project.root }); } catch { checkpoints = []; }
+  }
+  return [
+    `Project: ${project.root}`,
+    `.dsh: ${project.dsh ?? "нет"}`,
+    `Agents: ${agents.map((agent) => agent.name).join(", ") || "нет"}`,
+    `Commands: ${commands.map((command) => `/${command.name}`).join(", ") || "нет"}`,
+    `Hooks: ${hooks.trusted ? "trusted" : "не доверены"} · событий: ${Object.keys(hooks.hooks ?? {}).length}`,
+    `Checkpoints: ${checkpoints.length}`,
+  ].join("\n");
+}
+
+export function registerCommands(ctx) {
+  const register = (definition) => {
+    try {
+      return ctx.commands.register(definition);
+    } catch (error) {
+      ctx.logger?.warn?.(`[agent-extensions] command /${definition.name} skipped: ${error instanceof Error ? error.message : String(error)}`);
+      return undefined;
+    }
+  };
+
+  register({
+    name: "init",
+    description: "Создать .dsh/PROJECT.md и .dsh/rules/project.md",
+    input: { hint: "[--force]" },
+    recordInput: false,
+    handler: ({ rawInput }) => {
+      const project = sessionProject(ctx);
+      const dshDir = project.dsh ?? path.join(project.root, ".dsh");
+      return { kind: "success", text: initProject(project.root, dshDir, /--force/u.test(String(rawInput ?? ""))) };
+    },
+  });
+
+  register({
+    name: "doctor",
+    description: "Проверить hooks, agents, commands и checkpoints",
+    input: { hint: "" },
+    recordInput: false,
+    handler: () => ({ kind: "success", text: statusText(ctx) }),
+  });
+
+  register({
+    name: "hooks",
+    description: "Статус hooks, trust или отключение",
+    input: { hint: "status | trust | off" },
+    recordInput: false,
+    handler: ({ rawInput }) => {
+      const project = sessionProject(ctx);
+      if (!project.dsh) return { kind: "error", text: "Нет .dsh в проекте." };
+      const action = String(rawInput ?? "").trim().toLowerCase();
+      const marker = path.join(project.dsh, "hooks.trusted");
+      if (action === "trust") {
+        fs.writeFileSync(marker, `${new Date().toISOString()}\n`, "utf8");
+        return { kind: "success", text: "Hooks доверены. Команды из .dsh/hooks.json будут запускаться." };
+      }
+      if (action === "off") {
+        fs.rmSync(marker, { force: true });
+        return { kind: "success", text: "Доверие к hooks снято." };
+      }
+      const hooks = loadHooks(project.root, project.dsh);
+      return { kind: "success", text: `trusted: ${hooks.trusted}\nevents: ${Object.keys(hooks.hooks ?? {}).join(", ") || "none"}` };
+    },
+  });
+
+  register({
+    name: "verify",
+    description: "Запустить проверки проекта из .dsh/verify.json или npm test",
+    input: { hint: "" },
+    recordInput: false,
+    handler: () => {
+      const project = sessionProject(ctx);
+      const dshDir = project.dsh ?? path.join(project.root, ".dsh");
+      return { kind: "success", text: runVerify(project.root, dshDir).text };
+    },
+  });
+
+  register({
+    name: "checkpoint",
+    description: "Создать безопасный git-чекпоинт workspace",
+    input: { hint: "[label]" },
+    recordInput: false,
+    handler: ({ rawInput }) => {
+      const project = sessionProject(ctx);
+      try {
+        const meta = createCheckpoint({ cwd: project.root, label: String(rawInput ?? "").trim() });
+        return { kind: "success", text: `Checkpoint ${meta.id} (${meta.files} файлов).` };
+      } catch (error) {
+        return { kind: "error", text: `checkpoint: ${error instanceof Error ? error.message : String(error)}` };
+      }
+    },
+  });
+
+  register({
+    name: "rewind",
+    description: "Показать или восстановить checkpoint",
+    input: { hint: "[id]" },
+    recordInput: false,
+    handler: ({ rawInput }) => {
+      const project = sessionProject(ctx);
+      const id = String(rawInput ?? "").trim();
+      try {
+        if (!id) {
+          const items = listCheckpoints({ cwd: project.root }).slice(0, 10);
+          return { kind: "success", text: listLine(items.map((item) => `${item.id} · ${item.createdAt} · ${item.label || "без метки"}`), "Нет чекпоинтов.") };
+        }
+        const meta = restoreCheckpoint({ cwd: project.root, id });
+        return { kind: "success", text: `Восстановлен ${meta.id}. Файлы, созданные после, не удалены.` };
+      } catch (error) {
+        return { kind: "error", text: `rewind: ${error instanceof Error ? error.message : String(error)}` };
+      }
+    },
+  });
+
+  /* Project commands are loaded from the project of the *current* session. A
+   * single `/project` command is registered globally because DSH command
+   * names are process-wide; direct `/deploy` aliases would bind to whatever
+   * workspace happened to be first at plugin start. */
+  register({
+    name: "project",
+    description: "Список или запуск проектных команд из .dsh/commands",
+    input: { hint: "list | <name> [args]" },
+    recordInput: false,
+    handler: ({ rawInput }) => {
+      const project = sessionProject(ctx);
+      const dshDir = project.dsh ?? path.join(project.root, ".dsh");
+      const commands = loadCommands(project.root, dshDir);
+      const input = String(rawInput ?? "").trim();
+      if (input.length === 0 || input === "list") {
+        return {
+          kind: "success",
+          text: commands.length
+            ? commands.map((command) => `- /project ${command.name} — ${command.description}`).join("\n")
+            : "Нет .dsh/commands. Создайте файл .dsh/commands/<name>.md.",
+        };
+      }
+      const [name, ...rest] = input.split(/\s+/u);
+      const command = commands.find((item) => item.name === name);
+      if (!command) return { kind: "error", text: `Проектная команда не найдена: ${name}` };
+      try {
+        const agent = ctx.get("agents")?.currentInitiator?.();
+        if (!agent || typeof agent.steer !== "function") throw new Error("нет активного агента");
+        agent.steer({
+          id: `cmd-${Date.now()}-${Math.random().toString(16).slice(2)}`,
+          role: "user",
+          content: [{ type: "text", text: `${command.body}${rest.length > 0 ? `\n\n${rest.join(" ")}` : ""}` }],
+          source: { kind: "user" },
+        });
+        return { kind: "success", text: `Команда /project ${name} передана агенту.` };
+      } catch (error) {
+        return { kind: "error", text: error instanceof Error ? error.message : String(error) };
+      }
+    },
+  });
+}

package/plugins/dsh-agent-extensions/lib/hooks.js

@@ -0,0 +1,182 @@
+/**
+ * User-defined project hooks.
+ *
+ * `.dsh/hooks.json` is opt-in: commands run only when `.dsh/hooks.trusted`
+ * exists. Events mirror the useful subset of Claude Code hooks:
+ * PreToolUse, PostToolUse, Stop, FileChanged, SessionStart, SessionEnd.
+ */
+import { spawn } from "node:child_process";
+import path from "node:path";
+import { findDshDir, loadHooks } from "./project.js";
+
+const MAX_OUTPUT = 12_000;
+const DEFAULT_TIMEOUT = 30_000;
+const MAX_TIMEOUT = 120_000;
+
+function sessionCwd(agent) {
+  const cwd = agent?.session?.header?.cwd;
+  return typeof cwd === "string" && cwd.length > 0 ? cwd : "";
+}
+
+function hookProject(cwd, fallbackFile) {
+  const start = cwd || (typeof fallbackFile === "string" ? path.dirname(fallbackFile) : process.cwd());
+  return findDshDir(start);
+}
+
+function matcherMatches(matcher, value) {
+  if (typeof matcher !== "string" || matcher.trim().length === 0) return true;
+  try {
+    return new RegExp(matcher, "iu").test(String(value ?? ""));
+  } catch {
+    return false;
+  }
+}
+
+function runCommand(hook, payload, cwd, sessionId) {
+  return new Promise((resolve) => {
+    const timeout = Math.max(1_000, Math.min(MAX_TIMEOUT, Number(hook.timeoutMs) || DEFAULT_TIMEOUT));
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+    let child;
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve(result);
+    };
+    const timer = setTimeout(() => {
+      try { child?.kill(); } catch { /* best effort */ }
+      finish({ code: 124, stdout, stderr: `${stderr}\nhook timed out after ${timeout}ms`.trim(), timedOut: true });
+    }, timeout);
+    try {
+      child = spawn(String(hook.command), {
+        cwd,
+        shell: true,
+        windowsHide: true,
+        env: {
+          ...process.env,
+          DSH_HOOK_EVENT: String(hook.event ?? ""),
+          DSH_PROJECT_DIR: cwd,
+          DSH_SESSION_ID: sessionId,
+        },
+      });
+    } catch (error) {
+      finish({ code: 1, stdout: "", stderr: String(error) });
+      return;
+    }
+    child.stdout?.on("data", (chunk) => {
+      if (stdout.length < MAX_OUTPUT) stdout += chunk.toString("utf8");
+    });
+    child.stderr?.on("data", (chunk) => {
+      if (stderr.length < MAX_OUTPUT) stderr += chunk.toString("utf8");
+    });
+    child.on("error", (error) => finish({ code: 1, stdout, stderr: String(error) }));
+    child.on("close", (code) => finish({ code: Number(code) || 0, stdout, stderr }));
+    try {
+      child.stdin?.end(JSON.stringify(payload));
+    } catch {
+      /* no stdin */
+    }
+  });
+}
+
+export function registerProjectHooks(ctx) {
+  const disposers = [];
+  const logger = ctx.logger;
+
+  async function runEvent(event, agent, payload, matchValue) {
+    const project = hookProject(sessionCwd(agent), payload?.file ?? payload?.path);
+    const loaded = loadHooks(project.root, project.dsh);
+    if (!loaded.trusted) return { blocked: false, results: [], untrusted: true };
+    const hooks = Array.isArray(loaded.hooks?.[event]) ? loaded.hooks[event] : [];
+    if (hooks.length === 0) return { blocked: false, results: [] };
+    const results = [];
+    for (const hook of hooks) {
+      if (!hook || typeof hook.command !== "string" || hook.command.trim().length === 0) continue;
+      if (!matcherMatches(hook.matcher, matchValue)) continue;
+      const result = await runCommand(hook, { event, ...payload }, project.root, String(agent?.id ?? ""));
+      results.push({ ...result, command: hook.command });
+      const code = result.code;
+      if (code !== 0) {
+        logger?.warn?.(`[agent-extensions] ${event} hook exited ${code}: ${(result.stderr || result.stdout).slice(0, 300)}`);
+      }
+      if (code === 2) return { blocked: true, results, reason: (result.stderr || result.stdout || `${event} hook blocked`).trim() };
+    }
+    return { blocked: false, results };
+  }
+
+  const on = (event, handler) => {
+    try {
+      const dispose = ctx.on(event, handler);
+      if (typeof dispose === "function") disposers.push(dispose);
+    } catch (error) {
+      logger?.warn?.(`[agent-extensions] ${event} hook skipped: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  };
+
+  on("tools/pre-execute", async (exec, next) => {
+    const result = await runEvent("PreToolUse", exec?.agent, {
+      tool: exec?.name,
+      arguments: exec?.arguments ?? {},
+    }, exec?.name);
+    if (result.blocked) return { kind: "deny", reason: `project hook: ${result.reason}` };
+    return typeof next === "function" ? next() : { kind: "allow" };
+  });
+
+  on("tools/result", async (exec, result) => {
+    await runEvent("PostToolUse", exec?.agent, {
+      tool: exec?.name,
+      arguments: exec?.arguments ?? {},
+      ok: result?.isError !== true,
+    }, exec?.name);
+  });
+
+  on("fs/write-intent", async (target, actor, next) => {
+    const file = target?.displayPath ?? target?.path ?? "";
+    const result = await runEvent("FileChanged", actor, { file, operation: "write" }, file);
+    if (result.blocked) throw new Error(`project hook: ${result.reason}`);
+    return typeof next === "function" ? next() : undefined;
+  });
+
+  on("fs/edit-intent", async (target, actor, next) => {
+    const file = target?.displayPath ?? target?.path ?? "";
+    const result = await runEvent("FileChanged", actor, { file, operation: "edit" }, file);
+    if (result.blocked) throw new Error(`project hook: ${result.reason}`);
+    return typeof next === "function" ? next() : undefined;
+  });
+
+  on("agent/turn-stopping", async (payload) => {
+    const agent = payload?.agent;
+    const result = await runEvent("Stop", agent, { turn: payload?.turn ?? 0 }, "");
+    if (result.blocked) {
+      try {
+        agent?.steer?.({
+          id: `hook-${Date.now()}-${Math.random().toString(16).slice(2)}`,
+          role: "user",
+          content: [{ type: "text", text: `<project-hook-stop>\n${result.reason}\n</project-hook-stop>` }],
+          source: { kind: "user" },
+        });
+      } catch (error) {
+        logger?.warn?.(`[agent-extensions] stop steer failed: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
+  });
+
+  on("agent/created", async (payload) => {
+    await runEvent("SessionStart", payload?.agent, { session: String(payload?.agent?.id ?? "") }, "");
+  });
+  on("agent/disposed", async (payload) => {
+    await runEvent("SessionEnd", payload?.agent, { session: String(payload?.agent?.id ?? "") }, "");
+  });
+
+  return {
+    dispose() {
+      for (const dispose of disposers) {
+        try { dispose(); } catch { /* best effort */ }
+      }
+    },
+  };
+}
+
+export { runCommand, matcherMatches };

package/plugins/dsh-agent-extensions/lib/policy.js

@@ -0,0 +1,84 @@
+/**
+ * Enforcement for project subagents.
+ *
+ * DSH's subagents service starts a child before a parent can attach a policy,
+ * so `project_agent` reserves the child id, records the policy, and only then
+ * starts the child. The global pre-execute hook denies calls made by that child
+ * when its tool allowlist or permission level forbids them.
+ */
+const MUTATING_TOOLS = new Set(["write", "edit", "apply_patch", "patch", "delete", "move", "mkdir", "touch"]);
+const SHELL_TOOLS = new Set(["bash", "pwsh", "powershell", "shell", "sh", "zsh", "cmd", "terminal"]);
+const MUTATING_SHELL = /(?:^|[;&|]\s*|\s)(?:rm|rmdir|mv|cp|mkdir|touch|truncate|tee|dd|chmod|chown|Set-Content|Add-Content|Out-File|New-Item|Remove-Item|Move-Item|Copy-Item|git\s+(?:commit|push|reset|checkout|clean|merge|rebase)|npm\s+(?:install|uninstall|update)|pnpm\s+(?:add|remove|install)|composer\s+(?:install|update)|php\s+artisan\s+(?:migrate|db:)|dropdb|createdb|psql\b[^\n]*(?:insert|update|delete|drop|truncate|alter))/iu;
+
+const policies = new Map();
+
+export function parseAllowedTools(value) {
+  if (typeof value !== "string") return new Set();
+  return new Set(value.split(/[,\s]+/u).map((name) => name.trim()).filter(Boolean));
+}
+
+export function setChildPolicy(childId, definition) {
+  if (!childId) return;
+  policies.set(String(childId), {
+    name: definition?.name ?? "project-agent",
+    allowed: parseAllowedTools(definition?.tools),
+    permission: definition?.permission === "read-only" || definition?.permission === "workspace-write"
+      ? definition.permission
+      : "full",
+  });
+}
+
+export function clearChildPolicy(childId) {
+  if (childId) policies.delete(String(childId));
+}
+
+export function checkChildTool(exec) {
+  const id = String(exec?.agent?.id ?? "");
+  const policy = policies.get(id);
+  if (!policy) return null;
+  const tool = String(exec?.name ?? "");
+  if (policy.permission === "read-only") {
+    if (MUTATING_TOOLS.has(tool)) {
+      return { kind: "deny", reason: `subagent ${policy.name}: permission read-only запрещает ${tool}` };
+    }
+    if (SHELL_TOOLS.has(tool)) {
+      const command = exec?.arguments && typeof exec.arguments === "object" ? exec.arguments.command : "";
+      if (typeof command === "string" && MUTATING_SHELL.test(command)) {
+        return { kind: "deny", reason: `subagent ${policy.name}: permission read-only запрещает изменяющую shell-команду` };
+      }
+    }
+  }
+  if (policy.allowed.size > 0 && !policy.allowed.has(tool)) {
+    return { kind: "deny", reason: `subagent ${policy.name}: tool ${tool} не входит в allowlist` };
+  }
+  return null;
+}
+
+export function registerChildPolicyHook(ctx) {
+  const disposers = [];
+  const on = (event, handler) => {
+    try {
+      const dispose = ctx.on(event, handler);
+      if (typeof dispose === "function") disposers.push(dispose);
+    } catch (error) {
+      ctx.logger?.warn?.(`[agent-extensions] policy hook ${event} skipped: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  };
+  on("tools/pre-execute", (exec, next) => {
+    const hit = checkChildTool(exec);
+    if (hit) return { kind: "deny", reason: hit.reason };
+    return typeof next === "function" ? next() : { kind: "allow" };
+  });
+  on("agent/disposed", (payload) => clearChildPolicy(payload?.agent?.id));
+  return {
+    dispose() {
+      for (const dispose of disposers) {
+        try { dispose(); } catch { /* best effort */ }
+      }
+    },
+  };
+}
+
+export function childPolicyCount() {
+  return policies.size;
+}