@zeroroot-ai/zerocool-claude 0.1.0 → 0.2.0

package/.claude-plugin/plugin.json

@@ -3,11 +3,17 @@
   "name": "zerocool",
   "displayName": "Zerocool (Gibson)",
   "description": "Gibson platform integration for Claude Code. The session is a live mission. Memory and knowledge in the tenant graph, findings, Gibson tools, delegation. The model stays on your Claude subscription.",
-  "author": { "name": "ZeroRoot", "url": "https://zeroroot.ai" },
+  "author": {
+    "name": "ZeroRoot",
+    "url": "https://zeroroot.ai"
+  },
   "homepage": "https://github.com/zeroroot-ai/zerocool-plugins",
   "repository": "https://github.com/zeroroot-ai/zerocool-plugins",
   "license": "MIT",
-  "keywords": ["gibson", "security", "knowledge-graph", "mcp"],
-  "mcpServers": "./.mcp.json",
-  "hooks": "./hooks/hooks.json"
+  "keywords": [
+    "gibson",
+    "security",
+    "knowledge-graph",
+    "mcp"
+  ]
 }

package/dist/build.d.ts

@@ -0,0 +1,30 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type CliOptions } from "./cli.js";
+import { type Gibson, type OpenGibsonOptions } from "./session.js";
+/**
+ * @zeroroot-ai/zerocool-claude: the MCP server Claude Code starts for a session.
+ *
+ * The model stays on the user's Claude subscription. This server adds Gibson:
+ * one live mission per session, memory and knowledge, findings, tools,
+ * delegation. It never routes LLM traffic and never reads an Anthropic key
+ * (ADR-0007).
+ *
+ * The connection is made in the session, not before it. `gibson_login` starts
+ * the CLI device flow and returns the URL and code. `gibson_connect` enrolls
+ * through the CLI session, trusts the private CA, checks in, picks the
+ * target, starts the live mission and swaps the tool set live. The settings
+ * it learns are persisted, so later sessions connect on their own.
+ */
+export declare const log: (line: string) => void;
+export interface BuildDeps {
+    open?: Pick<OpenGibsonOptions, "connect" | "start" | "hostKeyExists" | "trust">;
+    cli?: CliOptions;
+}
+export interface Surface {
+    server: McpServer;
+    /** The current connection. Changes on gibson_connect. */
+    current(): Gibson;
+    /** Replace the connection and re-register the posture's tools. */
+    upgrade(next: Gibson): Promise<void>;
+}
+export declare function buildServer(env: NodeJS.ProcessEnv, cwd: string, deps?: BuildDeps): Promise<Surface>;

package/dist/build.js

@@ -0,0 +1,191 @@
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { ambientBlock } from "./ambient.js";
+import { createTarget, enrollIdentity, listTargets, startLogin } from "./cli.js";
+import { loadSettings, writeConfig } from "./config.js";
+import { openGibson } from "./session.js";
+import { stateDir, writeAmbient, writeLive } from "./state.js";
+import { registerComponentizeTool, registerEnrollTool } from "./tools/componentize.js";
+import { registerDelegationTools } from "./tools/delegate.js";
+import { gibsonFindingsBackend, localFindingsBackend, registerFindingTools } from "./tools/findings.js";
+import { registerGibsonTools } from "./tools/gibson-tools.js";
+import { registerMemoryTools } from "./tools/memory.js";
+import { failure, text } from "./tools/result.js";
+import { describeGibson, registerStatusTool } from "./tools/status.js";
+/**
+ * @zeroroot-ai/zerocool-claude: the MCP server Claude Code starts for a session.
+ *
+ * The model stays on the user's Claude subscription. This server adds Gibson:
+ * one live mission per session, memory and knowledge, findings, tools,
+ * delegation. It never routes LLM traffic and never reads an Anthropic key
+ * (ADR-0007).
+ *
+ * The connection is made in the session, not before it. `gibson_login` starts
+ * the CLI device flow and returns the URL and code. `gibson_connect` enrolls
+ * through the CLI session, trusts the private CA, checks in, picks the
+ * target, starts the live mission and swaps the tool set live. The settings
+ * it learns are persisted, so later sessions connect on their own.
+ */
+export const log = (line) => {
+    process.stderr.write(`${line}\n`);
+};
+/** Snapshot of the tools a posture registered, so an upgrade can drop them. */
+function collect(server, register) {
+    const before = new Set(Object.keys(toolTable(server)));
+    return Promise.resolve(register()).then(() => {
+        const after = toolTable(server);
+        return Object.keys(after)
+            .filter((n) => !before.has(n))
+            .map((n) => after[n]);
+    });
+}
+function toolTable(server) {
+    return server._registeredTools;
+}
+export async function buildServer(env, cwd, deps = {}) {
+    const settings = await loadSettings(env);
+    let gibson = await openGibson({ settings, log, ...deps.open });
+    const server = new McpServer({ name: "zerocool", version: "0.0.0" });
+    let posture = [];
+    const surface = {
+        server,
+        current: () => gibson,
+        upgrade: async (next) => {
+            for (const t of posture)
+                t.remove();
+            posture = await collect(server, () => registerPosture(server, next, env, cwd));
+            gibson = next;
+        },
+    };
+    registerStatusTool(server, () => gibson);
+    registerComponentizeTool(server, cwd);
+    registerConnectTools(server, surface, env, deps);
+    posture = await collect(server, () => registerPosture(server, gibson, env, cwd));
+    return surface;
+}
+/** The tools a posture carries, plus the handoff files for the hooks. */
+async function registerPosture(server, gibson, env, cwd) {
+    if (!gibson.session) {
+        registerFindingTools(server, gibson, localFindingsBackend(env.ZEROCOOL_FINDINGS_LOG ?? join(homedir(), ".zerocool", "findings.jsonl")));
+        return;
+    }
+    registerFindingTools(server, gibson, gibsonFindingsBackend(gibson));
+    registerMemoryTools(server, gibson);
+    registerEnrollTool(server, gibson.session);
+    registerDelegationTools(server, gibson.session);
+    try {
+        const discovery = await registerGibsonTools(server, gibson.session);
+        log(discovery.note ? `[zerocool-claude] Gibson tool discovery: ${discovery.note}` : `[zerocool-claude] ${discovery.discovered} Gibson tool(s) registered`);
+    }
+    catch (e) {
+        // Discovery is a convenience. The generic gibson_call_tool is registered
+        // before discovery runs, so a failure here costs the per-tool wrappers only.
+        log(`[zerocool-claude] Gibson tool discovery failed: ${e.message}`);
+    }
+    const dir = stateDir(env);
+    if (gibson.knowledge) {
+        const block = await ambientBlock(gibson.knowledge, env.ZEROCOOL_AMBIENT_QUERY ?? "memories, prior findings and security facts for this codebase");
+        if (block)
+            await writeAmbient(dir, cwd, block).catch((e) => log(`[zerocool-claude] ambient handoff failed: ${e.message}`));
+    }
+    if (gibson.live) {
+        const live = gibson.live;
+        await writeLive(dir, cwd, {
+            missionId: live.missionId,
+            workId: live.workId,
+            endpoint: live.harness.endpoint,
+            token: live.harness.token(),
+            insecure: gibson.settings.callbackInsecure,
+            writtenAt: Date.now(),
+        }).catch((e) => log(`[zerocool-claude] live handoff failed: ${e.message}`));
+    }
+}
+/** gibson_login and gibson_connect: the in-session path to a platform. */
+function registerConnectTools(server, surface, env, deps) {
+    const cli = (s) => ({ ...deps.cli, env, gibsonURL: s.platformURL, tenant: s.tenant });
+    server.registerTool("gibson_login", {
+        description: "Sign in to a Gibson platform as the person running this session. Starts the gibson CLI device " +
+            "flow and returns a URL and a code. The person opens the URL, confirms the code, and then calls " +
+            "gibson_connect. Needed once per host, and again when the login session expires.",
+        inputSchema: {
+            platform_url: z.string().optional().describe("Platform URL, e.g. https://api.example.com. Defaults to the last one used."),
+        },
+    }, async (args) => {
+        const s = surface.current().settings;
+        try {
+            const p = await startLogin({ ...deps.cli, env, gibsonURL: args.platform_url ?? s.platformURL });
+            return text("sign in", `Open ${p.url} and confirm the code ${p.code}. The CLI waits for the approval. When it is approved, call gibson_connect.`);
+        }
+        catch (e) {
+            return failure("gibson_login failed", e.message);
+        }
+    });
+    server.registerTool("gibson_connect", {
+        description: "Connect this session to a Gibson platform without a restart: enroll this host through the gibson " +
+            "CLI login session if needed, check in, pick the target, start the live mission, and add the " +
+            "platform tools (remember, recall, world_view, Gibson tools, delegation). The settings are kept, " +
+            "so later sessions connect on their own. Call gibson_status afterwards.",
+        inputSchema: {
+            platform_url: z.string().optional().describe("Platform URL. Defaults to the gibson CLI login session or the saved config."),
+            target_id: z.string().optional().describe("Target id for the live mission. Defaults to the only target in the tenant."),
+            create_target: z.string().optional().describe("Create a target with this name when none exists, and use it."),
+            bootstrap_token: z.string().optional().describe("One-time enrollment token. Only when the CLI cannot mint one."),
+            ca_cert_path: z.string().optional().describe("Path to a private CA to trust. Defaults to the CLI session's CA."),
+            callback_insecure: z.boolean().optional().describe("Dial the callback endpoint without TLS. Local daemons only."),
+        },
+    }, async (args) => {
+        const base = await loadSettings(env);
+        const s = {
+            ...base,
+            platformURL: args.platform_url ?? base.platformURL,
+            targetId: args.target_id ?? base.targetId,
+            caCertPath: args.ca_cert_path ?? base.caCertPath,
+            callbackInsecure: args.callback_insecure ?? base.callbackInsecure,
+            bootstrapToken: args.bootstrap_token ?? base.bootstrapToken,
+        };
+        if (!s.platformURL) {
+            return failure("no platform", "Pass platform_url, or call gibson_login first so the CLI session names the platform.");
+        }
+        const hostKeyExists = (deps.open?.hostKeyExists ?? existsSync)(s.hostKeyPath);
+        try {
+            if (!hostKeyExists && !s.bootstrapToken) {
+                s.bootstrapToken = await enrollIdentity(s.agentName, cli(s));
+            }
+            if (!s.targetId) {
+                if (args.create_target) {
+                    s.targetId = await createTarget(args.create_target, cli(s));
+                }
+                else {
+                    const targets = await listTargets(cli(s));
+                    if (targets.length === 1)
+                        s.targetId = targets[0].id;
+                    else if (targets.length === 0) {
+                        return failure("no target", "The tenant has no target. Call gibson_connect again with create_target set to a name for this workspace.");
+                    }
+                    else {
+                        return failure("choose a target", `The tenant has ${targets.length} targets. Call gibson_connect again with target_id:\n${targets.map((t) => `- ${t.id}  ${t.name} (${t.type}, ${t.status})`).join("\n")}`);
+                    }
+                }
+            }
+        }
+        catch (e) {
+            return failure("gibson_connect failed", e.message);
+        }
+        await writeConfig(env, {
+            platformURL: s.platformURL,
+            targetId: s.targetId,
+            ...(s.caCertPath ? { caCertPath: s.caCertPath } : {}),
+            ...(s.daemonURL ? { daemonURL: s.daemonURL } : {}),
+            callbackInsecure: s.callbackInsecure,
+        });
+        const previous = surface.current();
+        await previous.close().catch(() => { });
+        const next = await openGibson({ settings: s, log, ...deps.open });
+        await surface.upgrade(next);
+        const body = describeGibson(next);
+        return next.mode === "live" ? text("connected", body) : failure("connected, but not live", body);
+    });
+}

package/dist/cli.d.ts

@@ -0,0 +1,64 @@
+import { type ChildProcess } from "node:child_process";
+/**
+ * The `gibson` CLI as the session's user. It holds the login session
+ * (`gibson login`, a browser device flow), so it is the one process on the
+ * host that can mint an enrollment token or create a target. The plugin
+ * drives it instead of asking a person to copy tokens between terminals.
+ */
+export type Spawn = (cmd: string, args: string[], opts: {
+    detached?: boolean;
+    env?: NodeJS.ProcessEnv;
+}) => ChildProcess;
+export interface CliOptions {
+    bin?: string;
+    env?: NodeJS.ProcessEnv;
+    spawn?: Spawn;
+    timeoutMs?: number;
+}
+export interface CliResult {
+    code: number;
+    stdout: string;
+    stderr: string;
+}
+export declare function runGibson(args: string[], opts?: CliOptions): Promise<CliResult>;
+/** True when the CLI's failure reads as "no login session". */
+export declare function needsLogin(r: CliResult): boolean;
+/**
+ * `gibson agent enroll`: mint a one-time bootstrap token for a new machine
+ * identity, authenticated as the person who ran `gibson login`.
+ */
+export declare function enrollIdentity(name: string, opts?: CliOptions & {
+    gibsonURL?: string;
+    tenant?: string;
+}): Promise<string>;
+export interface Target {
+    id: string;
+    name: string;
+    type: string;
+    status: string;
+}
+/** `gibson target list`, a tabwriter table: UUID NAME TYPE STATUS. */
+export declare function parseTargetList(stdout: string): Target[];
+export declare function listTargets(opts?: CliOptions & {
+    gibsonURL?: string;
+    tenant?: string;
+}): Promise<Target[]>;
+/** `gibson target create`: prints the new target id. */
+export declare function createTarget(name: string, opts?: CliOptions & {
+    gibsonURL?: string;
+    tenant?: string;
+    type?: string;
+}): Promise<string>;
+export interface LoginPrompt {
+    url: string;
+    code: string;
+}
+/**
+ * `gibson login`: a browser device flow. The CLI prints a URL and a code, then
+ * waits for the approval. This starts it detached, returns the URL and code
+ * as soon as they appear, and leaves the CLI waiting so the session lands in
+ * `~/.gibson/auth/credentials` when the person approves.
+ */
+export declare function startLogin(opts?: CliOptions & {
+    gibsonURL?: string;
+}): Promise<LoginPrompt>;

package/dist/cli.js

@@ -0,0 +1,130 @@
+import { spawn as nodeSpawn } from "node:child_process";
+export async function runGibson(args, opts = {}) {
+    const spawn = opts.spawn ?? nodeSpawn;
+    const child = spawn(opts.bin ?? opts.env?.GIBSON_CLI ?? "gibson", args, { env: opts.env ?? process.env });
+    return await new Promise((resolve, reject) => {
+        const out = [];
+        const err = [];
+        const timer = setTimeout(() => {
+            child.kill();
+            reject(new Error(`gibson ${args[0] ?? ""} ${args[1] ?? ""} timed out after ${opts.timeoutMs ?? 60_000}ms`));
+        }, opts.timeoutMs ?? 60_000);
+        child.stdout?.on("data", (d) => out.push(d.toString()));
+        child.stderr?.on("data", (d) => err.push(d.toString()));
+        child.on("error", (e) => {
+            clearTimeout(timer);
+            reject(new Error(`cannot run the gibson CLI (${e.message}). Install it: see https://github.com/zeroroot-ai/adk`));
+        });
+        child.on("exit", (code) => {
+            clearTimeout(timer);
+            resolve({ code: code ?? -1, stdout: out.join(""), stderr: err.join("") });
+        });
+    });
+}
+/** True when the CLI's failure reads as "no login session". */
+export function needsLogin(r) {
+    return /login|credentials|unauthenticated|token expired|not signed in/i.test(r.stderr + r.stdout);
+}
+/**
+ * `gibson agent enroll`: mint a one-time bootstrap token for a new machine
+ * identity, authenticated as the person who ran `gibson login`.
+ */
+export async function enrollIdentity(name, opts = {}) {
+    const args = ["agent", "enroll", "--name", name, "--kind", "agent"];
+    if (opts.gibsonURL)
+        args.push("--gibson-url", opts.gibsonURL);
+    if (opts.tenant)
+        args.push("--tenant", opts.tenant);
+    const r = await runGibson(args, opts);
+    const m = /^bootstrap_token:\s*(\S+)/m.exec(r.stdout);
+    if (r.code !== 0 || !m) {
+        const why = (r.stderr || r.stdout).trim();
+        throw new Error(needsLogin(r)
+            ? `the gibson CLI has no login session (${why}). Call gibson_login first.`
+            : `gibson agent enroll failed (exit ${r.code}): ${why || "no bootstrap_token in the output"}`);
+    }
+    return m[1];
+}
+/** `gibson target list`, a tabwriter table: UUID NAME TYPE STATUS. */
+export function parseTargetList(stdout) {
+    return stdout
+        .split("\n")
+        .map((l) => l.trim())
+        .filter((l) => l && !/^UUID\s+NAME/.test(l))
+        .map((l) => l.split(/\s{2,}|\t/))
+        .filter((cols) => cols.length >= 2)
+        .map(([id, name, type, status]) => ({ id: id, name: name ?? "", type: type ?? "", status: status ?? "" }));
+}
+export async function listTargets(opts = {}) {
+    const args = ["target", "list"];
+    if (opts.gibsonURL)
+        args.push("--gibson-url", opts.gibsonURL);
+    if (opts.tenant)
+        args.push("--tenant", opts.tenant);
+    const r = await runGibson(args, opts);
+    if (r.code !== 0) {
+        const why = (r.stderr || r.stdout).trim();
+        throw new Error(needsLogin(r) ? `the gibson CLI has no login session (${why}). Call gibson_login first.` : `gibson target list failed: ${why}`);
+    }
+    return parseTargetList(r.stdout);
+}
+/** `gibson target create`: prints the new target id. */
+export async function createTarget(name, opts = {}) {
+    const args = ["target", "create", "--name", name, "--type", opts.type ?? "custom"];
+    if (opts.gibsonURL)
+        args.push("--gibson-url", opts.gibsonURL);
+    if (opts.tenant)
+        args.push("--tenant", opts.tenant);
+    const r = await runGibson(args, opts);
+    const id = r.stdout.trim().split("\n").pop()?.trim() ?? "";
+    if (r.code !== 0 || !id) {
+        const why = (r.stderr || r.stdout).trim();
+        throw new Error(needsLogin(r) ? `the gibson CLI has no login session (${why}). Call gibson_login first.` : `gibson target create failed: ${why}`);
+    }
+    return id;
+}
+/**
+ * `gibson login`: a browser device flow. The CLI prints a URL and a code, then
+ * waits for the approval. This starts it detached, returns the URL and code
+ * as soon as they appear, and leaves the CLI waiting so the session lands in
+ * `~/.gibson/auth/credentials` when the person approves.
+ */
+export async function startLogin(opts = {}) {
+    const spawn = opts.spawn ?? nodeSpawn;
+    const args = ["login"];
+    if (opts.gibsonURL)
+        args.push("--gibson-url", opts.gibsonURL);
+    const child = spawn(opts.bin ?? opts.env?.GIBSON_CLI ?? "gibson", args, { detached: true, env: opts.env ?? process.env });
+    return await new Promise((resolve, reject) => {
+        let buf = "";
+        const timer = setTimeout(() => {
+            child.kill();
+            reject(new Error(`gibson login printed no device code within ${opts.timeoutMs ?? 30_000}ms: ${buf.trim()}`));
+        }, opts.timeoutMs ?? 30_000);
+        const check = () => {
+            const url = /open:\s*\n?\s*(https?:\/\/\S+)/.exec(buf);
+            const code = /confirm this code:\s*(\S+)/.exec(buf);
+            if (url && code) {
+                clearTimeout(timer);
+                child.unref();
+                resolve({ url: url[1], code: code[1] });
+            }
+        };
+        child.stdout?.on("data", (d) => {
+            buf += d.toString();
+            check();
+        });
+        child.stderr?.on("data", (d) => {
+            buf += d.toString();
+            check();
+        });
+        child.on("error", (e) => {
+            clearTimeout(timer);
+            reject(new Error(`cannot run the gibson CLI (${e.message}). Install it: see https://github.com/zeroroot-ai/adk`));
+        });
+        child.on("exit", (code) => {
+            clearTimeout(timer);
+            reject(new Error(`gibson login exited with ${code} before printing a device code: ${buf.trim()}`));
+        });
+    });
+}

package/dist/config.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Where a session learns how to reach Gibson, in precedence order:
+ *
+ *  1. the environment (`GIBSON_*`), for people who script it,
+ *  2. the plugin config this plugin wrote after a `gibson_connect`,
+ *  3. the `gibson` CLI login session (`~/.gibson/auth/credentials`), which
+ *     already knows the platform URL, the active tenant and the private CA.
+ *
+ * So a person who ran `gibson login` once needs nothing else: the plugin
+ * finds the platform through the same session the CLI uses.
+ */
+export interface PluginConfig {
+    platformURL?: string;
+    daemonURL?: string;
+    targetId?: string;
+    caCertPath?: string;
+    callbackInsecure?: boolean;
+}
+export interface CliCredentials {
+    gibsonURL?: string;
+    tenant?: string;
+    caCertPath?: string;
+}
+export interface Settings {
+    platformURL?: string;
+    daemonURL?: string;
+    targetId?: string;
+    caCertPath?: string;
+    callbackInsecure: boolean;
+    bootstrapToken?: string;
+    hostKeyPath: string;
+    agentName: string;
+    tenant?: string;
+}
+export declare const DEFAULT_AGENT_NAME = "zerocool-claude";
+export declare function configPath(env: NodeJS.ProcessEnv): string;
+export declare function readConfig(env: NodeJS.ProcessEnv): Promise<PluginConfig>;
+/** Merge and persist. Only the keys given change. */
+export declare function writeConfig(env: NodeJS.ProcessEnv, patch: PluginConfig): Promise<PluginConfig>;
+export declare function cliCredentialsPath(env: NodeJS.ProcessEnv): string;
+/** The `gibson` CLI login session, addressing fields only. Tokens are never read. */
+export declare function cliCredentials(env: NodeJS.ProcessEnv): Promise<CliCredentials | undefined>;
+export declare function resolveSettings(env: NodeJS.ProcessEnv, cfg: PluginConfig, creds: CliCredentials | undefined): Settings;
+export declare function loadSettings(env: NodeJS.ProcessEnv): Promise<Settings>;

package/dist/config.js

@@ -0,0 +1,53 @@
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { stateDir } from "./state.js";
+export const DEFAULT_AGENT_NAME = "zerocool-claude";
+export function configPath(env) {
+    return join(stateDir(env), "config.json");
+}
+export async function readConfig(env) {
+    try {
+        return JSON.parse(await readFile(configPath(env), "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+/** Merge and persist. Only the keys given change. */
+export async function writeConfig(env, patch) {
+    const merged = { ...(await readConfig(env)), ...patch };
+    await mkdir(stateDir(env), { recursive: true, mode: 0o700 });
+    await writeFile(configPath(env), `${JSON.stringify(merged, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+    return merged;
+}
+export function cliCredentialsPath(env) {
+    return env.GIBSON_CLI_CREDENTIALS ?? join(homedir(), ".gibson", "auth", "credentials");
+}
+/** The `gibson` CLI login session, addressing fields only. Tokens are never read. */
+export async function cliCredentials(env) {
+    try {
+        const raw = JSON.parse(await readFile(cliCredentialsPath(env), "utf8"));
+        const str = (k) => (typeof raw[k] === "string" && raw[k] ? raw[k] : undefined);
+        return { gibsonURL: str("gibson_url"), tenant: str("active_tenant"), caCertPath: str("ca_cert_path") };
+    }
+    catch {
+        return undefined;
+    }
+}
+export function resolveSettings(env, cfg, creds) {
+    return {
+        platformURL: env.GIBSON_PLATFORM_URL ?? cfg.platformURL ?? creds?.gibsonURL,
+        daemonURL: env.GIBSON_DAEMON_URL ?? cfg.daemonURL,
+        targetId: env.GIBSON_TARGET_ID ?? cfg.targetId,
+        caCertPath: env.GIBSON_CA_CERT ?? cfg.caCertPath ?? creds?.caCertPath,
+        callbackInsecure: env.GIBSON_CALLBACK_INSECURE === "1" || cfg.callbackInsecure === true,
+        bootstrapToken: env.GIBSON_BOOTSTRAP_TOKEN,
+        hostKeyPath: env.GIBSON_HOST_KEY_PATH ?? join(homedir(), ".zerocool", "host.key"),
+        agentName: env.ZEROCOOL_AGENT_NAME ?? DEFAULT_AGENT_NAME,
+        tenant: creds?.tenant,
+    };
+}
+export async function loadSettings(env) {
+    return resolveSettings(env, await readConfig(env), await cliCredentials(env));
+}

package/dist/hook-run.d.ts

@@ -0,0 +1,21 @@
+import { readFile } from "node:fs/promises";
+/**
+ * The hook bin. Claude Code runs it as a separate process per event, with the
+ * event on stdin. It never talks to the MCP server. It reads what the server
+ * handed off through the state directory (state.ts) and fails open: a missing
+ * file means no output, and no output blocks nothing.
+ *
+ *  - SessionStart: inject the ambient knowledge block as additionalContext.
+ *  - SessionEnd: checkpoint the transcript to the daemon session store under
+ *    the live mission's task grant (zerocool-plugins#13, the session seam).
+ */
+export interface HookInput {
+    session_id?: string;
+    hook_event_name?: string;
+    cwd?: string;
+    transcript_path?: string;
+    reason?: string;
+}
+export declare function runHook(input: HookInput, env: NodeJS.ProcessEnv, deps?: {
+    readFile: typeof readFile;
+}): Promise<string>;

package/dist/hook-run.js

@@ -0,0 +1,51 @@
+import { readFile } from "node:fs/promises";
+import { openTaskHarness } from "@zeroroot-ai/sdk";
+import { readAmbient, readLive, stateDir } from "./state.js";
+/** The session store caps a blob at 8 MiB (gibson callback_session_context.go). */
+const MAX_TRANSCRIPT_BYTES = 8 * 1024 * 1024;
+export async function runHook(input, env, deps = { readFile }) {
+    const cwd = input.cwd ?? process.cwd();
+    const dir = stateDir(env);
+    switch (input.hook_event_name) {
+        case "SessionStart": {
+            const block = await readAmbient(dir, cwd);
+            if (!block)
+                return "";
+            return JSON.stringify({ hookSpecificOutput: { hookEventName: "SessionStart", additionalContext: block } });
+        }
+        case "SessionEnd": {
+            const live = await readLive(dir, cwd);
+            if (!live || !input.transcript_path || !input.session_id)
+                return "";
+            let data;
+            try {
+                data = await deps.readFile(input.transcript_path);
+            }
+            catch {
+                return "";
+            }
+            if (data.byteLength > MAX_TRANSCRIPT_BYTES)
+                data = data.subarray(data.byteLength - MAX_TRANSCRIPT_BYTES);
+            const harness = openTaskHarness({ endpoint: live.endpoint, token: live.token, insecure: live.insecure, renew: false });
+            try {
+                const res = await harness.client.putSessionContext({
+                    context: harness.context,
+                    sessionId: input.session_id,
+                    data: new Uint8Array(data),
+                    ifMatch: "",
+                });
+                if (res.error)
+                    return JSON.stringify({ systemMessage: `zerocool: session checkpoint refused: ${res.error.message}` });
+            }
+            catch (e) {
+                return JSON.stringify({ systemMessage: `zerocool: session checkpoint failed: ${e.message}` });
+            }
+            finally {
+                harness.stop();
+            }
+            return "";
+        }
+        default:
+            return "";
+    }
+}

package/dist/hook.d.ts

@@ -1,23 +1,2 @@
 #!/usr/bin/env node
-import { readFile } from "node:fs/promises";
-/**
- * The hook bin. Claude Code runs it as a separate process per event, with the
- * event on stdin. It never talks to the MCP server. It reads what the server
- * handed off through the state directory (state.ts) and fails open: a missing
- * file means no output, and no output blocks nothing.
- *
- *  - SessionStart: inject the ambient knowledge block as additionalContext.
- *  - SessionEnd: checkpoint the transcript to the daemon session store under
- *    the live mission's task grant (zerocool-plugins#13, the session seam).
- */
-interface HookInput {
-    session_id?: string;
-    hook_event_name?: string;
-    cwd?: string;
-    transcript_path?: string;
-    reason?: string;
-}
-export declare function runHook(input: HookInput, env: NodeJS.ProcessEnv, deps?: {
-    readFile: typeof readFile;
-}): Promise<string>;
 export {};

package/dist/hook.js

@@ -1,72 +1,24 @@
 #!/usr/bin/env node
-import { readFile } from "node:fs/promises";
-import { openTaskHarness } from "@zeroroot-ai/sdk";
-import { readAmbient, readLive, stateDir } from "./state.js";
-/** The session store caps a blob at 8 MiB (gibson callback_session_context.go). */
-const MAX_TRANSCRIPT_BYTES = 8 * 1024 * 1024;
-export async function runHook(input, env, deps = { readFile }) {
-    const cwd = input.cwd ?? process.cwd();
-    const dir = stateDir(env);
-    switch (input.hook_event_name) {
-        case "SessionStart": {
-            const block = await readAmbient(dir, cwd);
-            if (!block)
-                return "";
-            return JSON.stringify({ hookSpecificOutput: { hookEventName: "SessionStart", additionalContext: block } });
-        }
-        case "SessionEnd": {
-            const live = await readLive(dir, cwd);
-            if (!live || !input.transcript_path || !input.session_id)
-                return "";
-            let data;
-            try {
-                data = await deps.readFile(input.transcript_path);
-            }
-            catch {
-                return "";
-            }
-            if (data.byteLength > MAX_TRANSCRIPT_BYTES)
-                data = data.subarray(data.byteLength - MAX_TRANSCRIPT_BYTES);
-            const harness = openTaskHarness({ endpoint: live.endpoint, token: live.token, insecure: live.insecure, renew: false });
-            try {
-                const res = await harness.client.putSessionContext({
-                    context: harness.context,
-                    sessionId: input.session_id,
-                    data: new Uint8Array(data),
-                    ifMatch: "",
-                });
-                if (res.error)
-                    return JSON.stringify({ systemMessage: `zerocool: session checkpoint refused: ${res.error.message}` });
-            }
-            catch (e) {
-                return JSON.stringify({ systemMessage: `zerocool: session checkpoint failed: ${e.message}` });
-            }
-            finally {
-                harness.stop();
-            }
-            return "";
-        }
-        default:
-            return "";
-    }
-}
+import { runHook } from "./hook-run.js";
+/**
+ * The hook bin. Runs unconditionally: npm installs it as a symlink named
+ * `zerocool-claude-hook`, so an argv[1] guard would never match. Library
+ * code lives in hook-run.ts.
+ */
 async function readStdin() {
     const chunks = [];
     for await (const c of process.stdin)
         chunks.push(c);
     return Buffer.concat(chunks).toString("utf8");
 }
-const invokedDirectly = process.argv[1]?.endsWith("hook.js") ?? false;
-if (invokedDirectly) {
-    readStdin()
-        .then((raw) => runHook(raw ? JSON.parse(raw) : {}, process.env))
-        .then((out) => {
-        if (out)
-            process.stdout.write(out);
-        process.exit(0);
-    })
-        .catch((e) => {
-        process.stderr.write(`[zerocool-claude hook] ${e.message}\n`);
-        process.exit(0); // fail open: a hook error must not block the session
-    });
-}
+readStdin()
+    .then((raw) => runHook(raw ? JSON.parse(raw) : {}, process.env))
+    .then((out) => {
+    if (out)
+        process.stdout.write(out);
+    process.exit(0);
+})
+    .catch((e) => {
+    process.stderr.write(`[zerocool-claude hook] ${e.message}\n`);
+    process.exit(0); // fail open: a hook error must not block the session
+});

package/dist/index.d.ts

@@ -2,4 +2,7 @@ export * from "./mode.js";
 export * from "./session.js";
 export * from "./state.js";
 export * from "./ambient.js";
-export { buildServer } from "./server.js";
+export * from "./config.js";
+export * from "./cli.js";
+export { buildServer } from "./build.js";
+export { runHook } from "./hook-run.js";

package/dist/index.js

@@ -4,4 +4,7 @@ export * from "./mode.js";
 export * from "./session.js";
 export * from "./state.js";
 export * from "./ambient.js";
-export { buildServer } from "./server.js";
+export * from "./config.js";
+export * from "./cli.js";
+export { buildServer } from "./build.js";
+export { runHook } from "./hook-run.js";

package/dist/server.d.ts

@@ -1,7 +1,2 @@
 #!/usr/bin/env node
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { type Gibson } from "./session.js";
-export declare function buildServer(env: NodeJS.ProcessEnv, cwd: string): Promise<{
-    server: McpServer;
-    gibson: Gibson;
-}>;
+export {};

package/dist/server.js

@@ -1,76 +1,26 @@
 #!/usr/bin/env node
-import { homedir } from "node:os";
-import { join } from "node:path";
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { ambientBlock } from "./ambient.js";
-import { openGibson } from "./session.js";
-import { clearLive, stateDir, writeAmbient, writeLive } from "./state.js";
-import { registerComponentizeTool, registerEnrollTool } from "./tools/componentize.js";
-import { registerDelegationTools } from "./tools/delegate.js";
-import { gibsonFindingsBackend, localFindingsBackend, registerFindingTools } from "./tools/findings.js";
-import { registerGibsonTools } from "./tools/gibson-tools.js";
-import { registerMemoryTools } from "./tools/memory.js";
-import { describeGibson, registerStatusTool } from "./tools/status.js";
+import { buildServer, log } from "./build.js";
+import { clearLive, stateDir } from "./state.js";
+import { describeGibson } from "./tools/status.js";
 /**
- * @zeroroot-ai/zerocool-claude: the MCP server Claude Code starts for a session.
- *
- * The model stays on the user's Claude subscription. This server adds Gibson:
- * one live mission per session, memory and knowledge, findings, tools,
- * delegation. It never routes LLM traffic and never reads an Anthropic key
- * (ADR-0007).
+ * The MCP server bin. This file runs main() unconditionally: npm installs
+ * bins as symlinks named after the bin (`zerocool-claude-mcp`), so any
+ * "am I the entry point" check on argv[1] is false there and the process
+ * exits before it serves anything. Library code lives in build.ts.
  */
-const log = (line) => {
-    process.stderr.write(`${line}\n`);
-};
-export async function buildServer(env, cwd) {
-    const gibson = await openGibson({ env, log });
-    const server = new McpServer({ name: "zerocool", version: "0.0.0" });
-    registerStatusTool(server, gibson);
-    registerComponentizeTool(server, cwd);
-    if (!gibson.session) {
-        registerFindingTools(server, gibson, localFindingsBackend(env.ZEROCOOL_FINDINGS_LOG ?? join(homedir(), ".zerocool", "findings.jsonl")));
-        return { server, gibson };
-    }
-    registerFindingTools(server, gibson, gibsonFindingsBackend(gibson));
-    registerMemoryTools(server, gibson);
-    registerEnrollTool(server, gibson.session);
-    registerDelegationTools(server, gibson.session);
-    const discovery = await registerGibsonTools(server, gibson.session);
-    log(discovery.note ? `[zerocool-claude] Gibson tool discovery: ${discovery.note}` : `[zerocool-claude] ${discovery.discovered} Gibson tool(s) registered`);
-    // Handoff for the hooks: the ambient block now, the live coordinates while
-    // the mission runs. Both fail open.
-    const dir = stateDir(env);
-    if (gibson.knowledge) {
-        const block = await ambientBlock(gibson.knowledge, env.ZEROCOOL_AMBIENT_QUERY ?? "memories, prior findings and security facts for this codebase");
-        if (block)
-            await writeAmbient(dir, cwd, block).catch((e) => log(`[zerocool-claude] ambient handoff failed: ${e.message}`));
-    }
-    if (gibson.live) {
-        const live = gibson.live;
-        const write = () => writeLive(dir, cwd, {
-            missionId: live.missionId,
-            workId: live.workId,
-            endpoint: live.harness.endpoint,
-            token: live.harness.token(),
-            insecure: env.GIBSON_CALLBACK_INSECURE === "1",
-            writtenAt: Date.now(),
-        }).catch((e) => log(`[zerocool-claude] live handoff failed: ${e.message}`));
-        await write();
-    }
-    return { server, gibson };
-}
 async function main() {
     const cwd = process.cwd();
-    const { server, gibson } = await buildServer(process.env, cwd);
-    log(`[zerocool-claude] ${describeGibson(gibson).replaceAll("\n", "; ")}`);
+    const surface = await buildServer(process.env, cwd);
+    const { server } = surface;
+    log(`[zerocool-claude] ${describeGibson(surface.current()).replaceAll("\n", "; ")}`);
     let closing = false;
     const close = async () => {
         if (closing)
             return;
         closing = true;
         await clearLive(stateDir(process.env), cwd).catch(() => { });
-        await gibson.close().catch((e) => log(`[zerocool-claude] close: ${e.message}`));
+        await surface.current().close().catch((e) => log(`[zerocool-claude] close: ${e.message}`));
     };
     // Claude Code ends the session by closing stdio. The mission ends with it.
     process.stdin.on("close", () => void close().finally(() => process.exit(0)));
@@ -78,10 +28,7 @@ async function main() {
         process.on(sig, () => void close().finally(() => process.exit(0)));
     await server.connect(new StdioServerTransport());
 }
-const invokedDirectly = process.argv[1]?.endsWith("server.js") ?? false;
-if (invokedDirectly) {
-    main().catch((e) => {
-        log(`[zerocool-claude] fatal: ${e.message}`);
-        process.exit(1);
-    });
-}
+main().catch((e) => {
+    log(`[zerocool-claude] fatal: ${e.message}`);
+    process.exit(1);
+});

package/dist/session.d.ts

@@ -1,11 +1,14 @@
 import { connectGibson, startLiveMission, type GibsonSession, type KnowledgeSource, type LiveMission } from "@zeroroot-ai/sdk";
+import type { Settings } from "./config.js";
 import { type Mode } from "./mode.js";
-/** Everything the tools need, decided once at start. */
+export { DEFAULT_AGENT_NAME } from "./config.js";
+/** Everything the tools need, decided once per connect. */
 export interface Gibson {
     mode: Mode;
     reason: string;
     agentName: string;
     hostKeyPath: string;
+    settings: Settings;
     session?: GibsonSession;
     live?: LiveMission;
     knowledge?: KnowledgeSource;
@@ -13,14 +16,14 @@ export interface Gibson {
     close(): Promise<void>;
 }
 export interface OpenGibsonOptions {
-    env: NodeJS.ProcessEnv;
+    settings: Settings;
     log: (line: string) => void;
     /** Test seams. */
     connect?: typeof connectGibson;
     start?: typeof startLiveMission;
     hostKeyExists?: (path: string) => boolean;
+    trust?: (path: string) => Promise<void>;
 }
-export declare const DEFAULT_AGENT_NAME = "zerocool-claude";
 /**
  * Check in, then make the session a live mission. Fails open at every step:
  * a platform failure lands one posture down, never in a refusal to start.

package/dist/session.js

@@ -1,48 +1,43 @@
 import { existsSync } from "node:fs";
-import { homedir } from "node:os";
-import { join } from "node:path";
 import { componentKnowledge, connectGibson, startLiveMission, taskKnowledge, } from "@zeroroot-ai/sdk";
 import { decideMode } from "./mode.js";
-export const DEFAULT_AGENT_NAME = "zerocool-claude";
+import { trustCA } from "./tls.js";
+export { DEFAULT_AGENT_NAME } from "./config.js";
 /**
  * Check in, then make the session a live mission. Fails open at every step:
  * a platform failure lands one posture down, never in a refusal to start.
  */
 export async function openGibson(opts) {
-    const { env, log } = opts;
-    const hostKeyPath = env.GIBSON_HOST_KEY_PATH ?? join(homedir(), ".zerocool", "host.key");
+    const { settings, log } = opts;
+    const { hostKeyPath, agentName } = settings;
     const hostKeyExists = (opts.hostKeyExists ?? existsSync)(hostKeyPath);
-    const agentName = env.ZEROCOOL_AGENT_NAME ?? DEFAULT_AGENT_NAME;
-    const decision = decideMode({
-        platformURL: env.GIBSON_PLATFORM_URL,
-        bootstrapToken: env.GIBSON_BOOTSTRAP_TOKEN,
-        hostKeyExists,
-        targetId: env.GIBSON_TARGET_ID,
-    }, hostKeyPath);
-    const standalone = (reason) => ({
-        mode: "standalone",
-        reason,
-        agentName,
-        hostKeyPath,
-        close: async () => { },
-    });
+    const decision = decideMode({ platformURL: settings.platformURL, bootstrapToken: settings.bootstrapToken, hostKeyExists, targetId: settings.targetId }, hostKeyPath);
+    const standalone = (reason) => ({ mode: "standalone", reason, agentName, hostKeyPath, settings, close: async () => { } });
     if (decision.mode === "standalone") {
         log(`[zerocool-claude] standalone: ${decision.reason}`);
         return standalone(decision.reason);
     }
+    if (settings.caCertPath) {
+        try {
+            await (opts.trust ?? trustCA)(settings.caCertPath);
+        }
+        catch (e) {
+            log(`[zerocool-claude] CA at ${settings.caCertPath} not loaded: ${e.message}`);
+        }
+    }
     // The bootstrap token is passed ONLY when no host key exists yet. Replaying a
     // one-time token on every start would be rejected (gibson
     // capabilitygrant_register.go:134-155).
-    const bootstrapToken = hostKeyExists ? undefined : env.GIBSON_BOOTSTRAP_TOKEN;
+    const bootstrapToken = hostKeyExists ? undefined : settings.bootstrapToken;
     let session;
     try {
         session = await (opts.connect ?? connectGibson)({
-            platformURL: env.GIBSON_PLATFORM_URL,
-            daemonURL: env.GIBSON_DAEMON_URL,
+            platformURL: settings.platformURL,
+            daemonURL: settings.daemonURL,
             bootstrapToken,
             hostKeyPath,
             agentName,
-            agentMode: env.GIBSON_AGENT_MODE ?? "interactive",
+            agentMode: "interactive",
             agent: { name: agentName, version: "0.0.0", capabilities: ["code"] },
         });
     }
@@ -53,14 +48,14 @@ export async function openGibson(opts) {
     }
     log(`[zerocool-claude] checked in via ${hostKeyExists ? "the registered host key" : "first check-in"} ` +
         `as ${agentName} (component_scope=${session.componentScope})`);
-    if (!hostKeyExists) {
-        log(`[zerocool-claude] host key written to ${hostKeyPath}; unset GIBSON_BOOTSTRAP_TOKEN, it is spent`);
-    }
+    if (!hostKeyExists)
+        log(`[zerocool-claude] host key written to ${hostKeyPath}; the bootstrap token is spent`);
     const component = {
         mode: "component",
         reason: decision.reason,
         agentName,
         hostKeyPath,
+        settings,
         session,
         knowledge: componentKnowledge(session.clients.component),
         close: async () => session.stop(),
@@ -73,8 +68,8 @@ export async function openGibson(opts) {
     try {
         live = await (opts.start ?? startLiveMission)(session, {
             agentName,
-            targetId: env.GIBSON_TARGET_ID,
-            harness: { insecure: env.GIBSON_CALLBACK_INSECURE === "1" },
+            targetId: settings.targetId,
+            harness: { insecure: settings.callbackInsecure },
         });
     }
     catch (e) {
@@ -89,6 +84,7 @@ export async function openGibson(opts) {
         reason: "",
         agentName,
         hostKeyPath,
+        settings,
         session,
         live,
         knowledge: taskKnowledge(live.harness),

package/dist/tls.d.ts

@@ -0,0 +1 @@
+export declare function trustCA(path: string): Promise<void>;

package/dist/tls.js

@@ -0,0 +1,19 @@
+import { readFile } from "node:fs/promises";
+import tls from "node:tls";
+/**
+ * Trust a private CA for every TLS client in this process, at runtime.
+ *
+ * A self-hosted Gibson (kind, on-prem) fronts its edge with its own CA. Node
+ * reads NODE_EXTRA_CA_CERTS only at start, and the connect happens mid-session,
+ * so the CA is added through `tls.setDefaultCACertificates` (Node 22.15+).
+ * Both `fetch` (the Capability Grant register call) and the gRPC transports
+ * use the default CA set, so one call covers all of them.
+ */
+const trusted = new Set();
+export async function trustCA(path) {
+    if (trusted.has(path))
+        return;
+    const pem = await readFile(path, "utf8");
+    tls.setDefaultCACertificates([...tls.getCACertificates("default"), pem]);
+    trusted.add(path);
+}

package/dist/tools/status.d.ts

@@ -1,5 +1,5 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { Gibson } from "../session.js";
 /** One tool that says what posture this session runs in and why. */
-export declare function registerStatusTool(server: McpServer, g: Gibson): void;
+export declare function registerStatusTool(server: McpServer, current: () => Gibson): void;
 export declare function describeGibson(g: Gibson): string;

package/dist/tools/status.js

@@ -1,7 +1,7 @@
 import { text } from "./result.js";
 /** One tool that says what posture this session runs in and why. */
-export function registerStatusTool(server, g) {
-    server.registerTool("gibson_status", { description: "Show how this session is connected to Gibson: standalone, component, or a live mission, and what is missing if anything.", inputSchema: {} }, async () => text("", describeGibson(g)));
+export function registerStatusTool(server, current) {
+    server.registerTool("gibson_status", { description: "Show how this session is connected to Gibson: standalone, component, or a live mission, and what is missing if anything.", inputSchema: {} }, async () => text("", describeGibson(current())));
 }
 export function describeGibson(g) {
     const lines = [`posture: ${g.mode}`, `agent: ${g.agentName}`];
@@ -11,6 +11,10 @@ export function describeGibson(g) {
         const exp = g.live.harness.expiresAt();
         lines.push(`mission: ${g.live.missionId}`, `work: ${g.live.workId}`, `grant expires: ${exp ? new Date(exp).toISOString() : "unknown"}`);
     }
+    if (g.settings.platformURL)
+        lines.push(`platform: ${g.settings.platformURL}`);
+    if (g.settings.targetId)
+        lines.push(`target: ${g.settings.targetId}`);
     if (g.reason)
         lines.push(`note: ${g.reason}`);
     return lines.join("\n");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeroroot-ai/zerocool-claude",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Claude Code plugin: Gibson platform integration (zerocool). The session is a live mission. Memory, knowledge, findings, tools, delegation. The model stays on your Claude subscription.",
   "license": "MIT",
   "repository": {