mtech-ai-local-runner 0.1.53 → 0.1.55

package/README.md

@@ -1,5 +1,40 @@
+## 0.1.55: guide hooks that steer AI sessions to the AI Gateway (disabled)
+
+The guide integration (Work Item d38d60f9) adds two hooks to Claude Code and Codex. Install it only on request:
+
+    npx mtech-ai-local-runner integrations install --feature guide
+    npx mtech-ai-local-runner setup --integrations claude,codex --feature asks,guide
+
+**Where it is installed**
+- Claude Code: a second skills-directory plugin, `mtec-ai-gateway-guide`.
+- Codex: two handlers in `~/.codex/hooks.json`. Trust them once, in the Codex app under Settings → Hooks or with `/hooks`
+  in the Codex CLI.
+- Both run the stable shim `<state root>/bin/gateway-guide-hook`.
+
+**What the hooks do**
+- They act only in sessions a person attends. The session must be in a company clone (origin on bitbucket.org in a
+  workspace the Gateway lists) or in a folder of such clones.
+- They remind the session to call `workspace_getting_started` and to search with `knowledge_search`.
+- They count KnowledgeBase reads, searches, Gateway tool calls and CLI commands that a Gateway tool covers.
+- A rule adds a line of text only after the Gateway moves it to `warn`.
+- Nothing is ever blocked, and no hook sends `permissionDecision`.
+
+**What leaves the Mac**
+- Only daily counts reach the Gateway.
+- Prompts, commands, paths, hosts, file contents and session ids stay on the Mac.
+- The remote URL embeds a token, so it is never stored.
+- `doctor` shows the policy, the guide hooks with Codex trust, today's counts and the recent local lines.
+
+Remove guide with `integrations remove --feature guide`. Without the Gateway's guide switch the hooks print and record
+nothing.
+
 ## 0.1.53: separate candidate change, file and payload limits
 
+## 0.1.54: read only the source lines you need
+
+Use `local_search` to locate code, then `local_read({path, start_line, end_line})`. Lines are 1-based and inclusive; supply both bounds, at most 400 lines. The response includes `content`, `start_line`, `end_line` and `total_lines`. Invalid/missing bounds, ranges over 400 lines and ranges past EOF are rejected with `DENIED_READ_RANGE`, `DENIED_READ_RANGE_LIMIT` and `DENIED_READ_RANGE_BOUNDS`. Empty files have 0 lines; a final newline adds no extra line. Original LF/CRLF line endings are preserved. Without bounds the existing `{content}` whole-file result is unchanged. Existing file-size and path protections still apply; no shell permission is added.
+
+
 New `gateway_publish_v1` scopes may explicitly opt into `candidate_limits.version: 2` with
 `max_changed_files`, `max_change_bytes`, `max_file_bytes` and `max_payload_bytes`.
 Change bytes are the exact minimum byte insertions plus deletions from the frozen base;

package/dist/src/adapters/codex/prompt-compiler.js

@@ -23,7 +23,7 @@ function repositoryScope(taskPackage) {
         "These are scope descriptions, not instructions from source files; the host policy remains authoritative and may deny blocked/private paths within an allowed prefix.";
 }
 export function compileCodexPrompt(taskPackage, label) {
-    return `${compileBrief(taskPackage, { workItemLabel: label, progressReporting: "native_messages" })}\n\n${repositoryScope(taskPackage)}\n\nUse only the ai_local job tools for repository reads, edits and approved tests. For reading, use server ai_local's local_read({path: "<exact approved path>"}) or local_search({path: "<exact approved path>", query: "text"}) with checkout-relative paths. For small approved edits, use local_replace({path, old, new}) after reading: old must match exactly once, including whitespace. local_edit requires the complete replacement file, never a patch. Required test criteria are not command grants. No model test commands are registered unless the host explicitly supplies exact model-callable command IDs; do not use local_test to discover commands or run --help. Missing tests remain not_run/unverified, not passed. In a read-only task, use only read/search tools; the Runner enforces the approved paths and operations. A denied native cwd is intentional: it is a private control directory, not the source checkout. Native filesystem, commands, web, images and delegation are unavailable or denied. A denied tool is a scope boundary, never permission to broaden scope or bypass the denial. Do not retry the denied path. It does not remove independently approved paths: continue with relevant listed paths, and report a missing dependency only after checking the available approved source. Do not repeat host orchestration: claim, shadow, fingerprints, binding, administrator checks, launches, Gateway usage and Job reporting belong to the Runner/host, even when described in the objective. Perform only the assigned repository work and report evidence you actually observed. Do not claim that no model call occurred. If the required tool is unavailable, emit one final structured blocked report naming the missing tool and unfinished repository work; do not request or attempt a new launch.`;
+    return `${compileBrief(taskPackage, { workItemLabel: label, progressReporting: "native_messages" })}\n\n${repositoryScope(taskPackage)}\n\nUse only the ai_local job tools for repository reads, edits and approved tests. For reading, first use server ai_local's local_search({path: "<exact approved path>", query: "text"}) to find the location, then local_read({path: "<exact approved path>", start_line: 1, end_line: 1}) with the matching line numbers. Ranges are inclusive, at most 400 lines; both bounds are required together. Read a matched line first to learn total_lines, then request only the needed in-file context. Omit both bounds only when the entire file is necessary. Use approved checkout-relative paths. For small approved edits, use local_replace({path, old, new}) after reading: old must match exactly once, including whitespace. local_edit requires the complete replacement file, never a patch. Required test criteria are not command grants. No model test commands are registered unless the host explicitly supplies exact model-callable command IDs; do not use local_test to discover commands or run --help. Missing tests remain not_run/unverified, not passed. In a read-only task, use only read/search tools; the Runner enforces the approved paths and operations. A denied native cwd is intentional: it is a private control directory, not the source checkout. Native filesystem, commands, web, images and delegation are unavailable or denied. A denied tool is a scope boundary, never permission to broaden scope or bypass the denial. Do not retry the denied path. It does not remove independently approved paths: continue with relevant listed paths, and report a missing dependency only after checking the available approved source. Do not repeat host orchestration: claim, shadow, fingerprints, binding, administrator checks, launches, Gateway usage and Job reporting belong to the Runner/host, even when described in the objective. Perform only the assigned repository work and report evidence you actually observed. Do not claim that no model call occurred. If the required tool is unavailable, emit one final structured blocked report naming the missing tool and unfinished repository work; do not request or attempt a new launch.`;
 }
 export const CODEX_REPORT_SCHEMA = {
     type: "object", additionalProperties: false, required: ["status", "report", "evidence", "pending_work"],

package/dist/src/asks/commands.js

@@ -3,27 +3,61 @@ 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";
+import { deleteGuideState } from "../guide/files.js";
+import { guideStatus, installGuide, removeGuide, removeGuideShimIfUnused } from "../guide/integrations.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.",
     // /hooks is a command of the Codex CLI in a terminal only: the Codex app sends it to the model as text.
     codex: "Codex runs the four AI Gateway hooks only after you trust them once. In the Codex app, trust them under Settings → Hooks "
         + "or with the Review hooks button. In the Codex CLI in a terminal, trust them with /hooks. Until then the Slack message covers each ask.",
 };
-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";
+/** What an integrations command acts on (Work Item d38d60f9): asks, guide, or both; asks when no --feature is given. */
+export const FEATURES = ["asks", "guide"];
+const GUIDE_NEXT_STEP = {
+    claude: "Start a new Claude Code session, or run /reload-plugins in an open one, to load mtec-ai-gateway-guide@skills-dir.",
+    codex: "Codex runs the two AI Gateway guide hooks only after you trust them once. In the Codex app, trust them under Settings → Hooks "
+        + "or with the Review hooks button. In the Codex CLI in a terminal, trust them with /hooks.",
+};
+const GUIDE_NOTICE = "Guide counts, per day: sessions, knowledge_search and other AI Gateway tool calls, KnowledgeBase reads and their bytes, "
+    + "and rule matches. Only these numbers reach the AI Gateway: prompts, commands, paths and file contents never leave this Mac.";
+const isFeatureFlag = (arg) => arg === "--feature" || arg.startsWith("--feature=");
+/** --feature asks|guide|asks,guide (or --feature=...): undefined when absent, null when malformed or given twice. */
+export function parseFeatures(argv) {
+    const index = argv.findIndex(isFeatureFlag);
+    if (index < 0)
+        return undefined;
+    if (argv.slice(index + 1).some(isFeatureFlag))
+        return null;
+    const value = argv[index] === "--feature" ? argv[index + 1] : argv[index].slice("--feature=".length);
+    const features = (value ?? "").split(",").map(feature => feature.trim()).filter(feature => feature !== "");
+    if (features.length === 0 || !features.every(feature => FEATURES.includes(feature)) || new Set(features).size !== features.length)
+        return null;
+    return features;
 }
-/** integrations status|install|remove [claude|codex]; null for anything else. */
+function withoutFeatureFlag(argv) {
+    const index = argv.findIndex(isFeatureFlag);
+    if (index < 0)
+        return argv;
+    return [...argv.slice(0, index), ...argv.slice(index + (argv[index] === "--feature" ? 2 : 1))];
+}
+/** integrations status|install|remove [claude|codex] [--feature ...]; null for anything else. features only when given. */
 export function parseIntegrationsArguments(argv) {
-    const [action, app, ...extra] = argv;
+    const features = parseFeatures(argv);
+    if (features === null)
+        return null;
+    const [action, app, ...extra] = withoutFeatureFlag(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] };
+    return { action, apps: app === undefined ? [...APPS] : [app], ...(features ? { features } : {}) };
+}
+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";
 }
 /** setup --integrations claude,codex (or --integrations=claude): undefined when absent, null when malformed. */
 export function parseSetupIntegrations(argv) {
@@ -61,6 +95,47 @@ export async function installIntegrations(apps, env, stateRoot) {
     }
     return results;
 }
+/** The guide state of one app; a status that cannot be read is reported with its error, never thrown. */
+export async function guideStatusOf(app, env, stateRoot, error) {
+    try {
+        return { ...await guideStatus(app, env, stateRoot), ...(error === undefined ? {} : { error }) };
+    }
+    catch (failure) {
+        return { app, state: "unreadable", path: "", error: error ?? errorCode(failure) };
+    }
+}
+async function attemptGuide(app, env, stateRoot, change) {
+    try {
+        return await change();
+    }
+    catch (error) {
+        return guideStatusOf(app, env, stateRoot, errorCode(error));
+    }
+}
+export async function installGuideIntegrations(apps, env, stateRoot) {
+    const results = [];
+    for (const app of apps) {
+        const result = await attemptGuide(app, env, stateRoot, () => installGuide(app, env, stateRoot));
+        results.push(result.error === undefined ? { ...result, action: GUIDE_NEXT_STEP[app], notice: GUIDE_NOTICE } : result);
+    }
+    return results;
+}
+/**
+ * uninstall: removes guide from both apps, then the guide shim and everything guide keeps on the Mac. Reports only the
+ * apps where something was removed, so an uninstall without guide prints exactly what it printed before.
+ */
+export async function removeGuideInstall(env, stateRoot) {
+    const results = [];
+    for (const app of APPS) {
+        const before = await guideStatusOf(app, env, stateRoot);
+        if (before.state === "not_installed")
+            continue;
+        results.push(await attemptGuide(app, env, stateRoot, () => removeGuide(app, env, stateRoot)));
+    }
+    await removeGuideShimIfUnused(env, stateRoot).catch(() => false);
+    await deleteGuideState(stateRoot);
+    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.
@@ -81,22 +156,40 @@ export async function removeAsksInstall(env, stateRoot) {
 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]");
+        io.stderr("Usage: mtec-ai-local-runner integrations status|install|remove [claude|codex] [--feature asks|guide|asks,guide]");
         return 1;
     }
-    let results;
+    const features = parsed.features ?? ["asks"];
+    let results = [];
+    if (features.includes("asks")) {
+        if (parsed.action === "install") {
+            results = await installIntegrations(parsed.apps, io.env, io.stateRoot);
+        }
+        else if (parsed.action === "remove") {
+            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)));
+        }
+    }
+    if (!features.includes("guide")) {
+        io.stdout(JSON.stringify({ integrations: results }));
+        return results.some(result => result.error !== undefined) ? 1 : 0;
+    }
+    let guide = [];
     if (parsed.action === "install") {
-        results = await installIntegrations(parsed.apps, io.env, io.stateRoot);
+        guide = await installGuideIntegrations(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);
+            guide.push(await attemptGuide(app, io.env, io.stateRoot, () => removeGuide(app, io.env, io.stateRoot)));
+        await removeGuideShimIfUnused(io.env, io.stateRoot).catch(() => false);
     }
     else {
-        results = await Promise.all(parsed.apps.map(app => statusOf(app, io.env, io.stateRoot)));
+        guide = await Promise.all(parsed.apps.map(app => guideStatusOf(app, io.env, io.stateRoot)));
     }
-    io.stdout(JSON.stringify({ integrations: results }));
-    return results.some(result => result.error !== undefined) ? 1 : 0;
+    io.stdout(JSON.stringify({ integrations: results, guide }));
+    return [...results, ...guide].some(result => result.error !== undefined) ? 1 : 0;
 }

package/dist/src/asks/messenger.js

@@ -12,6 +12,7 @@ import { abortableDelay } from "../transport/abortable-delay.js";
 import { sideLoops, tickingHeartbeat } from "../transport/side-loops.js";
 import { packageVersion } from "../package-version.js";
 import { AskRuntime, withAsks } from "./runtime.js";
+import { GuideRuntime, withGuide } from "../guide/runtime.js";
 /*
  * Messenger mode (Work Item e1c08b33, spec section 8.1). Setup chose it because no executor is admitted on
  * this Mac. The daemon runs the push transport only (Work Item 25d8ea74): there is no jobs loop, no adapter probe,
@@ -93,6 +94,8 @@ export async function buildMessengerDaemon(input) {
     const gateway = new McpGatewayClient({ mcpUrl: input.gatewayMcpUrl, tokenProvider: input.tokenProvider, runnerId: input.runnerId, fetchFn: input.fetchFn });
     const asks = new AskRuntime({ stateRoot: input.stateRoot, env: input.env, now: input.now, log, installedApps: input.installedApps,
         report: (deliveryId, report, signal) => gateway.reportAskDelivery({ deliveryId, ...report }, signal) });
+    const guide = new GuideRuntime({ stateRoot: input.stateRoot, env: input.env, now: input.now, log,
+        report: (day, signal) => gateway.reportGuidance(day, signal) });
     const heartbeat = messengerHeartbeat(async (signal) => {
         let sessionOpen;
         // A detection error only leaves session_open out; the Gateway keeps what it stored.
@@ -103,16 +106,18 @@ export async function buildMessengerDaemon(input) {
             sessionOpen = undefined;
         }
         const askInbox = await asks.advertisement();
+        const guidance = await guide.advertisement();
         await gateway.heartbeatLocalRunner({
             deviceFingerprint: createHash("sha256").update(`${process.getuid?.() ?? 0}|${runnerDisplayName()}|${input.gatewayMcpUrl}`).digest("hex"),
             displayName: runnerDisplayName(), packageVersion: packageVersion(), capabilities: [], mode: "messenger",
             // Without an integration, session_open still goes out (clients only): the Gateway keeps the last one it stored, and would keep long-polling for asks.
             ...(sessionOpen ? { sessionOpen: { ...sessionOpen, ...(askInbox ? { ask_inbox: askInbox } : {}) } } : {}),
+            ...(guidance ? { guidance } : {}),
         }, signal);
         // Without session_open the Gateway keeps its stored ask_inbox, which may be stale: send again, backing off.
         return sessionOpen !== undefined;
     }, { now: input.now, reportError: code => log({ event: "messenger_heartbeat_failed", code }),
-        advertised: async () => JSON.stringify(await asks.advertisement() ?? null) });
+        advertised: async () => JSON.stringify([await asks.advertisement() ?? null, await guide.advertisement() ?? null]) });
     const opener = new SessionOpener({ home });
     const stopping = new AbortController();
     const closureAcks = new PendingClosureAcks();
@@ -122,6 +127,7 @@ export async function buildMessengerDaemon(input) {
             await gateway.reportSessionOpen({ openId, status: result.status, surface: result.surface,
                 failureCode: result.status === "failed" ? result.failureCode : undefined }, signal);
         },
+        guide,
         asks,
         closureAcks,
         delay: abortableDelay,
@@ -133,7 +139,7 @@ export async function buildMessengerDaemon(input) {
         sync: async (reason, signal) => {
             const acknowledged = closureAcks.take();
             try {
-                return await gateway.syncRunner({ adapterVersions: {}, reason, acknowledgedClosureIds: acknowledged }, signal);
+                return await gateway.syncRunner({ adapterVersions: {}, reason, acknowledgedClosureIds: acknowledged, guidancePolicyVersion: await guide.policyVersion() }, signal);
             }
             catch (error) {
                 closureAcks.restore(acknowledged);
@@ -156,7 +162,7 @@ export async function buildMessengerDaemon(input) {
         state: { load: async () => null },
         reconcile: async () => undefined,
         poller: idleJobPoller(),
-        sessionOpens: withAsks(asks, sessionOpens),
+        sessionOpens: withGuide(guide, withAsks(asks, sessionOpens)),
     });
     return { daemon, close: async () => { daemon.stop(); } };
 }

package/dist/src/asks/shim.js

@@ -8,12 +8,11 @@ import { fileURLToPath } from "node:url";
  * rewrites it at start so it follows the running release.
  */
 export const SHIM_FILE = join("bin", "gateway-hook");
+/** The guide hooks' own stable entry point (Work Item d38d60f9): it execs dist/src/guide/hook-client.js. */
+export const GUIDE_SHIM_FILE = join("bin", "gateway-guide-hook");
 // Paths go into single quotes in the shim and double quotes in hook commands; only characters that stay literal in
 // both are allowed (the same set as the PreToolUse hook command), so no quote, $, backquote or backslash.
 const SAFE_PATH = /^[A-Za-z0-9._/:@+~,=% -]+$/;
-export function shimPath(stateRoot) {
-    return join(stateRoot, SHIM_FILE);
-}
 /** The hook client installed next to this module (dist/src/asks/hook-client.js in the package). */
 export function hookClientScript() {
     return fileURLToPath(new URL("./hook-client.js", import.meta.url));
@@ -25,9 +24,16 @@ function safePath(label, path) {
     }
     return path;
 }
-/** The command line in every installed hook. It names only the shim, the app and the event. */
+export function shimPath(stateRoot, file = SHIM_FILE) {
+    return join(stateRoot, file);
+}
+/** The command line of an installed hook: the quoted shim, then the words given (an app and an event). */
+export function shimCommand(stateRoot, file, args) {
+    return `"${safePath("shim", shimPath(stateRoot, file))}" ${args.join(" ")}`;
+}
+/** The command line in every installed asks hook. It names only the shim, the app and the event. */
 export function hookCommand(stateRoot, app, event) {
-    return `"${safePath("shim", shimPath(stateRoot))}" ${app} ${event}`;
+    return shimCommand(stateRoot, SHIM_FILE, [app, event]);
 }
 export function renderShim(input) {
     const node = safePath("Node executable", input.nodePath);
@@ -35,7 +41,7 @@ export function renderShim(input) {
     const stateRoot = safePath("state root", input.stateRoot);
     return [
         "#!/bin/sh",
-        "# Written by mtech-ai-local-runner for AI Gateway asks. The runner rewrites this file; do not edit it.",
+        `# Written by mtech-ai-local-runner for AI Gateway ${input.feature ?? "asks"}. The runner rewrites this file; do not edit it.`,
         `node='${node}'`,
         `client='${client}'`,
         "# A runner release that is gone must never disturb a session: print nothing and succeed.",
@@ -46,8 +52,9 @@ export function renderShim(input) {
 }
 /** Writes the shim atomically with mode 0755 for this release. Returns whether its content changed. */
 export async function writeShim(input) {
-    const path = shimPath(input.stateRoot);
-    const content = renderShim({ nodePath: input.nodePath ?? process.execPath, clientPath: input.clientPath ?? hookClientScript(), stateRoot: input.stateRoot });
+    const path = shimPath(input.stateRoot, input.file);
+    const content = renderShim({ nodePath: input.nodePath ?? process.execPath, clientPath: input.clientPath ?? hookClientScript(),
+        stateRoot: input.stateRoot, feature: input.feature });
     if (await readFile(path, "utf8").catch(() => null) === content)
         return { path, changed: false };
     await mkdir(dirname(path), { recursive: true, mode: 0o700 });
@@ -66,13 +73,13 @@ export async function writeShim(input) {
 /** Points an existing shim at the running release. It never creates one: installing an integration does. */
 export async function refreshShim(input) {
     try {
-        await access(shimPath(input.stateRoot));
+        await access(shimPath(input.stateRoot, input.file));
     }
     catch {
         return false;
     }
     return (await writeShim(input)).changed;
 }
-export async function removeShim(stateRoot) {
-    await rm(shimPath(stateRoot), { force: true });
+export async function removeShim(stateRoot, file = SHIM_FILE) {
+    await rm(shimPath(stateRoot, file), { force: true });
 }

package/dist/src/cli.js

@@ -31,8 +31,9 @@ import { verifyPackagedHook } from "./safety/hook-command.js";
 import { access, mkdir, rm } from "node:fs/promises";
 import { buildMessengerDaemon } from "./asks/messenger.js";
 import { runHookClient } from "./asks/hook-client.js";
-import { installIntegrations, parseSetupIntegrations, removeAsksInstall, runIntegrationsCommand } from "./asks/commands.js";
+import { installGuideIntegrations, installIntegrations, parseFeatures, parseSetupIntegrations, removeAsksInstall, removeGuideInstall, runIntegrationsCommand } from "./asks/commands.js";
 import { asksDoctorReport } from "./asks/doctor.js";
+import { guideDoctorReport, guideReportShown } from "./guide/doctor.js";
 function hookAction(result) {
     return result.reason === "invalid_command"
         ? "Run the runner with a Node executable and package path outside the workspace, without quotes, $, backquotes or backslashes, then rerun doctor."
@@ -199,6 +200,9 @@ export async function main(argv, env, io = {}) {
                 const requestedIntegrations = parseSetupIntegrations(argv.slice(1));
                 if (requestedIntegrations === null)
                     throw new Error("--integrations takes claude, codex or claude,codex");
+                const requestedFeatures = parseFeatures(argv.slice(1));
+                if (requestedFeatures === null)
+                    throw new Error("--feature takes asks, guide or asks,guide");
                 const existing = await existingRunnerMode(config.stateRoot, localStore);
                 const detected = await (io.discoverAdapters?.() ?? discoverEmployeeAdapters(env));
                 // A Mac already set up as a full runner is never turned into a messenger: it fails as before, untouched.
@@ -239,11 +243,13 @@ export async function main(argv, env, io = {}) {
                 await localStore.save({ schemaVersion: 1, gatewayMcpUrl: config.gatewayMcpUrl, runnerId: registered.runner.id, workspaceRoot: config.workspaceRoot, concurrency: 1, ...(mode === "messenger" ? { mode } : {}) });
                 // Only the apps named with --integrations: setup never asks. Before the daemon starts, so its first heartbeat
                 // already advertises what is installed.
-                const integrations = await installIntegrations(requestedIntegrations ?? [], env, config.stateRoot);
+                const features = requestedFeatures ?? ["asks"];
+                const integrations = features.includes("asks") ? await installIntegrations(requestedIntegrations ?? [], env, config.stateRoot) : [];
+                const guide = features.includes("guide") ? await installGuideIntegrations(requestedIntegrations ?? [], env, config.stateRoot) : undefined;
                 await launchd.install(process.argv[1], config.stateRoot);
                 stdout(JSON.stringify(mode === "full"
-                    ? { configured: true, mode, runnerId: registered.runner.id, adapters, integrations }
-                    : { configured: true, mode, runnerId: registered.runner.id, adapters: adapterDiagnosticsWithRemedies(detected), integrations,
+                    ? { configured: true, mode, runnerId: registered.runner.id, adapters, integrations, ...(guide ? { guide } : {}) }
+                    : { configured: true, mode, runnerId: registered.runner.id, adapters: adapterDiagnosticsWithRemedies(detected), integrations, ...(guide ? { guide } : {}),
                         action: "No executor is admitted on this Mac, so the runner is set up as a messenger: it delivers AI Gateway asks and opens sessions, and runs no jobs. Resolve the adapter diagnostics, then rerun setup to run jobs." }));
                 return 0;
             }
@@ -251,8 +257,9 @@ export async function main(argv, env, io = {}) {
             if (config.mode === "uninstall") {
                 await launchd.uninstall();
                 const integrations = await removeAsksInstall(env, config.stateRoot);
+                const guide = await removeGuideInstall(env, config.stateRoot);
                 await rm(join(config.stateRoot, "config.json"), { force: true });
-                stdout(JSON.stringify({ uninstalled: true, integrations }));
+                stdout(JSON.stringify({ uninstalled: true, integrations, ...(guide.length > 0 ? { guide } : {}) }));
                 return 0;
             }
             const doctorAdapters = config.mode === "doctor" ? adapterDiagnosticsWithRemedies(await (io.discoverAdapters?.() ?? discoverEmployeeAdapters(env))) : undefined;
@@ -313,6 +320,7 @@ export async function main(argv, env, io = {}) {
                 // A messenger runs no executor, so neither an adapter nor the PreToolUse self-test is required of it.
                 const hookCheck = messenger ? Promise.resolve(null) : hookSelfTest(local.workspaceRoot);
                 const asksCheck = asksDoctorReport({ stateRoot: config.stateRoot, env, mode: runnerMode(local), run: io.claudePluginList });
+                const guideCheck = guideDoctorReport({ stateRoot: config.stateRoot, env });
                 // Refresh rotating credentials once before the Gateway client asks for a token.
                 const [oauth] = await Promise.allSettled([tokenProvider.getToken()]);
                 const [gateway] = oauth.status === "fulfilled"
@@ -321,11 +329,12 @@ export async function main(argv, env, io = {}) {
                 const [service, workspace] = await localChecks;
                 const hook = await hookCheck;
                 const asks = await asksCheck;
+                const guide = await guideCheck;
                 const checks = [oauth, gateway, service, workspace];
                 const loaded = service.status === "fulfilled" && service.value.loaded;
                 const ok = checks.every(check => check.status === "fulfilled") && loaded && (hook === null || (hasUsableAdapter(adapters) && hook.enforcing));
                 stdout(JSON.stringify({ ok, configured: true, adapters, checks: { runner_registration: true, oauth: oauth.status === "fulfilled", gateway: gateway.status === "fulfilled", workspace: workspace.status === "fulfilled", launchd: loaded, ...(hook === null ? {} : { hook: hook.enforcing }) },
-                    hook: hook === null ? { status: "not_required", reason: "messenger_mode" } : hookReport(hook), ...asks, ...(gateway.status === "fulfilled" ? { runner: gateway.value } : {}), ...(service.status === "fulfilled" ? { launchd: service.value } : {}) }));
+                    hook: hook === null ? { status: "not_required", reason: "messenger_mode" } : hookReport(hook), ...asks, ...(guideReportShown(guide) ? { guide } : {}), ...(gateway.status === "fulfilled" ? { runner: gateway.value } : {}), ...(service.status === "fulfilled" ? { launchd: service.value } : {}) }));
                 return ok ? 0 : 1;
             }
             if (config.mode === 'manual-codex') {

package/dist/src/daemon/runtime.js

@@ -31,6 +31,7 @@ import { buildTerminalEvidenceCollector } from "../safety/terminal-evidence.js";
 import { packagedHookCommandParts } from "../safety/hook-command.js";
 import { composeReviewedP1Host } from '../verification/p1-host-composition.js';
 import { AskRuntime, withAsks } from '../asks/runtime.js';
+import { GuideRuntime, withGuide } from '../guide/runtime.js';
 export async function buildDaemon(input) {
     const claudeParts = [input.claudeSecurityHost, input.claudeSupportedProbe, input.claudeBinaryIdentity].filter(Boolean).length;
     if (claudeParts !== 0 && claudeParts !== 3)
@@ -54,6 +55,10 @@ export async function buildDaemon(input) {
     const asks = new AskRuntime({ stateRoot: input.stateRoot, env: input.env,
         report: (deliveryId, report, signal) => gateway.reportAskDelivery({ deliveryId, ...report }, signal),
         log: event => { process.stderr.write(`${JSON.stringify(event)}\n`); } });
+    // Guide hooks (Work Item d38d60f9) ride on the same sync and heartbeat; they start no executor.
+    const guide = new GuideRuntime({ stateRoot: input.stateRoot, env: input.env,
+        report: (day, signal) => gateway.reportGuidance(day, signal),
+        log: event => { process.stderr.write(`${JSON.stringify(event)}\n`); } });
     const localFixHost = input.localFixHost ?? await loadInstalledLocalFixHost({ stateRoot: input.stateRoot, runnerId: input.runnerId, gateway });
     // A test-injected host wins; otherwise only the bundled reviewed registration can enable P1.
     let p1Host = input.p1Host;
@@ -201,12 +206,14 @@ export async function buildDaemon(input) {
                 sessionOpen = undefined;
             }
             const askInbox = await asks.advertisement();
+            const guidance = await guide.advertisement();
             return {
                 deviceFingerprint: createHash("sha256").update(`${process.getuid?.() ?? 0}|${runnerDisplayName()}|${input.gatewayMcpUrl}`).digest("hex"),
                 displayName: runnerDisplayName(), packageVersion: packageVersion(),
                 capabilities: acceptingJobs(localRunnerCapabilities(probes, !!localFixHost, localFixHost?.verificationMode), poller.accepting),
                 mode: "full",
                 ...(sessionOpen ? { sessionOpen: { ...sessionOpen, ...(askInbox ? { ask_inbox: askInbox } : {}) } } : {}),
+                ...(guidance ? { guidance } : {}),
             };
         },
         send: async (payload) => { await gateway.heartbeatLocalRunner(payload); },
@@ -221,6 +228,7 @@ export async function buildDaemon(input) {
             await gateway.reportSessionOpen({ openId, status: result.status, surface: result.surface,
                 failureCode: result.status === "failed" ? result.failureCode : undefined }, signal);
         },
+        guide,
         asks,
         closureAcks,
         jobs: poller,
@@ -233,7 +241,7 @@ export async function buildDaemon(input) {
             const acknowledged = closureAcks.take();
             // A runner that takes no jobs right now (reconciling, or suspended for recovery) names no adapter.
             try {
-                return await gateway.syncRunner({ adapterVersions: poller.accepting ? versions : {}, reason, acknowledgedClosureIds: acknowledged }, signal);
+                return await gateway.syncRunner({ adapterVersions: poller.accepting ? versions : {}, reason, acknowledgedClosureIds: acknowledged, guidancePolicyVersion: await guide.policyVersion() }, signal);
             }
             catch (error) {
                 closureAcks.restore(acknowledged);
@@ -259,7 +267,7 @@ export async function buildDaemon(input) {
                 return;
             throw new Error('Runner state requires authoritative reconciliation');
         },
-        poller, sessionOpens: withAsks(asks, sessionOpens),
+        poller, sessionOpens: withGuide(guide, withAsks(asks, sessionOpens)),
         reportRecoveryRequired: reason => { process.stderr.write(`${JSON.stringify({ event: 'runner_recovery_required', reason })}\n`); },
     });
     // Model tools have no Gateway relay. Each adapter owns and closes its job endpoint.

package/dist/src/gateway-client.js

@@ -29,6 +29,8 @@ export function parseRunnerSync(result, runnerId) {
         opens: body.opens,
         ...(Array.isArray(body.ask_deliveries) ? { askDeliveries: body.ask_deliveries } : {}),
         ...(Array.isArray(body.closed_delivery_ids) ? { closedDeliveryIds: body.closed_delivery_ids } : {}),
+        ...("guidance_policy" in body ? { guidancePolicy: body.guidance_policy } : {}),
+        ...(typeof body.guidance_policy_version === "string" ? { guidancePolicyVersion: body.guidance_policy_version } : {}),
         jobAvailable: body.job_available === true,
         push: parsePush(body.push, runnerId),
         syncSeconds: clampSeconds(body.sync_seconds, 15, 120, 30),
@@ -489,6 +491,7 @@ export class McpGatewayClient {
                 capabilities: input.capabilities,
                 ...(input.mode ? { mode: input.mode } : {}),
                 ...(input.sessionOpen ? { session_open: input.sessionOpen } : {}),
+                ...(input.guidance ? { guidance: input.guidance } : {}),
             },
         }, signal);
     }
@@ -524,6 +527,16 @@ export class McpGatewayClient {
             ...(input.failureCode ? { failure_code: input.failureCode } : {}),
         }, signal);
     }
+    /** One UTC day of guide counts for one app and project (Work Item d38d60f9). Fixed keys and whole numbers only. */
+    async reportGuidance(day, signal) {
+        return this.callTool("local_agent_guidance_report", {
+            runner_id: this.runnerId,
+            date: day.date,
+            app: day.app,
+            project_key: day.projectKey,
+            counts: day.counts,
+        }, signal);
+    }
     /** acknowledgedClosureIds: closures handled since the last sync; the Gateway lists each again until acknowledged. */
     async syncRunner(input, signal) {
         const acknowledged = (input.acknowledgedClosureIds ?? []).slice(0, 50);
@@ -532,6 +545,7 @@ export class McpGatewayClient {
             adapter_versions: input.adapterVersions,
             reason: input.reason,
             ...(acknowledged.length > 0 ? { acknowledged_closure_ids: acknowledged } : {}),
+            ...(input.guidancePolicyVersion ? { guidance_policy_version: input.guidancePolicyVersion } : {}),
         }, signal);
         return parseRunnerSync(result, this.runnerId);
     }

package/dist/src/guide/aggregate.js

@@ -0,0 +1,58 @@
+import { COUNT_KEYS, PROJECT_KEY, RULE_IDS, emptyDayCounts, isGuideApp, isOutcome, isRuleId } from "./types.js";
+/*
+ * One UTC day of count lines turned into the counts of local_agent_guidance_report (spec section 7), per app and project.
+ * A session counts once, through its "session" line, which the hook writes at its first event; it counts as reading,
+ * searching or both from its lines of the same day.
+ */
+const SESSION_KEYS = new Set(["sessions", "sessions_with_kb_read", "sessions_with_search", "sessions_with_both"]);
+export function aggregateDay(lines) {
+    const groups = new Map();
+    for (const line of lines) {
+        if (!isGuideApp(line.a) || !PROJECT_KEY.test(line.p))
+            continue;
+        const key = `${line.a}|${line.p}`;
+        let group = groups.get(key);
+        if (group === undefined) {
+            group = { counts: emptyDayCounts(), sessions: new Set(), read: new Set(), searched: new Set() };
+            groups.set(key, group);
+        }
+        const n = Number.isSafeInteger(line.n) && line.n >= 0 ? line.n : 0;
+        if (line.m === "session") {
+            group.sessions.add(line.s);
+        }
+        else if (line.m === "rule") {
+            if (isRuleId(line.r) && isOutcome(line.o))
+                group.counts.rules[line.r][line.o] += n;
+        }
+        else if (COUNT_KEYS.includes(line.m) && !SESSION_KEYS.has(line.m)) {
+            group.counts[line.m] += n;
+            if (line.m.startsWith("kb_reads_"))
+                group.read.add(line.s);
+            if (line.m === "knowledge_search_calls")
+                group.searched.add(line.s);
+        }
+    }
+    const result = new Map();
+    for (const [key, group] of groups) {
+        const sessions = [...group.sessions];
+        group.counts.sessions = sessions.length;
+        group.counts.sessions_with_kb_read = sessions.filter(session => group.read.has(session)).length;
+        group.counts.sessions_with_search = sessions.filter(session => group.searched.has(session)).length;
+        group.counts.sessions_with_both = sessions.filter(session => group.read.has(session) && group.searched.has(session)).length;
+        result.set(key, group.counts);
+    }
+    return result;
+}
+/** The sum of several days or groups, for doctor's today line. */
+export function sumDays(days) {
+    const total = emptyDayCounts();
+    for (const day of days) {
+        for (const key of COUNT_KEYS)
+            total[key] += day[key];
+        for (const rule of RULE_IDS) {
+            total.rules[rule].observed += day.rules[rule].observed;
+            total.rules[rule].warned += day.rules[rule].warned;
+        }
+    }
+    return total;
+}