@logicseek/hello-cc 1.0.1 → 1.0.2

package/lib/cli/app.mjs

@@ -33,6 +33,9 @@ import { createTeamCommands } from '../cli/commands/team.mjs';
 import { createMiscCommands } from '../cli/commands/misc.mjs';
 import { createInstallCommands } from '../cli/commands/install.mjs';
 import { createHookCommand } from '../cli/commands/hook.mjs';
+import { createDshCommands } from '../cli/commands/dsh.mjs';
+import { createNativeCommands } from '../cli/commands/native.mjs';
+import { createMcpCommands } from '../cli/commands/mcp.mjs';
 import { createPeerCommands } from '../cli/commands/peer.mjs';
 import { createRunCommands } from '../cli/commands/run.mjs';
 import { createTmuxCommands } from '../cli/commands/tmux.mjs';
@@ -291,6 +294,11 @@ const { cmdPeers, cmdStatus, cmdState, cmdPrompt } = createQueryCommands({
   clockGraceSuppressed, readClockGraceUntil, commandPath
 });
 
+const { cmdNative } = createNativeCommands({ connect, upsertPeer, upsertCanonicalPeerBinding,
+  sendMessage, ackMessage, queryInbox, addEvent, liveProcessIdentity, detectBranch,
+  resolveCurrentPeer });
+const { cmdMcp } = createMcpCommands({ connect, touchPeer, now, addEvent });
+
 const { cmdInit, cmdRegister, cmdEnv, cmdJoin } = createLifecycleCommands({
   connect, now, tx, addEvent, printResult, CliError, parseOpts, intOpt,
   registerProjectActivity, resolveCurrentPeer, resolveTargetPeer,
@@ -341,6 +349,8 @@ const { cmdHook } = createHookCommand({
   path, fs, process, CliError
 });
 
+const { cmdDsh } = createDshCommands();
+
 const { cmdPeer } = createPeerCommands({
   connect, now, tx, addEvent, auditPayload, printResult, CliError, parseOpts,
   detectBranch, buildPeerCommand, childSessionEnv, inferPeerKind,
@@ -471,8 +481,8 @@ const { cmdWeb } = createWebRuntime({
   sameResolvedPath, sendWebHtml, shellCommand, webErrorStatus
 });
 
-function renderWebIndex(nonce) {
-  return webUiTemplate.webIndexHtml({ nonce });
+function renderWebIndex(nonceOrOptions) {
+  return webUiTemplate.webIndexHtml(typeof nonceOrOptions === 'string' ? { nonce: nonceOrOptions } : nonceOrOptions);
 }
 
 function renderWebLogin(nonce) {
@@ -484,18 +494,24 @@ function renderWebLogin(nonce) {
 </body></html>`;
 }
 
-function sendWebHtml(res, render) {
+function sendWebHtml(res, render, { pane = false } = {}) {
   const nonce = randomBytes(18).toString('base64url');
-  sendHttp(res, 200, 'text/html; charset=utf-8', render(nonce), { nonce });
+  const options = { nonce, pane: pane === true };
+  sendHttp(res, 200, 'text/html; charset=utf-8', render(options.pane ? options : nonce), options);
 }
 
 function webErrorStatus(err) {
   if (!(err instanceof CliError)) return 500;
   if (err.code === 'REGISTRY_BUSY') return 503;
+  if (err.code === 'CODEX_START_FAILED') return 503;
+  if (err.code.startsWith('CODEX_') || ['STALE_CONTROL_EPOCH', 'UNKNOWN_CONTROL_CLIENT'].includes(err.code)) return 409;
   if (['BAD_ARGS', 'BAD_REQUEST', 'PEER_IDENTITY_REQUIRED', 'REQUEST_TOO_LARGE'].includes(err.code)) return 400;
-  if (['PEER_IDENTITY_MISMATCH', 'TASK_OWNED', 'LOCK_OWNED', 'PROJECT_NOT_REGISTERED', 'PROJECT_PATH_FORBIDDEN'].includes(err.code)) return 403;
+  if (['PEER_IDENTITY_MISMATCH', 'TASK_OWNED', 'TASK_OWNER_MISMATCH', 'LOCK_OWNED', 'PROJECT_NOT_REGISTERED', 'PROJECT_PATH_FORBIDDEN', 'RUNTIME_ADMIN_REQUIRED'].includes(err.code)) return 403;
+  if (err.code.startsWith('NATIVE_')) return err.code === 'NATIVE_RUNTIME_OFFLINE' ? 503 : 409;
   if (['NOT_FOUND'].includes(err.code)) return 404;
-  if (['LOCK_HELD', 'SESSION_NOT_RUNNING'].includes(err.code)) return 409;
+  if (['LOCK_HELD', 'SESSION_NOT_RUNNING', 'CONTROL_REQUIRED', 'CONTROL_STALE',
+    'CONTROL_HELD', 'CONTROL_DISCONNECTED', 'HANDOFF_REQUIRED', 'THREAD_IN_USE',
+    'SUBMISSION_EXISTS', 'STRUCTURED_SESSION_NO_TERMINAL', 'CODEX_UNCERTAIN_SUBMISSION', 'CODEX_TURN_ACTIVE'].includes(err.code)) return 409;
   return 500;
 }
 
@@ -598,6 +614,9 @@ async function dispatch(ctx, rest) {
   if (command === 'event') return cmdEvent(ctx, args);
   if (command === 'web') return cmdWeb(ctx, args);
   if (command === 'hook') return cmdHook(ctx, args);
+  if (command === 'dsh') return cmdDsh(ctx, args);
+  if (command === 'native') return cmdNative(ctx, args);
+  if (command === 'mcp') return cmdMcp(ctx, args);
   if (command === 'install-hooks') return cmdInstallHooks(ctx, args);
   if (command === 'shim') return cmdShim(ctx, args);
   if (command === 'setup') return cmdSetup(ctx, args);

package/lib/cli/commands/doctor.mjs

@@ -2,15 +2,20 @@
 
 import fs from 'node:fs';
 import { printResult } from '../../format.mjs';
+import { diagnoseCodex, unknownCodexDiagnostics } from '../../diagnostics/codex.mjs';
 
-export function createDoctorCommand({ connectReadOnly, readSchemaVersion, DB_SCHEMA_VERSION, CLI_NAME }) {
+export function createDoctorCommand({ connectReadOnly, readSchemaVersion, DB_SCHEMA_VERSION, CLI_NAME,
+  codexDiagnostics = diagnoseCodex }) {
   async function cmdDoctor(ctx, args) {
     if (args[0] === '--help' || args[0] === '-h') {
-      console.log(`${CLI_NAME} doctor [--json]
+      console.log(`${CLI_NAME} doctor [--codex] [--json]
 
 Runs a read-only health check on the project database: PRAGMA integrity_check,
 schema compatibility, persistent journal mode, DB and WAL file sizes, and
 per-table row counts. Exits non-zero for corruption or an unsupported schema.
+With --codex, also reads bounded version/help output, hooks configuration and
+project hook invocation evidence. Configuration is not trust or a delivery
+receipt. No model, session, hook, account or trust change is performed.
 `);
       return;
     }
@@ -52,6 +57,11 @@ per-table row counts. Exits non-zero for corruption or an unsupported schema.
         },
         row_counts: counts
       };
+      const delimiter = args.indexOf('--');
+      if ((delimiter < 0 ? args : args.slice(0, delimiter)).includes('--codex')) {
+        try { report.codex = codexDiagnostics(ctx, db); }
+        catch { report.codex = unknownCodexDiagnostics(); }
+      }
     } finally {
       db.close();
     }
@@ -72,6 +82,11 @@ per-table row counts. Exits non-zero for corruption or an unsupported schema.
         `  db size:         ${r.db_size_bytes ?? '?'} bytes${r.wal_size_bytes ? `  (wal ${r.wal_size_bytes})` : ''}`,
         `  rows:            ` + Object.entries(r.row_counts).map(([k, v]) => `${k}=${v}`).join('  ')
       ];
+      if (r.codex) {
+        lines.push(`  codex version:   ${r.codex.version.value ?? 'unknown'} (${r.codex.version.status})`,
+          `  app-server:      ${r.codex.app_server.status}  startup: ${r.codex.app_server.startup_arguments?.join(' ') || 'unknown'}  handshake: unknown`,
+          `  codex hooks:     configured=${r.codex.hooks.configuration.status}  invocation=${r.codex.hooks.invocation.status}  stdout receipt=unknown  provider acceptance=unknown  trust=unknown`);
+      }
       return lines.join('\n');
     });
     if (!healthy) process.exitCode = 1;

package/lib/cli/commands/dsh.mjs

@@ -0,0 +1,79 @@
+import process from 'node:process';
+import { CliError } from '../../shared/errors.mjs';
+import { parseOpts, validateOpts, wantsHelp } from '../../cli-args.mjs';
+import { commandPath } from '../../cli-runtime.mjs';
+import { printResult } from '../../format.mjs';
+import {
+  DSH_INSTALL_HINT, ensureDshIntegration, inspectDshIntegration,
+  resolveDshBinary, launchDshWeb
+} from '../../integrations/dsh.mjs';
+
+function defaultHelp() {
+  console.log([
+    'Usage: hcc dsh setup [--mode hooks|cordis|off]',
+    '       hcc dsh status [--dsh-bin PATH]',
+    '       hcc dsh web [--mode hooks|cordis|off] [--dsh-bin PATH] [--dsh-home PATH] -- [dsh web arguments]',
+    '',
+    'Setup writes project-local configuration under .hello-cc/dsh/. Modes: hooks (default), cordis (native tools), off.',
+    'Web starts the official dsh web runtime; its real sessions join hello-cc through the selected integration.',
+    'Pass runtime arguments after --, for example: hcc dsh web -- --port 8080',
+    'Show dsh web help: hcc dsh web -- --help',
+    `Install the tested dsh version: ${DSH_INSTALL_HINT}`
+  ].join('\n'));
+}
+
+export function createDshCommands(deps = {}) {
+  const getCommandPath = deps.commandPath || commandPath;
+  const help = deps.helpDsh || defaultHelp;
+
+  async function cmdDsh(ctx, args) {
+    const helpBoundary = args.indexOf('--');
+    const wrapperArgs = helpBoundary < 0 ? args : args.slice(0, helpBoundary);
+    if (!args.length || wantsHelp(wrapperArgs)) return help();
+    const sub = args[0];
+    if (!['setup', 'status', 'web'].includes(sub)) throw new CliError('BAD_ARGS', `Unknown dsh subcommand: ${sub}`);
+    const tail = args.slice(1);
+    const boundary = tail.indexOf('--');
+    const forwarded = boundary < 0 ? [] : tail.slice(boundary + 1);
+    const opts = parseOpts(boundary < 0 ? tail : tail.slice(0, boundary));
+    const allowed = sub === 'setup' ? ['mode'] : sub === 'status' ? ['dsh-bin'] : ['mode', 'dsh-bin', 'dsh-home'];
+    validateOpts(`dsh ${sub}`, opts, allowed);
+    if (sub !== 'web' && boundary >= 0) throw new CliError('BAD_ARGS', `dsh ${sub}: unexpected -- argument separator`);
+    if (opts.mode !== undefined && !['hooks', 'cordis', 'off'].includes(opts.mode)) throw new CliError('BAD_ARGS', '--mode must be hooks, cordis, or off');
+    for (const name of allowed.filter(name => name !== 'mode')) {
+      if (opts[name] !== undefined && !opts[name]) throw new CliError('BAD_ARGS', `--${name} must be a non-empty path`);
+    }
+    const config = { hccBin: getCommandPath(), ...(opts.mode !== undefined ? { mode: opts.mode } : {}) };
+    if (sub === 'setup') {
+      const result = ensureDshIntegration(ctx, config);
+      const label = result.changed.length ? 'configured' : 'already current';
+      printResult(ctx, result, (data) => [
+        `dsh integration ${label}: ${data.root}`,
+        `hooks: ${data.hooksPath}`,
+        `patch: ${data.patchPath}`,
+        `mode: ${data.mode}`,
+        'start: hcc dsh web'
+      ].join('\n'));
+      return;
+    }
+    if (sub === 'status') {
+      const result = inspectDshIntegration(ctx, config);
+      const binary = resolveDshBinary({ dshBin: opts['dsh-bin'], cwd: ctx.cwd });
+      const data = { ...result, binary, installed: Boolean(binary), installHint: binary ? null : DSH_INSTALL_HINT };
+      const binaryLabel = binary || `missing (install: ${DSH_INSTALL_HINT})`;
+      printResult(ctx, data, () => [
+        `dsh integration: ${result.state}`,
+        `mode: ${result.mode || 'unknown'}`,
+        `binary: ${binaryLabel}`,
+        result.error?.message,
+        !result.ready && result.state !== 'conflict' ? 'configure: hcc dsh setup' : null
+      ].filter(Boolean).join('\n'));
+      return;
+    }
+    const result = await launchDshWeb(ctx, { ...config, dshBin: opts['dsh-bin'], dshHome: opts['dsh-home'], args: forwarded });
+    if (result.signal) process.kill(process.pid, result.signal);
+    else process.exitCode = result.code ?? 1;
+  }
+
+  return { cmdDsh };
+}

package/lib/cli/commands/hook.mjs

@@ -1,5 +1,9 @@
 // Hook command extracted from bin/hcc.mjs.
-// This is the provider hook entry point called by Claude/Codex hooks.
+// This is the provider hook entry point called by Claude/Codex/dsh hooks.
+
+import { parseOpts, validateOpts } from '../../cli-args.mjs';
+import { tx } from '../../db/schema.mjs';
+import { resolveProjectDatabase } from '../../runtime/project-path.mjs';
 
 export function createHookCommand(deps) {
   const {
@@ -18,46 +22,86 @@ export function createHookCommand(deps) {
   } = deps;
 
 async function cmdHook(ctx, args) {
-  let hookType = args[0] || 'unknown';
+  const opts = parseOpts(args);
+  let hookType = opts._.shift() || 'unknown';
+  validateOpts('hook', opts, ['provider']);
+  if (opts.provider !== undefined && !['claude', 'codex', 'dsh'].includes(opts.provider)) {
+    throw new CliError('BAD_ARGS', 'hook: --provider must be claude, codex, or dsh');
+  }
+  const kind = opts.provider || autoPeerKind('other');
+  const isDsh = kind === 'dsh';
+  const nativeOwner = process.env.HCC_NATIVE_OWNER || null;
+  if (nativeOwner && (!process.env.HCC_PEER || !process.env.HCC_ROOT || !process.env.HCC_DB)) {
+    throw new CliError('NATIVE_HOOK_OWNERSHIP_MISMATCH', 'Native hook needs an explicit worker peer, root, and database');
+  }
 
   // Read stdin with a short timeout (hooks must complete quickly)
   const raw = await new Promise((resolve) => {
     let buf = '';
-    const timer = setTimeout(() => resolve(buf), 2000);
+    const finish = () => {
+      clearTimeout(timer);
+      process.stdin.removeListener('data', onData);
+      process.stdin.removeListener('end', finish);
+      process.stdin.removeListener('error', finish);
+      process.stdin.pause();
+      resolve(buf);
+    };
+    const onData = (c) => { buf += c; };
+    const timer = setTimeout(finish, 2000);
     process.stdin.setEncoding('utf8');
-    process.stdin.on('data', (c) => { buf += c; });
-    process.stdin.on('end', () => { clearTimeout(timer); resolve(buf); });
-    process.stdin.on('error', () => { clearTimeout(timer); resolve(buf); });
+    process.stdin.on('data', onData);
+    process.stdin.on('end', finish);
+    process.stdin.on('error', finish);
   });
 
   let payload = {};
   try { payload = JSON.parse(raw); } catch {}
+  if (isDsh && (!payload || typeof payload !== 'object' || Array.isArray(payload))) {
+    throw new CliError('BAD_HOOK_PAYLOAD', 'dsh hook requires a JSON object with session_id and cwd');
+  }
+  // Keep ordinary hooks tolerant of malformed/empty input as before.
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) payload = {};
   hookType = payload.hook_event_name || payload.hookEventName || hookType;
+  if (isDsh && typeof hookType !== 'string') {
+    throw new CliError('BAD_HOOK_PAYLOAD', 'dsh hook requires a valid hook event');
+  }
   const hookEventName = formatHookEventName(hookType);
   const hookKey = hookEventName.replace(/[^a-z]/gi, '').toLowerCase();
+  if (isDsh && !['sessionstart', 'userpromptsubmit', 'pretooluse', 'posttooluse', 'stop'].includes(hookKey)) {
+    throw new CliError('BAD_HOOK_PAYLOAD', 'Unsupported dsh hook event');
+  }
 
-  // Extract session identity (Claude Code sets these in its hook JSON)
-  const kind = autoPeerKind('other');
-  const providerSession = autoPeerProviderSession(kind);
-  const sessionId  = payload.session_id || payload.sessionId || payload.conversation_id || payload.conversationId ||
-    providerSession.sessionId || '';
-  const hookCwd    = payload.cwd         || payload.workingDirectory || process.cwd();
+  // A dsh service can host many sessions and workspaces. Only its per-hook
+  // payload identifies the conversation; service environment belongs to none.
+  const providerSession = isDsh ? {} : autoPeerProviderSession(kind);
+  const sessionId = isDsh
+    ? payload.session_id
+    : payload.session_id || payload.sessionId || payload.conversation_id || payload.conversationId || providerSession.sessionId || '';
+  const hookCwd = isDsh ? payload.cwd : payload.cwd || payload.workingDirectory || process.cwd();
+  if (isDsh) validateDshHookIdentity(sessionId, hookCwd);
 
   // Hooks auto-join the exact current project path, creating its mesh.db on
-  // first use. Cross-path sharing is explicit via HCC_ROOT/HCC_DB.
-  const hccRoot = process.env.HCC_ROOT
+  // first use. Ordinary hooks allow explicit cross-path sharing via HCC_ROOT.
+  const hccRoot = (nativeOwner || !isDsh) && process.env.HCC_ROOT
     ? path.resolve(process.env.HCC_ROOT)
     : path.resolve(hookCwd);
 
+  const dshProject = isDsh && !nativeOwner ? resolveProjectDatabase({ root: hccRoot, createStateDir: false }) : null;
+  const nativeProject = nativeOwner ? resolveProjectDatabase({ root: hccRoot,
+    db: process.env.HCC_DB, createStateDir: false }) : null;
+  if (nativeProject && !fs.existsSync(nativeProject.db)) {
+    throw new CliError('NATIVE_HOOK_OWNERSHIP_MISMATCH', 'Native hook database must already be owned by its runtime');
+  }
   const hookCtx = {
     ...ctx,
-    root: hccRoot,
-    dbPath: path.join(hccRoot, '.hello-cc', 'mesh.db')
+    root: nativeProject?.root || dshProject?.root || hccRoot,
+    dbPath: nativeProject?.db || dshProject?.db || path.join(hccRoot, '.hello-cc', 'mesh.db')
   };
-  registerProjectActivity(hookCtx);
+  if (!nativeOwner) registerProjectActivity(hookCtx);
 
-  // Derive peer ID: HCC_PEER > resume ID from parent cmdline > session ID > terminal
-  let peerId = process.env.HCC_PEER;
+  // dsh uses only its true session ID. Ordinary hooks retain environment,
+  // resume, session, and terminal identity precedence.
+  let peerId = isDsh && !nativeOwner ? providerSessionPeerId(kind, sessionId) : process.env.HCC_PEER;
   let resumeId = null;
   if (!peerId) {
     resumeId = providerSession.resumeId || readParentResumeId(kind);
@@ -71,67 +115,99 @@ async function cmdHook(ctx, args) {
       : `${kind}-${shortHash(`${hookCtx.root}:${autoPeerBasis(kind)}`)}`;
   }
 
-  const db = connect(hookCtx);
+  // Hook delivery must not migrate another workspace's registered database.
+  const db = isDsh || nativeOwner ? connect(hookCtx, { migrateRegistered: false }) : connect(hookCtx);
   try {
+    if (nativeOwner) {
+      // Native delivery owns context injection and completion receipts. Hooks
+      // only renew its verified owner, never turn a native binding into a
+      // terminal binding or consume the same inbox through a second path.
+      tx(db, () => {
+        const binding = db.prepare(`
+          SELECT b.*, p.kind AS peer_kind FROM peer_bindings b
+          JOIN peers p ON p.id = b.peer WHERE b.peer = ?
+        `).get(peerId);
+        if (!binding || binding.transport !== 'native' || binding.runtime_target !== nativeOwner ||
+            binding.peer_kind !== binding.provider || (opts.provider && binding.provider !== kind)) {
+          throw new CliError('NATIVE_HOOK_OWNERSHIP_MISMATCH', 'Native hook does not match its runtime-owned peer binding');
+        }
+        const observedAt = now();
+        db.prepare('UPDATE peers SET last_seen_at = ? WHERE id = ?').run(observedAt, peerId);
+        const renewed = renewOwnedLocks(db, { owner: peerId, nowSec: observedAt,
+          ttlCap: 3600, includeExpired: true });
+        if (renewed > 0) addEvent(db, 'lock.renewed_by_hook', peerId, null, { renewed, source: 'native-hook' });
+      });
+      process.exitCode = 0;
+      return;
+    }
     const status = hookKey === 'stop' ? 'idle' : 'working';
-    const providerAncestor = readAncestorCliInfo();
+    const providerAncestor = readAncestorCliInfo(isDsh ? 'dsh' : undefined);
     const providerPid = providerAncestor?.kind === kind ? Number(providerAncestor.pid) : null;
     const providerIdentity = providerPid ? liveProcessIdentity(providerPid) : null;
-    const existing = db.prepare('SELECT id FROM peers WHERE id = ?').get(peerId);
-    if (!existing) {
-      upsertPeer(db, {
-        id: peerId, kind, role: 'peer',
-        worktree: hookCwd,
-        branch: detectBranch(hookCwd),
-        pid: providerIdentity?.pid || null,
-        processIdentity: providerIdentity,
-        status,
-        capabilities: `hook-${hookKey}`
-      });
-    } else {
-      refreshHookOwnerIdentity(db, {
-        peerId,
-        status,
-        observedAt: now(),
-        processIdentity: providerIdentity
-      });
-    }
-    const hookBinding = {
-      peer: peerId,
-      provider: kind,
-      ...providerSessionParts(resumeId || sessionId),
-      resume_mode: resumeId ? 'resume' : (sessionId ? 'detected' : 'unknown'),
-      resume_arg: resumeId || null,
-      command: null,
-      transport: 'hook',
-      runtime_session_id: peerId
-    };
-    const canonical = upsertCanonicalPeerBinding(db, hookBinding, true);
-    if (canonical.peer !== peerId) {
-      const previousPeer = peerId;
-      peerId = canonical.peer;
-      refreshHookOwnerIdentity(db, {
-        peerId,
-        status,
-        observedAt: now(),
-        processIdentity: providerIdentity
-      });
-      addEvent(db, 'provider.session.merged', peerId, null, auditPayload({
+    const registerHookIdentity = () => {
+      if (isDsh) assertDshHookBinding(db, peerId, sessionId);
+      const existing = db.prepare('SELECT id FROM peers WHERE id = ?').get(peerId);
+      if (!existing) {
+        upsertPeer(db, {
+          id: peerId, kind, role: 'peer',
+          worktree: hookCwd,
+          branch: detectBranch(hookCwd),
+          pid: providerIdentity?.pid || null,
+          processIdentity: providerIdentity,
+          status,
+          capabilities: `hook-${hookKey}`
+        });
+      } else {
+        refreshHookOwnerIdentity(db, {
+          peerId,
+          status,
+          observedAt: now(),
+          processIdentity: providerIdentity
+        });
+      }
+      const hookBinding = {
+        peer: peerId,
+        provider: kind,
+        ...(isDsh
+          ? { provider_session_id: sessionId, provider_session_name: null }
+          : providerSessionParts(resumeId || sessionId)),
+        resume_mode: resumeId ? 'resume' : (sessionId ? 'detected' : 'unknown'),
+        resume_arg: resumeId || null,
+        command: null,
+        transport: 'hook',
+        runtime_session_id: peerId
+      };
+      const canonical = upsertCanonicalPeerBinding(db, hookBinding, true);
+      if (canonical.peer !== peerId) {
+        const previousPeer = peerId;
+        peerId = canonical.peer;
+        refreshHookOwnerIdentity(db, {
+          peerId,
+          status,
+          observedAt: now(),
+          processIdentity: providerIdentity
+        });
+        addEvent(db, 'provider.session.merged', peerId, null, auditPayload({
+          actor: peerId,
+          target: peerId,
+          source: 'hook',
+          from_peer: previousPeer,
+          provider: kind,
+          session_id: sessionId || resumeId || null
+        }));
+      }
+      addEvent(db, `hook.${hookKey}`, peerId, null, auditPayload({
         actor: peerId,
         target: peerId,
         source: 'hook',
-        from_peer: previousPeer,
-        provider: kind,
-        session_id: sessionId || resumeId || null
+        session_id: sessionId,
+        cwd: hookCwd
       }));
-    }
-    addEvent(db, `hook.${hookKey}`, peerId, null, auditPayload({
-      actor: peerId,
-      target: peerId,
-      source: 'hook',
-      session_id: sessionId,
-      cwd: hookCwd
-    }));
+    };
+    // Keep the dsh conflict check and identity/binding writes atomic, so a
+    // concurrent service/session registration cannot change the inspected row.
+    if (isDsh) tx(db, registerHookIdentity);
+    else registerHookIdentity();
     // hb-06: an active hook is proof the peer is working. During clock grace,
     // renew retained locks even when the wall-clock jump made them look expired.
     const hookNow = now();
@@ -152,46 +228,118 @@ async function cmdHook(ctx, args) {
     if (hookLockRenewals > 0) {
       addEvent(db, 'lock.renewed_by_hook', peerId, null, { renewed: hookLockRenewals });
     }
-    try {
-      reconcileRunningPeerBindings(db, hookCtx, {
-        inspectProcess: inspectProviderProcess,
-        latestProviderSessionForPeer: (peer) => latestHookProviderSession(db, peer),
-        addEvent,
-        now
-      });
-    } catch {}
+    if (!isDsh) {
+      try {
+        reconcileRunningPeerBindings(db, hookCtx, {
+          inspectProcess: inspectProviderProcess,
+          latestProviderSessionForPeer: (peer) => latestHookProviderSession(db, peer),
+          addEvent,
+          now
+        });
+      } catch {}
+    }
 
     if (['sessionstart', 'userpromptsubmit'].includes(hookKey)) {
       const snapshot = buildHookCoordinationContext(db, hookCtx, peerId);
-      ackMessages(db, peerId, snapshot.messages);
-      process.stdout.write(JSON.stringify({
+      await writeHookOutput({
         hookSpecificOutput: {
           hookEventName,
           additionalContext: snapshot.text
         }
-      }) + '\n');
-    } else if (['posttooluse', 'stop'].includes(hookKey)) {
+      });
+      ackMessages(db, peerId, snapshot.messages);
+    } else if (hookKey === 'posttooluse') {
       const snapshot = buildHookCoordinationContext(db, hookCtx, peerId);
       if (snapshot.messages.length > 0) {
-        ackMessages(db, peerId, snapshot.messages);
-        process.stdout.write(JSON.stringify({
+        await writeHookOutput({
           hookSpecificOutput: {
             hookEventName,
             additionalContext: snapshot.text
           }
-        }) + '\n');
+        });
+        ackMessages(db, peerId, snapshot.messages);
+      }
+    } else if (hookKey === 'stop' && payload.stop_hook_active !== true) {
+      // A blocking Stop hook causes another model turn. Do not block that
+      // continuation again; newly arrived messages stay unread for the next
+      // SessionStart, UserPromptSubmit, PostToolUse, or independent Stop.
+      const snapshot = buildHookCoordinationContext(db, hookCtx, peerId);
+      if (snapshot.messages.length > 0) {
+        await writeHookOutput({
+          decision: 'block',
+          reason: snapshot.text
+        });
+        ackMessages(db, peerId, snapshot.messages);
       }
     }
   } finally {
     try { db.close(); } catch {}
   }
-  process.exit(0);
+  // Let Node exit after the hook output has flushed instead of truncating a
+  // pipe with process.exit(). A successful write is not provider acceptance.
+  process.exitCode = 0;
 }
 
-// ─── hcc install-hooks ───────────────────────────────────────────────────────
+function writeHookOutput(output) {
+  return new Promise((resolve, reject) => {
+    const stdout = process.stdout;
+    const onError = (error) => reject(error);
+    stdout.once('error', onError);
+    try {
+      stdout.write(JSON.stringify(output) + '\n', (error) => {
+        if (error) {
+          // Writable emits its error after invoking the callback. Keep the
+          // once listener until that event so a failed pipe is handled.
+          reject(error);
+        } else {
+          stdout.removeListener('error', onError);
+          resolve();
+        }
+      });
+    } catch (error) {
+      stdout.removeListener('error', onError);
+      reject(error);
+    }
+  });
+}
 
+function validateDshHookIdentity(sessionId, cwd) {
+  if (typeof sessionId !== 'string' || !sessionId || sessionId.length > 1024 ||
+      sessionId.trim() !== sessionId || /[\u0000-\u001f\u007f]/.test(sessionId)) {
+    throw new CliError('BAD_HOOK_PAYLOAD', 'dsh hook requires a nonempty string session_id');
+  }
+  if (typeof cwd !== 'string' || !cwd || /[\u0000-\u001f\u007f]/.test(cwd) || !path.isAbsolute(cwd)) {
+    throw new CliError('BAD_HOOK_PAYLOAD', 'dsh hook requires an absolute cwd directory');
+  }
+  let isDirectory = false;
+  try { isDirectory = fs.statSync(cwd).isDirectory(); } catch {}
+  if (!isDirectory) throw new CliError('BAD_HOOK_PAYLOAD', 'dsh hook cwd must be an existing directory');
+}
 
-  return { cmdHook };
+function assertDshHookBinding(db, peerId, sessionId) {
+  const conflict = (reason, boundPeer = peerId) => {
+    throw new CliError('DSH_PEER_BINDING_CONFLICT',
+      `dsh hook session ${sessionId} conflicts with existing peer binding ${boundPeer}`, {
+        peer: peerId, bound_peer: boundPeer, session_id: sessionId, reason
+      });
+  };
+  const peer = db.prepare('SELECT kind FROM peers WHERE id = ?').get(peerId);
+  if (peer && peer.kind !== 'dsh') conflict('peer_provider_mismatch');
+  const binding = db.prepare('SELECT * FROM peer_bindings WHERE peer = ?').get(peerId);
+  if (binding) {
+    if (binding.provider !== 'dsh') conflict('binding_provider_mismatch');
+    if (binding.transport !== 'hook' || binding.runtime_target !== null) conflict('runtime_binding');
+    if (binding.provider_session_id !== sessionId || binding.provider_session_name !== null) {
+      conflict('session_id_mismatch');
+    }
+  }
+  const alias = db.prepare(`
+    SELECT peer FROM peer_bindings
+    WHERE provider = 'dsh' AND peer <> ?
+      AND (provider_session_id = ? OR provider_session_name = ?)
+    LIMIT 1
+  `).get(peerId, sessionId, sessionId);
+  if (alias) conflict('session_bound_to_another_peer', alias.peer);
 }
 
 function readParentResumeId(kind) {
@@ -203,3 +351,6 @@ function readParentResumeId(kind) {
   } catch {}
   return null;
 }
+
+  return { cmdHook };
+}