knodin 0.8.3 → 0.8.4

package/README.md

@@ -190,6 +190,8 @@ knodin repair
 | `knodin status --deep` | Index freshness, health, hooks, and integration status |
 | `knodin repair` | Repair or rebuild unhealthy local graph state |
 | `knodin diagnostics …` | Preview and archive explicit-allowlist local support evidence |
+| `knodin agent-hooks …` | Explicitly install, inspect, or remove optional user-global Claude lifecycle hooks |
+| `knodin telemetry …` | Opt into private repository-local adoption evidence and render the local dashboard |
 
 Run `knodin --help` or read the [CLI reference](docs/CLI.md) for complete syntax.
 
@@ -218,7 +220,11 @@ repository, and lifecycle capabilities. See the [MCP guide](docs/MCP.md).
 Each checkout stores its graph and lifecycle state in `.knodin/`. Shared model
 files live in the user cache rather than being duplicated per repository.
 Source and graph data stay local. Telemetry is metadata-only, disabled by
-default, and never sent by knodin. Troubleshooting diagnostics are also
+default, and never sent by knodin. Optional Claude hooks are installed only by
+`knodin agent-hooks install --client claude`; they inject bounded, freshness-aware
+session orientation and no-op outside initialized repositories. Adoption
+capture remains a separate opt-in through `knodin telemetry enable`.
+Troubleshooting diagnostics are also
 explicitly enabled, local-only, bounded, and never uploaded automatically.
 
 The optional `prs` command invokes the user's authenticated `gh` CLI. Network

package/dist/bin/cli.js

@@ -16,6 +16,8 @@ import fs from "node:fs";
 import path from "node:path";
 import readline from "node:readline/promises";
 import { fileURLToPath } from "node:url";
+import { canUseSessionContextCache, parseClaudeHookPayload, readSessionContextCache, recordClaudeLifecycleEvent, renderSessionContext, SESSION_CONTEXT_BUDGET_LINE, sessionStartHookOutput, writeSessionContextCache, } from "../src/agent-events.js";
+import { inspectClaudeAgentHooks, installClaudeAgentHooks, uninstallClaudeAgentHooks, } from "../src/agent-hooks.js";
 import { detectSupportedAgents, parseInitScope, } from "../src/agent-integration.js";
 import { refreshExternalGraphArtifacts, writeArtifactRefreshRecord, } from "../src/artifact-refresh.js";
 import { checkIndexed, extractPositionals, extractRepoFlag, parseReviewArgs, planIndex, resolveCliRuntimeCommand, resolveRepo, } from "../src/cli-args.js";
@@ -43,6 +45,7 @@ import { createRepairPlan, createRepairProgressRenderer, parseRepairCliArgs, res
 import { runRepositoryInitializationProcess } from "../src/repository-init-process.js";
 import { detectRepositorySignals, discoverRepositories, formatRepositoryHuman, initializeRepositories, inventoryRepository, parseFleetInitArgs, parseRepositoryCommandArgs, repositorySignalInspectionLimit, searchRepositories, withRepositorySignals, } from "../src/repository-management.js";
 import { applyResponseBudget } from "../src/response-budget.js";
+import { appendSessionEvent, clearSessionTelemetry, disableSessionTelemetry, enableSessionTelemetry, readSessionEvents, sessionTelemetryStatus, } from "../src/session-telemetry.js";
 import { configuredRepositoryInitMemoryLimitBytes, enrichSystemRelationships, incorporateSystemQueryEvidence, indexModeForPath, loadSystemConfiguration, queryConfiguredSystem, systemMembershipsForPath, validateSystemHealth, } from "../src/system-config.js";
 import { applyTrustedUpdate, checkTrustedUpdate, claimScheduledUpdateCheck, detectUpdateInstallMethod, explainTrustedUpdate, releaseScheduledUpdateCheck, rollbackTrustedUpdate, trustedUpdateStatus, } from "../src/update-policy.js";
 import { KNODIN_VERSION } from "../src/version.js";
@@ -684,9 +687,9 @@ async function main() {
     };
     const repoFlag = selectorValue("--repo");
     const runtimeCommand = resolveCliRuntimeCommand(process);
-    // hook-refresh is an internal machine-to-machine command. Keep it JSON even
+    // Internal machine-to-machine commands stay JSON regardless of TTY state.
     // when an older installed hook predates the explicit --json argument.
-    const jsonOutput = invocation.options.json === true || cmd === "hook-refresh";
+    const jsonOutput = invocation.options.json === true || cmd === "hook-refresh" || cmd === "agent-event";
     // `--json` is a shared output flag. Repair owns its richer --json/--jsonl
     // parser; all other commands receive their original arguments minus it.
     const rest = cmd === "repair" ? rawRest : rawRest.filter((argument) => argument !== "--json");
@@ -1075,12 +1078,43 @@ async function main() {
             background.unref();
         }
     }
+    if (cmd === "agent-hooks") {
+        const action = invocation.commandPath[1];
+        const client = selectorValue("--client") ?? "claude";
+        if (client !== "claude")
+            throw new Error("knodin agent-hooks: only --client claude is supported");
+        if (invocation.options.dryRun === true && action !== "install")
+            throw new Error("knodin agent-hooks: --dry-run applies only to install");
+        let hookResult;
+        if (action === "install") {
+            const quote = (value) => `'${value.replaceAll("'", `'"'"'`)}'`;
+            hookResult = installClaudeAgentHooks({
+                command: runtimeCommand.map(quote).join(" "),
+                dryRun: invocation.options.dryRun === true,
+            });
+        }
+        else if (action === "status")
+            hookResult = inspectClaudeAgentHooks();
+        else if (action === "uninstall")
+            hookResult = uninstallClaudeAgentHooks();
+        else
+            throw new Error("knodin agent-hooks requires install, status, or uninstall");
+        process.stdout.write(jsonOutput
+            ? `${JSON.stringify(hookResult)}\n`
+            : formatGenericHuman("agent-hooks", hookResult));
+        return;
+    }
     const resolved = resolveRepo(repoFlag, process.cwd());
     if (!resolved.ok) {
+        // Global agent hooks also run outside repositories and must fail open.
+        if (cmd === "agent-event")
+            return;
         process.stderr.write(`${resolved.error}\n`);
         process.exit(1);
     }
     const repo = resolved.repo;
+    if (cmd === "agent-event" && !fs.existsSync(resolveDbPath(repo)))
+        return;
     if (cmd === "doctor") {
         const gitProbe = spawnSync(gitExecutable(), ["rev-parse", "--is-inside-work-tree"], {
             cwd: repo,
@@ -1231,6 +1265,7 @@ async function main() {
     let repairWasPlan = false;
     let repairExitCode = 0;
     let statusWasWatched = false;
+    let agentEventOutput = false;
     const graphRead = async (run) => {
         const health = await inspectGraphQueryHealth(repo, async (target) => attachLifecycleHealth(target, await engine.status(target, { audit: "cached" })));
         if (!health.available) {
@@ -1246,6 +1281,103 @@ async function main() {
         return decorateGraphQueryResult(value, verified.state, verified.graph.freshness);
     };
     switch (cmd) {
+        case "agent-event": {
+            agentEventOutput = true;
+            const event = invocation.positionals[0];
+            if (!event)
+                throw new Error("knodin agent-event requires an event");
+            let payload;
+            try {
+                payload = parseClaudeHookPayload(await readBoundedStdin(65_536));
+            }
+            catch {
+                result = null;
+                break;
+            }
+            if (event !== "session-start") {
+                try {
+                    recordClaudeLifecycleEvent(repo, event, payload);
+                }
+                catch {
+                    // Optional telemetry must never interrupt the agent.
+                }
+                result = null;
+                break;
+            }
+            const startedAt = performance.now();
+            let status;
+            try {
+                status = await engine.status(repo, { audit: "cached" });
+            }
+            catch {
+                if (payload.session_id)
+                    try {
+                        appendSessionEvent(repo, {
+                            event: "session_start",
+                            sessionId: payload.session_id,
+                            context: "unavailable",
+                            freshness: "unavailable",
+                            latencyMs: Math.round((performance.now() - startedAt) * 100) / 100,
+                            cacheHit: false,
+                        });
+                    }
+                    catch {
+                        // Best-effort local recording remains fail-open.
+                    }
+                result = sessionStartHookOutput(`## knodin session context\n${SESSION_CONTEXT_BUDGET_LINE}\nContext generation was unavailable. Run knodin status before relying on graph evidence.`);
+                break;
+            }
+            const freshness = status.freshness?.state ?? "unknown";
+            const cacheKey = JSON.stringify({
+                schemaVersion: 1,
+                head: status.freshness?.currentHead,
+                fingerprint: status.freshness?.workingTree?.indexedFingerprint,
+                generation: status.indexGeneration,
+                budgets: [600, 8192, 12],
+            });
+            const cacheEligible = canUseSessionContextCache(status.status, freshness);
+            let text = cacheEligible ? readSessionContextCache(repo, cacheKey) : null;
+            let cacheHit = text !== null;
+            let contextState = "delivered";
+            if (!cacheEligible) {
+                contextState = "degraded";
+                text = `## knodin session context\n${SESSION_CONTEXT_BUDGET_LINE}\nGraph evidence is ${freshness}. Run knodin status and follow its repair or reindex guidance before relying on graph evidence.`;
+            }
+            else if (!text) {
+                cacheHit = false;
+                try {
+                    const context = await buildKnodinContext(engine, "Orient this coding session", repo, undefined, []);
+                    text = renderSessionContext(context, freshness);
+                    writeSessionContextCache(repo, cacheKey, text);
+                }
+                catch {
+                    contextState = "unavailable";
+                    text = `## knodin session context\n${SESSION_CONTEXT_BUDGET_LINE}\nContext generation was unavailable. Run knodin status, then call the connected knodin context operation when needed.`;
+                }
+            }
+            if (payload.session_id)
+                try {
+                    appendSessionEvent(repo, {
+                        event: "session_start",
+                        sessionId: payload.session_id,
+                        context: contextState,
+                        freshness: freshness === "fresh"
+                            ? "fresh"
+                            : status.status === "repair-needed"
+                                ? "repair-needed"
+                                : freshness === "unknown"
+                                    ? "unavailable"
+                                    : "stale",
+                        latencyMs: Math.round((performance.now() - startedAt) * 100) / 100,
+                        cacheHit,
+                    });
+                }
+                catch {
+                    // Best-effort local recording remains fail-open.
+                }
+            result = sessionStartHookOutput(text);
+            break;
+        }
         case "doctor": {
             const client = selectorValue("--client");
             if (client !== undefined &&
@@ -1973,16 +2105,23 @@ async function main() {
             if (!Number.isInteger(retentionDays) || retentionDays < 1 || retentionDays > 3650)
                 throw new Error("knodin telemetry: --retention-days must be an integer from 1 to 3650");
             const input = selectorValue("--input");
-            if (action === "status")
-                result = telemetryStatus(repo, input, retentionDays);
+            if (action === "enable")
+                result = enableSessionTelemetry(repo);
+            else if (action === "disable")
+                result = disableSessionTelemetry(repo);
+            else if (action === "status")
+                result = {
+                    ...telemetryStatus(repo, input, retentionDays),
+                    session: sessionTelemetryStatus(repo, retentionDays),
+                };
             else if (action === "report")
-                result = writeTelemetryReport(repo, readTelemetryRecords(repo, input, retentionDays), selectorValue("--output"));
+                result = writeTelemetryReport(repo, readTelemetryRecords(repo, input, retentionDays), selectorValue("--output"), readSessionEvents(repo, retentionDays));
             else if (action === "export")
-                result = exportTelemetry(repo, readTelemetryRecords(repo, input, retentionDays), selectorValue("--output"));
+                result = exportTelemetry(repo, readTelemetryRecords(repo, input, retentionDays), selectorValue("--output"), readSessionEvents(repo, retentionDays));
             else if (action === "clear")
-                result = clearTelemetry(repo, input);
+                result = { ...clearTelemetry(repo, input), session: clearSessionTelemetry(repo) };
             else
-                throw new Error("knodin telemetry requires status, report, export, or clear");
+                throw new Error("knodin telemetry requires enable, disable, status, report, export, or clear");
             break;
         }
         case "diagnostics": {
@@ -2074,6 +2213,11 @@ async function main() {
             process.exit(1);
     }
     await engine.close();
+    if (agentEventOutput) {
+        if (result !== null && result !== undefined)
+            process.stdout.write(`${JSON.stringify(result)}\n`);
+        return;
+    }
     if (statusWasWatched)
         return;
     const boundedResult = applyResponseBudget(result, cmd, responseBudget, {
@@ -2128,55 +2272,80 @@ try {
 }
 catch (err) {
     const argv = process.argv.slice(2);
-    const repoIndex = argv.indexOf("--repo");
-    const equalsRepo = argv.find((argument) => argument.startsWith("--repo="));
-    const explicitRepo = repoIndex >= 0 ? argv[repoIndex + 1] : undefined;
-    let candidate = process.cwd();
-    if (explicitRepo)
-        candidate = explicitRepo;
-    else if (equalsRepo)
-        candidate = equalsRepo.slice("--repo=".length);
-    const command = argv.find((argument, index) => {
-        if (argument.startsWith("-"))
-            return false;
-        return !(index > 0 && argv[index - 1] === "--repo") && argument !== candidate;
-    });
-    const knownCommands = new Set([
-        "init",
-        "configure",
-        "index",
-        "doctor",
-        "status",
-        "wait",
-        "repair",
-        "serve",
-        "context",
-        "explain",
-        "review",
-        "map",
-        "search",
-        "query",
-        "rename",
-        "wiki",
-        "visualize",
-        "pack",
-        "compress",
-        "prs",
-        "worktrees",
-        "telemetry",
-        "diagnostics",
-        "system",
-        "repos",
-        "remote",
-        "update",
-    ]);
-    const diagnostic = recordDiagnosticFailure(candidate, {
-        surface: "cli",
-        operation: command && knownCommands.has(command) ? command : "unknown",
-        phase: "dispatch",
-        error: err,
-    });
-    const correlation = diagnostic.recorded ? ` [diagnostic ${diagnostic.correlationId}]` : "";
-    console.error(`${err instanceof Error ? err.message : String(err)}${correlation}`);
-    process.exit(1);
+    let invokedCommand;
+    for (let index = 0; index < argv.length; index += 1) {
+        const argument = argv[index];
+        if (argument === "--repo") {
+            index += 1;
+            continue;
+        }
+        if (argument?.startsWith("--repo=") || argument === "--json")
+            continue;
+        if (!argument?.startsWith("-")) {
+            invokedCommand = argument;
+            break;
+        }
+    }
+    if (invokedCommand === "agent-event") {
+        const eventIndex = argv.indexOf("agent-event");
+        if (argv[eventIndex + 1] === "session-start") {
+            process.stdout.write(`${JSON.stringify(sessionStartHookOutput(`## knodin session context\n${SESSION_CONTEXT_BUDGET_LINE}\nContext generation was unavailable. Run knodin status before relying on graph evidence.`))}\n`);
+        }
+        process.exitCode = 0;
+    }
+    else {
+        const repoIndex = argv.indexOf("--repo");
+        const equalsRepo = argv.find((argument) => argument.startsWith("--repo="));
+        const explicitRepo = repoIndex >= 0 ? argv[repoIndex + 1] : undefined;
+        let candidate = process.cwd();
+        if (explicitRepo)
+            candidate = explicitRepo;
+        else if (equalsRepo)
+            candidate = equalsRepo.slice("--repo=".length);
+        const command = argv.find((argument, index) => {
+            if (argument.startsWith("-"))
+                return false;
+            return !(index > 0 && argv[index - 1] === "--repo") && argument !== candidate;
+        });
+        const knownCommands = new Set([
+            "init",
+            "configure",
+            "agent-hooks",
+            "agent-event",
+            "index",
+            "doctor",
+            "status",
+            "wait",
+            "repair",
+            "serve",
+            "context",
+            "explain",
+            "review",
+            "map",
+            "search",
+            "query",
+            "rename",
+            "wiki",
+            "visualize",
+            "pack",
+            "compress",
+            "prs",
+            "worktrees",
+            "telemetry",
+            "diagnostics",
+            "system",
+            "repos",
+            "remote",
+            "update",
+        ]);
+        const diagnostic = recordDiagnosticFailure(candidate, {
+            surface: "cli",
+            operation: command && knownCommands.has(command) ? command : "unknown",
+            phase: "dispatch",
+            error: err,
+        });
+        const correlation = diagnostic.recorded ? ` [diagnostic ${diagnostic.correlationId}]` : "";
+        console.error(`${err instanceof Error ? err.message : String(err)}${correlation}`);
+        process.exit(1);
+    }
 }

package/dist/src/agent-events.js

@@ -0,0 +1,128 @@
+import fs from "node:fs";
+import path from "node:path";
+import { countOutputTokens } from "./output-telemetry.js";
+import { appendSessionEvent, } from "./session-telemetry.js";
+export const SESSION_CONTEXT_BUDGET_LINE = "Budget: at most 600 tokens, 8 KiB, 12 items.";
+const KNOWN_OPERATIONS = new Set([
+    "context",
+    "explain",
+    "review",
+    "map",
+    "search",
+    "query",
+    "pack",
+    "compress",
+    "execute",
+    "prs",
+    "wiki",
+    "docs",
+    "remote",
+]);
+function knownOperation(value) {
+    return typeof value === "string" && KNOWN_OPERATIONS.has(value) ? value : undefined;
+}
+export function parseClaudeHookPayload(raw) {
+    if (Buffer.byteLength(raw) > 65_536)
+        throw new Error("knodin agent-event: hook input exceeds 65536 bytes");
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        throw new Error("knodin agent-event: hook input must be a JSON object");
+    return parsed;
+}
+export function classifyTool(payload) {
+    const name = payload.tool_name ?? "";
+    if (name === "mcp__knodin__knodin") {
+        const operation = knownOperation(payload.tool_input?.operation);
+        return {
+            toolCategory: "knodin",
+            ...(operation ? { operation } : {}),
+        };
+    }
+    if (["Read", "Glob", "Grep"].includes(name))
+        return { toolCategory: "manual_traversal" };
+    if (["Edit", "Write", "NotebookEdit", "MultiEdit"].includes(name))
+        return { toolCategory: "edit" };
+    if (name === "Bash") {
+        const command = typeof payload.tool_input?.command === "string" ? payload.tool_input.command : "";
+        const knodin = command.match(/(?:^|[;&|]\s*)knodin\s+([a-z][a-z0-9-]*)/i);
+        if (knodin) {
+            const operation = knownOperation(knodin[1]?.toLowerCase());
+            return { toolCategory: "knodin", ...(operation ? { operation } : {}) };
+        }
+        if (/(?:^|[;&|]\s*)(?:rg|grep|find)\b/.test(command))
+            return { toolCategory: "manual_traversal" };
+    }
+    return { toolCategory: "other" };
+}
+function cachePath(repo) {
+    return path.join(repo, ".knodin", "session-context-cache.json");
+}
+export function readSessionContextCache(repo, key, now = Date.now()) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(cachePath(repo), "utf8"));
+        return parsed.key === key && typeof parsed.at === "number" && now - parsed.at <= 300_000
+            ? (parsed.text ?? null)
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function writeSessionContextCache(repo, key, text) {
+    const filePath = cachePath(repo);
+    fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
+    const temporary = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+    fs.writeFileSync(temporary, JSON.stringify({ schemaVersion: 1, key, at: Date.now(), text }), {
+        mode: 0o600,
+        flag: "wx",
+    });
+    fs.renameSync(temporary, filePath);
+}
+export function canUseSessionContextCache(status, freshness) {
+    return status === "healthy" && freshness === "fresh";
+}
+export function renderSessionContext(context, freshness) {
+    const list = (values, render) => (values ?? []).slice(0, 3).map(render).join(", ") || "none reported";
+    let text = [
+        "## knodin session context",
+        `Graph evidence: ${freshness}. Treat stale or unavailable evidence as incomplete.`,
+        SESSION_CONTEXT_BUDGET_LINE,
+        `Repository: ${context.stats?.files ?? "?"} files, ${context.stats?.symbols ?? "?"} symbols.`,
+        `Subsystems: ${list(context.communities, (value) => `${value.name} (${value.size})`)}`,
+        `Hubs: ${list(context.hubs, (value) => `${value.symbol} (${value.degree})`)}`,
+        `Flows: ${list(context.flows, (value) => value.symbol ?? "unnamed")}`,
+        `Suggested next operation: ${context.suggestedOperation ?? "context"} (heuristic only).`,
+        "Use exact source evidence and preserve ambiguity, freshness, omissions, and response budgets.",
+    ].join("\n");
+    while ((countOutputTokens(text) > 600 || Buffer.byteLength(text) > 8192) && text.includes("\n")) {
+        text = `${text.slice(0, text.lastIndexOf("\n"))}\nContext truncated to the configured session budget.`;
+    }
+    return text;
+}
+export function recordClaudeLifecycleEvent(repo, event, payload) {
+    const sessionId = payload.session_id;
+    if (!sessionId)
+        return false;
+    const names = {
+        "session-start": "session_start",
+        "session-end": "session_end",
+        "turn-start": "turn_start",
+        "turn-end": "turn_end",
+        "pre-tool": "tool_start",
+        "post-tool": "tool_success",
+        "tool-failure": "tool_failure",
+    };
+    const mapped = names[event];
+    if (!mapped)
+        return false;
+    const tool = event.includes("tool") ? classifyTool(payload) : undefined;
+    return appendSessionEvent(repo, { event: mapped, sessionId, ...tool });
+}
+export function sessionStartHookOutput(text) {
+    return {
+        hookSpecificOutput: {
+            hookEventName: "SessionStart",
+            additionalContext: text,
+        },
+    };
+}

package/dist/src/agent-hooks.js

@@ -0,0 +1,156 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+const OWNED_COMMAND = "knodin agent-event";
+function settingsPath(homeDir = os.homedir()) {
+    return path.join(homeDir, ".claude", "settings.json");
+}
+function assertNotSymlink(filePath) {
+    for (const candidate of [path.dirname(filePath), filePath]) {
+        try {
+            if (fs.lstatSync(candidate).isSymbolicLink())
+                throw new Error(`knodin agent-hooks: refusing symlinked path ${candidate}`);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+    }
+}
+function readSettings(filePath) {
+    if (!fs.existsSync(filePath))
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(filePath, "utf8"));
+    }
+    catch (error) {
+        throw new Error(`knodin agent-hooks: invalid Claude settings JSON: ${error.message}`);
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        throw new Error("knodin agent-hooks: Claude settings must contain a JSON object");
+    return parsed;
+}
+function atomicWrite(filePath, content) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
+    const temporary = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+    fs.writeFileSync(temporary, content, { encoding: "utf8", mode: 0o600, flag: "wx" });
+    fs.renameSync(temporary, filePath);
+}
+function ownedEntry(value) {
+    return JSON.stringify(value).includes(OWNED_COMMAND);
+}
+function removeOwned(document) {
+    const hooks = document.hooks;
+    if (!hooks || typeof hooks !== "object" || Array.isArray(hooks))
+        return;
+    const hookObject = hooks;
+    for (const [event, value] of Object.entries(hookObject)) {
+        if (!Array.isArray(value))
+            continue;
+        const retained = value.filter((entry) => !ownedEntry(entry));
+        if (retained.length === 0)
+            delete hookObject[event];
+        else
+            hookObject[event] = retained;
+    }
+    if (Object.keys(hookObject).length === 0)
+        delete document.hooks;
+}
+function hook(command, event, matcher) {
+    return {
+        ...(matcher ? { matcher } : {}),
+        hooks: [
+            {
+                type: "command",
+                command: `${command} agent-event ${event}`,
+                timeout: 5,
+            },
+        ],
+    };
+}
+function managedHooks(command) {
+    const observed = "mcp__knodin__knodin|Bash|Read|Glob|Grep|Edit|Write|NotebookEdit";
+    return {
+        SessionStart: [hook(command, "session-start", "startup|resume|clear|compact")],
+        UserPromptSubmit: [hook(command, "turn-start")],
+        PreToolUse: [hook(command, "pre-tool", observed)],
+        PostToolUse: [hook(command, "post-tool", observed)],
+        PostToolUseFailure: [hook(command, "tool-failure", observed)],
+        Stop: [hook(command, "turn-end")],
+        SessionEnd: [hook(command, "session-end")],
+    };
+}
+function mergedSettings(existing, command) {
+    const document = structuredClone(existing);
+    removeOwned(document);
+    const hooks = document.hooks && typeof document.hooks === "object" && !Array.isArray(document.hooks)
+        ? document.hooks
+        : {};
+    for (const [event, entries] of Object.entries(managedHooks(command))) {
+        const current = Array.isArray(hooks[event]) ? hooks[event] : [];
+        hooks[event] = [...current, ...entries];
+    }
+    document.hooks = hooks;
+    return document;
+}
+export function inspectClaudeAgentHooks(options = {}) {
+    const filePath = settingsPath(options.homeDir);
+    assertNotSymlink(filePath);
+    const document = readSettings(filePath);
+    const serialized = JSON.stringify(document);
+    const count = serialized.split(OWNED_COMMAND).length - 1;
+    return {
+        schemaVersion: 1,
+        client: "claude",
+        settingsPath: filePath,
+        installed: count > 0,
+        managedEntries: count,
+    };
+}
+export function installClaudeAgentHooks(options = {}) {
+    const filePath = settingsPath(options.homeDir);
+    assertNotSymlink(filePath);
+    const before = readSettings(filePath);
+    const after = mergedSettings(before, options.command ?? "knodin");
+    const beforeText = `${JSON.stringify(before, null, 2)}\n`;
+    const afterText = `${JSON.stringify(after, null, 2)}\n`;
+    const changed = beforeText !== afterText;
+    if (changed && !options.dryRun) {
+        if (fs.existsSync(filePath)) {
+            const backup = `${filePath}.knodin-backup`;
+            if (!fs.existsSync(backup))
+                fs.copyFileSync(filePath, backup, fs.constants.COPYFILE_EXCL);
+        }
+        atomicWrite(filePath, afterText);
+    }
+    return {
+        schemaVersion: 1,
+        client: "claude",
+        settingsPath: filePath,
+        changed,
+        dryRun: options.dryRun === true,
+        managedEntries: Object.keys(managedHooks(options.command ?? "knodin")).length,
+    };
+}
+export function uninstallClaudeAgentHooks(options = {}) {
+    const filePath = settingsPath(options.homeDir);
+    assertNotSymlink(filePath);
+    if (!fs.existsSync(filePath))
+        return { removed: false, settingsPath: filePath };
+    const document = readSettings(filePath);
+    const hadOwned = ownedEntry(document);
+    removeOwned(document);
+    if (hadOwned) {
+        if (Object.keys(document).length === 0)
+            fs.unlinkSync(filePath);
+        else
+            atomicWrite(filePath, `${JSON.stringify(document, null, 2)}\n`);
+    }
+    return {
+        schemaVersion: 1,
+        client: "claude",
+        removed: hadOwned,
+        settingsPath: filePath,
+    };
+}

package/dist/src/cli-model.js

@@ -251,6 +251,14 @@ function createCliProgram(capture = () => { }) {
     leaf(program, "serve", "run the one-tool MCP gateway on stdio", capture);
     leaf(program, "version", "print the installed knodin version", capture);
     leaf(program, "hook-refresh <kind> [values...]", "internal Git lifecycle refresh", capture);
+    const agentHooks = program
+        .command("agent-hooks")
+        .description("manage optional user-global coding-agent lifecycle hooks");
+    for (const action of ["install", "status", "uninstall"])
+        leaf(agentHooks, action, `${action} optional coding-agent hooks`, capture)
+            .option("--client <client>", "coding-agent client; currently claude")
+            .option("--dry-run", "preview settings changes without writing");
+    leaf(program, "agent-event <event>", "internal coding-agent lifecycle event", capture);
     leaf(program, "refresh-artifacts [event]", "refresh external graph artifacts", capture);
     addRepositoryCommands(program, capture);
     addRemoteCommands(program, capture);
@@ -283,7 +291,14 @@ function createCliProgram(capture = () => { }) {
         .command("telemetry")
         .description("manage local opt-in ROI telemetry")
         .allowExcessArguments(false)
-        .addArgument(new Argument("<action>").choices(["status", "report", "export", "clear"]));
+        .addArgument(new Argument("<action>").choices([
+        "enable",
+        "disable",
+        "status",
+        "report",
+        "export",
+        "clear",
+    ]));
     telemetry
         .option("--input <path>", "telemetry input path")
         .option("--output <path>", "dashboard or evidence-bundle output path")

package/dist/src/output-telemetry.js

@@ -4,6 +4,7 @@ import path from "node:path";
 import { encode } from "gpt-tokenizer/encoding/o200k_base";
 import { compareBytes } from "./compare.js";
 import { resolveDbPath } from "./engine/state-paths.js";
+import { summarizeAdoption } from "./session-telemetry.js";
 export const TELEMETRY_TOKENIZER = "gpt-tokenizer@3.4.0:o200k_base";
 export const countOutputTokens = (value) => encode(value).length;
 export const DEFAULT_TELEMETRY_RETENTION_DAYS = 30;
@@ -182,7 +183,7 @@ function telemetrySummary(records) {
         indexingMs: records.reduce((sum, record) => sum + (record.indexingMs ?? 0), 0),
     };
 }
-export function writeTelemetryReport(repoPath, records, outputPath = ".knodin/telemetry-report.html") {
+export function writeTelemetryReport(repoPath, records, outputPath = ".knodin/telemetry-report.html", sessionEvents = []) {
     const { repo, target: output } = privatePath(repoPath, outputPath, "report");
     const groups = new Map();
     for (const record of records) {
@@ -201,6 +202,7 @@ export function writeTelemetryReport(repoPath, records, outputPath = ".knodin/te
     })
         .join("");
     const summary = telemetrySummary(records);
+    const adoption = summarizeAdoption(sessionEvents);
     const timeSeries = new Map();
     for (const record of records) {
         const day = typeof record.at === "string" ? record.at.slice(0, 10) : "unknown";
@@ -221,12 +223,13 @@ export function writeTelemetryReport(repoPath, records, outputPath = ".knodin/te
         .sort(([left], [right]) => compareBytes(left, right))
         .map(([id, calls]) => `<tr><td>${escapeHtml(id)}</td><td>${calls}</td></tr>`)
         .join("");
-    const html = `<!doctype html><meta charset="utf-8"><meta name="color-scheme" content="light dark"><title>knodin telemetry</title><style>:root{color-scheme:light dark;--line:#d0d7de;--card:#f6f8fa}body{font:14px system-ui;margin:2rem;max-width:76rem}section{background:var(--card);padding:1rem;margin:1rem 0;border-radius:.5rem}table{border-collapse:collapse;width:100%}th,td{padding:.55rem;border-bottom:1px solid var(--line);text-align:left}@media(prefers-color-scheme:dark){:root{--line:#30363d;--card:#161b22}}</style><h1>knodin local telemetry</h1><p>Tokenizer: ${TELEMETRY_TOKENIZER}. Local, opt-in, metadata-only; source, raw output, command text, usernames, and paths are not persisted.</p><section><h2>Summary</h2><p>Total measured tokens avoided: ${summary.measuredTokensAvoided}</p><p>Calls: ${summary.calls}; successes: ${summary.successes}; errors: ${summary.errors}; measured baselines: ${summary.measuredBaselines}</p><p>Latency p50 / p95: ${summary.latencyP50Ms} / ${summary.latencyP95Ms} ms</p><p>Freshness failures: ${summary.freshnessFailures}; compression fidelity samples / p50: ${summary.compressionFidelitySamples} / ${summary.compressionFidelityP50}; indexing time: ${summary.indexingMs} ms; index storage: ${summary.indexStorageBytes} bytes</p></section><section><h2>Operation breakdown</h2><table><thead><tr><th>Operation</th><th>Calls</th><th>Errors</th><th>Measured baselines</th><th>Net tokens saved</th><th>p50 ms</th><th>p95 ms</th></tr></thead><tbody>${rows}</tbody></table></section><section><h2>Time series</h2><table><thead><tr><th>Day</th><th>Calls</th><th>Tokens avoided</th></tr></thead><tbody>${seriesRows}</tbody></table></section><section><h2>Repository breakdown</h2><table><thead><tr><th>Private repository id</th><th>Calls</th></tr></thead><tbody>${repositoryRows}</tbody></table></section><p>Use <code>knodin telemetry export</code> for the machine-readable evidence bundle and <code>knodin telemetry clear</code> to delete persisted records.</p>`;
+    const html = `<!doctype html><meta charset="utf-8"><meta name="color-scheme" content="light dark"><title>knodin telemetry</title><style>:root{color-scheme:light dark;--line:#d0d7de;--card:#f6f8fa}body{font:14px system-ui;margin:2rem;max-width:76rem}section{background:var(--card);padding:1rem;margin:1rem 0;border-radius:.5rem}table{border-collapse:collapse;width:100%}th,td{padding:.55rem;border-bottom:1px solid var(--line);text-align:left}@media(prefers-color-scheme:dark){:root{--line:#30363d;--card:#161b22}}</style><h1>knodin local telemetry</h1><p>Tokenizer: ${TELEMETRY_TOKENIZER}. Local, opt-in, metadata-only; source, raw output, command text, prompts, usernames, and paths are not persisted.</p><section><h2>Summary</h2><p>Total measured tokens avoided: ${summary.measuredTokensAvoided}</p><p>Calls: ${summary.calls}; successes: ${summary.successes}; errors: ${summary.errors}; measured baselines: ${summary.measuredBaselines}</p><p>Latency p50 / p95: ${summary.latencyP50Ms} / ${summary.latencyP95Ms} ms</p><p>Freshness failures: ${summary.freshnessFailures}; compression fidelity samples / p50: ${summary.compressionFidelitySamples} / ${summary.compressionFidelityP50}; indexing time: ${summary.indexingMs} ms; index storage: ${summary.indexStorageBytes} bytes</p></section><section><h2>Adoption evidence</h2><p>Sessions: ${adoption.sessions}; context delivered / degraded: ${adoption.contextDelivered} / ${adoption.contextDegraded}; sessions using knodin: ${adoption.knodinSessions}; observed turns: ${adoption.turns}</p><p>Fallback traversal after knodin: ${adoption.fallbackTraversalAfterKnodin}; edits preceded by knodin evidence in the same turn: ${adoption.evidenceBeforeEdit}</p><p>Corrective round trips: unavailable. Ordinary hook events do not prove why a follow-up occurred.</p></section><section><h2>Operation breakdown</h2><table><thead><tr><th>Operation</th><th>Calls</th><th>Errors</th><th>Measured baselines</th><th>Net tokens saved</th><th>p50 ms</th><th>p95 ms</th></tr></thead><tbody>${rows}</tbody></table></section><section><h2>Time series</h2><table><thead><tr><th>Day</th><th>Calls</th><th>Tokens avoided</th></tr></thead><tbody>${seriesRows}</tbody></table></section><section><h2>Repository breakdown</h2><table><thead><tr><th>Private repository id</th><th>Calls</th></tr></thead><tbody>${repositoryRows}</tbody></table></section><p>Use <code>knodin telemetry export</code> for the machine-readable evidence bundle and <code>knodin telemetry clear</code> to delete persisted records.</p>`;
     atomicPrivateWrite(output, html);
     return {
         outputPath: path.relative(repo, output),
         records: records.length,
         operations: groups.size,
+        sessionEvents: sessionEvents.length,
     };
 }
 function sanitizeTelemetryRecord(record) {
@@ -335,7 +338,7 @@ export function telemetryStatus(repoPath, inputPath = DEFAULT_INPUT, retentionDa
         tokenizer: TELEMETRY_TOKENIZER,
     };
 }
-export function exportTelemetry(repoPath, records, outputPath = ".knodin/telemetry-export.json") {
+export function exportTelemetry(repoPath, records, outputPath = ".knodin/telemetry-export.json", sessionEvents = []) {
     const { repo, target } = privatePath(repoPath, outputPath, "export");
     const bundle = {
         schemaVersion: 1,
@@ -349,6 +352,8 @@ export function exportTelemetry(repoPath, records, outputPath = ".knodin/telemet
         },
         summary: telemetrySummary(records),
         records,
+        adoption: summarizeAdoption(sessionEvents),
+        sessionEvents,
     };
     atomicPrivateWrite(target, `${JSON.stringify(bundle, null, 2)}\n`);
     return {

package/dist/src/session-telemetry.js

@@ -0,0 +1,163 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+const CONFIG = ".knodin/telemetry-config.json";
+const EVENTS = ".knodin/session-events.jsonl";
+const KEY = ".knodin/telemetry-key";
+function target(repo, relative) {
+    const root = fs.realpathSync(repo);
+    const value = path.resolve(root, relative);
+    if (!value.startsWith(`${root}${path.sep}`))
+        throw new Error("knodin telemetry path escaped repository");
+    let candidate = root;
+    for (const segment of path.relative(root, value).split(path.sep)) {
+        candidate = path.join(candidate, segment);
+        try {
+            if (fs.lstatSync(candidate).isSymbolicLink())
+                throw new Error("knodin telemetry refuses symlinks");
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+    }
+    return value;
+}
+function atomic(filePath, value) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
+    const temporary = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+    fs.writeFileSync(temporary, value, { mode: 0o600, flag: "wx" });
+    fs.renameSync(temporary, filePath);
+}
+function enabled(repo) {
+    try {
+        return JSON.parse(fs.readFileSync(target(repo, CONFIG), "utf8")).enabled === true;
+    }
+    catch {
+        return false;
+    }
+}
+export function enableSessionTelemetry(repo) {
+    atomic(target(repo, CONFIG), `${JSON.stringify({ schemaVersion: 1, enabled: true })}\n`);
+    const key = target(repo, KEY);
+    if (!fs.existsSync(key))
+        atomic(key, crypto.randomBytes(32).toString("hex"));
+    return { schemaVersion: 1, enabled: true, localOnly: true };
+}
+export function disableSessionTelemetry(repo) {
+    atomic(target(repo, CONFIG), `${JSON.stringify({ schemaVersion: 1, enabled: false })}\n`);
+    return { schemaVersion: 1, enabled: false, retained: readSessionEvents(repo).length };
+}
+function sessionHash(repo, sessionId) {
+    const secret = fs.readFileSync(target(repo, KEY), "utf8").trim();
+    return `session_${crypto.createHmac("sha256", secret).update(sessionId).digest("hex").slice(0, 20)}`;
+}
+export function appendSessionEvent(repo, input) {
+    if (!enabled(repo))
+        return false;
+    if (!input.sessionId || input.sessionId.length > 256)
+        return false;
+    const record = {
+        schemaVersion: 1,
+        event: input.event,
+        session: sessionHash(repo, input.sessionId),
+        at: input.at ?? new Date().toISOString(),
+        client: input.client ?? "claude",
+        ...(input.context ? { context: input.context } : {}),
+        ...(input.toolCategory ? { toolCategory: input.toolCategory } : {}),
+        ...(input.operation && /^[a-z][a-z0-9_-]{0,63}$/.test(input.operation)
+            ? { operation: input.operation }
+            : {}),
+        ...(input.freshness ? { freshness: input.freshness } : {}),
+        ...(typeof input.latencyMs === "number" ? { latencyMs: input.latencyMs } : {}),
+        ...(typeof input.cacheHit === "boolean" ? { cacheHit: input.cacheHit } : {}),
+    };
+    const filePath = target(repo, EVENTS);
+    fs.appendFileSync(filePath, `${JSON.stringify(record)}\n`, { encoding: "utf8", mode: 0o600 });
+    return true;
+}
+export function readSessionEvents(repo, retentionDays, now = new Date()) {
+    const filePath = target(repo, EVENTS);
+    if (!fs.existsSync(filePath))
+        return [];
+    const cutoff = retentionDays === undefined ? undefined : now.getTime() - retentionDays * 24 * 60 * 60 * 1000;
+    return fs
+        .readFileSync(filePath, "utf8")
+        .split(/\r?\n/)
+        .filter(Boolean)
+        .flatMap((line) => {
+        try {
+            const value = JSON.parse(line);
+            if (value.schemaVersion !== 1 || typeof value.session !== "string")
+                return [];
+            if (cutoff !== undefined) {
+                const timestamp = typeof value.at === "string" ? Date.parse(value.at) : Number.NaN;
+                if (!Number.isFinite(timestamp) || timestamp < cutoff)
+                    return [];
+            }
+            return [value];
+        }
+        catch {
+            return [];
+        }
+    });
+}
+export function summarizeAdoption(events) {
+    const sessions = new Set(events.map(({ session }) => session));
+    const evidenceOperations = new Set(["context", "explain", "review", "map", "search", "query"]);
+    const knodinSessions = new Set(events
+        .filter(({ event, toolCategory, operation }) => event === "tool_success" &&
+        toolCategory === "knodin" &&
+        operation !== undefined &&
+        evidenceOperations.has(operation))
+        .map(({ session }) => session));
+    let fallbackTraversalAfterKnodin = 0;
+    let evidenceBeforeEdit = 0;
+    const seenKnodin = new Set();
+    for (const event of events) {
+        if (event.event === "turn_start")
+            seenKnodin.delete(event.session);
+        if (event.toolCategory === "knodin" &&
+            event.event === "tool_success" &&
+            event.operation !== undefined &&
+            evidenceOperations.has(event.operation))
+            seenKnodin.add(event.session);
+        if (event.event === "tool_success" &&
+            event.toolCategory === "manual_traversal" &&
+            seenKnodin.has(event.session))
+            fallbackTraversalAfterKnodin += 1;
+        if (event.event === "tool_success" &&
+            event.toolCategory === "edit" &&
+            seenKnodin.has(event.session))
+            evidenceBeforeEdit += 1;
+        if (event.event === "turn_end")
+            seenKnodin.delete(event.session);
+    }
+    return {
+        sessions: sessions.size,
+        contextDelivered: events.filter(({ event, context }) => event === "session_start" && context === "delivered").length,
+        contextDegraded: events.filter(({ event, context }) => event === "session_start" && context === "degraded").length,
+        knodinSessions: knodinSessions.size,
+        turns: events.filter(({ event }) => event === "turn_start").length,
+        fallbackTraversalAfterKnodin,
+        evidenceBeforeEdit,
+        correctiveRoundTrips: null,
+    };
+}
+export function sessionTelemetryStatus(repo, retentionDays) {
+    const records = readSessionEvents(repo, retentionDays);
+    return {
+        schemaVersion: 1,
+        enabled: enabled(repo),
+        localOnly: true,
+        records: records.length,
+        adoption: summarizeAdoption(records),
+    };
+}
+export function clearSessionTelemetry(repo) {
+    const filePath = target(repo, EVENTS);
+    const records = readSessionEvents(repo).length;
+    const bytes = fs.existsSync(filePath) ? fs.statSync(filePath).size : 0;
+    fs.rmSync(filePath, { force: true });
+    return { removed: bytes > 0, records, bytes };
+}

package/docs/CLI.md

@@ -32,6 +32,23 @@ example repository existence, mutually exclusive configuration modes, and
 graph-query target rules), but syntax cannot reach a handler unless the shared
 declarative model accepts it first.
 
+Optional Claude lifecycle integration is explicit and user-global:
+
+```bash
+knodin agent-hooks install --client claude --dry-run
+knodin agent-hooks install --client claude
+knodin agent-hooks status --client claude
+knodin agent-hooks uninstall --client claude
+```
+
+Installation atomically merges knodin-owned `SessionStart`, turn, tool, and
+session-end handlers into the user's Claude settings. It preserves unrelated
+settings and hooks, including aidev-track, and uninstall removes only exact
+knodin entries. SessionStart emits at most 600 tokens, 8 KiB, and 12 bounded
+orientation items. Hooks fail open and no-op outside initialized repositories.
+The internal `agent-event` command is machine-facing and consumes bounded JSON
+from stdin; it is not a general event-ingestion API.
+
 `knodin query resource_reachability --limit 100` runs cached, on-demand static
 TS/JS source-to-sink analysis. It covers literal `process.env` and
 `fs.readFileSync` reads reaching `console.log`, `fetch`, or `db.query` through

package/docs/INSTALLATION.md

@@ -205,6 +205,17 @@ idempotent. Local fixtures use zero hosted spend, no credentials, and no source
 egress. Diagnostic archives remain governed by the privacy-safe preview and
 archive contract in [`DIAGNOSTICS.md`](DIAGNOSTICS.md).
 
+Claude users may explicitly install one user-global lifecycle adapter after
+previewing its settings merge:
+
+```bash
+knodin agent-hooks install --client claude --dry-run
+knodin agent-hooks install --client claude
+```
+
+This is independent of `knodin init` and telemetry persistence. Remove only
+knodin-owned entries with `knodin agent-hooks uninstall --client claude`.
+
 Upgrade with the manager that owns the executable:
 
 ```bash

package/docs/TELEMETRY.md

@@ -25,13 +25,31 @@ knodin telemetry export
 knodin telemetry clear
 ```
 
+Claude adoption evidence is an independent repository-local opt-in:
+
+```text
+knodin telemetry enable
+knodin telemetry disable
+```
+
+When enabled and the optional Claude hooks are installed, knodin records HMAC'd
+session identity, lifecycle event kind, turn boundaries, coarse tool category,
+supported knodin operation, freshness, context delivery, cache state, and
+latency. It never persists prompts, transcript paths, source, raw tool input or
+output, shell command text, usernames, or absolute paths. Disable stops new
+session events without deleting retained history; `clear` removes both
+operation and session event stores.
+
 `--retention-days 1..3650` changes the read/persistence window. `--input` and
 `--output` accept only repository-contained, non-symlink paths. `clear` is the
 only command that deletes the private JSONL file; report and export never do.
 
 The default report is `.knodin/telemetry-report.html`. It includes summary,
 operation, time-series, private repository, indexing-cost, latency, freshness,
-and fidelity views with light/dark styling. The default machine-readable export
+fidelity, session adoption, evidence-before-edit, and observed fallback-traversal
+views with light/dark styling. Ordinary hooks cannot establish why a follow-up
+occurred, so corrective round trips and task success remain unavailable unless
+supplied by a controlled outcome replay. The default machine-readable export
 is `.knodin/telemetry-export.json` and labels measured, modeled, and unknown
 baselines explicitly. Neither artifact needs a daemon, hosted service,
 authentication, or source egress.

package/docs/releases/0.8.4.md

@@ -0,0 +1,22 @@
+# knodin 0.8.4
+
+This release adds optional, bounded coding-session orientation and local
+adoption evidence while preserving knodin's freshness and privacy boundaries.
+
+- Adds an explicit, idempotent Claude hook installer for compact SessionStart
+  context. Injection is limited to 600 tokens, 8 KiB, and 12 items, reports its
+  bounds, rejects stale cached evidence, and fails open outside initialized
+  repositories.
+- Adds opt-in, repository-local session telemetry and an adoption dashboard for
+  delivered context, successful graph-evidence operations, fallback traversal,
+  and evidence-before-edit observations.
+- Persists only coarse allowlisted metadata and locally keyed session hashes;
+  prompts, source, raw tool input, commands, paths, and unhashed session IDs are
+  not retained.
+- Keeps corrective round trips explicitly unavailable because ordinary hook
+  events cannot establish why an agent made a follow-up call or prove a causal
+  productivity improvement.
+- Adds C102's preregistered paired-evaluation design so future outcome claims
+  require replay evidence rather than being inferred from adoption counters.
+
+This remains an ordinary 0.x release, not a dogfood-only build and not GA.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "knodin",
-	"version": "0.8.3",
+	"version": "0.8.4",
 	"description": "knodin — source-evidenced local code intelligence with known bounds. Stable identity, fresh evidence, truthful budgets, and recoverable bounded views.",
 	"license": "MIT",
 	"repository": {
@@ -59,6 +59,7 @@
 		"docs/releases/0.8.0.md",
 		"docs/releases/0.8.2.md",
 		"docs/releases/0.8.3.md",
+		"docs/releases/0.8.4.md",
 		"docs/assets/knodin-favicon.svg",
 		"docs/SYSTEMS-AND-RELATIONSHIPS.md",
 		"docs/TELEMETRY.md",

package/roadmap/competitive-roadmap.md

@@ -137,6 +137,7 @@ new items or strengthen existing ones; they do not reopen the archived roadmap.
 | C99 | P1 | implemented | Resolve bounded TypeScript dependency-injection wiring | C2, C3, C24, C95 |
 | C100 | P1 | implemented | Prove bounded Salesforce Flow-to-Apex paths | C2, C3, C20, C23, C95, C96 |
 | C101 | P1 | implemented | Strengthen contract-led positioning | C95, C97, C98, C99, C100 |
+| C102 | P1 | implemented — opt-in observational evidence only | Add bounded Claude session context and adoption evidence | C3, C16, C61, C93, C95 |
 
 ### C98 — Bounded source-to-sink resource reachability
 
@@ -192,6 +193,25 @@ new items or strengthen existing ones; they do not reopen the archived roadmap.
   commits normally form one reasonably sized shared PR; assistants do not
   auto-open per-item PRs, and unrelated changes are not bundled for size.
 
+### C102 — Bounded Claude session context and adoption evidence
+
+- Status: implemented — opt-in observational evidence only
+- Priority: P1
+- DependsOn: C3, C16, C61, C93, C95
+- Evidence: `src/agent-hooks.ts`, `src/agent-events.ts`,
+  `src/session-telemetry.ts`, focused unit/CLI tests, and
+  `benchmarks/evaluations/c102-session-adoption/README.md`.
+- Implementation: an explicit user-global Claude hook installer atomically
+  preserves unrelated settings and supports status, dry-run, and targeted
+  uninstall. SessionStart injects cached, freshness-aware orientation under
+  600 tokens, 8 KiB, and 12 items. Separate repository-local telemetry opt-in
+  records private lifecycle categories and extends the existing local report.
+- Bounds: ordinary hooks prove neither task success nor why a follow-up turn
+  occurred. The dashboard labels corrective round trips unavailable, stores no
+  prompt/source/command/transcript/tool-output bodies, and authorizes no
+  productivity or superiority claim. Claude is the only supported client for
+  this adapter; the event model remains client-neutral for later evaluation.
+
 ## Roadmap completion contract
 
 This section is the control plane for completing this roadmap with a persistent