mtech-ai-local-runner 0.1.47 → 0.1.48

package/README.md

@@ -1,3 +1,92 @@
+## Unreleased: AI-first ask delivery and messenger mode (disabled)
+
+The runner can put an AI Gateway ask (a Work Decision, a named review or a work request), and the answer to it,
+into the employee's own running Claude Code or Codex session before any Slack message is sent (Work Item e1c08b33,
+owner Work Decision 266f9475, option A). Deliveries arrive as ids only on the existing session-open wait. The daemon
+keeps them in `asks.json` (mode 0600) and reports `received`, `shown`, `seen` or `dropped` with
+`local_agent_ask_delivery_report`; the runner sends the Gateway no session id, cwd, prompt or text. Hooks reach the
+daemon through `hub.sock` (0600, in the 0700 state root) and the stable shim `bin/gateway-hook`, which runs a small
+hook client that prints nothing unless the daemon answers within 300 ms.
+
+Only a session that a person is attending is served. A Claude Code session counts when `CLAUDE_CODE_SESSION_ATTENDED`
+is `1` or, where Claude Code does not export that variable, when `CLAUDE_CODE_ENTRYPOINT` names a terminal, the Claude
+desktop app or the VS Code extension. A headless `claude -p` or Agent SDK run gets nothing and is never counted as
+having seen an ask. Codex exports no such marker, so every Codex hook session counts. The runner's own jobs never
+count: a hook whose `HOME` is under `<stateRoot>/claude-jobs/` (where every Claude job runs) is refused, and Codex jobs
+run with `features.hooks=false`, so they run no hook at all.
+
+An ask is shown at a session start, at the next prompt (where it also counts as seen), at a turn end, or by waking an
+idle Claude session through an `asyncRewake` Stop watcher. An ask shown at a session start, at a turn end or by a wake
+counts as seen at the next prompt in that same session. A session is woken only within 30 minutes of a human prompt,
+and at most 6 times an hour. With no such session the ask becomes one macOS notification, which gives up after 3
+seconds and logs only an error code, and the ask waits for the next session start or prompt. Hook text is fixed and
+carries validated ids only; the AI reads the ask itself with the Gateway show tools, which mark its text as untrusted.
+
+The Gateway sends the ask keys on the wait only while asks are on for this runner. When a wait result comes without
+them, every stored delivery ends: it is dropped from `asks.json` with no report, and the Gateway's Slack fallback
+covers it. A stored delivery is forgotten an hour after it arrived, by which time the fallback (at most 15 minutes) has
+long run.
+
+Integrations are installed only on request, with `setup --integrations` or `integrations install`; setup never asks
+about them. An app already installed in the directory the environment names is skipped and reported installed, without
+rewriting its files:
+
+```bash
+npx mtech-ai-local-runner setup --integrations claude,codex
+npx mtech-ai-local-runner integrations status
+npx mtech-ai-local-runner integrations install codex
+npx mtech-ai-local-runner integrations remove claude
+```
+
+Claude Code gets the skills-directory plugin `~/.claude/skills/mtec-ai-gateway-asks/`, which loads as
+`mtec-ai-gateway-asks@skills-dir` in a new session or after `/reload-plugins`; `settings.json` is not touched. Codex gets
+four handlers appended to `~/.codex/hooks.json` after a backup of that file; trust them once with `/hooks`. A
+`hooks.json` that is not valid JSON, or whose hooks do not have the shape Codex reads, is left as it is and the install
+reports `CODEX_HOOKS_JSON_INVALID`. `uninstall` removes both integrations, the shim, `asks.json` and any temporary
+`asks.json.*.tmp` file a crash left behind, and it also works on a setup that never finished.
+
+`CLAUDE_CONFIG_DIR` and `CODEX_HOME` are honoured. The LaunchAgent that runs the daemon gets only `PATH`, so every
+install adds the directory it used to a list per app in `integrations.json` in the state root, and the daemon,
+`doctor`, `integrations remove` and `uninstall` look in every recorded directory as well as in the environment. A
+directory leaves the list only when nothing of the runner's is left in it, so installing into a second directory never
+orphans the first, and the shim stays while any directory still has the hooks. When no absolute home directory can be
+found, the command reports `INTEGRATION_HOME_UNKNOWN` for that app and writes nothing; set `HOME`, or `CLAUDE_CONFIG_DIR`
+and `CODEX_HOME`.
+
+On a fresh Mac without an admitted executor, or one already set up as a messenger, `setup` now completes in messenger
+mode. It registers with no adapter capability and stores `mode: "messenger"` in `config.json`. The daemon then runs only
+the session-open loop, for session opens and asks, and sends its own heartbeat at start, every 600 seconds and whenever
+the installed integrations change. It has no jobs loop, no adapter probe and no PreToolUse self-test, and `manual-codex`
+and `publication-recover` are refused with `MESSENGER_MODE_HAS_NO_EXECUTOR`. A full runner works as before and now
+reports `mode: "full"` in its heartbeat. `doctor` reports the mode, the hub and each integration, including whether
+Claude Code loads the plugin; for a messenger it requires neither an adapter nor the PreToolUse self-test.
+
+Setup never turns a Mac set up as a full runner into a messenger. With no usable adapter it fails as 0.1.47 did, before
+the login, and leaves `config.json`, the registration and the LaunchAgent as they were. Fix the adapter, or run
+`uninstall` and then `setup` to set the Mac up as a messenger.
+
+No ask is delivered until the Gateway's `AI_OPS_GATEWAY_WORK_ASK_AI_FIRST_ENABLED` switch is on and the employee is on
+its pilot list. Until then an existing runner works as before: setup never turns a full runner into a messenger and
+installs no integration it was not asked for. The one change without the switch is that setup on a fresh Mac without an
+admitted executor completes as a messenger instead of failing. Deploy the Gateway receivers before upgrading a runner.
+
+## 0.1.48: local_edit takes the complete file, not a patch
+
+Read the existing file first, then pass its complete desired new contents in
+`local_edit.content`, including unchanged text. The operation replaces the whole
+file or creates it; it never applies a diff. Recognizable apply_patch directives,
+unified hunk lines and diff headers return `DENIED_PATCH_CONTENT` before a write.
+The isolated writer enforces the same guard. Literal patch blocks in a document
+are also rejected by this conservative API; ordinary source string literals and
+YAML separators remain accepted. No partial old/new edit tool is introduced.
+
+Gateway and Runner must agree on the new tool inventory hash. Package runtime
+receipts change, while the reviewed Codex CLI release manifest identity stays
+unchanged. Keep existing -2G allowed paths; deploy the matching Gateway registry
+and exact runtime pins before switching a daemon. The candidate contains the
+newer development ask/messenger code documented in the Unreleased section and
+the 0.1.46/0.1.47 fixes; no integration is installed merely by preparing it.
+
 ## 0.1.47: Claude security host wiring remains gated
 
 Claude now shares the job security session and checks a live opaque executable
@@ -296,8 +385,11 @@ npx mtech-ai-local-runner setup
 The package stores safe runner configuration locally and keeps OAuth refresh credentials in macOS Keychain when available.
 
 Public npm installation requires no npm account or publishing OTP. Setup requires
-the employee's own Gateway OAuth login and a supported, authenticated selected
-CLI. Codex uses the employee's ChatGPT account. Claude requires its own login
+the employee's own Gateway OAuth login and, for a full runner, a supported,
+authenticated selected CLI. Since the AI-first ask delivery release (Unreleased,
+above), a fresh Mac without an admitted executor is set up as a messenger
+instead; a Mac already set up as a full runner still fails setup without one.
+Codex uses the employee's ChatGPT account. Claude requires its own login
 and a separately verified host admission; it is currently not admitted.
 
 For the current unattended Codex pilot, an administrator must separately install

package/dist/src/asks/commands.js

@@ -0,0 +1,100 @@
+import { readdir, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { ASKS_FILE } from "./store.js";
+import { installIntegration, integrationStatus, removeIntegration, removeShimIfUnused } from "./integrations.js";
+import { APPS, isApp } from "./types.js";
+const NEXT_STEP = {
+    claude: "Start a new Claude Code session, or run /reload-plugins in an open one, to load mtec-ai-gateway-asks@skills-dir.",
+    codex: "Open Codex and trust the four AI Gateway hooks once with /hooks. Until then Codex skips them and the Slack message covers the gap.",
+};
+function errorCode(error) {
+    const code = error?.code;
+    if (typeof code === "string" && /^[A-Z0-9_]{1,64}$/.test(code))
+        return code;
+    const message = error instanceof Error ? error.message.split(":")[0] : "";
+    return /^[A-Z0-9_]{1,64}$/.test(message) ? message : "INTEGRATION_FAILED";
+}
+/** integrations status|install|remove [claude|codex]; null for anything else. */
+export function parseIntegrationsArguments(argv) {
+    const [action, app, ...extra] = argv;
+    if (extra.length > 0 || (action !== "status" && action !== "install" && action !== "remove"))
+        return null;
+    if (app !== undefined && !isApp(app))
+        return null;
+    return { action, apps: app === undefined ? [...APPS] : [app] };
+}
+/** setup --integrations claude,codex (or --integrations=claude): undefined when absent, null when malformed. */
+export function parseSetupIntegrations(argv) {
+    const index = argv.findIndex(arg => arg === "--integrations" || arg.startsWith("--integrations="));
+    if (index < 0)
+        return undefined;
+    const value = argv[index] === "--integrations" ? argv[index + 1] : argv[index].slice("--integrations=".length);
+    const apps = (value ?? "").split(",").map(app => app.trim()).filter(app => app !== "");
+    if (apps.length === 0 || !apps.every(isApp) || new Set(apps).size !== apps.length)
+        return null;
+    return apps;
+}
+/** The state of one app; a status that cannot be read (no home directory, say) is reported with its error, never thrown. */
+export async function statusOf(app, env, stateRoot, error) {
+    try {
+        return { ...await integrationStatus(app, env, stateRoot), ...(error === undefined ? {} : { error }) };
+    }
+    catch (failure) {
+        return { app, state: "unreadable", path: "", error: error ?? errorCode(failure) };
+    }
+}
+async function attempt(app, env, stateRoot, change) {
+    try {
+        return await change();
+    }
+    catch (error) {
+        return statusOf(app, env, stateRoot, errorCode(error));
+    }
+}
+export async function installIntegrations(apps, env, stateRoot) {
+    const results = [];
+    for (const app of apps) {
+        const result = await attempt(app, env, stateRoot, () => installIntegration(app, env, stateRoot));
+        results.push(result.error === undefined ? { ...result, action: NEXT_STEP[app] } : result);
+    }
+    return results;
+}
+/**
+ * uninstall: removes both integrations, then the shim once nothing uses it, asks.json and the store's temporary files
+ * that a crash left behind (asks.json.<pid>.<uuid>.tmp), which can hold raw session ids.
+ */
+export async function removeAsksInstall(env, stateRoot) {
+    const results = [];
+    for (const app of APPS)
+        results.push(await attempt(app, env, stateRoot, () => removeIntegration(app, env, stateRoot)));
+    // A hook left behind (an unreadable Codex hooks file) keeps its shim, which then prints nothing and exits 0.
+    await removeShimIfUnused(env, stateRoot).catch(() => false);
+    await rm(join(stateRoot, ASKS_FILE), { force: true });
+    for (const name of await readdir(stateRoot).catch(() => [])) {
+        if (name.startsWith(`${ASKS_FILE}.`) && name.endsWith(".tmp"))
+            await rm(join(stateRoot, name), { force: true });
+    }
+    return results;
+}
+export async function runIntegrationsCommand(argv, io) {
+    const parsed = parseIntegrationsArguments(argv);
+    if (parsed === null) {
+        io.stderr("Usage: mtec-ai-local-runner integrations status|install|remove [claude|codex]");
+        return 1;
+    }
+    let results;
+    if (parsed.action === "install") {
+        results = await installIntegrations(parsed.apps, io.env, io.stateRoot);
+    }
+    else if (parsed.action === "remove") {
+        results = [];
+        for (const app of parsed.apps)
+            results.push(await attempt(app, io.env, io.stateRoot, () => removeIntegration(app, io.env, io.stateRoot)));
+        await removeShimIfUnused(io.env, io.stateRoot).catch(() => false);
+    }
+    else {
+        results = await Promise.all(parsed.apps.map(app => statusOf(app, io.env, io.stateRoot)));
+    }
+    io.stdout(JSON.stringify({ integrations: results }));
+    return results.some(result => result.error !== undefined) ? 1 : 0;
+}

package/dist/src/asks/doctor.js

@@ -0,0 +1,106 @@
+import { execFile } from "node:child_process";
+import { connect } from "node:net";
+import { statusOf } from "./commands.js";
+import { hubSocketPath } from "./hub.js";
+import { MAX_LINE_BYTES, encodeLine } from "./hub-protocol.js";
+import { CLAUDE_PLUGIN_NAME } from "./integrations.js";
+import { APPS } from "./types.js";
+const PLUGIN_ID = `${CLAUDE_PLUGIN_NAME}@skills-dir`;
+const CLAUDE_NOT_LOADED = `Claude Code does not load ${PLUGIN_ID}. Managed settings can block skills-directory plugins `
+    + "(strictPluginOnlyCustomization, a strictKnownMarketplaces list without the skills-dir source, or blockedMarketplaces): "
+    + "ask your administrator, or install the plugin from a directory marketplace your organization allows (claude plugin marketplace add <dir>). "
+    + "A Claude Code release without skills-directory plugins does not load it either.";
+const CODEX_TRUST = "Codex runs these hooks only after you trust them once with /hooks; until then the Slack message covers each ask.";
+/** Runs the Claude CLI with the environment doctor was given on top of the process's own (CLAUDE_CONFIG_DIR, for one). */
+const defaultRun = (env) => (file, args) => new Promise((resolve, reject) => {
+    execFile(file, args, { encoding: "utf8", timeout: 10_000, maxBuffer: 1024 * 1024, env: { ...process.env, ...env } }, (error, stdout) => (error ? reject(error) : resolve({ stdout })));
+});
+/** The three counts of a hub status answer, or null when it is anything else. */
+function parseStatus(value) {
+    if (value === null || typeof value !== "object")
+        return null;
+    const { deliveries, live_sessions: liveSessions, watchers } = value;
+    const counts = [deliveries, liveSessions, watchers];
+    if (!counts.every(count => typeof count === "number" && Number.isSafeInteger(count) && count >= 0))
+        return null;
+    return { deliveries: deliveries, live_sessions: liveSessions, watchers: watchers };
+}
+/** The running hub's counts (its status op), or null when nothing answers with a status within the time limit. Never rejects. */
+export function hubStatus(stateRoot, timeoutMs = 1000) {
+    return new Promise(resolve => {
+        let socket;
+        let buffer = "";
+        let done = false;
+        const finish = (value) => {
+            if (done)
+                return;
+            done = true;
+            clearTimeout(timer);
+            socket?.destroy();
+            resolve(value);
+        };
+        const timer = setTimeout(() => finish(null), timeoutMs);
+        try {
+            socket = connect(hubSocketPath(stateRoot));
+        }
+        catch {
+            finish(null);
+            return;
+        }
+        socket.setEncoding("utf8");
+        socket.on("error", () => finish(null));
+        socket.on("close", () => finish(null));
+        socket.on("data", (chunk) => {
+            buffer += chunk;
+            const newline = buffer.indexOf("\n");
+            if (newline < 0) {
+                if (buffer.length > MAX_LINE_BYTES)
+                    finish(null);
+                return;
+            }
+            try {
+                const response = JSON.parse(buffer.slice(0, newline));
+                finish(response.ok === true ? parseStatus(response.status) : null);
+            }
+            catch {
+                finish(null);
+            }
+        });
+        socket.write(encodeLine({ v: 1, op: "status" }));
+    });
+}
+/** true or false from `claude plugin list --json`; null when the Claude CLI cannot tell. Never rejects. */
+export async function claudePluginLoaded(env, run = defaultRun(env)) {
+    try {
+        const { stdout } = await run(env.AI_GATEWAY_LOCAL_RUNNER_CLAUDE_BINARY ?? "claude", ["plugin", "list", "--json"]);
+        const plugins = JSON.parse(stdout);
+        if (!Array.isArray(plugins))
+            return null;
+        const plugin = plugins.find(entry => entry?.id === PLUGIN_ID);
+        return plugin !== undefined && plugin.enabled !== false;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The asks section of doctor. The integrations go through statusOf, which reads the dir the environment names and the dir
+ * install recorded, and reports an app whose home cannot be found (INTEGRATION_HOME_UNKNOWN) on its own entry.
+ */
+export async function asksDoctorReport(input) {
+    const [status, statuses] = await Promise.all([hubStatus(input.stateRoot), Promise.all(APPS.map(app => statusOf(app, input.env, input.stateRoot)))]);
+    const integrations = [];
+    for (const report of statuses) {
+        if (report.state !== "installed") {
+            integrations.push(report);
+            continue;
+        }
+        if (report.app === "codex") {
+            integrations.push({ ...report, action: CODEX_TRUST });
+            continue;
+        }
+        const loaded = await claudePluginLoaded(input.env, input.run);
+        integrations.push({ ...report, ...(loaded === null ? {} : { loaded }), ...(loaded === false ? { action: CLAUDE_NOT_LOADED } : {}) });
+    }
+    return { mode: input.mode, hub: status === null ? { status: "not_running" } : { status: "running", ...status }, integrations };
+}

package/dist/src/asks/hook-client.js

@@ -0,0 +1,236 @@
+#!/usr/bin/env node
+import { connect } from "node:net";
+import { realpathSync } from "node:fs";
+import { isAbsolute, join, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { HUB_SOCKET, HUB_TIMEOUT_MS, MAX_HOOK_INPUT_BYTES, MAX_LINE_BYTES, WATCH_LIMIT_MS, encodeLine, parseEventResponse, parseWatchMessage, } from "./hub-protocol.js";
+import { MAX_CWD_LENGTH, SESSION_ID, isApp, isHookEvent } from "./types.js";
+const STDIN_TIMEOUT_MS = 1000;
+const STATE_ROOT_FLAG = "--state-root=";
+/**
+ * Values of CLAUDE_CODE_ENTRYPOINT under which a person types the prompts: a terminal, the Claude desktop app and
+ * the VS Code extension. Claude Code exports the variable itself (sdk-cli for claude -p, sdk-ts and sdk-py for the
+ * Agent SDK, mcp, local-agent, remote and the GitHub action for the rest), so any other value is not a person.
+ */
+const INTERACTIVE_ENTRYPOINTS = new Set(["cli", "claude-desktop", "claude-vscode"]);
+/** Where the Claude adapter puts each job's HOME: <stateRoot>/claude-jobs/<id>/home (src/adapters/claude-code/runtime-options.ts). */
+const CLAUDE_JOBS_DIR = "claude-jobs";
+/** True when HOME resolves inside <stateRoot>/claude-jobs/: a Claude job this runner started, never a person's session. */
+function isRunnerJobHome(env, stateRoot) {
+    const home = env.HOME;
+    if (!home || !isAbsolute(home))
+        return false;
+    const roots = new Set([resolve(stateRoot)]);
+    // The adapter builds job homes from the real state root; the shim may name it through a symlink.
+    try {
+        roots.add(realpathSync(stateRoot));
+    }
+    catch { /* A state root that does not exist holds no jobs. */ }
+    const resolved = resolve(home);
+    return [...roots].some(root => resolved.startsWith(join(root, CLAUDE_JOBS_DIR) + sep));
+}
+/**
+ * True when a person is attending the session that runs this hook (owner decision 2026-10-23). The one place that
+ * decides it, so it can be adjusted after the pilot.
+ *
+ * The runner's own jobs never count. A Claude job runs with its HOME under <stateRoot>/claude-jobs/, so a hook that
+ * sees such a HOME is refused whatever else the environment says. Codex jobs run with features.hooks=false (the Codex
+ * adapter's isolation overrides), so they never run a hook at all.
+ *
+ * Claude Code: CLAUDE_CODE_SESSION_ATTENDED, where the Claude Code version exports it, is the answer: "1" is a
+ * person, any other value is not, whatever the entrypoint says (a scheduled desktop task has the desktop entrypoint
+ * and nobody at the keyboard). A version that does not export it is judged by CLAUDE_CODE_ENTRYPOINT, and an unset
+ * or unknown entrypoint is not a person.
+ *
+ * Codex: no headless marker is exported to its hooks or present in its hook input that has been verified, so every
+ * Codex hook session counts as a person's. Claude's variables say nothing about Codex and are not read for it.
+ * `input` is the parsed hook input, passed for the day Codex exposes such a marker.
+ */
+export function isHumanSession(app, env, _input, stateRoot) {
+    if (isRunnerJobHome(env, stateRoot))
+        return false;
+    if (app !== "claude")
+        return true;
+    const attended = env.CLAUDE_CODE_SESSION_ATTENDED;
+    if (attended !== undefined && attended !== "")
+        return attended === "1";
+    return INTERACTIVE_ENTRYPOINTS.has(env.CLAUDE_CODE_ENTRYPOINT ?? "");
+}
+/** Same rule as defaultStateRootFromEnv in src/config.ts, repeated so this client loads nothing else. */
+function stateRootFrom(env) {
+    return env.XDG_STATE_HOME ? join(env.XDG_STATE_HOME, "mtec-ai-local-runner") : join(env.HOME ?? "", ".local", "state", "mtec-ai-local-runner");
+}
+function parseArguments(argv, env) {
+    const rest = [...argv];
+    let stateRoot = stateRootFrom(env);
+    if (rest[0]?.startsWith(STATE_ROOT_FLAG)) {
+        stateRoot = rest.shift().slice(STATE_ROOT_FLAG.length);
+        if (!isAbsolute(stateRoot))
+            return null;
+    }
+    const [app, event, ...extra] = rest;
+    if (extra.length > 0 || !isApp(app) || !isHookEvent(event))
+        return null;
+    return { stateRoot, app, event };
+}
+/** The hook's JSON from stdin, at most 64 KiB, within a second; null otherwise. */
+async function readInput(stdin, timeoutMs) {
+    let timer;
+    const timeout = new Promise(resolve => { timer = setTimeout(() => resolve(null), timeoutMs); });
+    const read = (async () => {
+        const chunks = [];
+        let size = 0;
+        for await (const chunk of stdin) {
+            const bytes = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
+            size += bytes.length;
+            if (size > MAX_HOOK_INPUT_BYTES)
+                return null;
+            chunks.push(bytes);
+        }
+        return Buffer.concat(chunks).toString("utf8");
+    })().catch(() => null);
+    try {
+        return await Promise.race([read, timeout]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** The hook input as an object, or null when it is not one. */
+function parseRecord(raw) {
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    return value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+/** Takes the session id, the cwd and Codex's stop_hook_active. Every other field, the prompt included, is ignored. */
+function hookFields(input) {
+    const { session_id: sessionId, cwd, stop_hook_active: stopHookActive } = input;
+    if (typeof sessionId !== "string" || !SESSION_ID.test(sessionId))
+        return null;
+    return { sessionId, cwd: typeof cwd === "string" && isAbsolute(cwd) && cwd.length <= MAX_CWD_LENGTH ? cwd : "", stopHookActive: stopHookActive === true };
+}
+/**
+ * Writes one line to the hub and calls onLine for each line it answers. The first line must arrive within
+ * firstMs; after that the connection may stay open until limitMs. Resolves with what onLine settled on, or null.
+ * A connection the hub closes without a message (a refused or late watch ends that way) resolves null.
+ */
+function converse(socketPath, line, firstMs, limitMs, onLine) {
+    return new Promise(resolve => {
+        const socket = connect(socketPath);
+        let buffer = "";
+        let first = true;
+        let settled = false;
+        let timer = setTimeout(() => finish(null), firstMs);
+        const finish = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            socket.destroy();
+            resolve(value);
+        };
+        socket.setEncoding("utf8");
+        socket.on("error", () => finish(null));
+        socket.on("close", () => finish(null));
+        socket.on("data", (chunk) => {
+            buffer += chunk;
+            if (Buffer.byteLength(buffer) > MAX_LINE_BYTES * 4) {
+                finish(null);
+                return;
+            }
+            let newline;
+            while (!settled && (newline = buffer.indexOf("\n")) >= 0) {
+                const text = buffer.slice(0, newline);
+                buffer = buffer.slice(newline + 1);
+                const step = onLine(text, first);
+                if (first) {
+                    first = false;
+                    clearTimeout(timer);
+                    timer = setTimeout(() => finish(null), limitMs);
+                }
+                if (step.done)
+                    finish(step.value);
+            }
+        });
+        socket.write(line);
+    });
+}
+function contextOutput(event, text) {
+    return JSON.stringify({ hookSpecificOutput: { hookEventName: event, additionalContext: text } });
+}
+/** Returns the exit code: 2 only when a Claude Stop watcher wakes its session, else 0. Never throws. */
+export async function runHookClient(argv, io) {
+    try {
+        const args = parseArguments(argv, io.env);
+        if (args === null)
+            return 0;
+        const raw = await readInput(io.stdin, io.stdinTimeoutMs ?? STDIN_TIMEOUT_MS);
+        const record = raw === null ? null : parseRecord(raw);
+        const input = record === null ? null : hookFields(record);
+        if (record === null || input === null)
+            return 0;
+        // Before the first byte goes to the hub: a session nobody attends is not registered, shown an ask or counted as seen.
+        if (!isHumanSession(args.app, io.env, record, args.stateRoot))
+            return 0;
+        const socketPath = join(args.stateRoot, HUB_SOCKET);
+        const hubTimeoutMs = io.hubTimeoutMs ?? HUB_TIMEOUT_MS;
+        if (args.app === "claude" && args.event === "stop") {
+            // The asyncRewake watcher: exit 2 with the text on stderr wakes Claude, even when the session is idle.
+            const text = await converse(socketPath, encodeLine({ v: 1, op: "watch", app: "claude", session_id: input.sessionId, cwd: input.cwd }), hubTimeoutMs, io.watchLimitMs ?? WATCH_LIMIT_MS, (line, first) => {
+                const message = parseWatchMessage(line);
+                if (message?.type === "wake")
+                    return { done: true, value: message.text };
+                if (message?.type === "watching" && first)
+                    return { done: false };
+                return { done: true, value: null };
+            });
+            if (text === null)
+                return 0;
+            io.stderr(text);
+            return 2;
+        }
+        const request = args.event === "stop"
+            ? { v: 1, op: "event", app: args.app, event: args.event, session_id: input.sessionId, cwd: input.cwd, stop_hook_active: input.stopHookActive }
+            : { v: 1, op: "event", app: args.app, event: args.event, session_id: input.sessionId, cwd: input.cwd };
+        const text = await converse(socketPath, encodeLine(request), hubTimeoutMs, hubTimeoutMs, line => ({ done: true, value: parseEventResponse(line)?.text ?? null }));
+        if (text === null || text === "")
+            return 0;
+        if (args.event === "session-start")
+            io.stdout(contextOutput("SessionStart", text));
+        else if (args.event === "prompt")
+            io.stdout(contextOutput("UserPromptSubmit", text));
+        else if (args.event === "stop")
+            io.stdout(JSON.stringify({ decision: "block", reason: text }));
+        return 0;
+    }
+    catch {
+        return 0;
+    }
+}
+/** True when Node runs this file as its entry point, directly or through a symlink. */
+function isDirectInvocation(moduleUrl, argvPath) {
+    if (!argvPath)
+        return false;
+    try {
+        return realpathSync(fileURLToPath(moduleUrl)) === realpathSync(argvPath);
+    }
+    catch {
+        return false;
+    }
+}
+if (isDirectInvocation(import.meta.url, process.argv[1])) {
+    void runHookClient(process.argv.slice(2), {
+        stdin: process.stdin,
+        stdout: text => { process.stdout.write(`${text}\n`); },
+        stderr: text => { process.stderr.write(`${text}\n`); },
+        env: process.env,
+    }).then(code => {
+        process.exitCode = code;
+        process.stdin.destroy();
+    });
+}

package/dist/src/asks/hub-protocol.js

@@ -0,0 +1,97 @@
+import { MAX_CWD_LENGTH, SESSION_ID, isApp, isHookEvent } from "./types.js";
+/*
+ * The line protocol between the hook client and the daemon's local hub (Work Item e1c08b33, spec section 8.2):
+ * one JSON object per line over the Unix socket <stateRoot>/hub.sock. The hook client imports this module, so it
+ * may import nothing but ./types.js.
+ *
+ * Client to hub, one line, then the client waits without closing its side:
+ *   {"v":1,"op":"event","app":"claude"|"codex","event":"session-start"|"prompt"|"session-end","session_id":…,"cwd":…}
+ *   {"v":1,"op":"event","app":"codex","event":"stop","session_id":…,"cwd":…,"stop_hook_active":false}
+ *   {"v":1,"op":"watch","app":"claude","session_id":…,"cwd":…}        (the Claude Stop watcher)
+ *   {"v":1,"op":"status"}                                             (doctor)
+ * Hub to client:
+ *   event:  {"v":1,"ok":true,"text":"…"|null}, then the hub closes the connection
+ *   status: {"v":1,"ok":true,"status":{"deliveries":n,"live_sessions":n,"watchers":n}}
+ *   error:  {"v":1,"ok":false,"code":"invalid_request"|"unavailable"}
+ *   watch:  {"v":1,"type":"wake","text":"…"} at once, or {"v":1,"type":"watching"} and later at most one of
+ *           {"v":1,"type":"wake","text":"…"} or {"v":1,"type":"release","reason":"replaced"|"session_ended"|"shutdown"}
+ *           A watch the hub refuses, or answers too late, ends with a bare close and no message; the client exits 0 on that too.
+ */
+export const HUB_SOCKET = "hub.sock";
+/** The hook client prints nothing and exits 0 when the hub has not answered within 300 ms. */
+export const HUB_TIMEOUT_MS = 300;
+/** A Claude Stop watcher exits 0 after 3500 s; its hook timeout is 3600 s. */
+export const WATCH_LIMIT_MS = 3_500_000;
+/** The most hook input the client reads from stdin. */
+export const MAX_HOOK_INPUT_BYTES = 64 * 1024;
+/** The longest request or response line. */
+export const MAX_LINE_BYTES = 16 * 1024;
+/** macOS keeps 104 bytes for a Unix socket path, including the terminating NUL; Node silently truncates longer ones. */
+export const MAX_SOCKET_PATH_BYTES = 103;
+export function encodeLine(message) {
+    return `${JSON.stringify(message)}\n`;
+}
+function record(line) {
+    try {
+        const value = JSON.parse(line);
+        return value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * A request from the hook client, or null when anything is missing, unknown or out of range. The session id and the
+ * cwd are held to the limits the ask store applies on a load (SESSION_ID, MAX_CWD_LENGTH): a session the store would
+ * drop at the next start must never be registered, because it would orphan every delivery pinned to it.
+ */
+export function parseHubRequest(line) {
+    const value = record(line);
+    if (value === null || value.v !== 1)
+        return null;
+    if (value.op === "status")
+        return Object.keys(value).length === 2 ? { v: 1, op: "status" } : null;
+    if (typeof value.session_id !== "string" || !SESSION_ID.test(value.session_id))
+        return null;
+    if (typeof value.cwd !== "string" || value.cwd.length > MAX_CWD_LENGTH)
+        return null;
+    if (value.op === "watch") {
+        if (value.app !== "claude" || Object.keys(value).length !== 5)
+            return null;
+        return { v: 1, op: "watch", app: "claude", session_id: value.session_id, cwd: value.cwd };
+    }
+    if (value.op !== "event" || !isApp(value.app) || !isHookEvent(value.event))
+        return null;
+    // A Claude turn end is always a watch; only Codex sends a plain stop, with its loop guard.
+    if (value.event === "stop") {
+        if (value.app !== "codex" || typeof value.stop_hook_active !== "boolean" || Object.keys(value).length !== 7)
+            return null;
+        return { v: 1, op: "event", app: "codex", event: "stop", session_id: value.session_id, cwd: value.cwd, stop_hook_active: value.stop_hook_active };
+    }
+    if (Object.keys(value).length !== 6)
+        return null;
+    return { v: 1, op: "event", app: value.app, event: value.event, session_id: value.session_id, cwd: value.cwd };
+}
+/** The hub's answer to an event request, or null when it is not one. */
+export function parseEventResponse(line) {
+    const value = record(line);
+    if (value === null || value.v !== 1 || value.ok !== true)
+        return null;
+    if (value.text === null)
+        return { text: null };
+    return typeof value.text === "string" ? { text: value.text } : null;
+}
+/** One message on a watch connection, or null when it is not one. */
+export function parseWatchMessage(line) {
+    const value = record(line);
+    if (value === null || value.v !== 1)
+        return null;
+    if (value.type === "watching")
+        return { v: 1, type: "watching" };
+    if (value.type === "wake" && typeof value.text === "string" && value.text !== "")
+        return { v: 1, type: "wake", text: value.text };
+    if (value.type === "release" && (value.reason === "replaced" || value.reason === "session_ended" || value.reason === "shutdown")) {
+        return { v: 1, type: "release", reason: value.reason };
+    }
+    return null;
+}