@toddzheng024/dscode-desktop 0.0.0-stage → 0.7.33

package/plugins/tui-tools/hook-sources.mjs

@@ -0,0 +1,113 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { hookEvents, validateHooks } from './hooks.mjs';
+import { enabledFlag } from './workspace-discovery.mjs';
+
+// Project hook files layer on top of the installation file by default. They run as
+// the OS user outside tool approval, so a cloned repository can install gates;
+// DSCODE_PROJECT_HOOKS=0/off/false loads the installation file alone.
+// `.codex/hooks.json` and `.dsh/hooks.json` are the bridge's own shape;
+// `.claude/settings.json` keeps hooks under a top-level `hooks` key and is skipped
+// when that key is absent.
+export const projectHookFiles = Object.freeze([
+  { path: '.codex/hooks.json' },
+  { path: '.dsh/hooks.json' },
+  { path: '.claude/settings.json', nested: true },
+]);
+
+export const resolvedHookFile = 'hooks.resolved.json';
+export const hookReportFile = 'hooks.resolved.report.json';
+
+export function projectHooksEnabled(env = process.env) {
+  const value = env.DSCODE_PROJECT_HOOKS;
+  return value === undefined ? true : enabledFlag(value);
+}
+
+function extractHooks(parsed, nested) {
+  const hooks = parsed?.hooks !== undefined ? parsed.hooks : (nested ? undefined : parsed);
+  if (hooks === undefined) return undefined;
+  if (!hooks || typeof hooks !== 'object' || Array.isArray(hooks)) throw new Error('hooks must be an event map');
+  return hooks;
+}
+
+// The installation file is trusted and must fail loudly on anything this bridge
+// cannot run.
+export function readInstallationHooks(path) {
+  return validateHooks(JSON.parse(readFileSync(path, 'utf8')));
+}
+
+// A project file is only filtered: a Claude Code settings.json routinely carries
+// events this bridge does not implement, and skipping them must not stop dscode
+// from starting. Every skip is reported so it is visible rather than silent.
+export function readProjectHooks(path, { nested = false } = {}) {
+  const hooks = extractHooks(JSON.parse(readFileSync(path, 'utf8')), nested);
+  if (hooks === undefined) return undefined;
+  const kept = {};
+  const skipped = [];
+  for (const [event, groups] of Object.entries(hooks)) {
+    if (!hookEvents.includes(event)) { skipped.push(event); continue; }
+    // A project file is untrusted input: a gate this bridge cannot run is dropped
+    // with its reason rather than allowed to stop dscode from starting.
+    try {
+      validateHooks({ hooks: { [event]: groups } });
+    } catch (error) {
+      const reason = error.message.startsWith(`${event}: `) ? error.message.slice(event.length + 2) : error.message;
+      skipped.push(`${event} (${reason})`);
+      continue;
+    }
+    kept[event] = groups;
+  }
+  return { hooks: Object.keys(kept).length ? kept : undefined, skipped };
+}
+
+export function resolveHookSources({ root, cwd = root, env = process.env }) {
+  const installation = join(root, 'config/hooks.local.json');
+  const sources = [{ path: installation, hooks: readInstallationHooks(installation) }];
+  const skipped = [];
+  if (!projectHooksEnabled(env)) return { sources, skipped };
+  for (const file of projectHookFiles) {
+    const path = join(cwd, file.path);
+    if (!existsSync(path)) continue;
+    let parsed;
+    try {
+      parsed = readProjectHooks(path, file);
+    } catch (error) {
+      // Unreadable JSON (a Claude settings file may even carry comments) is a
+      // report, not a startup failure, for a file dscode did not write.
+      skipped.push({ path: file.path, events: [`(not loaded: ${error.message})`] });
+      continue;
+    }
+    if (!parsed) continue;
+    if (parsed.skipped.length) skipped.push({ path: file.path, events: parsed.skipped });
+    if (parsed.hooks) sources.push({ path, hooks: parsed.hooks });
+  }
+  return { sources, skipped };
+}
+
+export function mergeHooks(sources) {
+  const hooks = {};
+  for (const source of sources) {
+    for (const [event, groups] of Object.entries(source.hooks ?? {})) hooks[event] = [...(hooks[event] ?? []), ...groups];
+  }
+  return { hooks };
+}
+
+// The pinned bridge takes one config path for the whole process, so layered files
+// are merged into a single resolved file. A single source stays where it is edited.
+export function writeHookConfig({ root, cwd = root, home, env = process.env }) {
+  const { sources, skipped } = resolveHookSources({ root, cwd, env });
+  const paths = sources.map(source => source.path);
+  const resolved = join(home, resolvedHookFile);
+  const report = join(home, hookReportFile);
+  if (sources.length === 1) {
+    // A stale merge must not outlive the layers it came from: /hooks reads the
+    // report, and a leftover one would describe sources that are no longer loaded.
+    if (existsSync(resolved)) rmSync(resolved);
+    if (existsSync(report)) rmSync(report);
+    return { path: sources[0].path, sources: paths, skipped };
+  }
+  mkdirSync(home, { recursive: true });
+  writeFileSync(resolved, JSON.stringify(mergeHooks(sources), null, 2) + '\n', { mode: 0o600 });
+  writeFileSync(report, JSON.stringify({ sources: paths, skipped }, null, 2) + '\n', { mode: 0o600 });
+  return { path: resolved, sources: paths, skipped };
+}

package/plugins/tui-tools/hooks.mjs

@@ -0,0 +1,23 @@
+export const hookEvents = ['SessionStart', 'UserPromptSubmit', 'PreToolUse', 'PostToolUse', 'Stop'];
+// Fail visibly instead of letting the upstream compatibility bridge silently skip gates.
+export function validateHooks(raw) {
+  const hooks = raw?.hooks ?? raw;
+  if (!hooks || typeof hooks !== 'object' || Array.isArray(hooks)) throw new Error('hooks must be an event map');
+  for (const [event, groups] of Object.entries(hooks)) {
+    if (!hookEvents.includes(event)) throw new Error(`Unsupported hook event: ${event}`);
+    if (!Array.isArray(groups)) throw new Error(`${event}: expected matcher groups`);
+    for (const group of groups) {
+      if (!group || !Array.isArray(group.hooks)) throw new Error(`${event}: expected hooks array`);
+      if (group.matcher !== undefined) {
+        if (typeof group.matcher !== 'string') throw new Error(`${event}: matcher must be a regex string`);
+        new RegExp(group.matcher);
+      }
+      for (const hook of group.hooks) {
+        if (!hook || (hook.type !== undefined && hook.type !== 'command') || hook.async === true || typeof hook.command !== 'string' || !hook.command.trim()) throw new Error(`${event}: only synchronous command hooks are supported`);
+        const timeout = hook.timeout ?? hook.timeoutSec;
+        if (timeout !== undefined && (!Number.isFinite(timeout) || timeout <= 0 || timeout > 600)) throw new Error(`${event}: timeout must be 0–600 seconds, excluding zero`);
+      }
+    }
+  }
+  return hooks;
+}

package/plugins/tui-tools/index.mjs

@@ -0,0 +1,268 @@
+import { runShell } from './shell.mjs';
+import { VERSION_PATTERN, scheduleUpdate } from './update.mjs';
+import { readLanguage, t } from '../i18n/messages.mjs';
+import { hookReportFile } from './hook-sources.mjs';
+import { readFile, readdir, access, stat } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { parse } from 'yaml';
+import { createUserMessage } from '@deepseek-ai/dsh-llm';
+import { inspectComposition, presetInventoryLines, presetMcpNotice } from './composition.mjs';
+import { hookEvents, validateHooks } from './hooks.mjs';
+import { redact } from '../auto-review/policy.mjs';
+import { plainConfig } from '../cordis-config/plain.mjs';
+import { analyzeDoctorEvidence, collectDoctorEvidence, recordRuntimeLog } from './doctor.mjs';
+
+export const name = 'dscode-tui-tools';
+export const inject = ['commands', 'agents', 'tools', 'skills', 'permissionPresets', 'sessionPersistence', 'llm'];
+const phases = ['pending', 'loading', 'active', 'failed', 'unavailable', 'unloading'];
+const ok = text => ({ kind: 'success', text });
+const fail = text => ({ kind: 'error', text });
+const show = value => typeof value === 'string' ? value : JSON.stringify(value ?? null);
+const exists = path => access(path).then(() => true, () => false);
+
+/** Ancestor skill roots the preset's own expression reads, for a reader that cannot evaluate it. */
+function ancestorDirsFrom(env) {
+  try {
+    const parsed = JSON.parse(env.DSCODE_SKILL_ANCESTOR_DIRS ?? '[]');
+    return Array.isArray(parsed) ? parsed : [];
+  } catch { return []; }
+}
+
+export async function findConflicts(cwd, configs, winners, env = process.env) {
+  let project = resolve(cwd);
+  while (!await exists(join(project, '.git')) && dirname(project) !== project) project = dirname(project);
+  if (!await exists(join(project, '.git'))) project = resolve(cwd);
+  const roots = [];
+  const skipSystemRoots = new Set();
+  for (const config of configs) {
+    if (config.includeDefaultRoots !== false) {
+      roots.push(join(project, '.dsh/skills'), join(project, '.agents/skills'));
+      const dshHome = config.dshHome ?? env.DSH_HOME;
+      const agentsHome = config.agentsHome ?? env.DSH_AGENTS_HOME;
+      if (typeof dshHome === 'string') { const path = resolve(dshHome, 'skills'); roots.push(path); skipSystemRoots.add(path); }
+      if (typeof agentsHome === 'string') roots.push(resolve(agentsHome, 'skills'));
+    }
+    // A preset declares its ancestor roots as a `!!js` expression over this variable, which
+    // a reader of the row cannot evaluate; the environment it reads is the same here.
+    const custom = Array.isArray(config.customSkillDirs) ? config.customSkillDirs : ancestorDirsFrom(env);
+    roots.push(...custom.filter(x => typeof x === 'string').map(x => resolve(x)));
+    const bundled = config.bundledSkillDir ?? (config.includeDefaultRoots !== false ? env.DSH_BUNDLED_SKILL_DIR : undefined);
+    if (typeof bundled === 'string') roots.push(resolve(bundled));
+  }
+  const candidates = new Map();
+  const errors = [];
+  for (const root of new Set(roots)) {
+    let entries;
+    try { entries = await readdir(root, { withFileTypes: true }); }
+    catch (e) { if (e.code !== 'ENOENT') errors.push(`${root}: ${e.code}`); continue; }
+    for (const entry of entries) {
+      if (entry.name === '.system' && skipSystemRoots.has(root)) continue;
+      const path = entry.isFile() && entry.name.endsWith('.md') ? join(root, entry.name) : join(root, entry.name, 'SKILL.md');
+      try {
+        const raw = await readFile(path, 'utf8');
+        const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+        const meta = match && parse(match[1]);
+        if (typeof meta?.name !== 'string' || typeof meta.description !== 'string') continue;
+        const list = candidates.get(meta.name) ?? [];
+        list.push(path); candidates.set(meta.name, list);
+      } catch (e) { if (!['ENOENT', 'ENOTDIR'].includes(e.code)) errors.push(`${path}: invalid or unreadable`); }
+    }
+  }
+  const lines = [];
+  for (const [name, paths] of candidates) if (paths.length > 1) {
+    const winner = winners.find(s => s.name === name);
+    lines.push(`${name}: effective source=${winner?.source ?? 'not in catalog'} provider=${winner?.provider ?? '?'}\n${paths.map(p => `  ${p}`).join('\n')}`);
+  }
+  return [...lines, ...errors, 'Scope: filesystem roots only; runtime/remote provider shadowed candidates are not exposed by DSH.'].join('\n');
+}
+
+// The pinned bridge reads one merged file for the whole process, and /hooks reload
+// remounts the plugin with the same path, so an edited layer is not picked up until
+// dscode restarts. Report that instead of letting the user believe the edit is live.
+export async function staleLayers(resolvedPath, sources = []) {
+  const mergedAt = await stat(resolvedPath).then(value => value.mtimeMs).catch(() => undefined);
+  if (mergedAt === undefined) return [];
+  const stale = [];
+  for (const source of sources) {
+    if (source === resolvedPath) continue;
+    const at = await stat(source).then(value => value.mtimeMs).catch(() => undefined);
+    if (at === undefined) stale.push(`${source} (missing)`);
+    else if (at > mergedAt) stale.push(`${source} (newer than the merge)`);
+  }
+  return stale;
+}
+
+export function apply(ctx) {
+  return install(ctx, false);
+}
+
+export function applyDesktop(ctx) {
+  return install(ctx, true);
+}
+
+function install(ctx, desktop) {
+  const diagnosticsHome = process.env.DSH_HOME ?? process.env.DSCODE_HOME;
+  // A minimal composition (and the unit fixtures) may mount no logger; diagnostics are best-effort.
+  if (diagnosticsHome) ctx.logger?.exporter?.({ levels: { default: 2 }, export: message => recordRuntimeLog(diagnosticsHome, message) });
+  const composition = agent => {
+    const inventory = inspectComposition(ctx, agent);
+    if (!desktop) return inventory;
+    // Older runtimes also expose mutable standing preset entries. Desktop keeps
+    // those out of process-wide controls on every supported runtime version.
+    return { ...inventory, hostOnly: true,
+      entries: [...(ctx.get('loader')?.entries() ?? [])].filter(entry => entry.options.group !== true) };
+  };
+  const entries = agent => composition(agent).entries;
+  const mcps = agent => entries(agent).filter(e => e.options.name === '@deepseek-ai/dsh-mcp-client');
+  const hook = () => entries().find(e => e.options.id === 'dscode-hooks');
+  const state = e => e.disabled ? 'disabled' : phases[e.fiber?.state] ?? 'unavailable';
+  let changing = false;
+  const commandName = name => desktop ? `dscode-${name}` : name;
+  const mutate = async fn => {
+    if (changing || ctx.agents.list().some(a => a.status === 'running')) return fail('Wait until all agents are idle before changing process-wide plugins.');
+    changing = true;
+    try { return await fn(); } finally { changing = false; }
+  };
+  const register = (name, description, handler) => {
+    // Desktop owns its updater and shell UI. Register diagnostics separately
+    // so the native commands and other presets retain their own handlers.
+    if (desktop && !['status', 'doctor', 'mcp', 'skills'].includes(name)) return;
+    const hint = { doctor: '[preview|local]', mcp: '[list|tools <id>|enable <id>|disable <id>|reconnect <id>]', skills: '[list|conflicts|<name>]' }[name];
+    return ctx.commands.register({ name: commandName(name), description, ...(hint ? { input: { hint } } : {}), handler: async inv => {
+      if (desktop && ctx.agentPresets.composedPreset(inv.agent.ctx) !== 'dscode') return fail('Choose a DSCODE session to use DSCODE diagnostics.');
+      try {
+        const result = await handler(inv);
+        return { ...result, text: redact(result.text ?? '') };
+      }
+      catch (e) { return fail(redact(`${name}: ${e.message}`)); }
+    }});
+  };
+  register('shell-exec', 'Run a user shell command (also !command)', async ({ rawInput, agent, signal }) => {
+    const result = await runShell(rawInput, { cwd: agent.session.header.cwd ?? process.cwd(), signal });
+    // What the user ran belongs to the conversation: the command and its (redacted) output
+    // are handed to the agent, which then gets a turn to react to them.
+    const handover = redact(`[shell] $ ${rawInput.trim()}\n${result.text}`).slice(0, 8000);
+    try {
+      agent.followup(createUserMessage({ content: [{ type: 'text', text: handover }], source: { kind: 'dscode-shell-exec' } }));
+      await ctx.get('sessions')?.flush?.(agent.session);
+    } catch (error) {
+      return fail(`shell: the command ran, but its output could not reach the agent (${error.message})`);
+    }
+    return { ...result, text: `${result.text}\n\n[output handed to the agent]` };
+  });
+  register('status', 'Session, model, permissions, usage and plugin health', ({ agent }) => {
+    const session = agent.session;
+    const route = session.requestHeader()?.config ?? agent.options;
+    const events = session.snapshotEvents();
+    const projections = ctx.get('sessionProjections');
+    const usage = projections?.stateOf(session, 'tokenUsage')?.totals;
+    const pressure = projections?.stateOf(session, 'contextPressure');
+    const inventory = composition(agent);
+    const hostOnly = inventory.hostOnly || inventory.inspections !== null;
+    return ok([
+      `Session: ${session.id}`, `Workspace: ${session.header.cwd ?? process.cwd()}`,
+      `Agent: ${agent.status} | preset: ${session.header.agentPreset ?? 'standard'}`,
+      `Model: ${route?.provider ?? 'default'} / ${route?.model ?? 'default'}`,
+      `Effort: ${route?.reasoningEffort ?? 'model default'}${route?.reasoningEffort === 'ultra' ? ` (${route.provider === 'deepseek-official' ? 'DeepSeek wire: max' : route.model?.startsWith('deepseek/') ? 'OpenRouter wire: xhigh' : "sent as the model's max level"}; collaboration enabled)` : ''}`,
+      `Permission: ${show(ctx.permissionPresets.current(session))}`,
+      `Tokens: ${show(usage ?? 'no provider usage yet')}`,
+      `Context: ${pressure?.pressureTokens ?? pressure?.surfaceTokens ?? '?'} / ${pressure?.contextWindow ?? '?'} tokens`,
+      `Events: ${events.length}; /review-usage shows reviewer tokens`,
+      `Tools: ${ctx.tools.schemas(agent).length}; ${hostOnly ? 'Host ' : ''}MCP entries: ${inventory.entries.filter(e => e.options.name === '@deepseek-ai/dsh-mcp-client').length}`,
+      `${hostOnly ? 'Host plugins' : 'Plugins'}: ${inventory.entries.filter(e => state(e) === 'active').length} active, ${inventory.entries.filter(e => state(e) === 'failed').length} failed`,
+      ...presetInventoryLines(inventory),
+      desktop ? 'Use /dscode-doctor for diagnostics; inspect execution details in Trajectory.' : 'Use /doctor for diagnostics; /statusline for live context/token display.',
+    ].join('\n'));
+  });
+  register('update', 'Upgrade DSCODE after this session exits', ({ rawInput }) => {
+    const version = rawInput.trim() || 'latest';
+    const locale = readLanguage();
+    if (version !== 'latest' && !VERSION_PATTERN.test(version)) return fail(t(locale, 'update.usage'));
+    const { log } = scheduleUpdate({ helperModuleUrl: new URL('./update.mjs', import.meta.url), pid: process.pid, version });
+    return ok(t(locale, 'update.scheduled', { version: version === 'latest' ? t(locale, 'update.newest') : version, log }));
+  });
+  register('doctor', 'Analyze recent runtime logs and session traces', async ({ agent, signal, rawInput }) => {
+    const action = rawInput.trim();
+    if (!['', 'preview', 'local'].includes(action)) return fail(`Usage: /${commandName('doctor')} [preview|local]`);
+    const tools = ctx.tools.schemas(agent).map(t => t.name);
+    const catalog = await ctx.skills.snapshot({ cwd: agent.session.header.cwd, scope: agent, signal });
+    const computer = ctx.get('computerUse');
+    const health = [
+      `Node: ${process.version}; platform: ${process.platform}/${process.arch}`,
+      ...entries(agent).filter(e => !e.disabled && state(e) !== 'active').map(e => `CHECK plugin ${e.id}: ${state(e)}`),
+      ...presetInventoryLines(composition(agent)),
+      `Skills: ${catalog.skills.length}; discovery ${catalog.complete ? 'complete' : 'incomplete'}`,
+      `Core tools: ${['bash', 'skill', 'computer_use_activate'].map(n => `${n}=${tools.includes(n)}`).join(', ')}`,
+      ...mcps(agent).map(e => `MCP ${e.id}: ${state(e)}; ${tools.filter(n => n.startsWith(`mcp__${e.options.config?.serverName}__`)).length} registered tools`),
+      `Computer Use: ${computer ? show(await computer.status()) : 'service unavailable'}`,
+      'Credentials are not read or printed. Diagnostic metadata may be sent to the selected model.',
+    ].join('\n');
+    const evidence = await collectDoctorEvidence(ctx, { agent, signal, workspaceOnly: desktop });
+    if (action === 'preview') return ok(JSON.stringify(evidence, null, 2));
+    const route = agent.session.requestHeader()?.config ?? agent.options;
+    return ok(`${health}\n\n${await analyzeDoctorEvidence(ctx, evidence, route, signal, { model: action !== 'local', sessionId: agent.session.id })}`);
+  });
+  register('mcp', 'MCP list, tools <id>, enable/disable/reconnect <id>', async ({ agent, rawInput }) => {
+    const [action = 'list', id, extra] = rawInput.trim().split(/\s+/).filter(Boolean);
+    const list = mcps(agent);
+    const notice = presetMcpNotice(composition(agent), commandName('mcp'))
+      || (desktop ? 'Only Host MCP entries can be changed here. Change preset servers through their bundle configuration and restart.' : '');
+    if (action === 'list') return ok([...list.map(e => `${e.id}: ${state(e)} | server=${show(e.options.config?.serverName)} | transport=${show(e.options.config?.transport)}`), ...(notice ? [notice] : [])].join('\n') + `\n/${commandName('mcp')} tools|enable|disable|reconnect <entry-id> — changes last for this process.`);
+    const matches = list.filter(e => e.id === id || e.options.id === id);
+    const entry = matches.length === 1 ? matches[0] : undefined;
+    if (!entry || extra) return fail(`Usage: /${commandName('mcp')} [list | tools|enable|disable|reconnect <entry-id>]` + (notice ? `\n${notice}` : ''));
+    if (action === 'tools') return ok(ctx.tools.schemas(agent).filter(t => t.name.startsWith(`mcp__${entry.options.config?.serverName}__`)).map(t => t.name).join('\n') || 'No tools currently registered.');
+    if (!['enable', 'disable', 'reconnect'].includes(action)) return fail('Unknown MCP action.');
+    return mutate(async () => {
+      if (action === 'reconnect' && entry.disabled) return fail('Enable this server before reconnecting.');
+      if (action === 'reconnect') await entry.update({ disabled: true });
+      await entry.update({ disabled: action === 'disable' });
+      return ok(`${entry.id}: ${state(entry)}. Use /${commandName('mcp')} tools ${entry.id} to check discovery.`);
+    });
+  });
+  register('skills', 'Skill catalog, sources, details and filesystem conflicts', async ({ agent, rawInput, signal }) => {
+    const options = { cwd: agent.session.header.cwd ?? process.cwd(), scope: agent, signal };
+    const { skills, complete } = await ctx.skills.snapshot(options);
+    const arg = rawInput.trim();
+    if (arg === 'conflicts') {
+      const inventory = composition(agent);
+      const report = await findConflicts(options.cwd, inventory.entries.filter(e => !e.disabled && e.options.name === '@deepseek-ai/dsh-skill-filesystem').map(e => plainConfig(e.options.config)), skills);
+      const missingPresetConfig = inventory.inspections?.some(preset => preset.modules.some(module => module.moduleName === '@deepseek-ai/dsh-skill-filesystem'));
+      return ok(report + (desktop ? '\nIncomplete: per-agent Desktop filesystem roots are not exposed by the preset inventory; only Host filesystem roots were checked.'
+        : missingPresetConfig ? '\nIncomplete: this runtime does not expose preset filesystem configuration; only Host filesystem roots were checked.' : ''));
+    }
+    if (arg && arg !== 'list') {
+      const skill = await ctx.skills.get(arg, options);
+      return skill ? ok(`${skill.name}\n${skill.description}\nsource: ${skill.source}\nprovider: ${skill.provider}\npath: ${skill.path ?? '(provider managed)'}\ninvocation: ${show(skill.invocation)}`) : fail(`Unknown skill: ${arg}`);
+    }
+    return ok(`Discovery: ${complete ? 'complete' : 'incomplete'}\n${skills.map(s => `${s.name} [${s.source}; ${s.provider}] user=${s.invocation.userInvocable} model=${s.invocation.modelInvocable}\n  ${s.description}`).join('\n')}\n/${commandName('skills')} <name> for details; /${commandName('skills')} conflicts for duplicate filesystem names.`);
+  });
+  const hookPaths = new WeakMap();
+  const hookPath = entry => {
+    const path = entry.fiber?.config?.configPath ?? entry.options.config?.configPath;
+    if (typeof path === 'string') { hookPaths.set(entry, path); return path; }
+    const cached = hookPaths.get(entry) ?? ctx.get('dscodePaths')?.hooks;
+    if (typeof cached !== 'string') throw new Error('Hook configuration path has not resolved');
+    return cached;
+  };
+  register('hooks', 'Hook status and reload/disable/enable (installation-owned config)', async ({ rawInput }) => {
+    const entry = hook();
+    if (!entry) return fail('Hooks plugin is not mounted. Restart dscode after setup.');
+    const action = rawInput.trim() || 'list';
+    if (action !== 'list') {
+      if (!['reload', 'disable', 'enable'].includes(action)) return fail('Usage: /hooks [list|reload|disable|enable]');
+      return mutate(async () => {
+        if (action !== 'disable') validateHooks(JSON.parse(await readFile(hookPath(entry), 'utf8')));
+        if (action === 'reload') await entry.update({ disabled: true });
+        await entry.update({ disabled: action === 'disable' });
+        return ok(`Hooks: ${state(entry)}. Configuration changes apply after reload or restart.`);
+      });
+    }
+    const path = hookPath(entry);
+    const raw = JSON.parse(await readFile(path, 'utf8'));
+    const hooks = raw.hooks ?? raw;
+    const report = await readFile(join(dirname(path), hookReportFile), 'utf8').then(JSON.parse).catch(() => undefined);
+    const stale = report ? await staleLayers(path, report.sources) : [];
+    return ok(`Hooks: ${state(entry)}\nConfig: ${path}\n${Object.entries(hooks).map(([event, groups]) => `${event}: ${hookEvents.includes(event) ? 'supported' : 'UNSUPPORTED'}; ${Array.isArray(groups) ? groups.length : 0} groups`).join('\n')}\nSupported: ${hookEvents.join(', ')}\nOnly synchronous command hooks. Runs as your OS user, outside tool approval. Edit only trusted installation-owned config; /hooks reload applies it. Project files (.codex/hooks.json, .dsh/hooks.json, .claude/settings.json) layer on top unless DSCODE_PROJECT_HOOKS=0; events this bridge does not support are skipped rather than fatal, and any edit to a layer needs a restart.${report ? `\nLayers: ${report.sources.join(', ')}${report.skipped.length ? `\nSkipped by this bridge: ${report.skipped.map(entry => `${entry.path}: ${entry.events.join(', ')}`).join('; ')}` : ''}` : ''}${stale.length ? `\nNeeds restart: ${stale.join('; ')} — /hooks reload re-reads the merged file, not its sources.` : ''}\nPreCompact/PostCompact, PermissionRequest and subagent events are not supported by this bridge.`);
+  });
+}

package/plugins/tui-tools/sandbox-runner.mjs

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+// A custom runner for @deepseek-ai/dsh-sandbox-local, selected through the `sandbox`
+// row's `runnerCommand`. The provider appends a bwrap-compatible profile and then
+// `--` and the command:
+//
+//   dsh-sandbox-runner --ro-bind / / --dev /dev --unshare-pid --proc /proc
+//     --die-with-parent [--tmpfs /tmp] [--bind <root> <root>] -- <command...>
+//
+// We translate the profile into a Seatbelt one and add the single grant the built-in
+// profile lacks: /dev/ptmx. Without it a confined command cannot allocate a PTY
+// (posix_openpt returns EPERM), which silently breaks nested harnesses, tmux, expect
+// and any node-pty based suite. When the kernel refuses to apply another profile —
+// which is exactly what happens inside an already-confined process — the command
+// inherits the enclosing profile instead of nesting a second one.
+import { spawn, spawnSync } from 'node:child_process';
+import { realpathSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const NAME = 'dscode-sandbox-runner';
+// Configure this string as runnerFailureSignatures so the provider recognises our
+// own failures instead of reading them as a denied command.
+export const FATAL_PREFIX = `${NAME}: fatal: `;
+// Informational output must never carry the configured failure signature: the provider
+// turns any non-zero exit whose stderr matches it into a sandbox failure, so a notice
+// would misreport a failing command as a broken runner.
+export const NOTICE_PREFIX = `${NAME}: notice: `;
+export const SANDBOX_EXEC = '/usr/bin/sandbox-exec';
+
+const OPERAND_FLAGS = new Map([['--ro-bind', 2], ['--bind', 2], ['--tmpfs', 1], ['--dev', 1], ['--proc', 1], ['--dir', 1]]);
+
+const canonical = path => {
+  try { return realpathSync(path); } catch { return resolve(path); }
+};
+
+const sbpl = path => `"${String(path).replaceAll('\\', '\\\\').replaceAll('"', '\\"')}"`;
+
+/** Split the appended bwrap-compatible profile from the command after `--`. */
+export function parseProfile(argv) {
+  const writable = [];
+  let index = 0;
+  while (index < argv.length) {
+    const token = argv[index];
+    if (token === '--') { index += 1; break; }
+    if (!token.startsWith('--')) throw new Error(`unexpected profile argument ${JSON.stringify(token)}`);
+    const operands = OPERAND_FLAGS.get(token) ?? 0;
+    if (operands === 2) {
+      const [, destination] = [argv[index + 1], argv[index + 2]];
+      if (!destination) throw new Error(`${token} needs two operands`);
+      if (token === '--bind') writable.push(destination);
+    } else if (operands === 1 && !argv[index + 1]) throw new Error(`${token} needs an operand`);
+    index += operands + 1;
+  }
+  return { writable, command: argv.slice(index) };
+}
+
+/** Writable roots that mirror the provider's own Seatbelt grant, plus the temp areas. */
+export function writableRoots(parsed, { temp = tmpdir() } = {}) {
+  return [...new Set([...parsed.writable, '/tmp', temp].map(canonical))];
+}
+
+/** The SBPL profile: upstream's deny-by-default write policy plus /dev/ptmx. */
+export function seatbeltProfile(roots) {
+  const forms = [
+    '(version 1)',
+    '(allow default)',
+    '(deny file-write*)',
+    `(allow file-write* (literal ${sbpl('/dev/null')}))`,
+    `(allow file-write* (literal ${sbpl('/dev/ptmx')}))`,
+  ];
+  if (roots.length) forms.push(`(allow file-write* ${roots.map(root => `(subpath ${sbpl(root)})`).join(' ')})`);
+  return forms.join(' ');
+}
+
+/** Whether this process may apply a Seatbelt profile at all. */
+export function seatbeltApplies(exec = SANDBOX_EXEC) {
+  const probe = spawnSync(exec, ['-p', '(version 1)(allow default)', '/usr/bin/true'], { stdio: ['ignore', 'ignore', 'pipe'], encoding: 'utf8' });
+  if (probe.error) return probe.error.code === 'ENOENT' ? { ok: false, reason: 'missing' } : { ok: false, reason: probe.error.message };
+  if (probe.status === 0) return { ok: true };
+  return { ok: false, reason: (probe.stderr ?? '').trim().split('\n').at(-1) || `exit ${probe.status}` };
+}
+
+const SIGNAL_CODES = { SIGHUP: 129, SIGINT: 130, SIGTERM: 143 };
+
+function runUnder(program, args) {
+  return new Promise(resolvePromise => {
+    const child = spawn(program, args, { stdio: 'inherit' });
+    const forward = signal => () => { try { child.kill(signal); } catch { /* already gone */ } };
+    const handlers = Object.keys(SIGNAL_CODES).map(signal => [signal, forward(signal)]);
+    for (const [signal, handler] of handlers) process.on(signal, handler);
+    child.on('error', error => { process.stderr.write(`${FATAL_PREFIX}${error.message}\n`); resolvePromise(126); });
+    child.on('exit', (code, signal) => resolvePromise(code ?? SIGNAL_CODES[signal] ?? 1));
+  });
+}
+
+export async function run(argv, { exec = SANDBOX_EXEC, stderr = process.stderr } = {}) {
+  const parsed = parseProfile(argv);
+  if (parsed.command.length === 0) {
+    stderr.write(`${FATAL_PREFIX}no command after --\n`);
+    return 126;
+  }
+  const [program, ...args] = parsed.command;
+  const applies = seatbeltApplies(exec);
+  if (!applies.ok && applies.reason === 'missing') {
+    stderr.write(`${FATAL_PREFIX}${exec} is not available; refusing to run unconfined\n`);
+    return 126;
+  }
+  if (!applies.ok) {
+    // Applying a profile is what the kernel refuses inside an existing one, so this
+    // process is already confined: inherit that profile rather than nest a second.
+    stderr.write(`${NOTICE_PREFIX}inheriting the enclosing profile (${applies.reason})\n`);
+    return runUnder(program, args);
+  }
+  return runUnder(exec, ['-p', seatbeltProfile(writableRoots(parsed)), '--', program, ...args]);
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  run(process.argv.slice(2)).then(code => { process.exitCode = code; }).catch(error => {
+    process.stderr.write(`${FATAL_PREFIX}${error.message}\n`);
+    process.exitCode = 126;
+  });
+}

package/plugins/tui-tools/shell.mjs

@@ -0,0 +1,27 @@
+import { spawn } from 'node:child_process';
+
+// User-authored shell commands only: never registered as an agent tool.
+export function runShell(command, { cwd, signal, timeoutMs = 120000, maxBytes = 65536 } = {}) {
+  if (!command.trim()) return Promise.resolve({ kind: 'error', text: 'Usage: !<shell command>' });
+  if (signal?.aborted) return Promise.resolve({ kind: 'error', text: 'Shell command cancelled' });
+  return new Promise(resolve => {
+    const child = spawn(process.env.SHELL || '/bin/sh', ['-c', command], { cwd, detached: true, stdio: ['ignore', 'pipe', 'pipe'] });
+    let output = '', bytes = 0, stopped = '', failure;
+    const collect = chunk => {
+      if (bytes < maxBytes) output += chunk.subarray(0, maxBytes - bytes).toString();
+      bytes += chunk.length;
+    };
+    const kill = () => { try { process.kill(-child.pid, 'SIGKILL'); } catch {} };
+    const cancel = () => { stopped = 'cancelled'; kill(); };
+    const timer = setTimeout(() => { stopped = 'timed out'; kill(); }, timeoutMs);
+    signal?.addEventListener('abort', cancel, { once: true });
+    child.stdout.on('data', collect);
+    child.stderr.on('data', collect);
+    child.on('error', error => { failure = error.message; });
+    child.on('close', (code, exitSignal) => {
+      clearTimeout(timer);
+      signal?.removeEventListener('abort', cancel);
+      resolve({ kind: code === 0 && !stopped && !failure ? 'success' : 'error', text: [output.trimEnd(), bytes > maxBytes ? '[output truncated]' : '', failure || (stopped ? `Shell command ${stopped}` : `Exit ${code ?? exitSignal}`)].filter(Boolean).join('\n') });
+    });
+  });
+}