@indigoai-us/hq-cli 5.327.0 → 5.329.0

package/dist/commands/pack-install.js

@@ -55,6 +55,7 @@ import { formatApiKeyCapabilityDenial, peekHqApiKey, } from '../utils/resolve-va
 import { redactSecrets, SECRET_REDACTION, isMcpRegistrationEnabled, registerMcpServers, McpManifestError, } from './mcp-registration.js';
 import { listSecretCacheScopes } from '../utils/secrets-cache.js';
 import { loadRevealedSecrets } from './secrets.js';
+import { syncCodexPackHooks, syncCodexPackSkills } from '../lib/install/codex-pack-contributions.js';
 const PACK_UPDATE_CACHE_TTL_MS = 12 * 60 * 60 * 1000;
 const PACK_UPDATE_FETCH_TIMEOUT_MS = 3_000;
 const gitLsRemoteMemo = new Map();
@@ -969,7 +970,7 @@ export function validateMcpManifest(payloadDir, item) {
 // ---------------------------------------------------------------------------
 // Manifest validation (spec §Validation, 10 checks)
 // ---------------------------------------------------------------------------
-export function validateManifest(payloadDir, hqVersion) {
+export function validateManifest(payloadDir, hqVersion, options = {}) {
     // 1. parse
     const manifestPath = path.join(payloadDir, 'package.yaml');
     if (!fs.existsSync(manifestPath)) {
@@ -990,8 +991,9 @@ export function validateManifest(payloadDir, hqVersion) {
         throw new Error('package.yaml must be a YAML mapping');
     }
     // 2. name
-    if (!m.name || !/^hq-pack-[a-z0-9][a-z0-9-]*$/.test(m.name)) {
-        throw new Error(`Invalid pack name "${m.name}" — must match ^hq-pack-[a-z0-9][a-z0-9-]*$`);
+    const reservedNameAllowed = m.name === 'hq-anywhere' && options.allowReservedName === true;
+    if (!m.name || (!reservedNameAllowed && !/^hq-pack-[a-z0-9][a-z0-9-]*$/.test(m.name))) {
+        throw new Error(`Invalid pack name "${m.name}" — must match ^hq-pack-[a-z0-9][a-z0-9-]*$ or the reserved hq-anywhere pack name`);
     }
     // 3. version
     if (!m.version || !semverValid(m.version)) {
@@ -1702,7 +1704,10 @@ export async function installPack(source, opts = {}) {
                 });
                 break;
         }
-        const pkg = validateManifest(fetched.payloadDir, hqVersion);
+        // Only an explicit local directory source may use the reserved bundled
+        // pack name. Publisher is self-declared package metadata and is not proof
+        // of registry identity, so remote transports never receive this exception.
+        const pkg = validateManifest(fetched.payloadDir, hqVersion, { allowReservedName: transport === 'local' });
         // M0 — pack-to-pack dependency pre-flight. Runs BEFORE any prompts or writes
         // so a missing/unsatisfied `requires.packs` aborts with no partial state, and
         // before we bother the operator with hook/MCP trust prompts for a pack that
@@ -1753,6 +1758,14 @@ export async function installPack(source, opts = {}) {
         const stampedSource = transport === 'marketplace' ? fetched.resolvedSource : source;
         stampInstallSource(destDir, stampedSource);
         runScanPackages(hqRoot, { quiet: opts.quiet });
+        // US-014: Codex user-scope contributions are opt-in and owned by the pack.
+        // Existing Claude/HQ scan-packages behavior remains unchanged when the flag is off.
+        const codexHome = process.env.HOME ?? os.homedir();
+        const packHooks = pkg.contributes.hooks ?? [];
+        const skillWarnings = syncCodexPackSkills(destDir, pkg.name, pkg.contributes.skills ?? [], false, codexHome);
+        syncCodexPackHooks(destDir, packHooks, false, codexHome);
+        for (const warning of skillWarnings)
+            say(chalk.yellow(`  ! ${warning}`));
         // US-007 — register `contributes.mcp` servers into the shared Claude/Codex
         // agent configs. Fires HERE (after installToPackages + runScanPackages, i.e.
         // pack on disk + symlinks wired) and only once the confirmMcp gate above

package/dist/commands/packs.js

@@ -17,6 +17,7 @@
  * Spec: knowledge/public/hq-core/package-yaml-spec.md.
  */
 import * as fs from 'fs';
+import * as os from 'os';
 import * as path from 'path';
 import * as readline from 'readline';
 import { spawnSync } from 'child_process';
@@ -26,6 +27,7 @@ import { findHqRoot } from '../utils/manifest.js';
 import { resolveHqRoot as resolveDetectedHqRoot } from './doctor.js';
 import { classify, resolveLatest, resolveLatestMarketplace, runScanPackages, installPack, } from './pack-install.js';
 import { contributionLinks, linkStatus, listInstalledPacks, findDependentPacks, readPackManifest, unwirePack, unwirePackMcp, readHqVersion, readRecommendedPackages, packagesDir, } from '../utils/pack-contributions.js';
+import { syncCodexPackHooks, syncCodexPackSkills } from '../lib/install/codex-pack-contributions.js';
 function resolveRoot(opts) {
     return opts.hqRoot ? path.resolve(opts.hqRoot) : findHqRoot();
 }
@@ -247,6 +249,11 @@ async function runUpdate(name, opts) {
             continue;
         }
         try {
+            // Remove Codex registrations and skills from the old manifest before the
+            // pack directory is replaced. The replacement may rename its commands or
+            // drop contributions entirely, so the new manifest cannot clean those.
+            syncCodexPackHooks(pack.dir, m.contributes?.hooks ?? [], true);
+            syncCodexPackSkills(pack.dir, pname, m.contributes?.skills ?? [], true);
             // Un-wire old contributions first so a contribution dropped by the new
             // version doesn't leave a dangling host symlink. installPack re-wires.
             unwirePack(hqRoot, pack.dir, m.contributes ?? {});
@@ -303,6 +310,16 @@ async function runUninstall(name, opts) {
     }
     // 1. Un-wire only our symlinks.
     const { unlinked, skipped } = unwirePack(hqRoot, packDir, contributes);
+    // Remove Codex user-scope contributions only when their installed ownership
+    // marker/absolute command still points at this pack.
+    try {
+        const home = process.env.HOME ?? os.homedir();
+        syncCodexPackHooks(packDir, contributes.hooks ?? [], true, home);
+        warnings.push(...syncCodexPackSkills(packDir, name, contributes.skills ?? [], true, home));
+    }
+    catch (e) {
+        warnings.push(`Codex contribution removal encountered an error: ${e.message}`);
+    }
     // 1b. Un-register the pack's MCP (`wire: 'merge'`) servers — invisible to the
     // symlink unwire above. Provenance-scoped: removes ONLY entries stamped with this
     // pack's `_hqPack`, and skip-and-warns on any foreign/unstamped same-named entry.

package/dist/commands/pkg-install.js

@@ -44,7 +44,9 @@ export function registerPackageInstallCommand(parent) {
         .option('--allow-mcp', 'Skip the MCP server confirmation prompt (content-pack flow)')
         .option('--branch', 'Follow a ref instead of SHA-pinning (git content-pack flow)')
         .option('--global', 'Install HQ into an agent runtime at user scope (requires the hq-anywhere-runtime flag)')
-        .option('--runtime <runtime>', 'Runtime for --global (claude | codex)', 'claude')
+        .option('--runtime <runtime>', 'Runtime for --global (claude | codex | chatgpt | grok)', 'claude')
+        .option('--via <mode>', 'With --global Claude: install directly or via plugin (direct | plugin)', 'direct')
+        .option('--marketplace-dir <dir>', 'With --via plugin: local Claude Code marketplace directory (or HQ_CLAUDE_PLUGIN_MARKETPLACE)')
         .option('--dry-run', 'With --global: print every file and config diff without writing')
         .option('--hq-root <dir>', 'With --global: HQ checkout to install from (default: walk up from cwd)')
         .action(async (source, opts) => {
@@ -55,6 +57,16 @@ export function registerPackageInstallCommand(parent) {
                 return;
             }
             const { runInstallGlobal } = await import('./install-global.js');
+            if (opts.via !== 'direct' && opts.via !== 'plugin') {
+                console.error("error: --via must be 'direct' or 'plugin'");
+                process.exitCode = 1;
+                return;
+            }
+            if (opts.via === 'plugin' && (opts.runtime ?? 'claude') !== 'claude') {
+                console.error('error: --via plugin is currently supported only with --runtime claude');
+                process.exitCode = 1;
+                return;
+            }
             runInstallGlobal(opts);
             return;
         }

package/dist/fast-scaffold.d.ts

@@ -85,4 +85,6 @@ export declare function parseSecretsEnvFastRequest(argv: readonly string[]): Par
 export declare function parseFastCore(argv: readonly string[]): ParsedFastCore | null;
 /** Whether this invocation is a fast-path scaffold dispatch. */
 export declare function isFastCoreRequest(argv: readonly string[]): boolean;
+/** Metadata-only help can render without importing the selected command graph. */
+export declare function isCommandHelpRequest(argv: readonly string[]): boolean;
 //# sourceMappingURL=fast-scaffold.d.ts.map

package/dist/fast-scaffold.js

@@ -421,4 +421,20 @@ export function parseFastCore(argv) {
 export function isFastCoreRequest(argv) {
     return parseFastCore(argv) !== null;
 }
+/** Metadata-only help can render without importing the selected command graph. */
+export function isCommandHelpRequest(argv) {
+    const args = argv.slice(2);
+    const delimiter = args.indexOf("--");
+    const beforeDelimiter = delimiter === -1 ? args : args.slice(0, delimiter);
+    const commandWords = beforeDelimiter.filter((token) => !token.startsWith("-"));
+    const explicitHelp = beforeDelimiter.some((token) => token === "--help" || token === "-h");
+    if (!explicitHelp && commandWords[0] !== "help")
+        return false;
+    if (commandWords[0] === "help")
+        return commandWords.length <= 2;
+    // Native core commands have their own pass-through help and stay on their established path.
+    if (commandWords[0] === "core" || commandWords[0] === "run")
+        return false;
+    return commandWords.length <= 1;
+}
 //# sourceMappingURL=fast-scaffold.js.map

package/dist/index.js

@@ -6,10 +6,12 @@ import "./node-network-compat-fast.js";
 import { isVersionRequest, wantsLabelledVersionReport } from "./version-request.js";
 // Dependency-light: a pure parser + table, no command graph. Safe to load on
 // every path (including --version) without reintroducing the heavy startup.
-import { isFastCoreRequest, parseFastCore, parseSecretsEnvFastRequest, } from "./fast-scaffold.js";
+import { isCommandHelpRequest, isFastCoreRequest, parseFastCore, parseSecretsEnvFastRequest, } from "./fast-scaffold.js";
+import { CLI_COMMAND_HELP_CATALOG_FLAG } from "./lib/cli-flag-keys.js";
 // Also dependency-light: registers a process-level rejection boundary; its only
 // heavy import (main.js) is lazy and reached only when a rejection fires.
 import { installProcessRejectionBoundary } from "./unhandled-rejection-boundary.js";
+import { installFastPathStreamErrorHandlers } from "./utils/fast-stream-errors.js";
 // Install BEFORE any dispatch so a floated rejection on ANY path (the command
 // graph or the fast-core forwarder) becomes a non-zero exit. @sentry/node's
 // onUnhandledRejection integration defaults to 'warn' — it captures but does
@@ -17,9 +19,11 @@ import { installProcessRejectionBoundary } from "./unhandled-rejection-boundary.
 // command never run (HQ-CLI-W). Sets process.exitCode only, never process.exit,
 // so runCli's finally still finalizes release health and flushes Sentry.
 installProcessRejectionBoundary();
+installFastPathStreamErrorHandlers();
 function dispatchCliEntry() {
     const versionRequest = isVersionRequest(process.argv);
-    const parsedFastCore = versionRequest ? null : parseFastCore(process.argv);
+    const helpRequest = !versionRequest && isCommandHelpRequest(process.argv);
+    const parsedFastCore = versionRequest || helpRequest ? null : parseFastCore(process.argv);
     if (versionRequest) {
         // Bare `--version` is the CLI semver only (the contract field updaters
         // compare). `hq version` and `--json` print the labelled HQ/CLI report.
@@ -38,6 +42,19 @@ function dispatchCliEntry() {
             });
         }
     }
+    else if (helpRequest) {
+        // The generated-catalog renderer is a default-off startup optimization.
+        // When disabled or unavailable, preserve the established main.ts behavior.
+        void import("./native-fast-route.js").then(async ({ fastFlagEnabled }) => {
+            if (await fastFlagEnabled(CLI_COMMAND_HELP_CATALOG_FLAG)) {
+                const { runCommandHelp } = await import("./command-help.js");
+                await runCommandHelp(process.argv);
+                return;
+            }
+            const { runCli } = await import("./main.js");
+            await runCli();
+        });
+    }
     else if (parsedFastCore?.entry.kind === "native" &&
         (process.env.HQ_FLAG_HQ_CORE_NATIVE_FAST_ROUTE === "true" ||
             process.env.HQ_FLAG_HQ_CORE_NATIVE_FAST_ROUTE === "1")) {

package/dist/lazy-commands.d.ts

@@ -17,6 +17,7 @@ export declare const LAZY_COMMANDS: readonly LazyCommand[];
  * replaces the installed tree between startup and command registration.
  */
 export declare function registerCommandRoot(program: Command, root: string): Promise<boolean>;
+export declare function findRuntimeHqRoot(start: string, parentOf?: (directory: string) => string, isRoot?: (directory: string) => boolean): string;
 /**
  * Register only generated root metadata. This is enough for root help and
  * Commander suggestions, without evaluating an implementation module.

package/dist/lazy-commands.js

@@ -1,4 +1,7 @@
-import { Command } from "commander";
+import { Argument, Command, Option } from "commander";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
 import { COMMAND_CATALOG } from "./command-catalog.generated.js";
 const commandCatalog = COMMAND_CATALOG;
 /**
@@ -26,18 +29,75 @@ export async function registerCommandRoot(program, root) {
 function commandDefinition(command) {
     const stub = new Command(command.name)
         .description(command.description);
+    if (command.helpOption === false)
+        stub.helpOption(false);
     for (const alias of command.aliases)
         stub.alias(alias);
     for (const argument of command.arguments) {
         const name = `${argument.name}${argument.variadic ? "..." : ""}`;
-        stub.argument(argument.required ? `<${name}>` : `[${name}]`);
+        const definition = new Argument(argument.required ? `<${name}>` : `[${name}]`, argument.description || undefined);
+        if ("defaultValue" in argument)
+            definition.default(restoreRuntimePath(argument.defaultValue));
+        stub.addArgument(definition);
+    }
+    for (const option of command.options) {
+        const description = restoreRuntimePath(option.description);
+        const definition = new Option(option.flags, description);
+        if (option.hidden)
+            definition.hideHelp();
+        if (option.choices)
+            definition.choices([...option.choices]);
+        if ("defaultValue" in option) {
+            definition.default(restoreRuntimePath(option.defaultValue));
+        }
+        stub.addOption(definition);
     }
-    for (const option of command.options)
-        stub.option(option.flags, option.description);
     if (command.hidden)
         stub._hidden = true;
+    for (const child of command.subcommands)
+        stub.addCommand(commandDefinition(child));
+    if (command.helpCommand !== undefined)
+        stub.addHelpCommand(command.helpCommand);
+    stub.usage(command.usage);
+    for (const helpText of command.helpText ?? [])
+        stub.addHelpText(helpText.position, helpText.text);
     return stub;
 }
+function restoreRuntimePath(value) {
+    if (typeof value === "string") {
+        let restored = value.replaceAll("<runtime-home>", homedir());
+        if (restored.includes("<runtime-path>"))
+            restored = restored.replaceAll("<runtime-path>", runtimeHqRoot());
+        return restored;
+    }
+    if (Array.isArray(value))
+        return value.map(restoreRuntimePath);
+    if (value && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, restoreRuntimePath(entry)]));
+    }
+    return value;
+}
+function runtimeHqRoot() {
+    const args = process.argv.slice(2);
+    const rootIndex = args.findIndex((arg) => arg === "--hq-root");
+    const explicit = rootIndex >= 0 ? args[rootIndex + 1] : args.find((arg) => arg.startsWith("--hq-root="))?.slice("--hq-root=".length);
+    const configured = explicit || process.env.HQ_ROOT || process.env.CLAUDE_PROJECT_DIR;
+    if (configured)
+        return resolve(configured);
+    return findRuntimeHqRoot(resolve(process.cwd()));
+}
+export function findRuntimeHqRoot(start, parentOf = dirname, isRoot = (directory) => existsSync(join(directory, "companies")) &&
+    (existsSync(join(directory, ".claude")) || existsSync(join(directory, "core")) || existsSync(join(directory, "personal")))) {
+    let directory = start;
+    for (;;) {
+        if (isRoot(directory))
+            return directory;
+        const parent = parentOf(directory);
+        if (parent === directory)
+            return start;
+        directory = parent;
+    }
+}
 /**
  * Register only generated root metadata. This is enough for root help and
  * Commander suggestions, without evaluating an implementation module.

package/dist/lib/cli-flag-keys.d.ts

@@ -0,0 +1,3 @@
+/** hq-flags keys used by CLI-wide routes. */
+export declare const CLI_COMMAND_HELP_CATALOG_FLAG = "cli.command-help-catalog";
+//# sourceMappingURL=cli-flag-keys.d.ts.map

package/dist/lib/cli-flag-keys.js

@@ -0,0 +1,3 @@
+/** hq-flags keys used by CLI-wide routes. */
+export const CLI_COMMAND_HELP_CATALOG_FLAG = "cli.command-help-catalog";
+//# sourceMappingURL=cli-flag-keys.js.map

package/dist/lib/daemon/ops/mcp.js

@@ -74,7 +74,7 @@ export class HqMcpBridge {
         });
     }
     async callTool(name, args, timeoutMs = this.timeoutMs) {
-        return this.withClient(async (client, token) => {
+        return this.withClient(async (client) => {
             const { tools } = await client.listTools();
             if (!tools.some((tool) => tool.name === name)) {
                 throw new McpOpError("hq_mcp_tool_unavailable", `Hosted hq-mcp does not expose ${name}.`);
@@ -93,10 +93,16 @@ export class HqMcpBridge {
         let token = "";
         let transport;
         let client;
-        let timeout;
         let timedOut = false;
         const abortController = new AbortController();
         let httpErrorClass;
+        const timeout = setTimeout(() => {
+            timedOut = true;
+            abortController.abort();
+            void client?.close().catch(() => {
+                // The deadline already ended the request.
+            });
+        }, timeoutMs);
         try {
             const [clientModule, httpModule] = await Promise.all([
                 import("@modelcontextprotocol/sdk/client/index.js"),
@@ -104,6 +110,8 @@ export class HqMcpBridge {
             ]);
             httpErrorClass = httpModule.StreamableHTTPError;
             token = await this.getToken();
+            if (timedOut)
+                throw new McpOpError("hq_mcp_timeout", `Hosted hq-mcp request did not finish within ${timeoutMs}ms.`);
             if (!token.trim())
                 throw new McpOpError("hq_mcp_auth_required", "An hq-mcp audience token is required.");
             transport = new httpModule.StreamableHTTPClientTransport(this.endpoint, {
@@ -117,15 +125,8 @@ export class HqMcpBridge {
             });
             client = new clientModule.Client({ name: "hqd", version: "1" }, { capabilities: {} });
             this.activeClients.add(client);
-            timeout = setTimeout(() => {
-                timedOut = true;
-                abortController.abort();
-                void client?.close().catch(() => {
-                    // The deadline already ended the request.
-                });
-            }, timeoutMs);
             await client.connect(transport);
-            return await work(client, token);
+            return await work(client);
         }
         catch (error) {
             if (timedOut) {

package/dist/lib/daemon/ops/policy.d.ts

@@ -43,7 +43,8 @@ export declare class PolicyIndex {
     private rewatch;
 }
 export interface PolicyCheckArgs {
-    company: string;
+    /** Absent means personal/core scope only. */
+    company?: string;
     event?: string;
     tool: string;
     input?: Record<string, unknown>;
@@ -66,7 +67,7 @@ export interface PolicyCheckResult {
  * session id of its own per company + caller, so a check never borrows the
  * binding of an unrelated session.
  */
-export declare function bindCheckSession(hqRoot: string, company: string, callerSession: string | undefined, now: Date): string;
+export declare function bindCheckSession(hqRoot: string, company: string | undefined, callerSession: string | undefined, now: Date): string;
 export interface PolicyCheckDeps {
     hqRoot: string;
     index: PolicyIndex;

package/dist/lib/daemon/ops/policy.js

@@ -162,12 +162,13 @@ function runScript(script, payload, env, cwd, timeoutMs) {
  */
 export function bindCheckSession(hqRoot, company, callerSession, now) {
     const caller = (callerSession ?? "default").replace(/[^A-Za-z0-9._-]/g, "_").slice(0, 80) || "default";
-    const sid = `hqd-${company}-${caller}`;
+    const scope = company ?? "personal";
+    const sid = `hqd-${scope}-${caller}`;
     if (!SESSION_RE.test(sid))
         throw new PolicyOpError("bad_args", "sessionId has no usable characters");
     const dir = path.join(hqRoot, "workspace", "sessions", sid);
     const meta = path.join(dir, "meta.yaml");
-    const body = `session_id: ${sid}\nstarted_at: ${now.toISOString()}\nsenior: user\ncompany_slug: ${company}\nsource: hqd\n`;
+    const body = `session_id: ${sid}\nstarted_at: ${now.toISOString()}\nsenior: user\n${company ? `company_slug: ${company}\n` : ""}source: hqd\n`;
     let current = "";
     try {
         current = fs.readFileSync(meta, "utf8");
@@ -176,7 +177,9 @@ export function bindCheckSession(hqRoot, company, callerSession, now) {
         if (err.code !== "ENOENT")
             throw err;
     }
-    if (!current.includes(`\ncompany_slug: ${company}\n`)) {
+    if (company
+        ? !current.includes(`\ncompany_slug: ${company}\n`)
+        : !current.includes(`session_id: ${sid}\n`) || current.includes("\ncompany_slug:")) {
         fs.mkdirSync(dir, { recursive: true });
         const tmp = `${meta}.${process.pid}.tmp`;
         fs.writeFileSync(tmp, body);
@@ -214,9 +217,9 @@ function blockFromJson(stdout) {
 }
 export async function policyCheck(args, deps) {
     const { hqRoot } = deps;
-    if (!SLUG_RE.test(args.company))
+    if (args.company !== undefined && !SLUG_RE.test(args.company))
         throw new PolicyOpError("bad_args", "company must be a company slug");
-    if (!isDir(path.join(hqRoot, "companies", args.company))) {
+    if (args.company !== undefined && !isDir(path.join(hqRoot, "companies", args.company))) {
         throw new PolicyOpError("unknown_company", `no companies/${args.company} under ${hqRoot}`);
     }
     const authorizer = path.join(hqRoot, SCOPE_AUTHORIZER);
@@ -237,9 +240,12 @@ export async function policyCheck(args, deps) {
         ...(deps.env ?? process.env),
         HQ_ROOT: hqRoot,
         CLAUDE_PROJECT_DIR: hqRoot,
-        HQ_POLICY_COMPANY: args.company,
         BASH_ENV: "/dev/null",
     };
+    if (args.company === undefined)
+        delete env.HQ_POLICY_COMPANY;
+    else
+        env.HQ_POLICY_COMPANY = args.company;
     delete env.HQ_HOOK_SESSION_ID;
     delete env.HQ_HOOK_TOOL_NAME;
     const timeoutMs = deps.timeoutMs ?? 15_000;

package/dist/lib/daemon/server.d.ts

@@ -8,7 +8,7 @@
  */
 import { type ResolveResult } from "../registry/registry.js";
 import { SessionRegistry } from "./session-registry.js";
-import { HqMcpBridge } from "./ops/mcp.js";
+import { HqMcpBridge, type RunWorkerRequest } from "./ops/mcp.js";
 export interface HqdServerOptions {
     socketPath: string;
     /** registry.json to resolve against (US-004). */
@@ -27,6 +27,8 @@ export interface HqdServerOptions {
     mcpEnabled?: () => boolean | Promise<boolean>;
     /** Test seam for the hosted Streamable HTTP MCP transport. */
     mcpBridge?: HqMcpBridge;
+    /** Test seam for reduced host parity runs without spawning an agent process. */
+    workerDispatch?: (request: RunWorkerRequest, hqRoot: string, env: NodeJS.ProcessEnv, now: Date) => Promise<Record<string, unknown>>;
     /** Crash reporter for internal op failures (US-012); run.ts wires Sentry here. */
     reportError?: (op: string, err: unknown) => void;
 }

package/dist/lib/daemon/server.js

@@ -20,6 +20,31 @@ import { PolicyIndex, PolicyOpError, policyCheck } from "./ops/policy.js";
 import { HqMcpBridge, jsonResult, McpOpError, runWorker } from "./ops/mcp.js";
 import { HQ_MCP_TOOL_NAMES, HQD_NATIVE_TOOL_NAMES } from "../mcp/tools.js";
 import { anywhereRuntimeEnabled, HQ_ANYWHERE_RUNTIME_FLAG } from "../../commands/anywhere-runtime-flag.js";
+// The allowlist is deliberately read-only. A newly added hosted MCP tool must
+// pass hq.policy_check until it is explicitly reviewed as read-only here.
+const MCP_READ_ONLY_TOOL_NAMES = new Set([
+    "search",
+    "fetch",
+    "hq_companies_list",
+    "hq_company_ping",
+    "hq_exec_check",
+    "hq_files_list",
+    "hq_files_read",
+    "hq_knowledge_get",
+    "hq_knowledge_list",
+    "hq_knowledge_search",
+    "hq_ping",
+    "hq_policies_list",
+    "hq_policy_get",
+    "hq_project_get",
+    "hq_project_status",
+    "hq_projects_list",
+    "hq_run_list",
+    "hq_secrets_list",
+    "hq_secrets_schema",
+    "hq_version",
+    "hq_whoami",
+]);
 class OpError extends Error {
     code;
     constructor(code, message) {
@@ -165,14 +190,15 @@ export async function startHqdServer(opts) {
             case "policy.check": {
                 const hqRoot = requireRoot();
                 const company = companyFor(args);
-                if (!company)
+                const personalCapture = args.personalScope === true && args.tool === "hq_personal_capture";
+                if (!company && !personalCapture)
                     throw new OpError("bad_args", "company is required (or a cwd linked to a company)");
                 const input = args.input;
                 if (input !== undefined && (input === null || typeof input !== "object" || Array.isArray(input))) {
                     throw new OpError("bad_args", "input must be an object");
                 }
                 return policyCheck({
-                    company,
+                    ...(company ? { company } : {}),
                     event: stringArg(args, "event", false),
                     tool: stringArg(args, "tool"),
                     input: input,
@@ -212,6 +238,7 @@ export async function startHqdServer(opts) {
                 }, { hqRoot: opts.hqRoot, workMeshRoot: opts.workMeshRoot, env, now: clock });
             }
             case "mcp.call": {
+                const requestStartedAt = Date.now();
                 const name = stringArg(args, "name");
                 const raw = args.arguments ?? {};
                 if (raw === null || typeof raw !== "object" || Array.isArray(raw))
@@ -229,21 +256,42 @@ export async function startHqdServer(opts) {
                     companyArgs.sessionId = sessionId;
                 const call = (op, a) => handle({ id: req.id, op, args: a });
                 const asResult = (value) => (value instanceof Promise ? value.then(jsonResult) : jsonResult(value));
+                const policyGuardedCall = (run) => {
+                    const company = companyFor(companyArgs);
+                    const personalCapture = name === "hq_personal_capture" && !company;
+                    if (!company && !personalCapture)
+                        throw new OpError("bad_args", "company is required for a write-capable MCP tool");
+                    return Promise.resolve(call("policy.check", {
+                        ...(company ? { company } : { personalScope: true }),
+                        cwd: typeof toolArgs.cwd === "string" ? toolArgs.cwd : process.cwd(),
+                        ...(runtime ? { runtime } : {}),
+                        ...(sessionId ? { sessionId } : {}),
+                        tool: name,
+                        input: raw,
+                    })).then((verdict) => {
+                        const decision = verdict;
+                        if (decision.decision !== "allow") {
+                            const reason = Array.isArray(decision.reasons) ? decision.reasons.filter((r) => typeof r === "string").join("; ") : "policy check did not allow this tool";
+                            throw new OpError("policy_blocked", reason || "policy check did not allow this tool");
+                        }
+                        return run();
+                    });
+                };
                 switch (name) {
                     case "hq_resolve_company":
                         return asResult(call("resolve", { cwd: toolArgs.cwd ?? process.cwd() }));
                     case "hq_policy_check":
                         return asResult(call("policy.check", companyArgs));
                     case "hq_journal_append":
-                        return asResult(call("journal.append", companyArgs));
+                        return policyGuardedCall(() => call("journal.append", companyArgs)).then(jsonResult);
                     case "hq_run_worker": {
                         const tool = companyArgs;
-                        return runWorker({
+                        return policyGuardedCall(() => (opts.workerDispatch ?? runWorker)({
                             worker: stringArg(tool, "worker"),
                             skill: stringArg(tool, "skill", false),
                             args: typeof tool.args === "string" ? tool.args : undefined,
                             company: companyFor(tool),
-                        }, requireRoot(), env, clock()).then(jsonResult);
+                        }, requireRoot(), env, clock())).then(jsonResult);
                     }
                     default: {
                         if (HQD_NATIVE_TOOL_NAMES.has(name) || !HQ_MCP_TOOL_NAMES.has(name))
@@ -252,13 +300,21 @@ export async function startHqdServer(opts) {
                         const timeoutMs = typeof args.timeoutMs === "number" && Number.isFinite(args.timeoutMs)
                             ? Math.max(1, Math.min(args.timeoutMs, 120_000))
                             : HQD_DEFAULT_REQUEST_TIMEOUT_MS;
-                        return Promise.resolve(mcpEnabled()).then((enabled) => {
+                        const deadline = requestStartedAt + timeoutMs;
+                        const forward = () => Promise.resolve(mcpEnabled()).then((enabled) => {
                             if (!enabled) {
                                 throw new McpOpError("hq_mcp_unavailable", `Hosted hq-mcp forwarding is disabled by the ${HQ_ANYWHERE_RUNTIME_FLAG} flag.`);
                             }
+                            const remainingMs = Math.floor(deadline - Date.now());
+                            if (remainingMs <= 0) {
+                                throw new McpOpError("hq_mcp_timeout", `Hosted hq-mcp request exceeded its ${timeoutMs}ms end-to-end deadline before forwarding.`);
+                            }
                             hqMcp ??= new HqMcpBridge({ env });
-                            return hqMcp.callTool(name, raw, timeoutMs);
+                            return hqMcp.callTool(name, raw, remainingMs);
                         });
+                        return !MCP_READ_ONLY_TOOL_NAMES.has(name)
+                            ? policyGuardedCall(forward)
+                            : forward();
                     }
                 }
             }