@indigoai-us/hq-cli 5.345.151 → 5.345.152

package/CHANGELOG.md

@@ -2,6 +2,47 @@
 
 ## [Unreleased]
 
+## [5.345.152] — 2026-10-20
+- The bundled sync engine now uses hq-cloud 6.18.91. When a company Outpost
+  fails to start and the server has already cleaned it up,
+  `hq outposts provision --company <slug>` (and `create --company --name`)
+  stops right away and says nothing was left running, you were not charged,
+  and it is safe to run the same command again. `hq outposts status --company`
+  shows the same line, and `--json` adds `code: "failed_cleaned_up"` and
+  `retrySafe: true`. Other blocked reasons keep their existing text.
+- CI: the "changelog entry" check sets up Node before it runs, so it no longer
+  fails with "node: command not found" on the self-hosted ARM runners. No change
+  to the `hq` command itself.
+- `hq files share --with out_…` and `hq files unshare --with out_…` now accept
+  a company Outpost id, with read or write. `hq files acl` shows the grantee as
+  `Outpost (out_…)`; `--json` output is unchanged.
+- `hq secrets share --with out_…` now refuses write or admin for a company
+  Outpost with "Company Outposts can only be given read access to a secret."
+  before anything is sent. Leaving out `--permission` for an Outpost gives it
+  read. A server refusal for the same reason shows the same message.
+- `hq rescue` (and so `/update-hq`) now re-trusts HQ's own Codex hooks after a
+  successful rescue. Before this, an update that changed a hook command left
+  Codex holding the old trusted hash, so Codex skipped that hook until you ran
+  `hq reindex`. Rescue trusts a hook only when its entry in the HQ root's
+  `.codex/hooks.json` or `.codex/config.toml` matches the copy shipped in the
+  installed core release, which it reads from GitHub at the synced commit.
+  It reads that copy only from `indigoai-us/hq-core` or
+  `indigoai-us/hq-core-staging`; if `core/core.yaml` names any other repo
+  (for example after `hq rescue --source <fork>`), rescue trusts nothing.
+  Hooks you added to those files by hand, or shipped entries you edited, are
+  never trusted. User and managed hooks are left alone, and hooks that are
+  already trusted are not rewritten. Rescue does not re-enable a shipped hook
+  you disabled; it only refreshes that hook's trust (`hq reindex` still
+  re-enables shipped hooks). Nothing happens when Codex is not installed, and
+  `--check` never touches hook trust. Rescue prints a warning that points at
+  `hq reindex` and keeps its exit status when the shipped files cannot be
+  read, when the release does not ship a file an HQ hook comes from, when a
+  shipped file does not parse, when the repo is not an HQ core repo, or when
+  the trust step fails.
+- `hq secrets exec` run without a session id (no `HQ_SESSION_ID`, `CLAUDE_CODE_SESSION_ID`, `CLAUDE_SESSION_ID`, `CODEX_SESSION_ID`, `CODEX_THREAD_ID` or `GROK_SESSION_ID`), such as a launchd or cron job, no longer borrows the company lock of whichever interactive session last wrote the sessions `.current` pointer. Before this, a job could load the same-named secret from that session's company. Such a job must now pass `--company <slug>` or `--personal`. Otherwise it prints how to fix the call and exits 78 without reading the vault. An `HQ_API_KEY` (`hqk_`) caller is unaffected because its key is bound to one company. A caller with its own session id keeps the existing lock rules: `--company` can only pick a company inside that session's lock.
+- Defines the Windows acceptance bar for the native hook engine and checks it before a release. Hook checks whose stories are not merged yet are reported as pending and do not block other releases. A failed check still blocks the release.
+- A pass requires runner evidence for that commit. Counts written into corpus files, a source-text match, or a signed-off latency number with no report stay pending and do not block a release.
+
 ## [5.345.151] — 2026-10-20
 - `hq lanes link _deliver` no longer hands a conductor message to a subagent. Subagent hook events share the root session id, so a subagent tool call used to claim the message and the root session never saw it. Child payloads, including Grok child sessions (`subagent_type`) and Codex child threads, now get nothing and the message stays queued until the root session's next tool call or stop. SubagentStop no longer delivers. A parent session id alone does not mark a child, so resumed, forked, or launcher-spawned Grok roots still receive their messages.
 - If you leave out `--company`, `hq meetings invite <url>` now uses your only active company. If you belong to several companies, it lists them and asks you to pick one. The command used to send the invite as Personal instead. Personal can never record, so you saw the HQ Workforce upgrade prompt even when your company already had meeting recording.

package/dist/command-catalog.generated.d.ts

@@ -2058,7 +2058,7 @@ export declare const COMMAND_CATALOG: readonly [{
             readonly hidden: false;
         }, {
             readonly flags: "--permission <level>";
-            readonly description: "Permission level: read | write | admin";
+            readonly description: "Permission level: read | write | admin (required, except for a company Outpost, which can only be given read and defaults to it)";
             readonly hidden: false;
         }];
         readonly subcommands: readonly [];
@@ -2813,7 +2813,7 @@ export declare const COMMAND_CATALOG: readonly [{
         }];
         readonly options: readonly [{
             readonly flags: "--with <principal>";
-            readonly description: "Email address, group id, or '@all' to share with every active company member";
+            readonly description: "Email address, group id, company Outpost id (out_...), or '@all' to share with every active company member";
             readonly hidden: false;
         }, {
             readonly flags: "--permission <level>";
@@ -2859,7 +2859,7 @@ export declare const COMMAND_CATALOG: readonly [{
         }];
         readonly options: readonly [{
             readonly flags: "--with <principal>";
-            readonly description: "Person uid, agent uid, email address, group id, or '@all' to remove the grant";
+            readonly description: "Person uid, agent uid, company Outpost id (out_...), email address, group id, or '@all' to remove the grant";
             readonly hidden: false;
         }];
         readonly subcommands: readonly [];

package/dist/command-catalog.generated.js

@@ -2469,7 +2469,7 @@ export const COMMAND_CATALOG = [
                     },
                     {
                         "flags": "--permission <level>",
-                        "description": "Permission level: read | write | admin",
+                        "description": "Permission level: read | write | admin (required, except for a company Outpost, which can only be given read and defaults to it)",
                         "hidden": false
                     }
                 ],
@@ -3380,7 +3380,7 @@ export const COMMAND_CATALOG = [
                 "options": [
                     {
                         "flags": "--with <principal>",
-                        "description": "Email address, group id, or '@all' to share with every active company member",
+                        "description": "Email address, group id, company Outpost id (out_...), or '@all' to share with every active company member",
                         "hidden": false
                     },
                     {
@@ -3437,7 +3437,7 @@ export const COMMAND_CATALOG = [
                 "options": [
                     {
                         "flags": "--with <principal>",
-                        "description": "Person uid, agent uid, email address, group id, or '@all' to remove the grant",
+                        "description": "Person uid, agent uid, company Outpost id (out_...), email address, group id, or '@all' to remove the grant",
                         "hidden": false
                     }
                 ],

package/dist/commands/files.js

@@ -4,7 +4,7 @@ import * as readline from "node:readline";
 import { resolveVaultCredential } from "../utils/resolve-vault-credential.js";
 import { gateApiKeyCapabilities } from "../utils/api-key-command-gate.js";
 import { vaultApiFetch, getCompanyUid } from "./secrets.js";
-import { GROUP_ID_PATTERN, EMAIL_PATTERN, isPrivateFolderPattern, normalizeFilePrefix, toSharedFolderGlob, } from "./_patterns.js";
+import { GROUP_ID_PATTERN, EMAIL_PATTERN, isPrivateFolderPattern, normalizeFilePrefix, OUTPOST_UID_PATTERN, toSharedFolderGlob, } from "./_patterns.js";
 import { looksLikeCompanyUid } from "../utils/vault-api.js";
 import { AuthError } from "../utils/auth-error.js";
 import { formatAccessDenied, offerAccessLadder, } from "../utils/access-denied-hint.js";
@@ -159,7 +159,7 @@ export function registerFilesCommand(program) {
     files
         .command("share [paths...]")
         .description("Share file paths. foo/ is a private folder (children stay creator-only); quote the shared-folder glob 'foo/*' so the shell passes it literally. Without --with: mint a share-session URL and open it in the browser. With --with: grant access directly to a person, group, or @all.")
-        .option("--with <principal>", "Email address, group id, or '@all' to share with every active company member")
+        .option("--with <principal>", "Email address, group id, company Outpost id (out_...), or '@all' to share with every active company member")
         .option("--permission <level>", "Permission level (only with --with): read | write")
         .option("--full", "Grant access to the ENTIRE vault (the '*' wildcard prefix) — no need to quote a glob. Requires --with; defaults to write permission.")
         .option("--expires <duration>", "Token expiry duration for share-session URL (e.g. 15m, 1h, 24h). Default 15m. Max 24h.")
@@ -268,7 +268,7 @@ export function registerFilesCommand(program) {
     files
         .command("unshare <prefix>")
         .description("Remove a named file access grant, or remove an empty ACL row or grantee-less entries without --with.")
-        .option("--with <principal>", "Person uid, agent uid, email address, group id, or '@all' to remove the grant")
+        .option("--with <principal>", "Person uid, agent uid, company Outpost id (out_...), email address, group id, or '@all' to remove the grant")
         .action(async (prefix, opts) => {
         try {
             // Unshare MUTATES access with no preview. Anchored content paths remain
@@ -286,9 +286,14 @@ export function registerFilesCommand(program) {
             const isEmail = !isAll && EMAIL_PATTERN.test(principal);
             const isGroup = !isAll && GROUP_ID_PATTERN.test(principal);
             const isAgent = !isAll && !isEmail && !isGroup && AGENT_UID_PATTERN.test(principal);
-            const isPerson = !isAll && !isEmail && !isGroup && !isAgent && PERSON_UID_PATTERN.test(principal);
+            // A company Outpost (out_<ULID>) rides the person grantee slot on the wire.
+            const isPerson = !isAll &&
+                !isEmail &&
+                !isGroup &&
+                !isAgent &&
+                (PERSON_UID_PATTERN.test(principal) || OUTPOST_UID_PATTERN.test(principal));
             if (opts.with && !isAll && !isEmail && !isGroup && !isPerson && !isAgent) {
-                console.error(chalk.red(`Invalid principal '${principal}': must be '@all', an email address, a person uid matching prs_<alphanumeric>, an agent uid matching agt_<alphanumeric>, or a group id matching grp_<alphanumeric>`));
+                console.error(chalk.red(`Invalid principal '${principal}': must be '@all', an email address, a person uid matching prs_<alphanumeric>, an agent uid matching agt_<alphanumeric>, a company Outpost id (out_<ULID>), or a group id matching grp_<alphanumeric>`));
                 process.exit(1);
             }
             // The vault ACL API stores first-class agent access on its backwards-
@@ -481,6 +486,9 @@ export function registerFilesCommand(program) {
                 if (e.granteeType === "company-wide") {
                     return "Everyone in company (including guests)";
                 }
+                if (e.granteeType === "person" && OUTPOST_UID_PATTERN.test(e.granteeId)) {
+                    return `Outpost (${e.granteeId})`;
+                }
                 return e.granteeId;
             }
             function printEntryTable(rows, showSource) {
@@ -773,9 +781,17 @@ async function runDirectGrant(params) {
     const isAll = principal === "@all";
     const isEmail = !isAll && EMAIL_PATTERN.test(principal);
     const isGroup = !isAll && GROUP_ID_PATTERN.test(principal);
-    const isPerson = !isAll && !isEmail && !isGroup && PERSON_UID_PATTERN.test(principal);
+    // A company Outpost (out_<ULID>) gets member-equivalent file access and
+    // rides the person grantee slot on the wire: { granteeType: "person",
+    // granteeId: "out_..." }. hq-pro validates out_ grantees (active binding,
+    // same company) from the paired server change; older servers store it as an
+    // inert person grant.
+    const isPerson = !isAll &&
+        !isEmail &&
+        !isGroup &&
+        (PERSON_UID_PATTERN.test(principal) || OUTPOST_UID_PATTERN.test(principal));
     if (!isAll && !isEmail && !isGroup && !isPerson) {
-        console.error(chalk.red(`Invalid principal '${principal}': must be '@all', an email address, a person uid, or a group id matching grp_<alphanumeric>`));
+        console.error(chalk.red(`Invalid principal '${principal}': must be '@all', an email address, a person uid, a company Outpost id (out_<ULID>), or a group id matching grp_<alphanumeric>`));
         process.exit(1);
     }
     const granteeType = isAll

package/dist/commands/rescue.d.ts

@@ -20,6 +20,7 @@
  * `HQ_NO_UPDATE_CHECK=1`; always best-effort.
  */
 import { Command } from 'commander';
+import { retrustCodexHooksAfterRescue } from '../utils/hook-trust.js';
 export interface RescueTarget {
     source: string;
     /** undefined → let the script apply its own default ref (`main`). */
@@ -45,6 +46,12 @@ export declare function shouldAttemptSelfUpdate(opts: {
     check?: boolean;
     selfUpdate?: boolean;
 }): boolean;
+/**
+ * Re-trust HQ's Codex hooks after a rescue that changed files on disk.
+ * Exported for tests. Best-effort: a trust failure is reported but never
+ * changes the rescue's exit status, because the core update itself succeeded.
+ */
+export declare function retrustHooksAfterRescue(hqRoot: string, retrust?: typeof retrustCodexHooksAfterRescue): Promise<void>;
 /** Latest release tag for a repo, e.g. `v12.3.0`. Throws on failure. */
 export declare function getLatestReleaseTag(repo: string, token?: string): Promise<string>;
 /** Resolve a tag to its commit SHA, dereferencing annotated tags. */

package/dist/commands/rescue.js

@@ -1,4 +1,3 @@
-import { spawnSync } from 'child_process';
 import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'js-yaml';
@@ -6,8 +5,8 @@ import chalk from 'chalk';
 import { rescue } from '@indigoai-us/hq-cloud';
 import { findHqRoot } from '../utils/manifest.js';
 import { selfUpdateAndReexec } from '../utils/self-update.js';
-const PROD_SOURCE = 'indigoai-us/hq-core';
-const STAGING_SOURCE = 'indigoai-us/hq-core-staging';
+import { retrustCodexHooksAfterRescue } from '../utils/hook-trust.js';
+import { PROD_SOURCE, STAGING_SOURCE, resolveGhToken } from '../utils/shipped-codex-hooks.js';
 /**
  * Resolve the source repo + ref from the user's flags. Pure + exported for
  * tests. `latestTag` is the resolved latest release tag (prod only); ignored
@@ -28,20 +27,27 @@ export function resolveRescueTarget(opts, latestTag) {
 export function shouldAttemptSelfUpdate(opts) {
     return opts.selfUpdate !== false && !opts.check;
 }
-/** Resolve a GitHub token: prefer `gh auth token`, fall back to env. */
-function resolveGhToken() {
+/**
+ * Re-trust HQ's Codex hooks after a rescue that changed files on disk.
+ * Exported for tests. Best-effort: a trust failure is reported but never
+ * changes the rescue's exit status, because the core update itself succeeded.
+ */
+export async function retrustHooksAfterRescue(hqRoot, retrust = retrustCodexHooksAfterRescue) {
+    let root = hqRoot;
     try {
-        const res = spawnSync('gh', ['auth', 'token'], { encoding: 'utf8' });
-        if (res.status === 0) {
-            const tok = res.stdout.trim();
-            if (tok)
-                return tok;
-        }
+        root = fs.realpathSync(hqRoot);
     }
     catch {
-        // gh not installed — fall through to env.
+        // Keep the path as given; trust reports its own failure if it is unusable.
+    }
+    const result = await retrust(root);
+    if (result.status === 'trusted') {
+        console.log(`rescue: re-trusted ${result.trusted} Codex HQ hook${result.trusted === 1 ? '' : 's'}`);
+    }
+    else if (result.status === 'failed') {
+        console.warn(chalk.yellow(`rescue: could not re-trust Codex HQ hooks: ${result.reason ?? 'unknown error'}. ` +
+            'Codex will skip changed HQ hooks until you run `hq reindex`.'));
     }
-    return process.env.GH_TOKEN || process.env.GITHUB_TOKEN || undefined;
 }
 function ghHeaders(token) {
     const headers = {
@@ -178,6 +184,9 @@ export function registerRescueCommand(program) {
                 cloudUpdate: opts.cloudUpdate,
                 ghToken: token,
             });
+            if (status === 0 && !opts.check) {
+                await retrustHooksAfterRescue(hqRoot);
+            }
             process.exit(status);
         }
         catch (error) {

package/dist/commands/secrets.d.ts

@@ -3,6 +3,13 @@ export { readSessionCompanyLock } from "../lib/session-company-lock.js";
 export { buildSecretUsage, emitEnvExportsAndExit, loadRevealedSecrets, parseSecretNameList, runSecretsEnvCommand, } from "../secrets-env-action.js";
 export type { SecretLoadResponse, SecretScriptLockMode, SecretTier, SecretUsage, SecretUsageChannel } from "../secrets-env-action.js";
 export type { SecretScriptUsage, SecretMetadata, SecretLoadSuccessRow } from "../secrets-env-action.js";
+/**
+ * Exit code for `hq secrets exec` run with no session id and no explicit
+ * company. 78 is EX_CONFIG from sysexits.h: the caller's invocation is missing
+ * required configuration, so retrying the same command will not help.
+ */
+export declare const SECRETS_EXEC_UNATTENDED_NO_COMPANY_EXIT = 78;
+export declare const SECRETS_EXEC_UNATTENDED_NO_COMPANY_MESSAGE: string;
 import { vaultApiFetch, getCompanyUid, getEntityUid } from "../utils/vault-api.js";
 export type { VaultApiOptions } from "../utils/vault-api.js";
 export { vaultApiFetch, getCompanyUid, getEntityUid };
@@ -17,6 +24,12 @@ interface SecretAclPrincipal {
     granteeType: "email" | "group" | "company-wide" | "person";
     granteeId: string;
 }
+/**
+ * hq-pro refuses any Outpost grant above read with 400
+ * OUTPOST_GRANT_READ_ONLY. The CLI refuses it first with the same message.
+ */
+export declare const OUTPOST_GRANT_READ_ONLY_CODE = "OUTPOST_GRANT_READ_ONLY";
+export declare const OUTPOST_GRANT_READ_ONLY_MESSAGE = "Company Outposts can only be given read access to a secret.";
 export declare function parseSecretAclPrincipal(principal: string): SecretAclPrincipal | null;
 export interface SecretInjectionRecipe {
     header: string;

package/dist/commands/secrets.js

@@ -3,6 +3,7 @@ import * as path from "node:path";
 import * as yaml from "js-yaml";
 import { assertApiKeyCompany, buildSecretUsage, extractApiMessage, highSecuritySandboxOnlyMessage, loadRevealedSecrets, normalizeScriptLockMode, normalizeSecretTier, parseSecretNameList, requestedApiKeyCompany, runSecretsEnvCommand, scopeOpts, secretsCredentialOptions, } from "../secrets-env-action.js";
 import { readSessionCompanyLock } from "../lib/session-company-lock.js";
+import { sessionIdFromEnv } from "../lib/core-utils/session-id.js";
 export { readSessionCompanyLock } from "../lib/session-company-lock.js";
 export { buildSecretUsage, emitEnvExportsAndExit, loadRevealedSecrets, parseSecretNameList, runSecretsEnvCommand, } from "../secrets-env-action.js";
 function companyUidForSlug(root, slug) {
@@ -53,6 +54,16 @@ async function resolveApiKeyCompanyWithinLock(input) {
 }
 import chalk from "chalk";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
+/**
+ * Exit code for `hq secrets exec` run with no session id and no explicit
+ * company. 78 is EX_CONFIG from sysexits.h: the caller's invocation is missing
+ * required configuration, so retrying the same command will not help.
+ */
+export const SECRETS_EXEC_UNATTENDED_NO_COMPANY_EXIT = 78;
+export const SECRETS_EXEC_UNATTENDED_NO_COMPANY_MESSAGE = "hq secrets exec has no session id (HQ_SESSION_ID, CLAUDE_CODE_SESSION_ID, CLAUDE_SESSION_ID, " +
+    "CODEX_SESSION_ID, CODEX_THREAD_ID and GROK_SESSION_ID are all unset), so it will not borrow a company " +
+    "from whichever interactive session last wrote workspace/sessions/.current. " +
+    "Pass --company <slug> (or --personal), or set HQ_SESSION_ID to the session this job runs under.";
 import { removeCacheEntry, clearAllCache } from "../utils/secrets-cache.js";
 import { isHqCliChild, releaseChildWrapperPackageUseLeaseAfterStart } from "../utils/child-wrapper-lease.js";
 import { resolveDefaultHqRoot } from "../utils/hq-root-resolver.js";
@@ -63,7 +74,7 @@ import { isPlanGateError } from "../utils/plan-gate-error.js";
 import { SECRET_NAME_PATTERN, GROUP_ID_PATTERN, EMAIL_PATTERN, OUTPOST_UID_PATTERN, } from "./_patterns.js";
 import { describeSecretsScope, formatSecretSaved, formatSecretsListEmpty, formatSecretsListHeader, } from "./secrets-scope.js";
 import { vaultApiFetch, getCompanyUid, getEntityUid, looksLikeCompanyUid, } from "../utils/vault-api.js";
-import { formatApiKeyCapabilityDenial, requireApiKeyCapability, resolveVaultCredentialForCapability, } from "../utils/resolve-vault-credential.js";
+import { formatApiKeyCapabilityDenial, peekHqApiKey, requireApiKeyCapability, resolveVaultCredentialForCapability, } from "../utils/resolve-vault-credential.js";
 import { runSandboxJobAfterSubmission } from "../utils/secrets-sandbox-resident.js";
 export { vaultApiFetch, getCompanyUid, getEntityUid };
 /**
@@ -277,6 +288,12 @@ function promptSecretInteractively() {
         process.stdin.resume();
     });
 }
+/**
+ * hq-pro refuses any Outpost grant above read with 400
+ * OUTPOST_GRANT_READ_ONLY. The CLI refuses it first with the same message.
+ */
+export const OUTPOST_GRANT_READ_ONLY_CODE = "OUTPOST_GRANT_READ_ONLY";
+export const OUTPOST_GRANT_READ_ONLY_MESSAGE = "Company Outposts can only be given read access to a secret.";
 export function parseSecretAclPrincipal(principal) {
     const p = principal.trim();
     if (p === "@all") {
@@ -1164,11 +1181,23 @@ export function registerSecretsCommand(program) {
                 process.exit(1);
             }
             const keys = parseSecretNameList(_opts.only);
-            const multiCompanyLockEnabled = await fastFlagEnabledDefaultOn(MULTI_COMPANY_SESSION_LOCK_FLAG);
-            const sessionLock = multiCompanyLockEnabled ? readSessionCompanyLock(process.env) : undefined;
             const parentScope = secrets.opts();
             const inheritedCompany = parentScope.company;
             const requestedCompany = _opts.company ?? inheritedCompany;
+            // A launchd or cron job has no session id. Session resolution would then
+            // fall back to workspace/sessions/.current, which names whichever
+            // interactive session last ran a hook, and the job would read that
+            // session's company's same-named secret. Without a session id the caller
+            // must name its scope. HQ_API_KEY is exempt: the key is bound to one
+            // company and never reads the session lock below.
+            const hasCallerSession = Boolean(sessionIdFromEnv(process.env));
+            if (!hasCallerSession && !requestedCompany && !parentScope.personal && peekHqApiKey() === undefined) {
+                console.error(chalk.red("Error:"), SECRETS_EXEC_UNATTENDED_NO_COMPANY_MESSAGE);
+                process.exit(SECRETS_EXEC_UNATTENDED_NO_COMPANY_EXIT);
+            }
+            const multiCompanyLockEnabled = await fastFlagEnabledDefaultOn(MULTI_COMPANY_SESSION_LOCK_FLAG);
+            // Only the caller's own session id may supply a lock; never .current.
+            const sessionLock = multiCompanyLockEnabled && hasCallerSession ? readSessionCompanyLock(process.env) : undefined;
             const hasLockedCompanies = (sessionLock?.companies.length ?? 0) > 0;
             const lockRoot = hasLockedCompanies ? resolveDefaultHqRoot({ env: process.env }) : undefined;
             const selectedCompany = (hasLockedCompanies && requestedCompany && looksLikeCompanyUid(requestedCompany)
@@ -1319,7 +1348,7 @@ export function registerSecretsCommand(program) {
         .command("share <path>")
         .description("Share a secret with an email address, group, company Outpost (out_…), or the entire company (@all)")
         .requiredOption("--with <principal>", "Email address, group id, out_ Outpost id, or @all (entire company) to share with")
-        .requiredOption("--permission <level>", "Permission level: read | write | admin")
+        .option("--permission <level>", "Permission level: read | write | admin (required, except for a company Outpost, which can only be given read and defaults to it)")
         .action(async (path, opts) => {
         try {
             rejectIfPersonal(secrets.opts(), "share");
@@ -1327,7 +1356,8 @@ export function registerSecretsCommand(program) {
                 console.error(chalk.red(`Invalid secret path '${path}': must match ^[A-Z][A-Z0-9_]*(/[A-Z][A-Z0-9_]+)*$ (e.g. MY_KEY or PROD/DB_PASSWORD)`));
                 process.exit(1);
             }
-            if (!["read", "write", "admin"].includes(opts.permission)) {
+            if (opts.permission !== undefined &&
+                !["read", "write", "admin"].includes(opts.permission)) {
                 console.error(chalk.red(`Invalid permission '${opts.permission}': must be one of read, write, admin`));
                 process.exit(1);
             }
@@ -1335,6 +1365,16 @@ export function registerSecretsCommand(program) {
             if (!principal) {
                 process.exit(1);
             }
+            const isOutpost = OUTPOST_UID_PATTERN.test(principal.granteeId);
+            if (opts.permission === undefined && !isOutpost) {
+                console.error(chalk.red("Missing --permission: must be one of read, write, admin"));
+                process.exit(1);
+            }
+            const permission = opts.permission ?? "read";
+            if (isOutpost && permission !== "read") {
+                console.error(chalk.red(OUTPOST_GRANT_READ_ONLY_MESSAGE));
+                process.exit(1);
+            }
             const target = await resolveSecretsTarget("secrets:share", "secrets share", secrets.opts());
             const res = await vaultApiFetch({
                 token: target.token,
@@ -1344,12 +1384,15 @@ export function registerSecretsCommand(program) {
                     path,
                     granteeType: principal.granteeType,
                     granteeId: principal.granteeId,
-                    permission: opts.permission,
+                    permission,
                 },
             });
             if (!res.ok) {
                 const body = await res.json().catch(() => ({}));
-                if (res.status === 401) {
+                if (res.status === 400 && body.code === OUTPOST_GRANT_READ_ONLY_CODE) {
+                    console.error(chalk.red(OUTPOST_GRANT_READ_ONLY_MESSAGE));
+                }
+                else if (res.status === 401) {
                     console.error(chalk.red("Not authenticated — please run `hq login`"));
                 }
                 else if (res.status === 403) {
@@ -1371,7 +1414,7 @@ export function registerSecretsCommand(program) {
                 }
                 process.exit(1);
             }
-            console.log(chalk.green(`Shared '${path}' with ${describeSecretAclPrincipal(principal)} (${opts.permission})`));
+            console.log(chalk.green(`Shared '${path}' with ${describeSecretAclPrincipal(principal)} (${permission})`));
         }
         catch (err) {
             console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));