@nurix/nustack 0.23.17 → 0.23.18

package/dist/commands/lane.js

@@ -0,0 +1,70 @@
+import os from "node:os";
+import { printJsonSuccess } from "../lib/json_output.js";
+import { decideFromFacts, LANE_SENTENCES, readLaneFacts, SUBAGENT_MODEL_OVERRIDES_ROUTE } from "../lib/lane/decide.js";
+import { haikuSentence } from "../lib/lane/mainModel.js";
+import { installLane, LANE_AGENT_ROUTE, laneHooksInstalled, removeLane } from "../lib/lane/install.js";
+function enableBlockersOf(facts) {
+    const blockers = [];
+    if (facts.mainModel.haikuClass && facts.mainModel.scope === "user") {
+        blockers.push({ code: "haiku-main-model", sentence: haikuSentence(facts.mainModel) });
+    }
+    if (SUBAGENT_MODEL_OVERRIDES_ROUTE && facts.subagentModel !== null)
+        blockers.push({ code: "subagent-model-override", sentence: LANE_SENTENCES["subagent-model-override"] });
+    return blockers;
+}
+function factsFor(cwd, interactive) {
+    return readLaneFacts({ env: process.env, cwd: cwd ?? process.cwd(), interactive, home: os.homedir() });
+}
+export function runLaneEnv(options) {
+    const decision = decideFromFacts(factsFor(options.cwd, options.nonInteractive !== true));
+    if (decision.state === "on") {
+        process.stdout.write(`ANTHROPIC_BASE_URL=${decision.baseUrl}\n`);
+        return;
+    }
+    if (decision.reason !== "unreleased" && decision.reason !== "switch-off") {
+        process.stderr.write(`NuStack lane off: ${decision.sentence}\n`);
+    }
+}
+export async function readLaneStatus(cwd, interactive) {
+    const facts = factsFor(cwd, interactive);
+    const decision = decideFromFacts(facts);
+    return {
+        released: facts.released,
+        switch: facts.switchOn,
+        proxy: facts.proxy.record === null ? null : { live: facts.proxy.live, port: facts.proxy.record.port },
+        credential: facts.credential.state === "on" ? facts.credential.credential : null,
+        mainModel: { value: facts.mainModel.value, source: facts.mainModel.source, haikuClass: facts.mainModel.haikuClass },
+        upstream: facts.upstream.state === "ok" ? facts.upstream.url : null,
+        routeMode: LANE_AGENT_ROUTE,
+        hooks: await laneHooksInstalled(),
+        decision: decision.state === "on"
+            ? { state: "on", reason: null, sentence: null }
+            : { state: "off", reason: decision.reason, sentence: decision.sentence },
+        enableBlockers: enableBlockersOf(facts),
+    };
+}
+export async function runLaneStatus(options) {
+    const status = await readLaneStatus(options.cwd, false);
+    if (options.json) {
+        printJsonSuccess("lane status", status);
+        return;
+    }
+    const lines = [
+        `Released: ${status.released ? "yes" : "no"} · Switch: ${status.switch ? "on" : "off"}`,
+        `Proxy: ${status.proxy === null ? "no record" : `${status.proxy.live ? "running" : "stopped"} on 127.0.0.1:${status.proxy.port}`}`,
+        `Credential: ${status.credential ?? "none the lane carries"} · Upstream: ${status.upstream ?? "refused"}`,
+        `Main model: ${status.mainModel.value ?? "Claude Code's default"}${status.mainModel.source ? ` (from ${status.mainModel.source})` : ""}`,
+        `Route mode: ${status.routeMode} · Hooks: Agent ${status.hooks.agent ? "installed" : "not installed"}, SubagentStop ${status.hooks.subagentStop ? "installed" : "not installed"}`,
+        `Decision: ${status.decision.state}${status.decision.reason ? ` (${status.decision.reason}): ${status.decision.sentence}` : ""}`,
+        ...status.enableBlockers.map((blocker) => `Blocks enabling: ${blocker.sentence}`),
+    ];
+    console.log(lines.join("\n"));
+}
+export async function runLaneInstall() {
+    const { changed } = await installLane();
+    console.log(changed ? "Installed the light-model lane's Agent and SubagentStop hooks." : "Installed the light-model lane's Agent and SubagentStop hooks (already installed — no change).");
+}
+export async function runLaneRemove() {
+    const { removed } = await removeLane();
+    console.log(removed ? "Removed the light-model lane's hooks." : "Removed the light-model lane's hooks (already absent — no change).");
+}

package/dist/lib/desktop_settings.js

@@ -17,7 +17,7 @@ function sectionOf(value) {
 export function readDesktopSettings() {
     const defaults = {
         placement: { memory: DEFAULT_PLACEMENT, securityFindings: DEFAULT_PLACEMENT },
-        routing: { localReader: false, gateThresholdTokens: null, digestBudgetMs: null },
+        routing: { localReader: false, gateThresholdTokens: null, digestBudgetMs: null, lane: false },
     };
     let parsed;
     try {
@@ -39,6 +39,7 @@ export function readDesktopSettings() {
             localReader: routing.localReader === true,
             gateThresholdTokens: boundedIntegerOf(routing.gateThresholdTokens, GATE_THRESHOLD_TOKENS_MIN, GATE_THRESHOLD_TOKENS_MAX),
             digestBudgetMs: boundedIntegerOf(routing.digestBudgetMs, DIGEST_BUDGET_MS_MIN, DIGEST_BUDGET_MS_MAX),
+            lane: routing.lane === true,
         },
     };
 }

package/dist/lib/gate/agentHook.js

@@ -0,0 +1,130 @@
+import { readdirSync, readFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { readDesktopSettings } from "../desktop_settings.js";
+import { readSettingsLayers } from "../lane/credential.js";
+import { LANE_AGENT_NAME, LANE_AGENT_ROUTE, LANE_MODEL_ID } from "../lane/install.js";
+import { isUnderPrefix, readProxy } from "../lane/proxyRecord.js";
+import { GateInputError } from "./readGate.js";
+export const READ_ONLY_TOOLS = new Set(["Read", "Grep", "Glob", "LS", "NotebookRead"]);
+export const PASS_ON_AGENT_PERMISSION_RULE = true;
+function parseAgentCall(text) {
+    let payload;
+    try {
+        payload = JSON.parse(text);
+    }
+    catch {
+        throw new GateInputError("stdin is not JSON");
+    }
+    if (payload === null || typeof payload !== "object" || Array.isArray(payload))
+        throw new GateInputError("stdin is not a JSON object");
+    const fields = payload;
+    if (typeof fields.session_id !== "string" || fields.session_id === "")
+        throw new GateInputError("session_id is missing");
+    if (typeof fields.cwd !== "string" || fields.cwd === "")
+        throw new GateInputError("cwd is missing");
+    const toolInput = fields.tool_input;
+    if (toolInput === null || typeof toolInput !== "object" || Array.isArray(toolInput))
+        throw new GateInputError("tool_input is missing");
+    return { sessionId: fields.session_id, cwd: fields.cwd, toolInput: toolInput };
+}
+function frontmatterOf(content) {
+    const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(content);
+    return match ? match[1] : null;
+}
+export function declaredTools(frontmatter) {
+    const lines = frontmatter.split(/\r?\n/);
+    const index = lines.findIndex((line) => /^tools\s*:/.test(line));
+    if (index === -1)
+        return null;
+    const inline = lines[index].replace(/^tools\s*:/, "").trim();
+    let items;
+    if (inline !== "") {
+        items = inline.replace(/^\[|\]$/g, "").split(",");
+    }
+    else {
+        items = [];
+        for (const line of lines.slice(index + 1)) {
+            const item = /^\s*-\s*(.+)$/.exec(line);
+            if (!item)
+                break;
+            items.push(item[1]);
+        }
+    }
+    const tools = items.map((item) => item.trim().replace(/^["']|["']$/g, "")).filter((item) => item !== "");
+    return tools.length === 0 ? null : tools;
+}
+function nameOf(frontmatter) {
+    const match = /^name\s*:\s*(.+)$/m.exec(frontmatter);
+    return match ? match[1].trim().replace(/^["']|["']$/g, "") : null;
+}
+export function isReadOnlyDefinition(type, cwd, home) {
+    for (const folder of [path.join(cwd, ".claude", "agents"), path.join(home, ".claude", "agents")]) {
+        let entries;
+        try {
+            entries = readdirSync(folder).filter((entry) => entry.endsWith(".md"));
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            let content;
+            try {
+                content = readFileSync(path.join(folder, entry), "utf8");
+            }
+            catch {
+                continue;
+            }
+            const frontmatter = frontmatterOf(content);
+            if (frontmatter === null || nameOf(frontmatter) !== type)
+                continue;
+            const tools = declaredTools(frontmatter);
+            return tools !== null && tools.every((tool) => READ_ONLY_TOOLS.has(tool));
+        }
+    }
+    return false;
+}
+export function hasAgentPermissionRule(layers) {
+    return layers.some((layer) => ["allow", "ask", "deny"].some((kind) => {
+        const rules = layer.permissions?.[kind];
+        return Array.isArray(rules) && rules.some((rule) => typeof rule === "string" && /^Agent(\(|$)/.test(rule.trim()));
+    }));
+}
+async function isLaneLatched(sessionId) {
+    const [{ openLocalStoreReadOnly }, { isLatched }] = await Promise.all([import("../local_store/database.js"), import("../local_store/routing.js")]);
+    const store = await openLocalStoreReadOnly();
+    if (store === null)
+        return false;
+    try {
+        return isLatched(store, sessionId, "lane.subagent");
+    }
+    catch {
+        return false;
+    }
+    finally {
+        store.close();
+    }
+}
+export async function answerAgentCall(text, env, home = os.homedir()) {
+    const call = parseAgentCall(text);
+    const baseUrl = env.ANTHROPIC_BASE_URL ?? "";
+    const proxy = readProxy();
+    if (!proxy.live || !isUnderPrefix(baseUrl, proxy.prefix))
+        return null;
+    if (!readDesktopSettings().routing.lane)
+        return null;
+    const model = call.toolInput.model;
+    if (model !== undefined && model !== null && model !== "haiku")
+        return null;
+    const type = call.toolInput.subagent_type;
+    if (typeof type !== "string")
+        return null;
+    if (type !== "Explore" && !isReadOnlyDefinition(type, call.cwd, home))
+        return null;
+    if (PASS_ON_AGENT_PERMISSION_RULE && hasAgentPermissionRule(readSettingsLayers({ env, cwd: call.cwd, home })))
+        return null;
+    if (await isLaneLatched(call.sessionId))
+        return null;
+    const updatedInput = LANE_AGENT_ROUTE === "model" ? { ...call.toolInput, model: LANE_MODEL_ID } : { ...call.toolInput, subagent_type: LANE_AGENT_NAME };
+    return `${JSON.stringify({ hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "allow", updatedInput } })}\n`;
+}

package/dist/lib/gate/grounding.js

@@ -0,0 +1,121 @@
+import { readFileSync, statSync } from "node:fs";
+import path from "node:path";
+export const GROUNDING_MAX_PATHS = 50;
+export const GROUNDING_MAX_IDENTIFIERS = 100;
+export const GROUNDING_MAX_FILE_BYTES = 2 * 1024 * 1024;
+const FILE_EXTENSIONS = new Set("ts tsx js jsx mjs cjs json md mdx rs py go toml yaml yml css scss html sh txt lock sql swift kt java c h cpp hpp rb php vue svelte astro proto graphql xml ini env cfg conf csv".split(" "));
+const LINE_SUFFIX = String.raw `(?::(\d+)(?:-(\d+))?)?`;
+const SLASHED_PATH = new RegExp(String.raw `(?<![\w./:-])((?:[\w.@-]+/)+[\w.@-]+\.[A-Za-z0-9]+)${LINE_SUFFIX}`, "g");
+const BACKTICKED = /`([^`\n]+)`/g;
+const BACKTICKED_FILE = new RegExp(String.raw `^([\w.@-]+\.([A-Za-z0-9]+))${LINE_SUFFIX}$`);
+const IDENTIFIER = /^[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)?$/;
+function lineOf(text) {
+    return text === undefined ? null : Number.parseInt(text, 10);
+}
+function pushPath(paths, seen, claim) {
+    const key = `${claim.path}:${claim.startLine ?? ""}-${claim.endLine ?? ""}`;
+    if (seen.has(key) || paths.length >= GROUNDING_MAX_PATHS)
+        return;
+    seen.add(key);
+    paths.push(claim);
+}
+export function extractClaims(text) {
+    const paths = [];
+    const identifiers = [];
+    const seenPaths = new Set();
+    const seenIdentifiers = new Set();
+    for (const match of text.matchAll(SLASHED_PATH)) {
+        const before = text.slice(Math.max(0, (match.index ?? 0) - 3), match.index ?? 0);
+        if (before.endsWith("://"))
+            continue;
+        pushPath(paths, seenPaths, { path: match[1], startLine: lineOf(match[2]), endLine: lineOf(match[3]) });
+    }
+    for (const match of text.matchAll(BACKTICKED)) {
+        const token = match[1].trim();
+        if (token.includes("/"))
+            continue;
+        const file = BACKTICKED_FILE.exec(token);
+        if (file && FILE_EXTENSIONS.has(file[2].toLowerCase())) {
+            pushPath(paths, seenPaths, { path: file[1], startLine: lineOf(file[3]), endLine: lineOf(file[4]) });
+            continue;
+        }
+        if (token.length < 3 || !IDENTIFIER.test(token) || seenIdentifiers.has(token))
+            continue;
+        if (identifiers.length >= GROUNDING_MAX_IDENTIFIERS)
+            continue;
+        seenIdentifiers.add(token);
+        identifiers.push(token);
+    }
+    return { paths, identifiers };
+}
+function sizeOf(file) {
+    try {
+        const stats = statSync(file);
+        return stats.isFile() ? stats.size : null;
+    }
+    catch {
+        return null;
+    }
+}
+function readSmall(file) {
+    const size = sizeOf(file);
+    if (size === null || size > GROUNDING_MAX_FILE_BYTES)
+        return null;
+    try {
+        return readFileSync(file, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+function lineCountOf(content) {
+    if (content === "")
+        return 0;
+    const lines = content.split("\n").length;
+    return content.endsWith("\n") ? lines - 1 : lines;
+}
+function resolveClaim(claim, cwd, readFiles) {
+    const direct = path.isAbsolute(claim.path) ? claim.path : path.resolve(cwd, claim.path);
+    if (sizeOf(direct) !== null)
+        return direct;
+    if (!claim.path.includes("/")) {
+        const byName = readFiles.find((file) => path.basename(file) === claim.path && sizeOf(file) !== null);
+        if (byName)
+            return byName;
+    }
+    return null;
+}
+export function verifyClaims(claims, cwd, readFiles) {
+    const citedFiles = [];
+    const fail = (failure) => ({ result: "fail", failure, citedFiles });
+    for (const claim of claims.paths) {
+        const file = resolveClaim(claim, cwd, readFiles);
+        if (file === null)
+            return fail(`no file ${claim.path}`);
+        if (!citedFiles.includes(file))
+            citedFiles.push(file);
+        const lastLine = Math.max(claim.startLine ?? 0, claim.endLine ?? 0);
+        if (lastLine === 0)
+            continue;
+        const content = readSmall(file);
+        if (content === null)
+            continue;
+        if (lastLine > lineCountOf(content))
+            return fail(`${claim.path}:${lastLine} is past the end of the file`);
+    }
+    const searchable = [...citedFiles, ...readFiles.map((file) => path.resolve(cwd, file)).filter((file) => !citedFiles.includes(file))];
+    const contents = new Map();
+    const contentOf = (file) => {
+        if (!contents.has(file))
+            contents.set(file, readSmall(file));
+        return contents.get(file) ?? null;
+    };
+    const hasSearchable = searchable.some((file) => contentOf(file) !== null);
+    if (hasSearchable) {
+        for (const identifier of claims.identifiers) {
+            if (!searchable.some((file) => contentOf(file)?.includes(identifier)))
+                return fail(`\`${identifier}\` appears in no cited or read file`);
+        }
+    }
+    return { result: "pass", failure: null, citedFiles };
+}

package/dist/lib/gate/hook.js

@@ -56,6 +56,25 @@ function denialOf(reason) {
         },
     })}\n`;
 }
+const LANE_URL_HEAD = "http://127.0.0.1:";
+export function isLaneSessionEnv(env) {
+    const baseUrl = env.ANTHROPIC_BASE_URL;
+    return typeof baseUrl === "string" && baseUrl.startsWith(LANE_URL_HEAD) && baseUrl.includes("/lane/");
+}
+async function runLaneHook(subcommand, io) {
+    const text = await readStdin(io.stdin);
+    if (!isLaneSessionEnv(io.env))
+        return;
+    if (subcommand === "agent") {
+        const { answerAgentCall } = await import("./agentHook.js");
+        const answer = await answerAgentCall(text, io.env);
+        if (answer !== null)
+            io.stdout.write(answer);
+        return;
+    }
+    const { answerSubagentStop } = await import("./subagentStop.js");
+    await answerSubagentStop(text, io.env);
+}
 function deniedPathOf(subcommand, call) {
     const written = subcommand === "read"
         ? call.toolInput.file_path
@@ -89,6 +108,10 @@ export async function runGateHook(subcommand, io = { stdin: process.stdin, stdou
         return;
     }
     try {
+        if (subcommand === "agent" || subcommand === "subagent-stop") {
+            await runLaneHook(subcommand, io);
+            return;
+        }
         const call = parseCall(await readStdin(io.stdin), startedAt);
         let answer;
         if (subcommand === "read")

package/dist/lib/gate/subagentStop.js

@@ -0,0 +1,121 @@
+import { randomUUID } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { isUnderPrefix, readProxy } from "../lane/proxyRecord.js";
+import { tokensOfLength } from "./estimate.js";
+import { extractClaims, verifyClaims } from "./grounding.js";
+import { GateInputError } from "./readGate.js";
+function parseStopCall(text) {
+    let payload;
+    try {
+        payload = JSON.parse(text);
+    }
+    catch {
+        throw new GateInputError("stdin is not JSON");
+    }
+    if (payload === null || typeof payload !== "object" || Array.isArray(payload))
+        throw new GateInputError("stdin is not a JSON object");
+    const fields = payload;
+    if (typeof fields.session_id !== "string" || fields.session_id === "")
+        throw new GateInputError("session_id is missing");
+    const transcript = fields.agent_transcript_path;
+    const agentType = fields.agent_type;
+    return {
+        sessionId: fields.session_id,
+        cwd: typeof fields.cwd === "string" && fields.cwd !== "" ? fields.cwd : process.cwd(),
+        transcriptPath: typeof transcript === "string" && transcript !== "" ? transcript : null,
+        agentType: typeof agentType === "string" && agentType !== "" ? agentType : "subagent",
+    };
+}
+function isRoutedModel(model) {
+    return typeof model === "string" && model !== "" && !model.startsWith("claude") && model !== "<synthetic>";
+}
+function numberOf(value) {
+    return typeof value === "number" && Number.isFinite(value) && value > 0 ? Math.round(value) : 0;
+}
+export function readSubagentRun(content) {
+    let routed = false;
+    let finalText = "";
+    let localTokens = 0;
+    let first = null;
+    let last = null;
+    let agentType = null;
+    const readFiles = [];
+    for (const line of content.split("\n")) {
+        if (line.trim() === "")
+            continue;
+        let entry;
+        try {
+            entry = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        const stamp = typeof entry.timestamp === "string" ? Date.parse(entry.timestamp) : Number.NaN;
+        if (!Number.isNaN(stamp)) {
+            first ??= stamp;
+            last = stamp;
+        }
+        if (agentType === null && typeof entry.agentType === "string")
+            agentType = entry.agentType;
+        if (entry.type !== "assistant")
+            continue;
+        const message = entry.message;
+        if (!message)
+            continue;
+        if (isRoutedModel(message.model)) {
+            routed = true;
+            const usage = message.usage;
+            localTokens += numberOf(usage?.input_tokens) + numberOf(usage?.output_tokens);
+        }
+        const blocks = Array.isArray(message.content) ? message.content : [];
+        const texts = blocks.filter((block) => block?.type === "text" && typeof block.text === "string").map((block) => block.text);
+        if (texts.length > 0)
+            finalText = texts.join("\n");
+        for (const block of blocks) {
+            if (block?.type !== "tool_use" || block.name !== "Read")
+                continue;
+            const filePath = block.input?.file_path;
+            if (typeof filePath === "string" && !readFiles.includes(filePath))
+                readFiles.push(filePath);
+        }
+    }
+    return { routed, finalText, readFiles, localTokens, latencyMs: first !== null && last !== null ? Math.max(0, last - first) : 0, agentType };
+}
+export async function answerSubagentStop(text, env) {
+    const call = parseStopCall(text);
+    const proxy = readProxy();
+    if (!proxy.live || !isUnderPrefix(env.ANTHROPIC_BASE_URL ?? "", proxy.prefix))
+        return;
+    if (call.transcriptPath === null)
+        return;
+    const run = readSubagentRun(readFileSync(call.transcriptPath, "utf8"));
+    if (!run.routed)
+        return;
+    const verdict = verifyClaims(extractClaims(run.finalText), call.cwd, run.readFiles);
+    const [{ openLocalStore, withTransaction }, routing] = await Promise.all([import("../local_store/database.js"), import("../local_store/routing.js")]);
+    const store = await openLocalStore();
+    try {
+        const now = Date.now();
+        withTransaction(store, () => {
+            routing.insertLabelRow(store, {
+                id: `lr_${randomUUID()}`,
+                session_id: call.sessionId,
+                agent_type: call.agentType !== "subagent" ? call.agentType : (run.agentType ?? call.agentType),
+                path: verdict.citedFiles[0] ?? null,
+                estimated_tokens: run.localTokens,
+                returned_tokens: tokensOfLength(run.finalText.length),
+                handler: "local_model",
+                check_result: verdict.result,
+                bypass_used: 0,
+                latency_ms: run.latencyMs,
+                tokens_kept_out: 0,
+                created_at: now,
+            });
+            if (verdict.result === "fail")
+                routing.recordRoutingMiss(store, call.sessionId, "lane.subagent", "failure", now);
+        });
+    }
+    finally {
+        store.close();
+    }
+}

package/dist/lib/gate/subcommands.js

@@ -1 +1 @@
-export const HOOK_SUBCOMMANDS = ["read", "bash"];
+export const HOOK_SUBCOMMANDS = ["read", "bash", "agent", "subagent-stop"];

package/dist/lib/lane/credential.js

@@ -0,0 +1,101 @@
+import { readFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+export const CLAUDE_MANAGED_SETTINGS_PATH = "/Library/Application Support/ClaudeCode/managed-settings.json";
+function objectOf(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function readJsonObject(file) {
+    try {
+        return objectOf(JSON.parse(readFileSync(file, "utf8")));
+    }
+    catch {
+        return null;
+    }
+}
+function layerOf(scope, label, file) {
+    const settings = readJsonObject(file);
+    if (settings === null)
+        return null;
+    const env = {};
+    for (const [key, value] of Object.entries(objectOf(settings.env) ?? {})) {
+        if (typeof value === "string")
+            env[key] = value;
+        else if (typeof value === "number" || typeof value === "boolean")
+            env[key] = String(value);
+    }
+    return {
+        scope,
+        label,
+        env,
+        model: typeof settings.model === "string" && settings.model !== "" ? settings.model : null,
+        apiKeyHelper: typeof settings.apiKeyHelper === "string" && settings.apiKeyHelper !== "" ? settings.apiKeyHelper : null,
+        permissions: objectOf(settings.permissions),
+    };
+}
+function homeOf(context) {
+    return context.home ?? os.homedir();
+}
+export function readSettingsLayers(context) {
+    const home = homeOf(context);
+    const candidates = [
+        ["user", "~/.claude/settings.json", path.join(home, ".claude", "settings.json")],
+        ["project", ".claude/settings.json", path.join(context.cwd, ".claude", "settings.json")],
+        ["local", ".claude/settings.local.json", path.join(context.cwd, ".claude", "settings.local.json")],
+        ["managed", "managed settings", context.managedSettingsPath ?? CLAUDE_MANAGED_SETTINGS_PATH],
+    ];
+    const layers = [];
+    const seen = new Set();
+    for (const [scope, label, file] of candidates) {
+        const resolved = path.resolve(file);
+        if (seen.has(resolved))
+            continue;
+        seen.add(resolved);
+        const layer = layerOf(scope, label, resolved);
+        if (layer !== null)
+            layers.push(layer);
+    }
+    return layers;
+}
+export function effectiveEnv(env, layers) {
+    const merged = {};
+    for (const [key, value] of Object.entries(env))
+        if (typeof value === "string")
+            merged[key] = value;
+    for (const layer of layers)
+        Object.assign(merged, layer.env);
+    return merged;
+}
+function isSet(value) {
+    return value !== undefined && value.trim() !== "";
+}
+function isTruthy(value) {
+    return isSet(value) && !["0", "false", "no", "off"].includes(value.trim().toLowerCase());
+}
+export function isKeyApproved(key, home) {
+    const config = readJsonObject(path.join(home, ".claude.json"));
+    const approved = objectOf(config?.customApiKeyResponses)?.approved;
+    if (!Array.isArray(approved))
+        return false;
+    return approved.includes(key.slice(-20));
+}
+export function detectCredential(effective, layers, options) {
+    if (isTruthy(effective.CLAUDE_CODE_USE_BEDROCK) || isTruthy(effective.CLAUDE_CODE_USE_VERTEX)) {
+        return { state: "off", reason: "bedrock-or-vertex" };
+    }
+    const authToken = effective.ANTHROPIC_AUTH_TOKEN;
+    if (isSet(effective.CLAUDE_CODE_OAUTH_TOKEN) || (isSet(authToken) && authToken.startsWith("sk-ant-oat"))) {
+        return { state: "off", reason: "subscription-credential" };
+    }
+    if (isSet(authToken))
+        return { state: "on", credential: "gateway" };
+    const apiKey = effective.ANTHROPIC_API_KEY;
+    if (isSet(apiKey)) {
+        if (options.interactive && !isKeyApproved(apiKey, options.home))
+            return { state: "off", reason: "key-not-approved" };
+        return { state: "on", credential: "api-key" };
+    }
+    if (layers.some((layer) => layer.apiKeyHelper !== null))
+        return { state: "on", credential: "api-key-helper" };
+    return { state: "off", reason: "no-api-credential" };
+}

package/dist/lib/lane/decide.js

@@ -0,0 +1,105 @@
+import os from "node:os";
+import { readDesktopSettings } from "../desktop_settings.js";
+import { detectCredential, effectiveEnv, readSettingsLayers } from "./credential.js";
+import { effectiveMainModel, haikuSentence } from "./mainModel.js";
+import { readProxy } from "./proxyRecord.js";
+import { isLaneReleased } from "./release.js";
+export const DEFAULT_UPSTREAM = "https://api.anthropic.com";
+export const SUBAGENT_MODEL_ENV = "CLAUDE_CODE_SUBAGENT_MODEL";
+export const SUBAGENT_MODEL_OVERRIDES_ROUTE = false;
+export const LANE_SENTENCES = {
+    unreleased: "The light-model lane is not released in this build.",
+    "switch-off": "The lane is switched off in NuStack's Routing & agents settings.",
+    "proxy-down": "NuStack's lane proxy is not running; open the NuStack desktop app.",
+    "bedrock-or-vertex": "This session runs on Bedrock or Vertex, which the lane does not carry.",
+    "subscription-credential": "This session signs in with a Claude subscription, which the lane never carries.",
+    "key-not-approved": "ANTHROPIC_API_KEY is set but not approved in Claude Code, so this terminal session would use your claude.ai login; approve the key in Claude Code first.",
+    "no-api-credential": "This session has no API key or gateway credential; a Claude subscription session gets nothing from the lane.",
+    "upstream-not-https": "ANTHROPIC_BASE_URL must be https: (or http: on loopback) for the lane to forward to it.",
+    "base-url-in-settings": "ANTHROPIC_BASE_URL is set in a Claude Code settings file, which would override the lane's.",
+    "haiku-main-model": "",
+    "subagent-model-override": `${SUBAGENT_MODEL_ENV} is set, and Claude Code lets it override the lane's sub-agent model.`,
+};
+export function base64Url(text) {
+    return Buffer.from(text, "utf8").toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+export function laneBaseUrl(port, token, upstream) {
+    const prefix = `http://127.0.0.1:${port}/lane/${token}`;
+    return upstream === null || upstream === DEFAULT_UPSTREAM ? prefix : `${prefix}/up/${base64Url(upstream)}`;
+}
+const LOOPBACK_HOSTS = new Set(["127.0.0.1", "localhost", "[::1]", "::1"]);
+export function isUpstreamAllowed(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return false;
+    }
+    if (parsed.protocol === "https:")
+        return true;
+    return parsed.protocol === "http:" && LOOPBACK_HOSTS.has(parsed.hostname);
+}
+function upstreamOf(env, layers) {
+    if (layers.some((layer) => layer.env.ANTHROPIC_BASE_URL !== undefined))
+        return { state: "off", reason: "base-url-in-settings" };
+    const preset = env.ANTHROPIC_BASE_URL?.trim();
+    if (!preset)
+        return { state: "ok", url: DEFAULT_UPSTREAM, preset: false };
+    if (!isUpstreamAllowed(preset))
+        return { state: "off", reason: "upstream-not-https" };
+    return { state: "ok", url: preset.replace(/\/+$/, ""), preset: true };
+}
+function subagentModelOf(env, layers) {
+    for (const layer of [...layers].reverse()) {
+        const value = layer.env[SUBAGENT_MODEL_ENV]?.trim();
+        if (value)
+            return { value, source: layer.label };
+    }
+    const fromEnv = env[SUBAGENT_MODEL_ENV]?.trim();
+    return fromEnv ? { value: fromEnv, source: SUBAGENT_MODEL_ENV } : null;
+}
+export function readLaneFacts(input) {
+    const home = input.home ?? os.homedir();
+    const layers = readSettingsLayers({ ...input, home });
+    const effective = effectiveEnv(input.env, layers);
+    return {
+        released: isLaneReleased(input.env),
+        switchOn: readDesktopSettings().routing.lane,
+        proxy: readProxy(),
+        layers,
+        effective,
+        credential: detectCredential(effective, layers, { interactive: input.interactive, home }),
+        upstream: upstreamOf(input.env, layers),
+        mainModel: effectiveMainModel(effective, layers),
+        subagentModel: subagentModelOf(input.env, layers),
+    };
+}
+function off(reason, sentence = LANE_SENTENCES[reason]) {
+    return { state: "off", reason, sentence };
+}
+export function decideFromFacts(facts) {
+    if (!facts.released)
+        return off("unreleased");
+    if (!facts.switchOn)
+        return off("switch-off");
+    if (!facts.proxy.live || !facts.proxy.record.accepting)
+        return off("proxy-down");
+    if (facts.credential.state === "off")
+        return off(facts.credential.reason);
+    if (facts.upstream.state === "off")
+        return off(facts.upstream.reason);
+    if (facts.mainModel.haikuClass)
+        return off("haiku-main-model", haikuSentence(facts.mainModel));
+    if (SUBAGENT_MODEL_OVERRIDES_ROUTE && facts.subagentModel !== null)
+        return off("subagent-model-override");
+    const { port, token } = facts.proxy.record;
+    return {
+        state: "on",
+        baseUrl: laneBaseUrl(port, token, facts.upstream.preset ? facts.upstream.url : null),
+        credential: facts.credential.credential,
+    };
+}
+export function decideLane(input) {
+    return decideFromFacts(readLaneFacts(input));
+}

package/dist/lib/lane/install.js

@@ -0,0 +1,74 @@
+import { existsSync, readFileSync } from "node:fs";
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { hasManagedHook, installManagedHook, removeManagedHook } from "../agent/claudeHooks.js";
+export const LANE_MODEL_ID = "nustack-local";
+export const LANE_AGENT_NAME = "nustack-local-explore";
+export const LANE_AGENT_ROUTE = "definition";
+export const LANE_HOOK_TIMEOUT_SECONDS = 10;
+export const LANE_HOOKS = [
+    { event: "PreToolUse", matcher: "Agent", command: "nustack gate agent" },
+    { event: "SubagentStop", matcher: "", command: "nustack gate subagent-stop" },
+];
+const MANAGED_MARKER = "nustack:managed";
+export function claudeSettingsPath(home = os.homedir()) {
+    return path.join(home, ".claude", "settings.json");
+}
+export function laneAgentDefinitionPath(home = os.homedir()) {
+    return path.join(home, ".claude", "agents", `${LANE_AGENT_NAME}.md`);
+}
+export function laneAgentDefinition() {
+    return [
+        "---",
+        `name: ${LANE_AGENT_NAME}`,
+        "description: Read-only exploration on your own local model, through NuStack's light-model lane. Use for finding files, reading code and answering where-is questions.",
+        "tools: Read, Grep, Glob",
+        `model: ${LANE_MODEL_ID}`,
+        "---",
+        "",
+        `<!-- ${MANAGED_MARKER}: written by \`nustack lane install\`, removed by \`nustack lane remove\` -->`,
+        "",
+        "You explore a codebase read-only and report what you found, citing every file as a path with its line range.",
+        "",
+    ].join("\n");
+}
+export async function installLane(home = os.homedir(), route = LANE_AGENT_ROUTE) {
+    let changed = false;
+    for (const hook of LANE_HOOKS) {
+        const result = await installManagedHook(claudeSettingsPath(home), hook.event, hook.matcher, hook.command, {
+            timeout: LANE_HOOK_TIMEOUT_SECONDS,
+        });
+        changed ||= result.changed;
+    }
+    if (route === "definition") {
+        const file = laneAgentDefinitionPath(home);
+        const wanted = laneAgentDefinition();
+        if (!existsSync(file) || readFileSync(file, "utf8") !== wanted) {
+            await mkdir(path.dirname(file), { recursive: true });
+            await writeFile(file, wanted, "utf8");
+            changed = true;
+        }
+    }
+    return { changed };
+}
+export async function removeLane(home = os.homedir()) {
+    let removed = false;
+    for (const hook of LANE_HOOKS) {
+        const result = await removeManagedHook(claudeSettingsPath(home), hook.event, hook.matcher);
+        removed ||= result.removed;
+    }
+    const file = laneAgentDefinitionPath(home);
+    if (existsSync(file) && readFileSync(file, "utf8").includes(MANAGED_MARKER)) {
+        await rm(file, { force: true });
+        removed = true;
+    }
+    return { removed };
+}
+export async function laneHooksInstalled(home = os.homedir()) {
+    const settingsPath = claudeSettingsPath(home);
+    return {
+        agent: await hasManagedHook(settingsPath, "PreToolUse", "Agent"),
+        subagentStop: await hasManagedHook(settingsPath, "SubagentStop", ""),
+    };
+}

package/dist/lib/lane/mainModel.js

@@ -0,0 +1,47 @@
+const SONNET_ALIASES = new Set(["sonnet", "default"]);
+const OPUS_ALIASES = new Set(["opus", "opusplan"]);
+function aliasOf(value) {
+    return value.replace(/\[[^\]]*\]$/, "").trim().toLowerCase();
+}
+export function resolveAlias(value, effective) {
+    const alias = aliasOf(value);
+    const sonnet = effective.ANTHROPIC_DEFAULT_SONNET_MODEL?.trim();
+    const opus = effective.ANTHROPIC_DEFAULT_OPUS_MODEL?.trim();
+    if (SONNET_ALIASES.has(alias) && sonnet)
+        return { value: sonnet, via: "ANTHROPIC_DEFAULT_SONNET_MODEL" };
+    if (OPUS_ALIASES.has(alias) && opus)
+        return { value: opus, via: "ANTHROPIC_DEFAULT_OPUS_MODEL" };
+    return { value, via: null };
+}
+export function effectiveMainModel(effective, layers) {
+    let raw = null;
+    let source = null;
+    let scope = null;
+    const fromEnv = effective.ANTHROPIC_MODEL?.trim();
+    if (fromEnv) {
+        raw = fromEnv;
+        source = "ANTHROPIC_MODEL";
+    }
+    else {
+        for (const layer of [...layers].reverse()) {
+            if (layer.model !== null) {
+                raw = layer.model;
+                source = layer.label;
+                scope = layer.scope;
+                break;
+            }
+        }
+    }
+    if (raw === null)
+        return { value: null, source: null, scope: null, haikuClass: false };
+    const resolved = resolveAlias(raw, effective);
+    return {
+        value: resolved.value,
+        source: resolved.via === null ? source : `${source} via ${resolved.via}`,
+        scope,
+        haikuClass: /haiku/i.test(resolved.value),
+    };
+}
+export function haikuSentence(model) {
+    return `Your main model is Haiku-class (\`${model.value ?? ""}\` from \`${model.source ?? ""}\`); the lane would trade Anthropic's light model for a local one at the smallest saving.`;
+}

package/dist/lib/lane/proxyRecord.js

@@ -0,0 +1,67 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { desktopConfigDir } from "../agent/desktopDoor.js";
+export const PROXY_RECORD_FILE = "proxy.json";
+export function proxyRecordPath() {
+    return path.join(desktopConfigDir(), PROXY_RECORD_FILE);
+}
+export function parseProxyRecord(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
+        return null;
+    const fields = parsed;
+    if (fields.schemaVersion !== 1)
+        return null;
+    if (typeof fields.port !== "number" || !Number.isInteger(fields.port) || fields.port < 1 || fields.port > 65535)
+        return null;
+    if (typeof fields.token !== "string" || !/^[0-9a-f]{16,128}$/.test(fields.token))
+        return null;
+    if (fields.pid !== null && (typeof fields.pid !== "number" || !Number.isInteger(fields.pid) || fields.pid < 1))
+        return null;
+    if (typeof fields.startedAt !== "string" || typeof fields.accepting !== "boolean")
+        return null;
+    return {
+        schemaVersion: 1,
+        port: fields.port,
+        token: fields.token,
+        pid: fields.pid,
+        startedAt: fields.startedAt,
+        accepting: fields.accepting,
+    };
+}
+export function isPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+export function lanePrefixOf(record) {
+    return `http://127.0.0.1:${record.port}/lane/${record.token}`;
+}
+export function isUnderPrefix(baseUrl, prefix) {
+    return baseUrl === prefix || baseUrl.startsWith(`${prefix}/`);
+}
+export function readProxy(recordPath = proxyRecordPath()) {
+    let text;
+    try {
+        text = readFileSync(recordPath, "utf8");
+    }
+    catch {
+        return { live: false, record: null };
+    }
+    const record = parseProxyRecord(text);
+    if (record === null)
+        return { live: false, record: null };
+    if (record.pid === null || !isPidAlive(record.pid))
+        return { live: false, record };
+    return { live: true, record, prefix: lanePrefixOf(record) };
+}

package/dist/lib/lane/release.js

@@ -0,0 +1,4 @@
+export const LANE_RELEASED_ENV = "NUSTACK_LANE_RELEASED";
+export function isLaneReleased(env) {
+    return env[LANE_RELEASED_ENV] === "1";
+}

package/dist/lib/session-engine/frames.js

@@ -48,7 +48,8 @@ export function parseInboundFrame(line) {
                 return { ok: false, error: { code: "BAD_FRAME", name: type, message: "session.open commit must be a hex object name" } };
             }
             const commit = rawCommit ?? undefined;
-            return { ok: true, frame: { v: FRAME_VERSION, type, sessionId, projectPath, permissionMode, isolated, commit, resumeSessionId } };
+            const lane = frame.lane === true ? true : undefined;
+            return { ok: true, frame: { v: FRAME_VERSION, type, sessionId, projectPath, permissionMode, isolated, commit, resumeSessionId, lane } };
         }
         case "session.turn": {
             const sessionId = requireString("sessionId");

package/dist/lib/session-engine/supervisor.js

@@ -8,6 +8,7 @@ import { SESSION_ID_VARIABLE } from "../records/environment.js";
 import { mountFacts } from "../sessions/mountFacts.js";
 import { createSessionWorktree } from "./worktree.js";
 import { readProjectContract } from "../project_contract.js";
+import { decideLane } from "../lane/decide.js";
 function defaultProbeClaude(env) {
     return new Promise((resolve) => {
         execFile("claude", ["--version"], { env, timeout: 5_000 }, (error, stdout) => {
@@ -85,7 +86,7 @@ export class SessionSupervisor {
                 await this.shutdown();
                 return;
             case "session.open":
-                await this.openSession(frame.sessionId, frame.projectPath, frame.permissionMode, frame.isolated, frame.resumeSessionId, frame.commit);
+                await this.openSession(frame.sessionId, frame.projectPath, frame.permissionMode, frame.isolated, frame.resumeSessionId, frame.commit, frame.lane);
                 return;
             case "session.turn": {
                 const session = this.sessions.get(frame.sessionId);
@@ -137,7 +138,7 @@ export class SessionSupervisor {
             log(`nustack: harness mount skipped for session ${sessionId} - ${error instanceof Error ? error.message : String(error)}`);
         }
     }
-    async openSession(sessionId, projectPath, permissionMode, isolated, resumeSessionId, commit) {
+    async openSession(sessionId, projectPath, permissionMode, isolated, resumeSessionId, commit, lane) {
         if (this.sessions.has(sessionId))
             return this.error(sessionId, "SESSION_ALREADY_OPEN", `session ${sessionId} is already open`);
         this.status(sessionId, "starting");
@@ -173,11 +174,14 @@ export class SessionSupervisor {
             ...(facts?.harnessDigest ? { harnessDigest: facts.harnessDigest } : {}),
             ...(facts?.configDigest ? { configDigest: facts.configDigest } : {}),
         };
+        const sessionEnv = { ...this.env, [SESSION_ID_VARIABLE]: sessionId };
+        const laneOutcome = lane === true ? this.laneFor(sessionEnv, worktree.worktreePath) : null;
+        const spawnEnv = laneOutcome?.state === "on" ? { ...sessionEnv, ANTHROPIC_BASE_URL: laneOutcome.baseUrl } : sessionEnv;
         const adapterOptions = {
             cwd: worktree.worktreePath,
             permissionMode,
             resumeSessionId,
-            env: { ...this.env, [SESSION_ID_VARIABLE]: sessionId },
+            env: spawnEnv,
             onEvent: (event) => {
                 this.emit({ v: FRAME_VERSION, type: "session.event", sessionId, event });
                 if (typeof event === "object" && event !== null && event.type === "result") {
@@ -266,9 +270,18 @@ export class SessionSupervisor {
             branch: worktree.branch,
             isolated: worktree.isolated,
             commit: worktree.baseCommit,
+            ...(laneOutcome === null ? {} : { lane: { state: laneOutcome.state, reason: laneOutcome.state === "on" ? null : laneOutcome.reason } }),
         });
         this.status(sessionId, "ready");
     }
+    laneFor(env, cwd) {
+        try {
+            return decideLane({ env, cwd, interactive: false, home: env.HOME || undefined });
+        }
+        catch (error) {
+            return { state: "off", reason: "proxy-down", sentence: error instanceof Error ? error.message : String(error) };
+        }
+    }
     async sendRoster() {
         const { records, dropped } = await readSessionRegistry(this.env);
         const rows = [];

package/dist/program.js

@@ -42,6 +42,7 @@ import { runCensus } from "./commands/census.js";
 import { runGateInstall, runGateRemove, runGateStatus } from "./commands/gate.js";
 import { parseBudgetMs, parseLineWindow, runReadBulk } from "./commands/read.js";
 import { HOOK_SUBCOMMANDS } from "./lib/gate/subcommands.js";
+import { runLaneEnv, runLaneInstall, runLaneRemove, runLaneStatus } from "./commands/lane.js";
 import { printJsonError } from "./lib/json_output.js";
 import { setCliVersion } from "./lib/auth_grant.js";
 const { version } = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
@@ -250,7 +251,7 @@ registerReviewCommands(program.command("review").description("Read and mirror Nu
 registerRecordsCommands(program.command("records").description("Emit, send and list harness records"), () => program.opts());
 registerRecordAliases(program, () => program.opts());
 const LOCAL_ONLY_COMMANDS = ["census", "check"];
-const UNDRAINED_GROUPS = ["records", "gate", "session", "read", ...RECORD_ALIAS_GROUPS];
+const UNDRAINED_GROUPS = ["records", "gate", "session", "read", "lane", ...RECORD_ALIAS_GROUPS];
 program.hook("preAction", async (_program, action) => {
     if (program.opts().nonInteractive)
         process.env[NON_INTERACTIVE_VARIABLE] = "1";
@@ -383,7 +384,7 @@ program
 const gate = program.command("gate").description("The large-read gate: answer a large full read with an outline, once per session");
 for (const subcommand of HOOK_SUBCOMMANDS) {
     gate.command(subcommand)
-        .description(`Claude Code PreToolUse hook entry point (${subcommand}); reads the hook JSON on stdin`)
+        .description(`Claude Code hook entry point (${subcommand}); reads the hook JSON on stdin`)
         .action(async () => {
         const { runGateHook } = await import("./lib/gate/hook.js");
         await runGateHook(subcommand);
@@ -410,6 +411,23 @@ read.command("bulk")
     .option("--budget-ms <n>", "the whole call's wall-time budget, 5000 to 300000 ms (default: NUSTACK_READ_BULK_BUDGET_MS, the desktop setting, then the desktop's own)", parseBudgetMs)
     .option("--json", "emit the versioned machine envelope")
     .action(async (options) => runReadBulk(options));
+const lane = program.command("lane").description("The light-model lane: send read-only sub-agents of API-key sessions to your local model");
+lane.command("env")
+    .description("Print ANTHROPIC_BASE_URL=<lane url> when the lane is on for a session in --cwd, nothing otherwise")
+    .option("--cwd <dir>", "the session's folder (default: the current folder)")
+    .option("--non-interactive", "decide for a non-interactive launch (no API-key approval check)")
+    .action((options) => runLaneEnv({ ...options, nonInteractive: options.nonInteractive === true || program.opts().nonInteractive === true }));
+lane.command("status")
+    .description("Report the lane's release, switch, proxy, credential, main model and decision")
+    .option("--cwd <dir>", "the session's folder (default: the current folder)")
+    .option("--json", "emit the versioned machine envelope")
+    .action(async (options) => runLaneStatus(options));
+lane.command("install")
+    .description("Register the lane's Agent and SubagentStop hooks in ~/.claude/settings.json (idempotent)")
+    .action(async () => runLaneInstall());
+lane.command("remove")
+    .description("Remove exactly the lane's hook entries")
+    .action(async () => runLaneRemove());
 function describeError(error) {
     const directCode = error?.code;
     if (directCode === "PROJECT_CONTEXT_MISSING") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nurix/nustack",
-  "version": "0.23.17",
+  "version": "0.23.18",
   "description": "The nustack CLI — bootstrap NuStack services into a repo via the NuStack discovery plane.",
   "type": "module",
   "private": false,
@@ -34,8 +34,8 @@
     "@types/node": "^22.19.20",
     "typescript": "^5.7.2",
     "vitest": "^4.1.11",
-    "@nurix/harness": "0.0.0",
     "@nurix/contracts": "2.0.2",
+    "@nurix/harness": "0.0.0",
     "@nurix/nustack.studio": "0.0.0",
     "@nurix/nustack.ui": "0.0.0"
   },