slaunt 0.1.17 → 0.1.19

package/src/desktop/chat-hook-capture.js

@@ -0,0 +1,445 @@
+'use strict';
+
+// Codex JSONL is an unstable local format. Only this explicit, completed visible
+// message shape is understood. Never recursively search arbitrary envelopes.
+const fs = require('node:fs');
+const net = require('node:net');
+const os = require('node:os');
+const path = require('node:path');
+const { createHash } = require('node:crypto');
+const hash = value => createHash('sha256').update(value).digest('hex');
+const EVENTS = new Set(['UserPromptSubmit', 'PreToolUse', 'PostToolUse', 'Stop', 'Interrupt']);
+const PHASES = new Set(['commentary', 'final_answer']);
+const MAX_IPC_BYTES = 128 * 1024;
+const MAX_LINE_BYTES = 1024 * 1024;
+const MAX_SCAN_BYTES = 2 * 1024 * 1024;
+const validId = value => typeof value === 'string' && value.length > 0 && value.length <= 256
+  && !/[\x00-\x1f\x7f]/.test(value);
+const rootPath = () => {
+  if (!process.getuid || process.platform === 'win32') throw new Error('capture-platform-unsupported');
+  return `/tmp/slaunt-capture-${process.getuid()}`;
+};
+function ensureRoot(root) {
+  try { fs.mkdirSync(root, { mode: 0o700 }); } catch (error) { if (error.code !== 'EEXIST') throw error; }
+  const stat = fs.lstatSync(root);
+  if (!stat.isDirectory() || stat.isSymbolicLink() || stat.uid !== process.getuid() || (stat.mode & 0o077)) {
+    throw new Error('unsafe-capture-directory');
+  }
+}
+function socketPath(root, sessionId, turnId) {
+  if (!validId(sessionId) || !validId(turnId)) throw new Error('invalid-capture-binding');
+  const address = path.join(root, `${hash(JSON.stringify([sessionId, turnId])).slice(0, 40)}.sock`);
+  if (Buffer.byteLength(address) > 100) throw new Error('capture-socket-path-too-long');
+  return address;
+}
+function requestFromHook(input) {
+  const event = input?.hook_event_name ?? input?.event_name;
+  if (!EVENTS.has(event) || !validId(input?.session_id) || !validId(input?.turn_id)
+      || typeof input.transcript_path !== 'string' || !path.isAbsolute(input.transcript_path)
+      || input.transcript_path.length > 4096 || /[\x00-\x1f\x7f]/.test(input.transcript_path)) {
+    throw new Error('invalid-capture-event');
+  }
+  // The native hook may contain prompts, tool arguments and results. None of
+  // those are retained; the short-lived command reads only the allowlisted shape.
+  return { event_name: event, session_id: input.session_id, turn_id: input.turn_id,
+    transcript_path: input.transcript_path };
+}
+function parseVisibleRecord(record, state) {
+  if (record?.type === 'session_meta') {
+    if (state.sawSession || record.payload?.id !== state.threadId) throw new Error('capture-transcript-identity-mismatch');
+    state.sawSession = true;
+    return null;
+  }
+  if (!state.sawSession) throw new Error('capture-transcript-identity-missing');
+  if (record?.type === 'turn_context') {
+    state.currentTurn = validId(record.payload?.turn_id) ? record.payload.turn_id : null;
+    return null;
+  }
+  const message = record?.payload;
+  if ((!state.catchUp && state.currentTurn !== state.turnId) || record.type !== 'response_item'
+      || message?.type !== 'message' || message.role !== 'assistant') return null;
+  // Missing phase on older visible-message records is safe to keep unknown.
+  // Explicit unknown/private channels or phases are never reclassified.
+  const channels = { commentary: 'commentary', final: 'final_answer', final_answer: 'final_answer' };
+  const channelPhase = Object.hasOwn(channels, message.channel) ? channels[message.channel] : null;
+  if ((message.phase != null && !PHASES.has(message.phase))
+      || (message.channel != null && !channelPhase)
+      || (message.phase != null && channelPhase && message.phase !== channelPhase)
+      || (message.recipient !== undefined && message.recipient !== 'all')
+      || message.status !== 'completed' || !validId(message.id)
+      || !Array.isArray(message.content) || !message.content.length
+      || message.content.some(part => part?.type !== 'output_text' || typeof part.text !== 'string')) return null;
+  const content = message.content.map(part => part.text).join('');
+  if (!content || Buffer.byteLength(JSON.stringify(content)) > 120 * 1024) throw new Error('capture-message-too-large');
+  return {
+    event_id: `codex-visible:${hash(JSON.stringify([state.threadId, state.currentTurn, message.id]))}`,
+    role: 'assistant', content,
+    ...((message.phase ?? channelPhase) ? { phase: message.phase ?? channelPhase } : {}),
+    ...(typeof record.timestamp === 'string' && Number.isFinite(Date.parse(record.timestamp))
+      ? { occurred_at: new Date(record.timestamp).toISOString() } : {})
+  };
+}
+
+// All path components below the configured home, including sessionsRoot, must
+// remain owned directories without symlinks. O_NOFOLLOW + fstat binds the open
+// regular file to the inode validated before opening it.
+function openTranscript(file, sessionsRoot, homeDir) {
+  const root = path.resolve(sessionsRoot);
+  const home = path.resolve(homeDir);
+  const resolved = path.resolve(file);
+  const relative = path.relative(root, resolved);
+  if (!relative || relative.startsWith('..') || path.isAbsolute(relative) || path.extname(resolved) !== '.jsonl'
+      || (root !== home && (!root.startsWith(`${home}${path.sep}`)))) throw new Error('unsafe-capture-transcript');
+  let current = home;
+  for (const part of ['', ...path.relative(home, path.dirname(resolved)).split(path.sep)]) {
+    current = part ? path.join(current, part) : current;
+    const stat = fs.lstatSync(current);
+    if (!stat.isDirectory() || stat.isSymbolicLink() || stat.uid !== process.getuid() || (stat.mode & 0o022)) {
+      throw new Error('unsafe-capture-transcript');
+    }
+  }
+  const expected = fs.lstatSync(resolved);
+  if (!expected.isFile() || expected.isSymbolicLink() || expected.uid !== process.getuid()
+      || (expected.mode & 0o022) || expected.nlink !== 1 || expected.size > 1024 * 1024 * 1024) {
+    throw new Error('unsafe-capture-transcript');
+  }
+  const fd = fs.openSync(resolved, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK);
+  try {
+    const actual = fs.fstatSync(fd);
+    if (!actual.isFile() || actual.ino !== expected.ino || actual.dev !== expected.dev || actual.uid !== process.getuid()
+        || (actual.mode & 0o022) || actual.nlink !== 1) {
+      throw new Error('unsafe-capture-transcript');
+    }
+    // Recheck directory ancestry after opening to reject concurrent replacement.
+    if (fs.realpathSync(resolved) !== resolved) throw new Error('unsafe-capture-transcript');
+    return { fd, stat: actual };
+  } catch (error) { fs.closeSync(fd); throw error; }
+}
+function acknowledged(response) {
+  return !response?.isError && response?.structuredContent?.ok === true
+    && response.structuredContent.status === 'captured_or_duplicate';
+}
+function createTranscriptReader({ client, threadId, turnId, sessionsRoot, homeDir, cursor = null, onCheckpoint = async () => {} }) {
+  const state = { offset: 0, sawSession: false, currentTurn: null, skipping: false, inode: null,
+    ...(cursor ?? {}), threadId, turnId, catchUp: Boolean(cursor) };
+  let file = null;
+  return {
+    get offset() { return state.offset; },
+    snapshot() { return Object.fromEntries(['offset', 'sawSession', 'currentTurn', 'skipping', 'inode'].map(key => [key, state[key]])); },
+    async scan(transcriptPath, isCurrent = () => true) {
+      if (file && file !== transcriptPath) throw new Error('capture-transcript-path-changed');
+      file = transcriptPath;
+      const { fd, stat } = openTranscript(file, sessionsRoot, homeDir);
+      try {
+        const inode = `${stat.dev}:${stat.ino}`;
+        if ((state.inode && state.inode !== inode) || stat.size < state.offset) throw new Error('capture-transcript-replaced');
+        state.inode = inode;
+        const initialOffset = state.offset;
+        const buffer = Buffer.alloc(Math.min(MAX_SCAN_BYTES, stat.size - state.offset));
+        const length = fs.readSync(fd, buffer, 0, buffer.length, state.offset);
+        let position = 0;
+        let captured = 0;
+        while (position < length && captured < 32 && isCurrent()) {
+          const newline = buffer.indexOf(10, position);
+          if (newline < 0) {
+            if (length - position >= MAX_LINE_BYTES || state.skipping) {
+              state.currentTurn = null;
+              state.skipping = true;
+              state.offset += length - position;
+            }
+            break; // A partial JSONL append remains unacknowledged.
+          }
+          const bytes = newline + 1 - position;
+          if (state.skipping || bytes > MAX_LINE_BYTES) {
+            state.currentTurn = null;
+            state.skipping = false;
+            position = newline + 1;
+            state.offset += bytes;
+            continue;
+          }
+          const line = buffer.subarray(position, newline).toString('utf8');
+          let record;
+          try { record = JSON.parse(line); }
+          catch { throw new Error('capture-transcript-format-unsupported'); }
+          const event = parseVisibleRecord(record, state);
+          if (event) {
+            // This selector comes from the native MCP lifecycle request, never
+            // from transcript text, the hook command, or the last active chat.
+            const response = await client.callTool({ name: 'chat_capture', arguments: event,
+              _meta: { threadId } }, undefined, { timeout: 5000 });
+            if (!isCurrent()) throw new Error('capture-binding-stale');
+            if (!acknowledged(response)) throw new Error('capture-upstream-unavailable');
+            captured += 1;
+          }
+          // Never commit the source cursor until capture has been acknowledged.
+          state.offset += bytes;
+          position = newline + 1;
+          if (event) await onCheckpoint();
+        }
+        return { captured, pending: state.offset < stat.size,
+          backlog: buffer.length === MAX_SCAN_BYTES && state.offset > initialOffset && state.offset < stat.size };
+      } finally { fs.closeSync(fd); }
+    }
+  };
+}
+
+const SAFE_ERRORS = new Set(['capture-transcript-identity-mismatch', 'capture-transcript-identity-missing',
+  'unsafe-capture-transcript', 'capture-transcript-path-changed', 'capture-transcript-replaced',
+  'capture-transcript-format-unsupported', 'capture-message-too-large', 'capture-upstream-unavailable',
+  'capture-binding-stale', 'capture-busy', 'capture-backlog-remains', 'capture-broker-unavailable']);
+function safeError(error) { return SAFE_ERRORS.has(error?.message) ? error.message : 'capture-unavailable'; }
+function validCursor(cursor, previous) {
+  return cursor && Object.keys(cursor).sort().join(',') === 'currentTurn,inode,offset,sawSession,skipping'
+    && Number.isSafeInteger(cursor.offset) && cursor.offset >= (previous?.offset ?? 0)
+    && cursor.offset <= 1024 * 1024 * 1024
+    && typeof cursor.sawSession === 'boolean' && typeof cursor.skipping === 'boolean'
+    && (cursor.currentTurn === null || validId(cursor.currentTurn))
+    && (cursor.inode === null || /^[0-9]+:[0-9]+$/.test(cursor.inode))
+    && (!previous?.inode || previous.inode === cursor.inode);
+}
+function validUpload(event) {
+  return event && Object.keys(event).every(key => ['event_id', 'role', 'phase', 'content', 'occurred_at'].includes(key))
+    && /^codex-visible:[a-f0-9]{64}$/.test(event.event_id) && event.role === 'assistant'
+    && typeof event.content === 'string' && event.content.length > 0
+    && Buffer.byteLength(JSON.stringify(event.content)) <= 120 * 1024
+    && (event.phase === undefined || PHASES.has(event.phase))
+    && (event.occurred_at === undefined || (typeof event.occurred_at === 'string' && Number.isFinite(Date.parse(event.occurred_at))));
+}
+async function clearStaleSocket(address) {
+  let previous;
+  try { previous = fs.lstatSync(address); } catch (error) { if (error.code === 'ENOENT') return; throw error; }
+  if (!previous.isSocket() || previous.uid !== process.getuid()) throw new Error('unsafe-capture-socket');
+  await new Promise((resolve, reject) => {
+    const probe = net.createConnection(address);
+    probe.setTimeout(250, () => { probe.destroy(); reject(new Error('capture-broker-busy')); });
+    probe.once('connect', () => { probe.destroy(); reject(new Error('capture-broker-busy')); });
+    probe.once('error', error => {
+      if (['ECONNREFUSED', 'ENOENT'].includes(error.code)) resolve(); else reject(new Error('capture-broker-busy'));
+    });
+  });
+  const current = fs.lstatSync(address);
+  if (current.ino !== previous.ino || current.dev !== previous.dev) throw new Error('unsafe-capture-socket');
+  fs.unlinkSync(address);
+}
+
+// This is only an authenticated upload route on the existing MCP broker. It
+// never opens transcripts, scans files, schedules capture, or polls for text.
+function createHookCaptureServer({ client, root = rootPath() }) {
+  const bindings = new Map();
+  const pendingBindings = new Map();
+  const threads = new Map();
+  const sockets = new Set();
+  let closed = false;
+  function dispose(record) {
+    record.closed = true;
+    record.server.close();
+    try { if (fs.lstatSync(record.address).ino === record.inode) fs.unlinkSync(record.address); } catch {}
+    bindings.delete(record.address);
+    if (![...bindings.values()].some(binding => binding.threadId === record.threadId)) threads.delete(record.threadId);
+  }
+  async function bindInternal(sessionId, { turnId, threadId }) {
+    if (closed || !validId(threadId)) throw new Error('capture-binding-stale');
+    const address = socketPath(root, sessionId, turnId);
+    const existing = bindings.get(address);
+    if (existing) {
+      if (existing.threadId !== threadId) throw new Error('capture-binding-stale');
+      return existing.ready;
+    }
+    if (bindings.size >= 128) {
+      const oldest = [...bindings.values()].find(record => !threads.get(record.threadId)?.busy);
+      if (!oldest) throw new Error('capture-busy');
+      dispose(oldest);
+    }
+    ensureRoot(root);
+    await clearStaleSocket(address);
+    const bucket = threads.get(threadId) ?? { cursor: null, pathHash: null, busy: null };
+    threads.set(threadId, bucket);
+    const record = { threadId, address, closed: false, inode: null, server: null };
+    const server = net.createServer(socket => {
+      sockets.add(socket);
+      let acquired = false;
+      let data = '';
+      let chain = Promise.resolve();
+      let queuedFrames = 0;
+      const send = value => { if (!socket.destroyed && !socket.writableEnded) socket.write(JSON.stringify(value) + '\n'); };
+      socket.on('error', () => {});
+      socket.setTimeout(10000, () => socket.destroy());
+      socket.once('close', () => {
+        sockets.delete(socket);
+        // Do not release serialization while an acknowledged upload is still
+        // in flight: a following hook must see its committed cursor or retry ID.
+        void chain.finally(() => { if (bucket.busy === socket) bucket.busy = null; });
+      });
+      async function handle(message) {
+        if (closed || record.closed || socket.destroyed || socket.writableEnded) throw new Error('capture-binding-stale');
+        if (!acquired) {
+          if (message.op !== 'open' || message.session_id !== sessionId || message.turn_id !== turnId
+              || !/^[a-f0-9]{64}$/.test(message.path_hash)
+              || Object.keys(message).some(key => !['op', 'session_id', 'turn_id', 'path_hash'].includes(key))) throw new Error('capture-binding-stale');
+          if (bucket.busy) throw new Error('capture-busy');
+          if (bucket.pathHash && bucket.pathHash !== message.path_hash) throw new Error('capture-transcript-path-changed');
+          bucket.pathHash = message.path_hash;
+          bucket.busy = socket; acquired = true;
+          return send({ ok: true, type: 'ready', threadId, cursor: bucket.cursor });
+        }
+        if (message.op === 'capture' && Object.keys(message).every(key => ['op', 'event'].includes(key)) && validUpload(message.event)) {
+          const response = await client.callTool({ name: 'chat_capture', arguments: message.event, _meta: { threadId } }, undefined, { timeout: 5000 });
+          if (!acknowledged(response)) throw new Error('capture-upstream-unavailable');
+          return send({ ok: true, type: 'captured' });
+        }
+        if (message.op === 'commit' && Object.keys(message).every(key => ['op', 'cursor'].includes(key)) && validCursor(message.cursor, bucket.cursor)) {
+          bucket.cursor = { ...message.cursor };
+          return send({ ok: true, type: 'committed' });
+        }
+        throw new Error('capture-binding-stale');
+      }
+      socket.on('data', chunk => {
+        data += chunk.toString('utf8');
+        if (Buffer.byteLength(data) > MAX_IPC_BYTES) { socket.destroy(); return; }
+        let newline;
+        while ((newline = data.indexOf('\n')) >= 0) {
+          const line = data.slice(0, newline); data = data.slice(newline + 1);
+          if (++queuedFrames > 4) { socket.destroy(); return; }
+          chain = chain.then(() => handle(JSON.parse(line))).catch(error => {
+            send({ ok: false, code: safeError(error) }); socket.end();
+          }).finally(() => { queuedFrames -= 1; });
+        }
+      });
+    });
+    server.maxConnections = 16; record.server = server;
+    record.ready = new Promise((resolve, reject) => {
+      server.once('error', () => reject(new Error('capture-broker-unavailable')));
+      server.listen(address, () => {
+        try {
+          if (closed || record.closed) throw new Error('capture-binding-stale');
+          fs.chmodSync(address, 0o600); record.inode = fs.lstatSync(address).ino; resolve();
+        } catch { reject(new Error('capture-broker-unavailable')); }
+      });
+    });
+    bindings.set(address, record);
+    try { await record.ready; } catch (error) { dispose(record); throw error; }
+  }
+  async function bind(sessionId, options = {}) {
+    if (!validId(options.turnId)) return;
+    const address = socketPath(root, sessionId, options.turnId);
+    const pending = pendingBindings.get(address);
+    if (pending) {
+      if (pending.threadId !== options.threadId) throw new Error('capture-binding-stale');
+      return pending.promise;
+    }
+    const promise = bindInternal(sessionId, options);
+    pendingBindings.set(address, { threadId: options.threadId, promise });
+    try { await promise; } finally { pendingBindings.delete(address); }
+  }
+  return { bind, close() {
+    closed = true;
+    for (const socket of sockets) socket.destroy();
+    for (const record of bindings.values()) dispose(record);
+    threads.clear();
+  } };
+}
+
+async function connectHook(root, input, timeoutMs) {
+  ensureRoot(root);
+  const address = socketPath(root, input.session_id, input.turn_id);
+  const stat = fs.lstatSync(address);
+  if (!stat.isSocket() || stat.uid !== process.getuid() || (stat.mode & 0o077)) throw new Error('capture-broker-unavailable');
+  const socket = net.createConnection(address);
+  let buffer = ''; let waiting = null;
+  const finish = (error, response) => {
+    if (!waiting) return;
+    const current = waiting; waiting = null; clearTimeout(current.timer);
+    if (error) current.reject(error); else current.resolve(response);
+  };
+  socket.on('error', () => finish(new Error('capture-broker-unavailable')));
+  socket.on('close', () => finish(new Error('capture-broker-unavailable')));
+  socket.on('data', chunk => {
+    buffer += chunk.toString('utf8');
+    if (Buffer.byteLength(buffer) > 8192) { socket.destroy(); return; }
+    const newline = buffer.indexOf('\n');
+    if (newline < 0) return;
+    const line = buffer.slice(0, newline); buffer = buffer.slice(newline + 1);
+    try {
+      const result = JSON.parse(line);
+      if (!result.ok) finish(new Error(SAFE_ERRORS.has(result.code) ? result.code : 'capture-broker-unavailable'));
+      else finish(null, result);
+    } catch { finish(new Error('capture-broker-unavailable')); }
+  });
+  const request = message => new Promise((resolve, reject) => {
+    if (waiting || socket.destroyed) return reject(new Error('capture-broker-unavailable'));
+    waiting = { resolve, reject, timer: setTimeout(() => {
+      finish(new Error('capture-broker-unavailable')); socket.destroy();
+    }, timeoutMs) };
+    socket.write(JSON.stringify(message) + '\n');
+  });
+  try {
+    const ready = await request({ op: 'open', session_id: input.session_id, turn_id: input.turn_id, path_hash: hash(input.transcript_path) });
+    if (ready.type !== 'ready' || !validId(ready.threadId)
+        || (ready.cursor !== null && !validCursor(ready.cursor, null))) throw new Error('capture-binding-stale');
+    return { ready, request, close: () => socket.destroy() };
+  } catch (error) { socket.destroy(); throw error; }
+}
+
+// One invocation, one bounded flush, then exit. There are no background scans
+// or late-append watchers; the next native hook drains subsequent appends.
+async function captureHook({ input, root = rootPath(), homeDir = os.homedir(),
+  sessionsRoot = path.join(homeDir, '.codex', 'sessions'), timeoutMs = 7000 } = {}) {
+  const request = requestFromHook(input);
+  const deadline = Date.now() + timeoutMs;
+  let connection;
+  while (!connection && Date.now() < deadline) {
+    try { connection = await connectHook(root, request, Math.min(5000, deadline - Date.now())); }
+    catch (error) {
+      if (error.message !== 'capture-busy' && error.message !== 'capture-broker-unavailable' && error.code !== 'ENOENT') throw error;
+      await new Promise(resolve => setTimeout(resolve, 50));
+    }
+  }
+  if (!connection) throw new Error('capture-broker-unavailable');
+  try {
+    const reader = createTranscriptReader({ threadId: connection.ready.threadId, turnId: request.turn_id,
+      sessionsRoot, homeDir, cursor: connection.ready.cursor,
+      onCheckpoint: async () => {
+        const result = await connection.request({ op: 'commit', cursor: reader.snapshot() });
+        if (result.type !== 'committed') throw new Error('capture-upstream-unavailable');
+      },
+      client: { async callTool(call) {
+        if (Date.now() >= deadline) throw new Error('capture-backlog-remains');
+        const response = await connection.request({ op: 'capture', event: call.arguments });
+        if (response.type !== 'captured') throw new Error('capture-upstream-unavailable');
+        return { structuredContent: { ok: true, status: 'captured_or_duplicate' } };
+      } } });
+    let result; let captured = 0;
+    for (let pass = 0; pass < 4 && Date.now() < deadline; pass += 1) {
+      const before = reader.offset;
+      result = await reader.scan(request.transcript_path, () => Date.now() < deadline);
+      captured += result.captured;
+      const committed = await connection.request({ op: 'commit', cursor: reader.snapshot() });
+      if (committed.type !== 'committed') throw new Error('capture-upstream-unavailable');
+      if (!result.pending || reader.offset === before) break;
+    }
+    return { ok: true, captured, pending: Boolean(result?.pending) };
+  } finally { connection.close(); }
+}
+async function runCaptureCommand({ stdin = process.stdin, stdout = process.stdout, stderr = process.stderr,
+  timeoutMs = 9000, capture = captureHook } = {}) {
+  return new Promise(resolve => {
+    let done = false; let data = '';
+    function finish(error, result) {
+      if (done) return;
+      done = true; clearTimeout(timer); stdin.pause();
+      if (error || result?.pending) stderr.write(`Slaunt visible chat capture: ${error ? safeError(error) : 'capture-backlog-remains'}\n`);
+      stdout.write('{}\n', resolve);
+    }
+    const timer = setTimeout(() => finish(new Error('capture-broker-unavailable')), timeoutMs);
+    stdin.on('error', () => finish(new Error('capture-broker-unavailable')));
+    stdin.on('data', chunk => { data += chunk.toString('utf8'); if (Buffer.byteLength(data) > 1024 * 1024) finish(new Error('capture-message-too-large')); });
+    stdin.on('end', () => {
+      if (done) return;
+      try { void capture({ input: requestFromHook(JSON.parse(data)) }).then(result => finish(null, result), finish); }
+      catch (error) { finish(error); }
+    });
+    stdin.resume();
+  });
+}
+module.exports = { parseVisibleRecord, createTranscriptReader, createHookCaptureServer,
+  requestFromHook, captureHook, runCaptureCommand };

package/src/desktop/claude-lifecycle.js

@@ -0,0 +1,143 @@
+'use strict';
+
+const { randomUUID } = require('node:crypto');
+
+const EVENTS = ['SessionStart', 'UserPromptSubmit', 'PreToolUse', 'PostToolUse', 'SubagentStart', 'SubagentStop', 'PreCompact', 'PostCompact', 'Stop'];
+const FIELDS = ['session_id', 'tool_name', 'tool_use_id', 'permission_mode', 'agent_type', 'agent_id', 'trigger', 'prompt_id', 'prompt', 'last_assistant_message'];
+const MAX_CAPTURE_BYTES = 120 * 1024;
+const CLAUDE_HOOK_TOOL = Object.freeze({
+  name: 'slaunt_hook_event',
+  description: 'Maintain Claude Code lifecycle state and capture submitted prompts and final visible assistant messages.',
+  inputSchema: { type: 'object', additionalProperties: false, required: ['event_name', 'session_id'],
+    properties: {
+      event_name: { type: 'string', enum: EVENTS },
+      ...Object.fromEntries(FIELDS.map(key => [key, { type: 'string', maxLength: ['prompt', 'last_assistant_message'].includes(key) ? 524288 : 256 }]))
+    } }
+});
+
+function validId(value) {
+  return typeof value === 'string' && value.length > 0 && value.length <= 256 && !/[\x00-\x1f\x7f]/.test(value);
+}
+
+function captureMeta(meta) {
+  return validId(meta?.threadId) ? { _meta: { threadId: meta.threadId } } : {};
+}
+
+function isRateLimited(response) {
+  return response?.isError === true && (response.content || []).some(block =>
+    block?.type === 'text' && /http_rate_limited|rate limit(?:ed)?|\b429\b/i.test(block.text || ''));
+}
+
+function validateInput(input) {
+  if (!input || typeof input !== 'object' || Array.isArray(input) || !EVENTS.includes(input.event_name)
+      || !validId(input.session_id)
+      || Object.keys(input).some(key => key !== 'event_name' && !FIELDS.includes(key))) {
+    throw new Error('invalid-hook-metadata');
+  }
+  for (const [key, value] of Object.entries(input)) {
+    if (key === 'event_name') continue;
+    if (typeof value !== 'string' || value.length > (['prompt', 'last_assistant_message'].includes(key) ? 524288 : 256)
+        || (!['prompt', 'last_assistant_message'].includes(key) && /[\x00-\x1f\x7f]/.test(value))) {
+      throw new Error('invalid-hook-metadata');
+    }
+  }
+  if (input.event_name === 'UserPromptSubmit' && input.prompt !== undefined && !validId(input.prompt_id)) {
+    throw new Error('invalid-hook-metadata');
+  }
+  if (input.event_name === 'Stop' && input.last_assistant_message && !validId(input.prompt_id)) {
+    throw new Error('invalid-hook-metadata');
+  }
+}
+
+function createClaudeLifecycle(client) {
+  let boundSession = null;
+  let runActive = false;
+  let toolCallCount = 0;
+  let queue = Promise.resolve();
+
+  async function call(name, args) {
+    const response = await client.callTool({ name, arguments: args });
+    if (response.isError) throw new Error('slaunt-lifecycle-unavailable');
+    return response;
+  }
+
+  async function captureVisible(input, eventName, content, meta) {
+    if (!validId(input.prompt_id) || typeof content !== 'string' || content.length === 0) return;
+    const args = { hook_event_name: eventName, session_id: input.session_id, turn_id: input.prompt_id };
+    if (eventName === 'UserPromptSubmit') args.prompt = content;
+    else args.last_assistant_message = content;
+    if (Buffer.byteLength(JSON.stringify(args)) > MAX_CAPTURE_BYTES) {
+      process.stderr.write('Slaunt visible chat capture: capture-message-too-large\n');
+      return;
+    }
+    try {
+      for (let attempt = 0; attempt < 2; attempt += 1) {
+        const response = await client.callTool({ name: 'chat_hook_event', arguments: args, ...captureMeta(meta) }, undefined, { timeout: 5000 });
+        if (!response.isError) return;
+        if (attempt === 0 && isRateLimited(response)) {
+          // The backend deduplicates this event by session, event, and turn ID.
+          // Retry one explicit 429 once without repeating lifecycle writes.
+          await new Promise(resolve => setTimeout(resolve, 300));
+          continue;
+        }
+        process.stderr.write('Slaunt visible chat capture: capture-upstream-unavailable\n');
+        return;
+      }
+    } catch {
+      // Chat capture is best-effort and must not block the user's Claude turn.
+      process.stderr.write('Slaunt visible chat capture: capture-upstream-unavailable\n');
+    }
+  }
+
+  async function handle(input, meta) {
+    validateInput(input);
+    // Claude can fire UserPromptSubmit while a background subagent reports to
+    // its parent. That internal prompt is not part of the visible user chat.
+    if (input.event_name === 'UserPromptSubmit' && input.agent_id) return { content: [] };
+
+    if (boundSession !== input.session_id) {
+      if (boundSession) await call('run_end', {
+        outcome: 'interrupted', summary: `Claude Code session changed after ${toolCallCount} tool calls`
+      });
+      runActive = false;
+      toolCallCount = 0;
+      await call('thread_begin', { request_id: randomUUID(), ...(boundSession ? { new_thread: true } : {}), label: 'Claude Code' });
+      boundSession = input.session_id;
+    }
+    if (input.event_name === 'UserPromptSubmit') {
+      if (runActive) await call('run_end', {
+        outcome: 'interrupted', summary: `Previous Claude Code turn interrupted after ${toolCallCount} tool calls`
+      });
+      await captureVisible(input, 'UserPromptSubmit', input.prompt, meta);
+      await call('run_begin', { task: 'Claude Code turn' });
+      runActive = true;
+      toolCallCount = 0;
+      return call('aki_workspace_context', { include_agents: true, recent_limit: 5 });
+    }
+    if (input.event_name === 'SessionStart') {
+      return call('aki_workspace_context', { include_agents: true, recent_limit: 5 });
+    }
+    if (input.event_name === 'Stop') {
+      await captureVisible(input, 'Stop', input.last_assistant_message, meta);
+      runActive = false;
+      const completedToolCalls = toolCallCount;
+      toolCallCount = 0;
+      return call('run_end', { outcome: 'completed', summary: `Claude Code turn ended after ${completedToolCalls} tool calls` });
+    }
+    // Keep Claude's event adapter installed, but aggregate tool activity into
+    // run_end instead of issuing a remote telemetry write for every tool.
+    if (input.event_name === 'PostToolUse') {
+      toolCallCount = Math.min(toolCallCount + 1, 10_000);
+      return { content: [] };
+    }
+    const metadata = Object.fromEntries(FIELDS.filter(key => key !== 'session_id' && key !== 'prompt' && key !== 'last_assistant_message' && input[key]).map(key => [key, input[key]]));
+    return call('run_step', { activity: `Claude Code ${input.event_name}`, metadata });
+  }
+
+  return (input, meta) => {
+    const next = queue.then(() => handle(input, meta));
+    queue = next.catch(() => {});
+    return next;
+  };
+}
+module.exports = { CLAUDE_HOOK_TOOL, createClaudeLifecycle };

package/src/desktop/client-identity.js

@@ -0,0 +1,19 @@
+'use strict';
+
+// Central's canonical runtime keys, distinct from onboarding catalog IDs.
+const CLIENT_IDENTITIES = Object.freeze({
+  'claude-code': Object.freeze({ key: 'claude-code', name: 'Claude Code' }),
+  'codex-cli': Object.freeze({ key: 'codex', name: 'Codex' })
+});
+function brokerArgsForClient(broker, clientId) {
+  if (!CLIENT_IDENTITIES[clientId]) throw new Error('unsupported-client-identity');
+  return [...broker.args, `--slaunt-client=${clientId}`];
+}
+function resolveBrokerIdentity(argv) {
+  const markers = argv.filter(value => value.startsWith('--slaunt-client='));
+  if (markers.length !== 1) throw new Error('client-identity-required');
+  const identity = CLIENT_IDENTITIES[markers[0].slice('--slaunt-client='.length)];
+  if (!identity) throw new Error('unsupported-client-identity');
+  return identity;
+}
+module.exports = { CLIENT_IDENTITIES, brokerArgsForClient, resolveBrokerIdentity };

package/src/desktop/native-claude-broker.js

@@ -0,0 +1,34 @@
+'use strict';
+const {createClaudeLifecycle}=require('./claude-lifecycle');
+const {createToolGuardServer}=require('./tool-guard');
+
+// The caller owns and authenticates the MCP connection. This broker must not
+// accept a token or account identity from hook input, and cannot use a client
+// that has not already connected to Slaunt.
+function createNativeClaudeBroker({client,root,timeoutMs=6000}={}) {
+  if(!client || typeof client.callTool!=='function')throw new Error('broker-connection-required');
+  const lifecycle=createClaudeLifecycle(client);
+  const guard=createToolGuardServer({client,clientKey:'claude-code',...(root?{root}:{}),timeoutMs});
+  let closed=false;
+  let generation=0,queue=Promise.resolve();
+  function event(input,meta) {
+    if(closed)throw new Error('broker-closed');
+    const name=input?.event_name;
+    const bind=name==='SessionStart'||(name==='UserPromptSubmit' && !input?.agent_id);
+    // Invalidate before the lifecycle transition so an old session never
+    // continues authorizing while a new run is being created.
+    if(bind || name==='Stop'){generation++;guard.invalidate();}
+    const current=generation;
+    const next=queue.then(async()=>{
+      if(closed)throw new Error('broker-closed');
+      const result=await lifecycle(input,meta);
+      if(bind && !input.agent_id && !closed && current===generation)await guard.bind(input.session_id);
+      return result;
+    });
+    queue=next.catch(()=>{});
+    return next;
+  }
+  function close(){if(closed)return;closed=true;generation++;guard.close();}
+  return {event,close};
+}
+module.exports={createNativeClaudeBroker};