@nurix/nustack 0.23.8 → 0.23.10

package/dist/index.js

@@ -1,453 +1,10 @@
 #!/usr/bin/env node
-import { readFileSync } from "node:fs";
-import { Command } from "commander";
-import { runLogin } from "./commands/login.js";
-import { runInit } from "./commands/init.js";
-import { runAdd } from "./commands/add.js";
-import { runList } from "./commands/list.js";
-import { runSync } from "./commands/sync.js";
-import { runDescribe } from "./commands/describe.js";
-import { runValidate } from "./commands/validate.js";
-import { runGraph } from "./commands/graph.js";
-import { runLogscope } from "./commands/logscope.js";
-import { runDoctor } from "./commands/doctor.js";
-import { runTokenCreate, runTokenList, runTokenRevoke } from "./commands/token.js";
-import { runOpen } from "./commands/open.js";
-import { runBootstrap } from "./commands/bootstrap.js";
-import { runLogout } from "./commands/logout.js";
-import { runTelemetry } from "./commands/telemetry.js";
-import { runSearch, runSearchServices } from "./commands/search.js";
-import { runDeviceList, runDeviceRevoke, runDeviceStatus } from "./commands/device.js";
-import { registerProjectSyncCommands } from "./commands/project-sync.js";
-import { registerProjectCommands } from "./commands/project.js";
-import { registerDeployCommands, registerLogsCommand, registerProjectSetCommand } from "./commands/deploy.js";
-import { registerActivityCommand } from "./commands/activity.js";
-import { registerWhoamiCommand } from "./commands/whoami.js";
-import { registerApiCommand } from "./commands/api.js";
-import { registerMcpCommands } from "./commands/mcp.js";
-import { NON_INTERACTIVE_VARIABLE } from "./lib/interactive.js";
-import { runOrganizationList, runOrganizationCreate, runOrganizationUse } from "./commands/organization.js";
-import { runDocsList, runDocsShow, runDocsStatus } from "./commands/docs.js";
-import { runHandoffList, runHandoffShow } from "./commands/handoff.js";
-import { runToolkitStatus, runToolkitReconcile } from "./commands/toolkit.js";
-import { runHarnessMount, runHarnessStatus } from "./commands/harness.js";
-import { runSessionsList, runSessionsPrune, runSessionsRecord, runSessionsServe, } from "./commands/sessions.js";
-import { registerReviewCommands } from "./commands/review.js";
-import { registerRecordsCommands, startDrainIfDue } from "./commands/records.js";
-import { RECORD_ALIAS_GROUPS, registerRecordAliases } from "./commands/recordAliases.js";
-import { runAgentContext, runAgentHookInstall, runAgentHookRemove } from "./commands/agent.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"));
-setCliVersion(version);
-const program = new Command();
-program
-    .name("nustack")
-    .description("Bootstrap NuStack services into your repo via the NuStack discovery plane.")
-    .version(version)
-    .option("--nustack-url <url>", "NuStack base URL (defaults to $NUSTACK_URL, then the hosted instance)")
-    .option("--non-interactive", `never prompt — take the default or refuse with a coded error (also $${NON_INTERACTIVE_VARIABLE}=1)`)
-    .action(async () => runBootstrap(program.opts()));
-program.addHelpText("after", "\nRun `nustack` with no command to bootstrap: it checks your sign-in, runs login if needed, then init.");
-program
-    .command("login")
-    .description("Sign in with your browser; this machine's grant is saved to your OS keychain")
-    .option("--no-open", "don't auto-open the browser; just print the sign-in URL")
-    .option("--manual", "sign in anywhere and paste the code here instead of using a browser on this machine")
-    .option("--force", "sign in again even if this machine is already signed in")
-    .action(async (options) => runLogin(program.opts(), options));
-program
-    .command("logout")
-    .description("Sign out: end this machine's grant and clear the shared keychain credential (both CLI and desktop)")
-    .option("--forget-device", "also clear the shared ~/.nustack/device_id machine identity")
-    .action(async (options) => runLogout(program.opts(), { forgetDevice: options.forgetDevice }));
-program
-    .command("init")
-    .description("Onboard this folder: sign in, then bind it to a Project (the onboarding router)")
-    .option("--organization <id>", "the Organization to create or select the Project in")
-    .option("--yes", "pre-confirm the populated-folder onboarding guard")
-    .action(async (options) => runInit({ ...program.opts(), ...options }));
-program
-    .command("add [service]")
-    .description("Record a stack service in this repo: install its package, add the consumes edge")
-    .option("--json", "emit the versioned machine envelope instead of interactive output")
-    .option("--yes", "assume yes for the package-install and manifest-scaffold prompts")
-    .action(async (service, options) => runAdd(service, { ...program.opts(), ...options }));
-program
-    .command("list")
-    .description("List the services in the NuStack catalogue")
-    .option("--json", "emit the versioned machine envelope wrapping the catalogue entries")
-    .action(async (options) => runList(options, program.opts()));
-program
-    .command("sync")
-    .description("Project this Project's Service credentials into the managed .env block (not Documents or Git)")
-    .option("--project <id>", "the Project to act as (defaults to nustack.service.json / NUSTACK_WORKSPACE_ID)")
-    .option("--json", "emit the versioned machine envelope instead of interactive output")
-    .action(async (options) => runSync({ ...program.opts(), ...options }));
-program
-    .command("describe <service>")
-    .description("Show the full catalogue entry for a service")
-    .option("--json", "emit the raw catalogue entry as JSON")
-    .action(async (service, options) => runDescribe(service, options, program.opts()));
-program
-    .command("validate [manifest]")
-    .description("Validate an nustack.service.json (path or URL) against the nustack.dev/v1 schema")
-    .option("--schema <pathOrUrl>", "override the bundled packages/contracts/spec/schema.json")
-    .option("--json", "emit the versioned machine envelope with { target, isValid, errors }")
-    .action(async (manifest, options) => runValidate(manifest, options));
-program
-    .command("graph [fn] [args...]")
-    .description("The code graph: ask a question of this repository's index, or `index` / `status` / `functions`")
-    .option("--repo <pathOrId>", "the repository to ask about (default: the working tree's root)")
-    .option("--no-refresh", "answer from the index as it stands, however old")
-    .option("--budget <n>", "token ceiling for the answer; 0 means unbounded")
-    .option("--commits <n>", "history depth for `graph index` (default 5000)")
-    .option("--json", "emit the versioned machine envelope with the answer as data")
-    .allowUnknownOption()
-    .allowExcessArguments()
-    .action(async (_fn, _args, options) => runGraph(process.argv, options));
-program
-    .command("logscope [fn] [args...]")
-    .description("Log tracking: ask this machine's log corpus a question, or `index` / `corpora` / `allow` / `prune`")
-    .option("--root <dir>", "the project this command is about (default: the working tree's root)")
-    .option("--corpus <ref>", "a corpus id, or a path belonging to one")
-    .option("--budget <n>", "token ceiling for the answer; 0 means unbounded")
-    .option("--limit <n>", "rows requested — beats a default budget, never an explicit one")
-    .option("--retain <days>", "retention for `index`; 0 keeps the corpus until it is forgotten")
-    .option("--examples", "keep up to three exemplar log lines per template (off by default)")
-    .option("--no-redact", "store exemplars unredacted (loud, recorded on the corpus)")
-    .option("--since <ts>", "window start for container sources")
-    .option("--until <ts>", "window end for container sources")
-    .option("--revision <sha>", "the source revision these logs were written by")
-    .option("--note <text>", "a note recorded with an `allow` grant")
-    .option("--dry-run", "for `prune`: report what would be dropped and delete nothing")
-    .option("--json", "emit the versioned machine envelope with the answer as data")
-    .allowUnknownOption()
-    .allowExcessArguments()
-    .action(async (_fn, _args, options) => runLogscope(process.argv, options));
-program
-    .command("doctor")
-    .description("Run the full local diagnostics matrix (identity, repository, manifests, toolkit, telemetry, credentials)")
-    .option("--project <id>", "the Project to diagnose (defaults to the bound repository)")
-    .option("--json", "emit the versioned machine envelope (secrets and absolute paths redacted)")
-    .option("--local-verbose", "include Device-local absolute paths in the output")
-    .action(async (options) => runDoctor({ ...program.opts(), ...options }));
-registerDeployCommands(program, () => program.opts());
-registerLogsCommand(program, () => program.opts());
-registerWhoamiCommand(program, () => program.opts());
-registerApiCommand(program, () => program.opts());
-registerMcpCommands(program, () => program.opts());
-program
-    .command("open <service>")
-    .description("Open the service's dev endpoint (or repository) in the browser")
-    .option("--env <name>", "pick a specific endpoint environment (default: dev)")
-    .option("--json", "print the resolved URL as the machine envelope instead of launching")
-    .action(async (service, options) => runOpen(service, options, program.opts()));
-const token = program.command("token").description("Mint, list and revoke your personal access tokens (the NUSTACK_TOKEN a pipeline or agent uses)");
-token
-    .command("create")
-    .description("Mint a personal access token; the secret is printed once, on stdout alone")
-    .requiredOption("--label <label>", "a name for the token, unique among your live ones")
-    .option("--expires <days>", "days until the token expires (1–365); no expiry when omitted")
-    .option("--json", "emit the versioned machine envelope")
-    .action(async (options) => runTokenCreate(options, program.opts()));
-token
-    .command("list")
-    .description("List your personal access tokens (never a secret)")
-    .option("--json", "emit the versioned machine envelope")
-    .action(async (options) => runTokenList(options, program.opts()));
-token
-    .command("revoke <token-id>")
-    .description("Revoke a personal access token; it stops working on the next request")
-    .option("--json", "emit the versioned machine envelope")
-    .action(async (tokenId, options) => runTokenRevoke(tokenId, options, program.opts()));
-const device = program.command("device").description("Inspect your signed-in devices and end this machine's access");
-device
-    .command("list")
-    .description("List your signed-in devices (never a token)")
-    .option("--json", "emit the versioned machine envelope")
-    .action(async (options) => runDeviceList(options, program.opts()));
-device
-    .command("status")
-    .description("Show this device's local state merged with its server record")
-    .option("--json", "emit the versioned machine envelope")
-    .action(async (options) => runDeviceStatus(options, program.opts()));
-device
-    .command("revoke [device-id]")
-    .description("End this machine's access (other machines are revoked from Profile › Devices)")
-    .option("--json", "emit the versioned machine envelope")
-    .option("--yes", "skip the confirmation prompt")
-    .action(async (deviceId, options) => runDeviceRevoke(deviceId, options, program.opts()));
-program
-    .command("telemetry [action]")
-    .description("Inspect or control telemetry (status | enable | disable | reinstall | output). Inside a bound folder, enable/disable move that folder alone; output points the shipper at your own Elastic, its key read from NUSTACK_ELASTIC_API_KEY")
-    .option("--json", "emit the versioned machine envelope")
-    .option("--device", "move this machine's switch instead of the current folder's")
-    .option("--local-verbose", "include each folder's absolute path (local consumers only — never pipe into a log)")
-    .option("--elastic-url <url>", "output: the Elastic endpoint (default NUSTACK_ELASTIC_URL)")
-    .option("--index <name>", "output: the index events are written to (default claude-sessions)")
-    .action(async (action, options) => {
-    const allowed = ["status", "enable", "disable", "reinstall", "output"];
-    const chosen = (allowed.includes(action ?? "") ? action : "status");
-    return runTelemetry(chosen, {
-        ...program.opts(),
-        json: options.json,
-        device: options.device,
-        localVerbose: options.localVerbose,
-        elasticUrl: options.elasticUrl,
-        index: options.index,
-    });
-});
-const toLimit = (value) => Number.parseInt(value, 10);
-const search = program
-    .command("search [keywords...]")
-    .description("Search the NuStack Directory for projects by keyword")
-    .option("--json", "emit the raw results array as JSON")
-    .option("--category <cat>", "filter projects by category")
-    .option("--limit <n>", "max results (default 20)", toLimit)
-    .action(async (keywords, options) => runSearch(keywords, options, program.opts()));
-search
-    .command("services [keywords...]")
-    .description("Search the services registry by keyword (then `nustack add <name>` to integrate)")
-    .option("--json", "emit the raw results array as JSON")
-    .option("--type <type>", "filter services by type")
-    .option("--limit <n>", "max results (default 20)", toLimit)
-    .action(async (keywords, options) => runSearchServices(keywords, { ...search.opts(), ...options }, program.opts()));
-search.addHelpText("after", '\n`services` is a reserved subcommand. To search projects for the literal word "services", use the\n' +
-    "explicit separator: `nustack search -- services` (everything after `--` is an projects query).");
-const organization = program.command("organization").description("Work with your NuStack Organizations");
-organization
-    .command("list")
-    .description("List your Organization memberships (name, slug, role, active marker)")
-    .option("--json", "emit the versioned machine envelope")
-    .action(async (options) => runOrganizationList(options, program.opts()));
-organization
-    .command("create <name>")
-    .description("Create an Organization and print it")
-    .option("--json", "emit the versioned machine envelope")
-    .action(async (name, options) => runOrganizationCreate(name, options, program.opts()));
-organization
-    .command("use <id-or-slug>")
-    .description("Set the active Organization context for this device")
-    .option("--json", "emit the versioned machine envelope")
-    .action(async (target, options) => runOrganizationUse(target, options, program.opts()));
-const project = program.command("project").description("Work with NuStack Projects");
-registerProjectCommands(project, () => program.opts());
-registerProjectSetCommand(project, () => program.opts());
-registerActivityCommand(project, () => program.opts());
-registerProjectSyncCommands(project, () => program.opts());
-registerReviewCommands(program.command("review").description("Read and mirror NuStack Review items"), () => program.opts());
-registerRecordsCommands(program.command("records").description("Emit, send and list harness records"), () => program.opts());
-registerRecordAliases(program, () => program.opts());
-program.hook("preAction", async (_program, action) => {
-    if (program.opts().nonInteractive)
-        process.env[NON_INTERACTIVE_VARIABLE] = "1";
-    const group = action.parent?.name() ?? "";
-    if (group !== "records" && !RECORD_ALIAS_GROUPS.includes(group))
-        await startDrainIfDue(program.opts());
-});
-const docs = program.command("docs").description("Work with a Project's Documents");
-docs
-    .command("list")
-    .description("List the Project's Documents")
-    .option("--project <id>", "the Project to act as (defaults to the bound repository)")
-    .option("--json", "emit the versioned machine envelope")
-    .action(async (options) => runDocsList(options, program.opts()));
-docs
-    .command("show <slug-or-id>")
-    .description("Show a Document: a bounded inline body or its content URL")
-    .option("--project <id>", "the Project to act as (defaults to the bound repository)")
-    .option("--json", "emit the versioned machine envelope")
-    .action(async (target, options) => runDocsShow(target, options, program.opts()));
-docs
-    .command("status")
-    .description("Report per-path local/cloud Document convergence for the bound repository")
-    .option("--project <id>", "the Project to act as (defaults to the bound repository)")
-    .option("--json", "emit the versioned machine envelope")
-    .action(async (options) => runDocsStatus(options, program.opts()));
-const handoff = program.command("handoff").description("Work with a Project's Handoffs");
-handoff
-    .command("list")
-    .description("List the Project's Handoffs")
-    .option("--project <id>", "the Project to act as (defaults to the bound repository)")
-    .option("--json", "emit the versioned machine envelope")
-    .action(async (options) => runHandoffList(options, program.opts()));
-handoff
-    .command("show <id>")
-    .description("Show a Handoff (add --targets for the binding-scoped per-target manifest)")
-    .option("--project <id>", "the Project to act as (defaults to the bound repository)")
-    .option("--targets", "list each target's path, operation, and base semantics")
-    .option("--json", "emit the versioned machine envelope")
-    .action(async (id, options) => runHandoffShow(id, options, program.opts()));
-const sessions = program
-    .command("sessions")
-    .description("Sessions on this machine — the engine the desktop drives, and the record of what ran");
-sessions
-    .command("serve")
-    .description("Run the long-lived session supervisor: JSONL frames on stdin/stdout (used by the NuStack desktop)")
-    .action(async () => runSessionsServe(version));
-sessions
-    .command("record")
-    .description("Record the sessions one desktop scan found in a bound folder (used by the NuStack desktop)")
-    .option("--scan <json>", "the scan payload as JSON, or @<path> to read it from a file")
-    .option("--json", "emit the versioned machine envelope")
-    .action(async (options) => runSessionsRecord(options, program.opts()));
-sessions
-    .command("list")
-    .description("List the sessions this machine's engine opened, and what each one's worktree and branch still hold")
-    .option("--json", "emit the versioned machine envelope")
-    .action(async (options) => runSessionsList(options));
-sessions
-    .command("prune")
-    .description("Reclaim the worktree and branch of a session that has ended (preview unless --yes)")
-    .option("--session <id>", "reclaim one session instead of every reclaimable one")
-    .option("--yes", "apply the preview without prompting")
-    .option("--force", "also reclaim an unmerged or dirty session — never one whose engine is running")
-    .option("--json", "emit the versioned machine envelope")
-    .action(async (options) => runSessionsPrune(options));
-const harness = program.command("harness").description("Mount the Project's harness and compare it with the cloud pin");
-harness
-    .command("mount [path]")
-    .description("Mount the resolved harness version into a checkout (default: the current repository)")
-    .option("--project <id>", "the Project to act as (defaults to the bound repository)")
-    .option("--manifest <url>", "mount this manifest instead of the one the Project resolves")
-    .option("--json", "emit the versioned machine envelope")
-    .action(async (target, options) => runHarnessMount(target, options, program.opts()));
-harness
-    .command("status")
-    .description("Print the mounted harness against the cloud pin; exits 1 when they differ")
-    .option("--project <id>", "the Project to act as (defaults to the bound repository)")
-    .option("--json", "emit the versioned machine envelope")
-    .action(async (options) => runHarnessStatus(options, program.opts()));
-const toolkit = program.command("toolkit").description("Inspect and reconcile the Project's toolkit pin");
-toolkit
-    .command("status")
-    .description("Compare the cloud pin against .nustack/workspace.json and nustack.service.json (F-026)")
-    .option("--project <id>", "the Project to act as (defaults to the bound repository)")
-    .option("--json", "emit the versioned machine envelope")
-    .action(async (options) => runToolkitStatus(options, program.opts()));
-toolkit
-    .command("reconcile")
-    .description("Preview and apply the deterministic toolkit repair (no User content is touched)")
-    .option("--project <id>", "the Project to act as (defaults to the bound repository)")
-    .option("--yes", "apply the deterministic preview without prompting")
-    .option("--json", "emit the versioned machine envelope")
-    .action(async (options) => runToolkitReconcile(options, program.opts()));
-const agent = program.command("agent").description("The discovery hook an agent uses to find the running NuStack desktop");
-agent
-    .command("context")
-    .description("Print the SessionStart hook payload when the NuStack desktop is reachable (silent otherwise)")
-    .action(async () => runAgentContext());
-const agentHook = agent.command("hook").description("Manage the `nustack agent context` SessionStart hook in ~/.claude/settings.json");
-agentHook
-    .command("install")
-    .description("Register the SessionStart hook (idempotent — a second install is a no-op)")
-    .action(async () => runAgentHookInstall());
-agentHook
-    .command("remove")
-    .description("Remove exactly the managed SessionStart hook entry")
-    .action(async () => runAgentHookRemove());
-function describeError(error) {
-    const directCode = error?.code;
-    if (directCode === "PROJECT_CONTEXT_MISSING") {
-        return "no Project in context — run inside a bound repository (`.nustack/workspace.json`) or pass `--project <id>`.";
-    }
-    if (directCode === "ORGANIZATION_CONTEXT_MISSING") {
-        return "no Organization in context — run `nustack organization use <id>` or pass `--organization <id>`.";
-    }
-    if (directCode === "TOOLKIT_INCOMPATIBLE") {
-        return "the installed toolkit is incompatible with the Project's cloud pin — run `nustack toolkit reconcile`.";
-    }
-    const cause = error?.cause;
-    const code = cause?.code;
-    if (code === "ENOTFOUND" || code === "EAI_AGAIN") {
-        return "couldn't resolve the NuStack host — check your connection or pass --nustack-url.";
-    }
-    if (code === "ECONNREFUSED") {
-        return "the NuStack host refused the connection — is it up? Override with --nustack-url.";
-    }
-    if (error instanceof Error && (error.name === "TimeoutError" || error.name === "AbortError")) {
-        return "the request to NuStack timed out — check your connection or try again.";
-    }
-    if (error instanceof Error && error.message === "fetch failed") {
-        return "couldn't reach NuStack — check your connection or pass --nustack-url.";
-    }
-    return error instanceof Error ? error.message : String(error);
-}
-function searchSeparatorInvocation(rawArgv) {
-    const args = rawArgv.slice(2);
-    const searchIdx = args.indexOf("search");
-    if (searchIdx === -1)
-        return null;
-    if (searchIdx > 0 && args[searchIdx - 1] === "--nustack-url")
-        return null;
-    let cut = searchIdx + 1;
-    while (cut < args.length) {
-        const token = args[cut] ?? "";
-        if (token === "--category" || token === "--limit" || token === "--nustack-url") {
-            cut += 2;
-        }
-        else if (token.startsWith("--") && token !== "--") {
-            cut += 1;
-        }
-        else {
-            break;
-        }
-    }
-    if (args[cut] !== "--")
-        return null;
-    const beforeSeparator = args.slice(0, cut);
-    const literalKeywords = args.slice(cut + 1);
-    return {
-        run: async () => {
-            const scoped = new Command();
-            scoped.exitOverride();
-            scoped.name("nustack").option("--nustack-url <url>", "");
-            scoped
-                .command("search [keywords...]")
-                .option("--json", "")
-                .option("--category <cat>", "")
-                .option("--limit <n>", "", toLimit)
-                .action(async (keywords, options) => runSearch(keywords, options, scoped.opts()));
-            await scoped.parseAsync(["node", "nustack", ...beforeSeparator, ...literalKeywords]);
-        },
-    };
-}
-function isJsonInvocation(argv) {
-    return argv.slice(2).includes("--json");
-}
-function commandLabelFromArgv(argv) {
-    const args = argv.slice(2);
-    const parts = [];
-    for (let i = 0; i < args.length; i++) {
-        const token = args[i] ?? "";
-        if (token === "--nustack-url") {
-            i++;
-            continue;
-        }
-        if (token.startsWith("-"))
-            break;
-        parts.push(token);
-    }
-    return parts.length ? parts.join(" ") : "nustack";
-}
-function errorCodeOf(error) {
-    const direct = error?.code ?? error?.cause?.code;
-    return typeof direct === "string" ? direct : "UNEXPECTED";
-}
-try {
-    const separated = searchSeparatorInvocation(process.argv);
-    if (separated)
-        await separated.run();
-    else
-        await program.parseAsync(process.argv);
-}
-catch (error) {
-    if (isJsonInvocation(process.argv)) {
-        printJsonError(commandLabelFromArgv(process.argv), { code: errorCodeOf(error), message: describeError(error) });
-    }
-    else {
-        console.error(`nustack: ${describeError(error)}`);
-        process.exitCode = 1;
-    }
+import { HOOK_SUBCOMMANDS } from "./lib/gate/subcommands.js";
+const [, , command, subcommand] = process.argv;
+if (command === "gate" && subcommand !== undefined && HOOK_SUBCOMMANDS.includes(subcommand)) {
+    const { runGateHook } = await import("./lib/gate/hook.js");
+    await runGateHook(subcommand);
+}
+else {
+    await import("./program.js");
 }

package/dist/lib/agent/claudeHooks.js

@@ -2,11 +2,14 @@ import { readFile, writeFile, mkdir } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import path from "node:path";
 const MANAGED_MARKER = "nustack:managed";
-const MANAGED_COMMAND = `nustack agent context # ${MANAGED_MARKER}`;
-function managedEntry() {
-    return { matcher: "", hooks: [{ type: "command", command: MANAGED_COMMAND }] };
+const SESSION_START_COMMAND = "nustack agent context";
+function managedEntry(matcher, command, options) {
+    const hook = { type: "command", command: `${command} # ${MANAGED_MARKER}` };
+    if (options.timeout !== undefined)
+        hook.timeout = options.timeout;
+    return { matcher, hooks: [hook] };
 }
-function isManagedEntry(entry) {
+function carriesMarker(entry) {
     if (entry === null || typeof entry !== "object")
         return false;
     const hooks = entry.hooks;
@@ -17,6 +20,12 @@ function isManagedEntry(entry) {
         typeof hook.command === "string" &&
         hook.command.includes(MANAGED_MARKER));
 }
+function isManagedEntry(entry, matcher) {
+    if (!carriesMarker(entry))
+        return false;
+    const entryMatcher = entry.matcher;
+    return (typeof entryMatcher === "string" ? entryMatcher : "") === matcher;
+}
 const DEFAULT_INDENT = 2;
 function detectIndent(raw) {
     const indented = /\n(\x20+)"/.exec(raw);
@@ -34,44 +43,55 @@ async function writeSettings(settingsPath, settings, indent) {
     await mkdir(path.dirname(settingsPath), { recursive: true });
     await writeFile(settingsPath, `${JSON.stringify(settings, null, indent)}\n`, "utf8");
 }
-export async function installSessionStartHook(settingsPath) {
+export async function installManagedHook(settingsPath, event, matcher, command, options = {}) {
     const { settings, indent } = await readSettings(settingsPath);
     const hooks = { ...(settings.hooks ?? {}) };
-    const sessionStart = Array.isArray(hooks.SessionStart) ? [...hooks.SessionStart] : [];
-    const existingIndex = sessionStart.findIndex(isManagedEntry);
-    const entry = managedEntry();
+    const entries = Array.isArray(hooks[event]) ? [...hooks[event]] : [];
+    const existingIndex = entries.findIndex((entry) => isManagedEntry(entry, matcher));
+    const entry = managedEntry(matcher, command, options);
     if (existingIndex !== -1) {
-        const current = sessionStart[existingIndex];
+        const current = entries[existingIndex];
         if (JSON.stringify(current) === JSON.stringify(entry)) {
             return { changed: false };
         }
-        sessionStart[existingIndex] = entry;
+        entries[existingIndex] = entry;
     }
     else {
-        sessionStart.push(entry);
+        entries.push(entry);
     }
-    hooks.SessionStart = sessionStart;
+    hooks[event] = entries;
     settings.hooks = hooks;
     await writeSettings(settingsPath, settings, indent);
     return { changed: true };
 }
-export async function removeSessionStartHook(settingsPath) {
+export async function removeManagedHook(settingsPath, event, matcher) {
     const { settings, indent } = await readSettings(settingsPath);
     const hooks = settings.hooks;
-    const sessionStart = hooks?.SessionStart;
-    if (!hooks || !Array.isArray(sessionStart))
+    const entries = hooks?.[event];
+    if (!hooks || !Array.isArray(entries))
         return { removed: false };
-    const filtered = sessionStart.filter((entry) => !isManagedEntry(entry));
-    if (filtered.length === sessionStart.length)
+    const filtered = entries.filter((entry) => !isManagedEntry(entry, matcher));
+    if (filtered.length === entries.length)
         return { removed: false };
     const nextHooks = { ...hooks };
     if (filtered.length > 0) {
-        nextHooks.SessionStart = filtered;
+        nextHooks[event] = filtered;
     }
     else {
-        delete nextHooks.SessionStart;
+        delete nextHooks[event];
     }
     settings.hooks = nextHooks;
     await writeSettings(settingsPath, settings, indent);
     return { removed: true };
 }
+export async function hasManagedHook(settingsPath, event, matcher) {
+    const { settings } = await readSettings(settingsPath);
+    const entries = settings.hooks?.[event];
+    return Array.isArray(entries) && entries.some((entry) => isManagedEntry(entry, matcher));
+}
+export async function installSessionStartHook(settingsPath) {
+    return installManagedHook(settingsPath, "SessionStart", "", SESSION_START_COMMAND);
+}
+export async function removeSessionStartHook(settingsPath) {
+    return removeManagedHook(settingsPath, "SessionStart", "");
+}