apt-mcp-agent-setup 3.5.65 → 3.9.0

package/src/installer/hook-dispatcher.js

@@ -1,179 +1,372 @@
-'use strict';
-
-// Embedded with a trusted installation key. Only built-in modules may be used
-// until the committed release has been verified.
-function hookDispatcher(root, publicKey) {
-  return { runCLI(host, event, projectPath, executionOptions = {}) {
-    const fs = require('node:fs'), path = require('node:path'), crypto = require('node:crypto');
-    // Host adapters pass the workspace as base64 so hook command shells never
-    // reinterpret path data. Keep absolute raw paths usable for internal calls.
-    const inputPath = String(projectPath);
-    const decodedProjectPath = Buffer.from(inputPath, 'base64').toString('utf8');
-    const workspaceInput = path.isAbsolute(inputPath) || !fs.existsSync(decodedProjectPath) ? inputPath : decodedProjectPath;
-    const workspace = fs.realpathSync(workspaceInput);
-    const canonical = process.platform === 'win32' ? workspace.toLowerCase() : workspace;
-    const authorityFile = path.join(workspace, '.agents', 'runtime', 'generation.json');
-    let selected;
-    try { selected = JSON.parse(fs.readFileSync(authorityFile, 'utf8')); }
-    catch (error) {
-      if (error.code !== 'ENOENT') throw error;
-      // Migration only: the workspace pin is explicit, never the machine's
-      // latest pointer or a release inferred from deployed resource version.
-      selected = JSON.parse(fs.readFileSync(path.join(root, 'workspaces',
-        crypto.createHash('sha256').update(canonical).digest('hex') + '.json'), 'utf8'));
-    }
-    if (selected.workspace && (process.platform === 'win32' ? selected.workspace.toLowerCase() : selected.workspace) !== canonical)
-      throw Error('HOOK_WORKSPACE_BINDING_CONFLICT');
-    if (!/^\d+\.\d+\.\d+$/.test(selected.version) || !/^[a-f0-9]{64}$/.test(selected.digest))
-      throw Error('HOOK_RUNTIME_BINDING_REQUIRED');
-    const release = path.join(root, 'releases', `${selected.version}-${selected.digest}`);
-    if (fs.lstatSync(release).isSymbolicLink()) throw Error('HOOK_RUNTIME_LINK_REJECTED');
-    const manifest = JSON.parse(fs.readFileSync(path.join(release, 'integrity-manifest.json'), 'utf8'));
-    if (crypto.createHash('sha256').update(JSON.stringify(manifest)).digest('hex') !== selected.digest ||
-        !crypto.verify(null, Buffer.from(JSON.stringify(manifest.files)), publicKey, Buffer.from(manifest.signature, 'base64url')))
-      throw Error('HOOK_RUNTIME_SIGNATURE_INVALID');
-    for (const required of ['src/core/hook-bridge.js'])
-      if (!manifest.files[required]) throw Error('HOOK_RUNTIME_RECONNECT_REQUIRED');
-    for (const [file, digest] of Object.entries(manifest.files)) {
-      if (path.isAbsolute(file) || file.includes('\\') || file.split('/').some(part => !part || part === '..' || part === '.'))
-        throw Error('HOOK_RUNTIME_PATH_INVALID');
-      let cursor = release;
-      for (const part of file.split('/')) {
-        cursor = path.join(cursor, part);
-        if (fs.lstatSync(cursor).isSymbolicLink()) throw Error('HOOK_RUNTIME_LINK_REJECTED');
-      }
-      if (crypto.createHash('sha256').update(fs.readFileSync(cursor)).digest('hex') !== digest)
-        throw Error('HOOK_RUNTIME_INTEGRITY_INVALID');
-    }
-    return require(path.join(release, 'src/core/hook-bridge.js')).runCLI(host, event,
-      Buffer.from(workspace, 'utf8').toString('base64'), executionOptions);
-  } };
-}
-
-// The parent only uses built-ins. Synchronous hashing/locks in the signed
-// worker cannot prevent the parent from producing a blocking decision.
-function superviseHook(root, publicKey, dispatcherSource, args, timeoutMs, passive) {
-  const cp = require('node:child_process'), crypto = require('node:crypto');
-  const lease = { id: crypto.randomUUID(), notAfter: Date.now() + timeoutMs, maxDurationMs: timeoutMs };
-  // The worker lives for one host event. APT_HOOK_PROCESS lets its runtime
-  // locks record a start hint instead of starting PowerShell on every tool call.
-  const program = `process.env.APT_HOOK_PROCESS = '1';
-const dispatcher = (${dispatcherSource})(${JSON.stringify(root)}, ${JSON.stringify(publicKey)});
-process.once('message', async message => {
-  try { await dispatcher.runCLI(...message.args, { hookLease: message.lease }); }
-  catch (error) { process.stderr.write('APT hook: ' + (error.message || String(error)) + '\\n'); process.exitCode = 2; }
-  finally { if (process.connected) process.disconnect(); }
-});`;
-  return new Promise((resolve, reject) => {
-    let settled = false, output = '', errors = '', inputBytes = 0;
-    const received = [];
-    // APT allows a passive host read in every session state. A fault of APT
-    // itself, a missed deadline above all, must not refuse one. The answer is
-    // the output that lets the call proceed, or null for every other call.
-    const allowance = () => {
-      try {
-        const table = passive && passive[args[0]];
-        const allow = table && table.events[args[1]];
-        if (typeof allow !== 'string') return null;
-        const input = JSON.parse(Buffer.concat(received).toString('utf8'));
-        const name = input.tool_name;
-        if (typeof name !== 'string' || input.toolCall !== undefined || input.userStopped === true) return null;
-        return table.exact.includes(name) || table.insensitive.includes(name.toLowerCase()) ? allow : null;
-      } catch { return null; }
-    };
-    const child = cp.spawn(process.execPath, ['-e', program], { windowsHide: true, stdio: ['pipe', 'pipe', 'pipe', 'ipc'] });
-    const detach = () => {
-      clearTimeout(timer); process.stdin.unpipe(child.stdin); process.stdin.removeListener('data', countInput);
-      child.stdin.destroy();
-    };
-    const fail = code => {
-      if (settled) return;
-      settled = true; detach();
-      if (child.connected) child.disconnect();
-      child.kill(); child.stdout.destroy(); child.stderr.destroy(); child.unref();
-      const allow = allowance();
-      if (allow === null) return reject(new Error(code));
-      process.stderr.write('APT hook: ' + code + ' (not refused)\n');
-      process.stdout.write(allow + '\n');
-      process.exitCode = 0;
-      resolve();
-    };
-    const countInput = chunk => {
-      inputBytes += chunk.length;
-      if (inputBytes > 2 * 1024 * 1024) fail('HOOK_INPUT_LIMIT'); else received.push(Buffer.from(chunk));
-    };
-    const timer = setTimeout(() => fail('HOOK_DEADLINE_EXCEEDED'), timeoutMs);
-    child.on('error', () => fail('HOOK_WORKER_UNAVAILABLE'));
-    child.stdin.on('error', () => {});
-    child.stdout.on('data', chunk => { output += chunk.toString(); if (Buffer.byteLength(output) > 2 * 1024 * 1024) fail('HOOK_OUTPUT_LIMIT'); });
-    child.stderr.on('data', chunk => { errors += chunk.toString(); if (Buffer.byteLength(errors) > 64 * 1024) fail('HOOK_OUTPUT_LIMIT'); });
-    child.on('close', code => {
-      if (settled) return;
-      if (Date.now() >= lease.notAfter) return fail('HOOK_DEADLINE_EXCEEDED');
-      settled = true; detach();
-      // A worker that failed before the bridge could decide refuses nothing
-      // that APT always allows.
-      const allow = code === 0 ? null : allowance();
-      if (code === 0) { if (output) process.stdout.write(output); }
-      if (errors) process.stderr.write(errors);
-      if (allow !== null) process.stdout.write(allow + '\n');
-      process.exitCode = code === 0 || allow !== null ? 0 : 2;
-      resolve();
-    });
-    process.stdin.on('data', countInput); process.stdin.pipe(child.stdin);
-    child.send({ args, lease }, error => { if (error) fail('HOOK_WORKER_UNAVAILABLE'); });
-  });
-}
-
-// Only a pre-tool decision may block its host. Any other event observes
-// something that already happened, so a dispatcher or runtime fault there is a
-// non-blocking error: it must not reject a prompt or force a continuation.
-function blockingEvents() {
-  const { HOSTS } = require('../core/host-adapters');
-  return Object.fromEntries(Object.entries(HOSTS).map(([host, adapter]) =>
-    [host, Object.keys(adapter.events).filter(event => adapter.events[event] === 'before-tool')]));
-}
-
-// For each host: the events that guard a tool call, each with the output
-// that lets the call proceed, and the tools APT allows in every session state.
-function passiveReads() {
-  const { HOSTS, formatHookResult } = require('../core/host-adapters');
-  const { passiveHostTools } = require('../core/hook-bridge');
-  return Object.fromEntries(Object.entries(HOSTS).map(([host, adapter]) => [host, {
-    events: Object.fromEntries(Object.keys(adapter.events).filter(event => adapter.events[event] === 'before-tool')
-      .map(event => [event, JSON.stringify(formatHookResult(host, event, { allow: true }).output)])),
-    ...passiveHostTools(host) }]));
-}
-
-function renderDispatcher(runtimeRoot, publicKey, options = {}) {
-  const timeoutMs = options.timeoutMs === undefined ? 10000 : options.timeoutMs;
-  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 100 || timeoutMs > 10000) throw new Error('HOOK_DEADLINE_INVALID');
-  return `'use strict';
-const dispatcher = (${hookDispatcher.toString()})(${JSON.stringify(runtimeRoot)}, ${JSON.stringify(publicKey.toString())});
-const blockingEvents = ${JSON.stringify(blockingEvents())};
-// An unknown host or event stays blocking.
-const failureCode = args => !blockingEvents[args[0]] || blockingEvents[args[0]].includes(args[1]) ? 2 : 1;
-function reportFailure(error, args) {
-  process.stderr.write('APT hook: ' + (error && error.message ? error.message : String(error)) + '\\n');
-  process.exitCode = failureCode(args);
-}
-module.exports = { runCLI(...args) {
-  try {
-    // Generated host commands use node --eval. Direct verifier consumers keep
-    // the synchronous interface; host execution always has an outer watchdog.
-    const hostCLI = process.argv.length === 1 && process.execArgv.some(arg => arg === '-e' || arg === '--eval');
-    const result = hostCLI
-      ? (${superviseHook.toString()})(${JSON.stringify(runtimeRoot)}, ${JSON.stringify(publicKey.toString())}, ${JSON.stringify(hookDispatcher.toString())}, args, ${timeoutMs}, ${JSON.stringify(passiveReads())})
-      : dispatcher.runCLI(...args);
-    if (result && typeof result.then === 'function')
-      result.then(() => { if (hostCLI && process.exitCode) process.exitCode = failureCode(args); },
-        error => reportFailure(error, args));
-    return result;
-  } catch (error) {
-    reportFailure(error, args);
-  }
-} };
-`;
-}
-
-module.exports = { hookDispatcher, renderDispatcher };
+'use strict';
+
+// Embedded with a trusted installation key. Only built-in modules may be used
+// until the committed release has been verified.
+function hookDispatcher(root, publicKey) {
+  const fs = require('node:fs'), path = require('node:path'), crypto = require('node:crypto'), os = require('node:os');
+  const canonicalOf = value => process.platform === 'win32' ? value.toLowerCase() : value;
+  // Machine install: the hook file is the user's, shared by every folder, so
+  // the workspace comes from the host's payload. A folder with a project
+  // install has its own hooks; this one yields there, since hosts run both.
+  function machineWorkspace(input) {
+    const candidate = input && (input.cwd || (input.workspace_roots || [])[0] || (input.workspacePaths || [])[0]);
+    if (typeof candidate !== 'string' || !path.isAbsolute(candidate) || !fs.existsSync(path.join(root, 'global-install.json'))) return null;
+    let real;
+    try { real = fs.realpathSync(candidate); } catch { return null; }
+    const refused = [os.homedir(), path.parse(real).root, path.join(os.homedir(), '.anhdh'), root].map(value => canonicalOf(path.resolve(value)));
+    const inside = (parent, child) => { const relative = path.relative(parent, child); return !relative || !relative.startsWith('..') && !path.isAbsolute(relative); };
+    if (refused.includes(canonicalOf(real)) || refused.slice(2).some(parent => inside(parent, canonicalOf(real)))) return null;
+    const ancestors = [];
+    for (let cursor = real; ; cursor = path.dirname(cursor)) {
+      if (fs.existsSync(path.join(cursor, '.agents', 'manifest.json'))) return null;
+      ancestors.push(cursor);
+      if (path.dirname(cursor) === cursor) break;
+    }
+    // The folder a session bound, else the checkout around the current directory.
+    const enrolled = ancestors.find(value => fs.existsSync(path.join(root, 'projects',
+      crypto.createHash('sha256').update(canonicalOf(value)).digest('hex').slice(0, 24) + '.json')));
+    return enrolled || ancestors.find(value => fs.existsSync(path.join(value, '.git'))) || real;
+  }
+  // The step a supervised worker has reached, for the deadline message.
+  const mark = phase => {
+    if (process.env.APT_HOOK_PROCESS === '1' && typeof process.send === 'function' && process.connected)
+      try { process.send({ type: 'apt-hook-phase', phase }); } catch { /* the supervisor is gone */ }
+  };
+  function dispatch(host, event, workspace, executionOptions, machine) {
+    mark('verify-release');
+    const canonical = canonicalOf(workspace);
+    const store = path.join(root, 'global');
+    const authorityFile = machine ? path.join(store, '.agents', 'runtime', 'generation.json') : path.join(workspace, '.agents', 'runtime', 'generation.json');
+    let selected;
+    try { selected = JSON.parse(fs.readFileSync(authorityFile, 'utf8')); }
+    catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+      // Before the first connection writes the generation: the pin install
+      // wrote, never the machine's latest pointer or a release inferred from
+      // deployed resource version. The machine install has the pin of its store.
+      const pinned = machine ? canonicalOf(fs.realpathSync(store)) : canonical;
+      selected = JSON.parse(fs.readFileSync(path.join(root, 'workspaces',
+        crypto.createHash('sha256').update(pinned).digest('hex') + '.json'), 'utf8'));
+    }
+    const owner = machine ? canonicalOf(fs.realpathSync(store)) : canonical;
+    if (selected.workspace && canonicalOf(selected.workspace) !== owner)
+      throw Error('HOOK_WORKSPACE_BINDING_CONFLICT');
+    if (!/^\d+\.\d+\.\d+$/.test(selected.version) || !/^[a-f0-9]{64}$/.test(selected.digest))
+      throw Error('HOOK_RUNTIME_BINDING_REQUIRED');
+    const release = path.join(root, 'releases', `${selected.version}-${selected.digest}`);
+    if (fs.lstatSync(release).isSymbolicLink()) throw Error('HOOK_RUNTIME_LINK_REJECTED');
+    const manifest = JSON.parse(fs.readFileSync(path.join(release, 'integrity-manifest.json'), 'utf8'));
+    if (crypto.createHash('sha256').update(JSON.stringify(manifest)).digest('hex') !== selected.digest ||
+        // The public key may be a set of keys (several PEM blocks) while a signing key is rotated.
+        !(String(publicKey).match(/-----BEGIN PUBLIC KEY-----[\s\S]+?-----END PUBLIC KEY-----/g) || [publicKey]).some(key => { try { return crypto.verify(null, Buffer.from(JSON.stringify(manifest.files)), key, Buffer.from(manifest.signature, 'base64url')); } catch { return false; } }))
+      throw Error('HOOK_RUNTIME_SIGNATURE_INVALID');
+    for (const required of ['src/core/hook-bridge.js'])
+      if (!manifest.files[required]) throw Error('HOOK_RUNTIME_RECONNECT_REQUIRED');
+    // Verified release file identities (size, mtime, ctime, inode, signed digest)
+    // live outside releases/ so unsigned cache files never enter release trees.
+    const cacheDir = path.join(root, 'release-cache');
+    const cacheFile = path.join(cacheDir, `${selected.version}-${selected.digest}.json`);
+    let cachedFiles = null;
+    try {
+      if (!fs.lstatSync(cacheDir).isSymbolicLink() && !fs.lstatSync(cacheFile).isSymbolicLink()) {
+        const parsed = JSON.parse(fs.readFileSync(cacheFile, 'utf8'));
+        if (parsed && parsed.digest === selected.digest && parsed.files && typeof parsed.files === 'object')
+          cachedFiles = parsed.files;
+      }
+    } catch { /* cold or unreadable cache */ }
+    const nextCache = {};
+    let cacheDirty = !cachedFiles;
+    for (const [file, digest] of Object.entries(manifest.files)) {
+      if (path.isAbsolute(file) || file.includes('\\') || file.split('/').some(part => !part || part === '..' || part === '.'))
+        throw Error('HOOK_RUNTIME_PATH_INVALID');
+      // A hook runs code from src/ only. The signed list still names every
+      // file; the encrypted bundles (15 of 19 MB) were read and hashed on every
+      // hook call, and a cold read on comaker ran hooks past their deadline.
+      if (!file.startsWith('src/') && file !== 'package.json') continue;
+      let cursor = release, leafStat = null;
+      for (const part of file.split('/')) {
+        cursor = path.join(cursor, part);
+        leafStat = fs.lstatSync(cursor, { bigint: true });
+        if (leafStat.isSymbolicLink()) throw Error('HOOK_RUNTIME_LINK_REJECTED');
+      }
+      const identity = `${leafStat.size}:${leafStat.mtimeNs}:${leafStat.ctimeNs}:${leafStat.ino}:${digest}`;
+      if (cachedFiles && cachedFiles[file] === identity) {
+        nextCache[file] = identity;
+        continue;
+      }
+      const bytes = fs.readFileSync(cursor);
+      if (crypto.createHash('sha256').update(bytes).digest('hex') !== digest)
+        throw Error('HOOK_RUNTIME_INTEGRITY_INVALID');
+      const after = fs.lstatSync(cursor, { bigint: true });
+      if (!after.isSymbolicLink() && BigInt(bytes.length) === leafStat.size && after.size === leafStat.size &&
+          after.mtimeNs === leafStat.mtimeNs && after.ctimeNs === leafStat.ctimeNs && after.ino === leafStat.ino) {
+        nextCache[file] = identity;
+        cacheDirty = true;
+      }
+    }
+    if (cacheDirty) {
+      let tempCache = null;
+      try {
+        fs.mkdirSync(cacheDir, { recursive: true });
+        if (!fs.lstatSync(cacheDir).isSymbolicLink()) {
+          tempCache = `${cacheFile}.${process.pid}.${crypto.randomUUID()}.tmp`;
+          fs.writeFileSync(tempCache, JSON.stringify({ version: selected.version, digest: selected.digest, files: nextCache }), { mode: 0o600 });
+          fs.renameSync(tempCache, cacheFile);
+        }
+      } catch {
+        try { if (tempCache && fs.existsSync(tempCache)) fs.unlinkSync(tempCache); } catch { /* observational cache */ }
+      }
+    }
+    mark('load-runtime');
+    return require(path.join(release, 'src/core/hook-bridge.js')).runCLI(host, event,
+      Buffer.from(workspace, 'utf8').toString('base64'), executionOptions);
+  }
+  return { runCLI(host, event, projectPath, executionOptions = {}) {
+    // Host adapters pass the workspace as base64 so hook command shells never
+    // reinterpret path data. Keep absolute raw paths usable for internal calls.
+    const inputPath = String(projectPath);
+    if (inputPath === '-') return (async () => {
+      let text = typeof executionOptions.input === 'string' ? executionOptions.input : '';
+      if (typeof executionOptions.input !== 'string') for await (const chunk of process.stdin) {
+        text += chunk;
+        if (Buffer.byteLength(text) > 2 * 1024 * 1024) throw Error('Hook input exceeds 2 MiB');
+      }
+      let input = null;
+      try { input = JSON.parse(text || '{}'); } catch { /* the bridge reports malformed input */ }
+      const workspace = machineWorkspace(input);
+      if (!workspace) { process.stdout.write('{}\n'); return; }
+      return dispatch(host, event, workspace, { ...executionOptions, input: text }, true);
+    })();
+    const decodedProjectPath = Buffer.from(inputPath, 'base64').toString('utf8');
+    const workspaceInput = path.isAbsolute(inputPath) || !fs.existsSync(decodedProjectPath) ? inputPath : decodedProjectPath;
+    return dispatch(host, event, fs.realpathSync(workspaceInput), executionOptions, false);
+  } };
+}
+
+// The parent only uses built-ins. Synchronous hashing/locks in the signed
+// worker cannot prevent the parent from producing a blocking decision.
+function superviseHook(root, publicKey, dispatcherSource, args, timeoutMs, passive) {
+  const cp = require('node:child_process'), crypto = require('node:crypto'), fs = require('node:fs'), path = require('node:path');
+  const { performance } = require('node:perf_hooks');
+  const lease = { id: crypto.randomUUID(), notAfter: Date.now() + timeoutMs, maxDurationMs: timeoutMs,
+    ...(Number.isSafeInteger(process.ppid) && process.ppid > 0 ? { hostPid: process.ppid } : {}) };
+  // The worker lives for one host event. APT_HOOK_PROCESS lets its runtime
+  // locks record a start hint instead of starting PowerShell on every tool call.
+  const program = `process.env.APT_HOOK_PROCESS = '1';
+const dispatcher = (${dispatcherSource})(${JSON.stringify(root)}, ${JSON.stringify(publicKey)});
+process.once('message', async message => {
+  try { await dispatcher.runCLI(...message.args, { hookLease: message.lease }); }
+  catch (error) { process.stderr.write('APT hook: ' + (error.message || String(error)) + '\\n'); process.exitCode = 2; }
+  finally { if (process.connected) process.disconnect(); }
+});`;
+  return new Promise((resolve, reject) => {
+    let settled = false, answeredEarly = false, output = '', errors = '', inputBytes = 0;
+    const received = [], phases = [], started = Date.now();
+    const recordPhase = name => {
+      const clean = String(name || '').slice(0, 96);
+      if (!clean) return;
+      const now = Date.now() - started;
+      if (phases.length && phases[phases.length - 1].phase === clean) return;
+      phases.push({ phase: clean, enteredAt: now });
+    };
+    // Where a missed deadline spent its time: duration in the final step plus prior steps.
+    const buildTimeline = refused => {
+      const elapsed = Math.max(0, Date.now() - started);
+      const deadlineSec = timeoutMs / 1000;
+      const tail = refused ? '. Nothing was run; retry the call once.' : '';
+      if (!phases.length)
+        return { phase: 'startup', durationMs: elapsed, timeline: 'before-worker-start',
+          message: `HOOK_DEADLINE_EXCEEDED: before the hook worker started (deadline ${deadlineSec} s)${tail}` };
+      const last = phases[phases.length - 1];
+      const ranMs = Math.max(0, elapsed - last.enteredAt);
+      const prior = phases.slice(0, -1).map((item, idx) =>
+        `${item.phase} ${(Math.max(0, phases[idx + 1].enteredAt - item.enteredAt) / 1000).toFixed(2)} s`);
+      const beforePart = prior.length ? `; before it: ${prior.join(', ')}` : '';
+      const timeline = [...prior, `${last.phase} ${(ranMs / 1000).toFixed(2)} s (unfinished)`].join(', ');
+      return {
+        phase: last.phase,
+        durationMs: ranMs,
+        timeline,
+        message: `HOOK_DEADLINE_EXCEEDED: step "${last.phase}" ran ${(ranMs / 1000).toFixed(1)} s and did not finish ` +
+          `(entered ${(last.enteredAt / 1000).toFixed(1)} s after the hook started${beforePart}; deadline ${deadlineSec} s)${tail}`
+      };
+    };
+    const writeDeadlineDiagnostic = info => {
+      try {
+        const canonical = value => process.platform === 'win32' ? value.toLowerCase() : value;
+        const inputArg = String(args[2] || '');
+        let workspace = null;
+        if (inputArg === '-') {
+          const parsed = JSON.parse(Buffer.concat(received).toString('utf8') || '{}');
+          const candidate = parsed && (parsed.cwd || (parsed.workspace_roots || [])[0] || (parsed.workspacePaths || [])[0]);
+          if (typeof candidate === 'string' && path.isAbsolute(candidate)) workspace = fs.realpathSync(candidate);
+        } else if (inputArg) {
+          const decoded = Buffer.from(inputArg, 'base64').toString('utf8');
+          const raw = path.isAbsolute(inputArg) || !fs.existsSync(decoded) ? inputArg : decoded;
+          workspace = fs.realpathSync(raw);
+        }
+        if (!workspace) return;
+        const isProject = process.env.APT_WORKSPACE_MODE === 'project' ||
+          fs.existsSync(path.join(workspace, '.agents', 'manifest.json')) ||
+          fs.existsSync(path.join(workspace, '.agents', 'runtime')) ||
+          !fs.existsSync(path.join(root, 'global-install.json'));
+        const stateRoot = isProject
+          ? workspace
+          : path.join(fs.realpathSync(root), 'workspaces', crypto.createHash('sha256').update(canonical(workspace)).digest('hex'));
+        fs.mkdirSync(stateRoot, { recursive: true });
+        let directory = stateRoot;
+        for (const part of ['.agents', 'runtime', 'diagnostics']) {
+          directory = path.join(directory, part);
+          fs.mkdirSync(directory, { recursive: true });
+          const dirStat = fs.lstatSync(directory);
+          if (!dirStat.isDirectory() || dirStat.isSymbolicLink()) return;
+        }
+        const file = path.join(directory, `hook-${process.pid}.jsonl`);
+        let stat = null;
+        try { stat = fs.lstatSync(file); } catch { /* first entry */ }
+        if (stat && (!stat.isFile() || stat.isSymbolicLink() || stat.size > 4 * 1024 * 1024)) return;
+        const entry = {
+          at: new Date().toISOString(),
+          monotonicMs: performance.now(),
+          pid: process.pid,
+          event: 'hook-deadline',
+          phase: info.phase,
+          durationMs: info.durationMs,
+          reason: String(info.timeline || '').slice(0, 500),
+          attempts: phases.length
+        };
+        fs.appendFileSync(file, JSON.stringify(entry) + '\n', { mode: 0o600 });
+      } catch { /* Diagnostics never alter hook authority. */ }
+    };
+    // APT allows a passive host read in every session state. A fault of APT
+    // itself, a missed deadline above all, must not refuse one. The answer is
+    // the output that lets the call proceed, or null for every other call.
+    const allowance = () => {
+      try {
+        const table = passive && passive[args[0]];
+        const allow = table && table.events[args[1]];
+        if (typeof allow !== 'string') return null;
+        const input = JSON.parse(Buffer.concat(received).toString('utf8'));
+        const name = input.tool_name;
+        if (typeof name !== 'string' || input.toolCall !== undefined || input.userStopped === true) return null;
+        return table.exact.includes(name) || table.insensitive.includes(name.toLowerCase()) ? allow : null;
+      } catch { return null; }
+    };
+    const child = cp.spawn(process.execPath, ['-e', program], { windowsHide: true, stdio: ['pipe', 'pipe', 'pipe', 'ipc'] });
+    const detach = () => {
+      clearTimeout(timer); process.stdin.unpipe(child.stdin); process.stdin.removeListener('data', countInput);
+      process.stdin.removeListener('end', answerPassiveEarly);
+      child.stdin.destroy();
+    };
+    const fail = (code, precomputedAllow) => {
+      if (settled) return;
+      settled = true; detach();
+      if (child.connected) child.disconnect();
+      child.kill(); child.stdout.destroy(); child.stderr.destroy(); child.unref();
+      const allow = precomputedAllow === undefined ? allowance() : precomputedAllow;
+      if (allow === null) return reject(new Error(code));
+      process.stderr.write('APT hook: ' + code + ' (not refused)\n');
+      if (!answeredEarly) process.stdout.write(allow + '\n');
+      process.exitCode = 0;
+      resolve();
+    };
+    const failDeadline = () => {
+      if (settled) return;
+      const allow = allowance();
+      const info = buildTimeline(allow === null);
+      writeDeadlineDiagnostic(info);
+      fail(info.message, allow);
+    };
+    const countInput = chunk => {
+      inputBytes += chunk.length;
+      if (inputBytes > 2 * 1024 * 1024) fail('HOOK_INPUT_LIMIT', null); else received.push(Buffer.from(chunk));
+    };
+    const answerPassiveEarly = () => {
+      if (settled || answeredEarly) return;
+      const allow = allowance();
+      if (allow !== null) {
+        answeredEarly = true;
+        process.stdout.write(allow + '\n');
+      }
+    };
+    const timer = setTimeout(failDeadline, timeoutMs);
+    child.on('message', message => {
+      if (message && message.type === 'apt-hook-phase' && typeof message.phase === 'string')
+        recordPhase(message.phase);
+    });
+    child.on('error', () => fail('HOOK_WORKER_UNAVAILABLE'));
+    child.stdin.on('error', () => {});
+    child.stdout.on('data', chunk => { output += chunk.toString(); if (Buffer.byteLength(output) > 2 * 1024 * 1024) fail('HOOK_OUTPUT_LIMIT'); });
+    child.stderr.on('data', chunk => { errors += chunk.toString(); if (Buffer.byteLength(errors) > 64 * 1024) fail('HOOK_OUTPUT_LIMIT'); });
+    child.on('close', code => {
+      if (settled) return;
+      if (Date.now() >= lease.notAfter) return failDeadline();
+      settled = true; detach();
+      // A worker that failed before the bridge could decide refuses nothing
+      // that APT always allows.
+      const allow = code === 0 ? null : allowance();
+      if (code === 0) { if (output && !answeredEarly) process.stdout.write(output); }
+      if (errors) process.stderr.write(errors);
+      if (allow !== null && !answeredEarly) process.stdout.write(allow + '\n');
+      process.exitCode = code === 0 || allow !== null ? 0 : 2;
+      resolve();
+    });
+    process.stdin.on('data', countInput);
+    process.stdin.on('end', answerPassiveEarly);
+    process.stdin.pipe(child.stdin);
+    child.send({ args, lease }, error => { if (error) fail('HOOK_WORKER_UNAVAILABLE'); });
+  });
+}
+
+// Only a pre-tool decision may block its host. Any other event observes
+// something that already happened, so a dispatcher or runtime fault there is a
+// non-blocking error: it must not reject a prompt or force a continuation.
+function blockingEvents() {
+  const { HOSTS } = require('../core/host-adapters');
+  return Object.fromEntries(Object.entries(HOSTS).map(([host, adapter]) =>
+    [host, Object.keys(adapter.events).filter(event => adapter.events[event] === 'before-tool')]));
+}
+
+// For each host: the events that guard a tool call, each with the output
+// that lets the call proceed, and the tools APT allows in every session state.
+function passiveReads() {
+  const { HOSTS, formatHookResult } = require('../core/host-adapters');
+  const { passiveHostTools } = require('../core/hook-bridge');
+  return Object.fromEntries(Object.entries(HOSTS).map(([host, adapter]) => [host, {
+    events: Object.fromEntries(Object.keys(adapter.events).filter(event => adapter.events[event] === 'before-tool')
+      .map(event => [event, JSON.stringify(formatHookResult(host, event, { allow: true }).output)])),
+    ...passiveHostTools(host) }]));
+}
+
+function renderDispatcher(runtimeRoot, publicKey, options = {}) {
+  const timeoutMs = options.timeoutMs === undefined ? 10000 : options.timeoutMs;
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 100 || timeoutMs > 10000) throw new Error('HOOK_DEADLINE_INVALID');
+  return `'use strict';
+const dispatcher = (${hookDispatcher.toString()})(${JSON.stringify(runtimeRoot)}, ${JSON.stringify(publicKey.toString())});
+const blockingEvents = ${JSON.stringify(blockingEvents())};
+// An unknown host or event stays blocking.
+const failureCode = args => !blockingEvents[args[0]] || blockingEvents[args[0]].includes(args[1]) ? 2 : 1;
+function reportFailure(error, args) {
+  process.stderr.write('APT hook: ' + (error && error.message ? error.message : String(error)) + '\\n');
+  process.exitCode = failureCode(args);
+}
+module.exports = { runCLI(...args) {
+  try {
+    // Generated host commands use node --eval. Direct verifier consumers keep
+    // the synchronous interface; host execution always has an outer watchdog.
+    const hostCLI = process.argv.length === 1 && process.execArgv.some(arg => arg === '-e' || arg === '--eval');
+    const result = hostCLI
+      ? (${superviseHook.toString()})(${JSON.stringify(runtimeRoot)}, ${JSON.stringify(publicKey.toString())}, ${JSON.stringify(hookDispatcher.toString())}, args, ${timeoutMs}, ${JSON.stringify(passiveReads())})
+      : dispatcher.runCLI(...args);
+    if (result && typeof result.then === 'function')
+      result.then(() => { if (hostCLI && process.exitCode) process.exitCode = failureCode(args); },
+        error => reportFailure(error, args));
+    return result;
+  } catch (error) {
+    reportFailure(error, args);
+  }
+} };
+`;
+}
+
+module.exports = { hookDispatcher, renderDispatcher };