@phnx-labs/agents-cli 1.20.24 → 1.20.26

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## Unreleased
 
+**Secrets default policy is now `daily` (one Touch ID per ~24h), not `always`**
+
+- The default prompt policy for bundles without an explicit one flipped from `always` (Touch ID on *every* read) to **`daily`** (one prompt, then held ~24h until screen-lock / sleep / logout). This is the fix for the prompt storm: a background reader like sessions-sync hammering a bundle now costs one Touch ID per ~24h instead of one per read.
+- **Auto-cache is on by default.** The secrets-agent is the mechanism that delivers the daily policy, so it self-caches a `daily` bundle on first read with no `secrets.agent.auto: true` needed. Opt out with `secrets.agent.auto: false`.
+- **Configurable, still flexible.** Set the global default in `agents.yaml` (`secrets.policy: always` to restore prompt-every-time), or override per bundle with `agents secrets policy <bundle> always` for high-value keys (signing, SSH) you want to confirm on every read.
+- **Explicit `always` now persists** under the legacy `tier: biometry` token (older CLIs read it as their own always default). Bundles with no stored policy inherit the configured default — so an existing always-by-default bundle quietly becomes `daily` on first read by the new CLI, which is the intended migration.
+
+**`agents repos view [name]`: inspect one repo's contents without opening it**
+
+- New `agents repo view <name>` (also reachable as `agents repos view`, now a first-class alias of the `repo` command) prints a single repo's git state and per-kind resource counts — `system`, `user`, `project`, or an extra-repo alias. Omit the name for an interactive picker over the registered repos. It reuses the `inspect` repo renderer, so output matches `agents inspect <repo>`; supports `--brief` and `--json`. Source: `src/commands/repo.ts`, `src/commands/inspect.ts`.
+
 **Secrets prompt policy: human-readable `always` / `daily`, and `secrets list` now shows it**
 
 - Renamed the secrets-agent `tier` to a **prompt policy** with plain-language names: `biometry` → **`always`** (ask every time), `session` → **`daily`** (ask once, then held ~24h until screen-lock / sleep / logout). The old name `session` was misleading — it never meant "once per login session" — and collided with the half-dozen other "session" concepts in the CLI (`agents sessions`, sessions-sync, pty/browser sessions). Set it with `agents secrets policy <bundle> [always|daily]`.

package/dist/commands/inspect.d.ts

@@ -32,7 +32,7 @@ interface ResourceItem {
     /** For plugins: the resource categories (skills, commands, …) the bundle packages. */
     groups?: PluginResourceGroup[];
 }
-interface InspectOptions {
+export interface InspectOptions {
     brief?: boolean;
     json?: boolean;
     commands?: boolean | string;
@@ -66,6 +66,7 @@ export interface RepoTarget {
  * Returns null when the target is none of these.
  */
 export declare function resolveRepoTarget(target: string, cwd?: string): RepoTarget | null;
+export declare function inspectRepo(repo: RepoTarget, options: InspectOptions): Promise<void>;
 /** List one resource kind from a single repo root — no layering, no overrides. */
 export declare function collectRepoKind(repo: RepoTarget, kind: DrillableKind): ResourceItem[];
 /** Recursive size + file count of a path; symlinks are not followed. */

package/dist/commands/inspect.js

@@ -227,7 +227,7 @@ function isDotAgentsRoot(dir) {
     }
     return false;
 }
-async function inspectRepo(repo, options) {
+export async function inspectRepo(repo, options) {
     const drill = pickDrillKind(options);
     const jsonHead = { repo: repo.label, root: repo.root };
     if (drill) {

package/dist/commands/menubar.js

@@ -61,9 +61,14 @@ export function registerMenubarCommands(program) {
         console.log(`  running            ${yn(s.running)}`);
         console.log(`  service installed  ${yn(s.serviceInstalled)}`);
         console.log(`  app installed      ${s.installedApp ? chalk.gray(s.installedApp) : chalk.gray('no')}`);
+        console.log(`  installed version  ${s.installedVersion ? chalk.gray(s.installedVersion) : chalk.gray('unknown')}`);
+        console.log(`  current version    ${chalk.gray(s.currentVersion)}`);
         console.log(`  bundle source      ${s.source ? chalk.gray(s.source) : chalk.red('missing (cannot enable)')}`);
         console.log(`  disabled by user   ${yn(s.disabledByUser)}`);
-        if (!s.serviceInstalled && !s.disabledByUser) {
+        if (s.stale) {
+            console.log(chalk.yellow('\n  Installed helper is stale — runs on next `agents` startup, or `agents menubar enable` now.'));
+        }
+        else if (!s.serviceInstalled && !s.disabledByUser) {
             console.log(chalk.gray('\n  Enable it with `agents menubar enable`.'));
         }
     });

package/dist/commands/repo.js

@@ -7,6 +7,8 @@ import simpleGit from 'simple-git';
 import { confirm, input } from '@inquirer/prompts';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
 import { setHelpSections } from '../lib/help.js';
+import { itemPicker } from '../lib/picker.js';
+import { inspectRepo, resolveRepoTarget, } from './inspect.js';
 const HOME = os.homedir();
 /**
  * Resolve a target argument to an absolute path.
@@ -162,6 +164,7 @@ async function listRepos(alias) {
 export function registerRepoCommands(program) {
     const repoCmd = program
         .command('repo')
+        .alias('repos')
         .description('Manage extra DotAgent repos alongside ~/.agents/ (for private or team skills).');
     setHelpSections(repoCmd, {
         examples: `
@@ -180,6 +183,9 @@ export function registerRepoCommands(program) {
       # See what's registered
       agents repo list
 
+      # View one repo's contents (git state + resource counts); omit the name for a picker
+      agents repos view system
+
       # Temporarily disable without deleting
       agents repo disable acme
     `,
@@ -356,6 +362,40 @@ export function registerRepoCommands(program) {
         .action(async (alias) => {
         await listRepos(alias);
     });
+    repoCmd
+        .command('view [name]')
+        .description("Show one repo's contents: git state and per-kind resource counts. Omit the name for an interactive picker.")
+        .option('--brief', 'header + git only; skip resource counts')
+        .option('--json', 'machine-readable JSON output')
+        .action(async (name, options) => {
+        if (name) {
+            const repo = resolveRepoTarget(name);
+            if (!repo) {
+                console.log(chalk.red(`Unknown repo "${name}". Use "system", "user", "project", or a registered extra alias.`));
+                process.exitCode = 1;
+                return;
+            }
+            await inspectRepo(repo, options);
+            return;
+        }
+        const targets = collectRepoTargets(undefined) || [];
+        if (!isInteractiveTerminal()) {
+            console.log(chalk.red('No repo name given and not an interactive terminal.'));
+            console.log(chalk.gray('Pass a name (e.g. `agents repos view system`) or run in a TTY for the picker.'));
+            process.exitCode = 1;
+            return;
+        }
+        const picked = await itemPicker({
+            message: 'Select a repo to view',
+            items: targets,
+            filter: (q) => targets.filter((t) => t.alias.toLowerCase().includes(q.toLowerCase())),
+            labelFor: (t) => `${chalk.cyan(t.alias.padEnd(10))} ${chalk.gray(t.dir)}`,
+        });
+        if (!picked)
+            return;
+        const repo = { label: picked.item.alias, root: picked.item.dir };
+        await inspectRepo(repo, options);
+    });
     repoCmd
         .command('remove <alias>')
         .alias('rm')

package/dist/commands/secrets.js

@@ -424,14 +424,15 @@ export function registerSecretsCommands(program) {
       never touch disk in plaintext. Every item is device-local and gated by Touch ID
       or device passcode; cross-machine sync is handled by 'agents secrets push/pull'.
 
-      Touch ID noise: macOS pops a prompt per bundle per process, so concurrent
-      agents each re-prompt. Each bundle has a prompt policy, shown in the POLICY
-      column of 'agents secrets list':
-        always (default)  ask for Touch ID every time — never auto-held.
-        daily             ask once, then hold it silently in the local agent up
+      Touch ID noise: macOS pops a prompt per bundle per process. Each bundle has
+      a prompt policy, shown in the POLICY column of 'agents secrets list':
+        daily (default)   ask once, then hold it silently in the local agent up
                           to ~24h, until screen-lock / sleep / logout or 'lock'.
-      Set it with 'agents secrets policy <bundle> daily'. 'agents secrets unlock
-      <bundle>' holds any bundle after one prompt regardless of policy. Nothing on disk.
+        always            ask for Touch ID every time — never auto-held.
+      The default is 'daily' (one Touch ID per ~24h); change it globally with
+      'secrets.policy' in agents.yaml, or per bundle with 'agents secrets policy
+      <bundle> always'. 'agents secrets unlock <bundle>' holds any bundle after one
+      prompt regardless of policy. Nothing on disk.
 
       See also:
         agents secrets policy <bundle> daily           ask once a day, not every run
@@ -623,7 +624,7 @@ export function registerSecretsCommands(program) {
         .description('Create an empty bundle')
         .option('--description <text>', 'Free-form description')
         .option('--allow-exec', 'Allow exec: refs in this bundle (off by default)')
-        .option('--policy <policy>', 'prompt policy: always (default, ask every time) or daily (ask once a day)')
+        .option('--policy <policy>', 'prompt policy: daily (default, ask once a day) or always (ask every time)')
         .addOption(new Option('--tier <policy>', 'deprecated alias for --policy').hideHelp())
         .option('--backend <backend>', 'storage backend: keychain (default) or file (passphrase-encrypted, headless-readable)', 'keychain')
         .option('--force', 'Overwrite an existing bundle')
@@ -631,7 +632,10 @@ export function registerSecretsCommands(program) {
         try {
             const resolvedName = name ?? (await promptBundleName());
             validateBundleName(resolvedName);
-            const policy = parsePolicyOpt(opts.policy ?? opts.tier);
+            // Leave policy unset unless the user explicitly chose one, so the bundle
+            // inherits the configured default (`daily`) instead of being pinned.
+            const policyOpt = opts.policy ?? opts.tier;
+            const policy = policyOpt ? parsePolicyOpt(policyOpt) : undefined;
             const backend = parseBackendOpt(opts.backend);
             if (bundleExists(resolvedName) && !opts.force) {
                 console.error(chalk.red(`Bundle '${resolvedName}' already exists. Use --force to overwrite.`));
@@ -647,7 +651,7 @@ export function registerSecretsCommands(program) {
             };
             writeBundle(bundle);
             const tags = [
-                policy === 'daily' ? 'policy: daily' : 'policy: always ask',
+                bundlePolicy(bundle) === 'daily' ? 'policy: daily' : 'policy: always ask',
                 backend === 'file' ? 'backend: file' : null,
             ].filter(Boolean);
             console.log(chalk.green(`Bundle '${resolvedName}' created (${tags.join(', ')}).`));
@@ -1430,7 +1434,7 @@ Examples:
     cmd
         .command('policy <bundle> [policy]')
         .alias('tier')
-        .description("Show or set a bundle's prompt policy: always (default, ask every time) or daily (ask once a day).")
+        .description("Show or set a bundle's prompt policy: daily (default, ask once a day) or always (ask every time).")
         .action((bundleName, policyArg) => {
         try {
             const bundle = readBundle(bundleName);
@@ -1443,7 +1447,7 @@ Examples:
             writeBundle(bundle);
             console.log(chalk.green(`${bundle.name} policy set to ${next}.`));
             if (next === 'daily') {
-                console.log(chalk.gray('Held by the secrets-agent after one unlock: run `agents secrets unlock`, or enable auto-cache with `secrets.agent.auto: true` in agents.yaml.'));
+                console.log(chalk.gray('Held by the secrets-agent for ~24h after one unlock (auto-cache is on by default; disable with `secrets.agent.auto: false` in agents.yaml).'));
             }
             else {
                 console.log(chalk.gray('Asks for Touch ID every time — never auto-held.'));

package/dist/lib/fs-atomic.d.ts

@@ -12,7 +12,8 @@ export declare function ensureLockTarget(filePath: string, initialContent?: stri
 export declare function atomicWriteFileSync(filePath: string, content: string): void;
 /**
  * Acquires an exclusive proper-lockfile lock on filePath, runs fn, then
- * releases the lock. Retries up to LOCK_RETRIES times with linear back-off.
- * Breaks stale locks older than LOCK_STALE_MS.
+ * releases the lock. Retries with capped linear back-off until either the lock
+ * is acquired or LOCK_ACQUIRE_TIMEOUT_MS elapses. Breaks stale locks older than
+ * LOCK_STALE_MS, so a crashed holder never blocks past the stale window.
  */
 export declare function withFileLock<T>(filePath: string, fn: () => T): T;

package/dist/lib/fs-atomic.js

@@ -3,7 +3,18 @@ import * as path from 'path';
 import { randomBytes } from 'crypto';
 import lockfile from 'proper-lockfile';
 const LOCK_STALE_MS = 5_000;
-const LOCK_RETRIES = 5;
+// Wall-clock budget to acquire the lock before giving up. A count-bounded retry
+// (the old 5 attempts / ~750ms ceiling) could expire while a peer legitimately
+// held the lock — under CI/parallel load two `agents` invocations mutating
+// agents.yaml would have one throw and silently drop its write. The budget must
+// comfortably exceed both a normal critical-section hold and the stale-break
+// window (LOCK_STALE_MS): a dead holder's lock turns stale at 5s and is then
+// broken on the next attempt, so this only ever waits out a live, in-progress
+// holder. Bounded (not unbounded) so a truly wedged holder still surfaces an
+// error instead of hanging the CLI forever.
+const LOCK_ACQUIRE_TIMEOUT_MS = 30_000;
+const LOCK_RETRY_MIN_MS = 50;
+const LOCK_RETRY_MAX_MS = 250;
 // Reused across all sleepSync calls — avoids allocating a new SAB each time.
 const _sleepBuf = new Int32Array(new SharedArrayBuffer(4));
 export function sleepSync(ms) {
@@ -46,26 +57,30 @@ export function atomicWriteFileSync(filePath, content) {
 }
 /**
  * Acquires an exclusive proper-lockfile lock on filePath, runs fn, then
- * releases the lock. Retries up to LOCK_RETRIES times with linear back-off.
- * Breaks stale locks older than LOCK_STALE_MS.
+ * releases the lock. Retries with capped linear back-off until either the lock
+ * is acquired or LOCK_ACQUIRE_TIMEOUT_MS elapses. Breaks stale locks older than
+ * LOCK_STALE_MS, so a crashed holder never blocks past the stale window.
  */
 export function withFileLock(filePath, fn) {
     let release = null;
     let lastError;
-    for (let attempt = 0; attempt <= LOCK_RETRIES; attempt++) {
+    const deadline = Date.now() + LOCK_ACQUIRE_TIMEOUT_MS;
+    for (let attempt = 0;; attempt++) {
         try {
             release = lockfile.lockSync(filePath, { stale: LOCK_STALE_MS });
             break;
         }
         catch (err) {
             lastError = err;
-            if (attempt < LOCK_RETRIES)
-                sleepSync(50 * (attempt + 1));
+            if (Date.now() >= deadline)
+                break;
+            const backoff = Math.min(LOCK_RETRY_MIN_MS * (attempt + 1), LOCK_RETRY_MAX_MS);
+            sleepSync(Math.min(backoff, Math.max(0, deadline - Date.now())));
         }
     }
     if (!release) {
         const message = lastError instanceof Error ? lastError.message : String(lastError);
-        throw new Error(`Could not acquire lock for ${filePath}: ${message}`);
+        throw new Error(`Could not acquire lock for ${filePath} after ${LOCK_ACQUIRE_TIMEOUT_MS}ms: ${message}`);
     }
     try {
         return fn();

package/dist/lib/hooks.js

@@ -15,7 +15,8 @@ import * as TOML from 'smol-toml';
 import { AGENTS, agentConfigDirName } from './agents.js';
 import { supports, explainSkip, capableAgents } from './capabilities.js';
 import { setGeminiAutoUpdateDisabled, updateGeminiSettings } from './gemini-settings.js';
-import { getHooksDir as getSystemHooksDir, getUserHooksDir, getUserAgentsDir, getSystemAgentsDir, getProjectAgentsDir, getTrashHooksDir, getEnabledExtraRepos } from './state.js';
+import { getHooksDir as getSystemHooksDir, getUserHooksDir, getUserAgentsDir, getSystemAgentsDir, getProjectAgentsDir, getTrashHooksDir, getEnabledExtraRepos, getResolvedRulesDir, getUserRulesDir } from './state.js';
+import { collectSubruleHooksFromState } from './rules/compose.js';
 function getCentralHooksDir() { return getUserHooksDir(); }
 /**
  * Resolve a hook script's absolute path. Checks user dir first, then enabled
@@ -52,6 +53,12 @@ function getManagedHookPrefixes() {
         path.join(getUserAgentsDir(), 'hooks') + path.sep,
         ...extraDirs.map(d => path.join(d, 'hooks') + path.sep),
         path.join(getSystemAgentsDir(), 'hooks') + path.sep,
+        // Subrule-dir hook scripts register by their absolute source path under a
+        // rules `subrules/` tree. Cover those trees so a removed subrule/hook's
+        // stale settings entry gets garbage-collected like any other managed hook.
+        path.join(getUserRulesDir(), 'subrules') + path.sep,
+        ...extraDirs.map(d => path.join(d, 'rules', 'subrules') + path.sep),
+        path.join(getResolvedRulesDir(), 'subrules') + path.sep,
     ];
 }
 /**
@@ -159,6 +166,19 @@ const SCRIPT_EXTENSIONS = new Set([
 function isExecutable(mode) {
     return (mode & 0o111) !== 0;
 }
+/**
+ * Ensure a script file carries an exec bit. Subrule-dir hook scripts are
+ * registered by their source path (not copied), so they must be executable in
+ * place. Best-effort: a chmod failure (read-only fs, foreign owner) is ignored.
+ */
+function ensureExecutable(scriptPath) {
+    try {
+        const mode = fs.statSync(scriptPath).mode;
+        if (!isExecutable(mode))
+            fs.chmodSync(scriptPath, mode | 0o755);
+    }
+    catch { /* best effort */ }
+}
 function getHooksDir(agentId) {
     const agent = AGENTS[agentId];
     const home = getEffectiveHome(agentId);
@@ -666,6 +686,15 @@ export function parseHookManifest(opts = {}) {
     const warn = opts.warn !== false;
     const merged = {};
     const systemHooks = {};
+    // Lowest-precedence layer: hooks declared inside active subrule directories.
+    // Seeded first so any same-key entry from system/user agents.yaml wins.
+    // Gated so a malformed hooks.yaml never breaks rule sync.
+    try {
+        const subruleHooks = collectSubruleHooksFromState();
+        for (const [name, def] of Object.entries(subruleHooks))
+            merged[name] = def;
+    }
+    catch { /* subrule hook collection is best-effort */ }
     // System layer: hooks: section of agents.yaml (npm-shipped, separate repo).
     const systemPath = path.join(getSystemAgentsDir(), 'agents.yaml');
     if (fs.existsSync(systemPath)) {
@@ -780,6 +809,12 @@ export function registerHooksToSettings(agentId, versionHome, hookManifest, agen
         ? path.join(versionHome, agentConfigDirName(agentId), AGENTS[agentId].hooksDir)
         : null;
     const resolveScript = (script) => {
+        // Subrule-dir hooks declare an already-absolute script path. Use it
+        // directly (made executable) — these are not copied into the version home.
+        if (path.isAbsolute(script) && fs.existsSync(script)) {
+            ensureExecutable(script);
+            return script;
+        }
         if (overrideRoots) {
             return resolveContainedHookPath(path.join(overrideRoots[0], 'hooks'), script);
         }

package/dist/lib/menubar/install-menubar.d.ts

@@ -35,21 +35,45 @@ export declare function ensureMenubarAppInstalled(opts?: {
 export declare function enableMenubarService(opts?: {
     clearOptOut?: boolean;
 }): boolean;
+/**
+ * Pure staleness decision (no I/O) so the truth table is unit-testable. The
+ * installed service is stale when the helper binary is gone, or when it was
+ * installed by a different CLI version than the one now running — a version
+ * change is the signal that the plist's baked interpreter/entry/bundle paths
+ * and the helper binary itself may have drifted. A null installedVersion
+ * (pre-stamp install) counts as stale so old installs get re-stamped once.
+ */
+export declare function isMenubarStale(opts: {
+    installedVersion: string | null;
+    currentVersion: string;
+    execExists: boolean;
+}): boolean;
 /**
  * Stop + remove the menu-bar service and write the sticky opt-out so the
  * upgrade migration won't re-enable it.
  */
 export declare function disableMenubarService(): void;
 /**
- * Upgrade-time auto-enable. Runs from runMigration() once per sentinel bump.
- * No-ops if: not darwin, the user opted out, no helper bundle ships, or the
- * service is already installed. Best-effort — never throws into migration.
+ * Startup self-heal, run on every darwin CLI invocation (see src/index.ts).
+ * No-ops cheaply (a couple of existsSync + a tiny file read) unless work is
+ * needed:
+ *   - fresh install (no service yet)      -> enable
+ *   - upgrade (version stamp changed) or  -> re-enable: recopy the new helper
+ *     the App Support helper went missing     binary + rewrite the plist + kick
+ *
+ * Without the staleness re-enable, `npm update` refreshed the CLI but left the
+ * menu bar running the previous release's helper binary on a possibly-stale
+ * plist. No-ops if: not darwin, the user opted out, or no helper bundle ships.
+ * Best-effort — never throws into startup.
  */
 export declare function installMenubarLaunchAgentOnUpgrade(): void;
 export interface MenubarStatus {
     platform: string;
     source: string | null;
     installedApp: string | null;
+    installedVersion: string | null;
+    currentVersion: string;
+    stale: boolean;
     serviceInstalled: boolean;
     running: boolean;
     disabledByUser: boolean;

package/dist/lib/menubar/install-menubar.js

@@ -20,15 +20,38 @@ import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import { getRuntimeStateDir, getHelpersDir } from '../state.js';
+import { getCliVersion } from '../version.js';
 const APP_BUNDLE_NAME = 'MenubarHelper.app';
 const INSTALL_DIR_NAME = 'agents-cli';
 const SERVICE_LABEL = 'com.phnx-labs.agents-menubar';
 function onDarwin() {
     return process.platform === 'darwin';
 }
+/** ~/Library/Application Support/agents-cli */
+function installDir() {
+    return path.join(os.homedir(), 'Library', 'Application Support', INSTALL_DIR_NAME);
+}
 /** ~/Library/Application Support/agents-cli/MenubarHelper.app */
 function installedAppPath() {
-    return path.join(os.homedir(), 'Library', 'Application Support', INSTALL_DIR_NAME, APP_BUNDLE_NAME);
+    return path.join(installDir(), APP_BUNDLE_NAME);
+}
+/**
+ * Version stamp written next to the installed bundle. The upgrade self-heal
+ * compares this against the running CLI's version to decide whether the App
+ * Support copy + plist need to be rebuilt — without it, a `npm update` refreshes
+ * dist/index.js but leaves the menu bar running the OLD helper binary and a
+ * plist whose baked paths may have drifted.
+ */
+function installedVersionMarkerPath() {
+    return path.join(installDir(), '.menubar-version');
+}
+function readInstalledMenubarVersion() {
+    try {
+        return fs.readFileSync(installedVersionMarkerPath(), 'utf-8').trim() || null;
+    }
+    catch {
+        return null;
+    }
 }
 /** Executable inside the installed bundle. */
 function installedExecutablePath() {
@@ -222,8 +245,34 @@ export function enableMenubarService(opts = { clearOptOut: true }) {
         execFileSync('launchctl', ['kickstart', '-k', `gui/${uid}/${SERVICE_LABEL}`], { stdio: ['ignore', 'ignore', 'ignore'] });
     }
     catch { /* best effort */ }
+    // Stamp the version we just installed so the upgrade self-heal can tell when
+    // a later release ships a newer helper that needs reinstalling.
+    try {
+        fs.writeFileSync(installedVersionMarkerPath(), getCliVersion());
+    }
+    catch { /* best effort */ }
     return true;
 }
+/**
+ * Pure staleness decision (no I/O) so the truth table is unit-testable. The
+ * installed service is stale when the helper binary is gone, or when it was
+ * installed by a different CLI version than the one now running — a version
+ * change is the signal that the plist's baked interpreter/entry/bundle paths
+ * and the helper binary itself may have drifted. A null installedVersion
+ * (pre-stamp install) counts as stale so old installs get re-stamped once.
+ */
+export function isMenubarStale(opts) {
+    if (!opts.execExists)
+        return true;
+    return opts.installedVersion !== opts.currentVersion;
+}
+function menubarSetupStale() {
+    return isMenubarStale({
+        installedVersion: readInstalledMenubarVersion(),
+        currentVersion: getCliVersion(),
+        execExists: fs.existsSync(installedExecutablePath()),
+    });
+}
 /**
  * Stop + remove the menu-bar service and write the sticky opt-out so the
  * upgrade migration won't re-enable it.
@@ -253,9 +302,17 @@ export function disableMenubarService() {
     catch { /* best effort */ }
 }
 /**
- * Upgrade-time auto-enable. Runs from runMigration() once per sentinel bump.
- * No-ops if: not darwin, the user opted out, no helper bundle ships, or the
- * service is already installed. Best-effort — never throws into migration.
+ * Startup self-heal, run on every darwin CLI invocation (see src/index.ts).
+ * No-ops cheaply (a couple of existsSync + a tiny file read) unless work is
+ * needed:
+ *   - fresh install (no service yet)      -> enable
+ *   - upgrade (version stamp changed) or  -> re-enable: recopy the new helper
+ *     the App Support helper went missing     binary + rewrite the plist + kick
+ *
+ * Without the staleness re-enable, `npm update` refreshed the CLI but left the
+ * menu bar running the previous release's helper binary on a possibly-stale
+ * plist. No-ops if: not darwin, the user opted out, or no helper bundle ships.
+ * Best-effort — never throws into startup.
  */
 export function installMenubarLaunchAgentOnUpgrade() {
     try {
@@ -263,14 +320,18 @@ export function installMenubarLaunchAgentOnUpgrade() {
             return;
         if (menubarDisabledByUser())
             return;
-        if (menubarServiceInstalled())
-            return;
         if (!sourceAppPath())
             return;
-        enableMenubarService({ clearOptOut: false });
+        if (!menubarServiceInstalled()) {
+            enableMenubarService({ clearOptOut: false });
+            return;
+        }
+        if (menubarSetupStale()) {
+            enableMenubarService({ clearOptOut: false });
+        }
     }
     catch {
-        /* never block migration on the menu bar */
+        /* never block startup on the menu bar */
     }
 }
 export function getMenubarStatus() {
@@ -280,11 +341,15 @@ export function getMenubarStatus() {
         const r = spawnSync('pgrep', ['-f', 'MenubarHelper'], { stdio: ['ignore', 'pipe', 'ignore'], encoding: 'utf-8' });
         running = r.status === 0 && (r.stdout || '').trim().length > 0;
     }
+    const serviceInstalled = menubarServiceInstalled();
     return {
         platform: process.platform,
         source: sourceAppPath(),
         installedApp: fs.existsSync(dest) ? dest : null,
-        serviceInstalled: menubarServiceInstalled(),
+        installedVersion: readInstalledMenubarVersion(),
+        currentVersion: getCliVersion(),
+        stale: onDarwin() && serviceInstalled && menubarSetupStale(),
+        serviceInstalled,
         running,
         disabledByUser: menubarDisabledByUser(),
     };

package/dist/lib/resources/rules.d.ts

@@ -22,8 +22,11 @@ export interface RulesLayerDir {
     dir: string;
 }
 /**
- * List subrule markdown files in a directory.
- * Returns names without the .md extension.
+ * List subrule names in a directory.
+ *
+ * A name comes from either the flat form `<name>.md` OR the dir form
+ * `<name>/rule.md`; a directory without `rule.md` is not a subrule. Returns
+ * names without the .md extension.
  */
 export declare function listSubrulesInDir(subrulesDir: string): string[];
 /**

package/dist/lib/resources/rules.js

@@ -14,19 +14,46 @@ import * as path from 'path';
 import { getSystemRulesDir, getUserRulesDir, getProjectAgentsDir, getEnabledExtraRepos, } from '../state.js';
 const SUBRULES_DIR = 'subrules';
 const SUBRULES_README = 'README.md';
+/** Inside a dir-form subrule, the prose file. */
+const SUBRULE_RULE_FILE = 'rule.md';
 /**
- * List subrule markdown files in a directory.
- * Returns names without the .md extension.
+ * Resolve the prose file path for a subrule named `name` under `subrulesDir`.
+ *
+ * Dir form `<name>/rule.md` wins when present; otherwise the flat `<name>.md`.
+ * Returns null when neither exists.
+ */
+function resolveSubruleFile(subrulesDir, name) {
+    const dirForm = path.join(subrulesDir, name, SUBRULE_RULE_FILE);
+    if (fs.existsSync(dirForm))
+        return dirForm;
+    const flatForm = path.join(subrulesDir, `${name}.md`);
+    if (fs.existsSync(flatForm))
+        return flatForm;
+    return null;
+}
+/**
+ * List subrule names in a directory.
+ *
+ * A name comes from either the flat form `<name>.md` OR the dir form
+ * `<name>/rule.md`; a directory without `rule.md` is not a subrule. Returns
+ * names without the .md extension.
  */
 export function listSubrulesInDir(subrulesDir) {
     if (!fs.existsSync(subrulesDir))
         return [];
     try {
-        return fs
-            .readdirSync(subrulesDir)
-            .filter((f) => f.endsWith('.md') && f !== SUBRULES_README)
-            .map((f) => f.slice(0, -3))
-            .sort();
+        const names = new Set();
+        for (const entry of fs.readdirSync(subrulesDir, { withFileTypes: true })) {
+            if (entry.isDirectory()) {
+                if (fs.existsSync(path.join(subrulesDir, entry.name, SUBRULE_RULE_FILE))) {
+                    names.add(entry.name);
+                }
+            }
+            else if (entry.name.endsWith('.md') && entry.name !== SUBRULES_README) {
+                names.add(entry.name.slice(0, -3));
+            }
+        }
+        return [...names].sort();
     }
     catch {
         return [];
@@ -77,7 +104,9 @@ export function listAllRules(layers) {
             if (seen.has(name))
                 continue;
             seen.add(name);
-            const filePath = path.join(subrulesDir, `${name}.md`);
+            const filePath = resolveSubruleFile(subrulesDir, name);
+            if (!filePath)
+                continue;
             let content = '';
             try {
                 content = fs.readFileSync(filePath, 'utf-8');
@@ -101,8 +130,8 @@ export function listAllRules(layers) {
  */
 export function resolveRule(name, layers) {
     for (const { layer, dir } of layers) {
-        const filePath = path.join(dir, SUBRULES_DIR, `${name}.md`);
-        if (fs.existsSync(filePath)) {
+        const filePath = resolveSubruleFile(path.join(dir, SUBRULES_DIR), name);
+        if (filePath) {
             let content = '';
             try {
                 content = fs.readFileSync(filePath, 'utf-8');

package/dist/lib/rules/compose.d.ts

@@ -18,6 +18,7 @@
  * No filesystem writes happen here — callers (`syncResourcesToVersion`,
  * project-rules compile) decide where to land the composed output.
  */
+import type { ManifestHook } from '../types.js';
 export type LayerScope = 'project' | 'user' | 'extra' | 'system';
 export interface RulesLayer {
     scope: LayerScope;
@@ -43,6 +44,8 @@ export interface ComposedSubrule {
     sourcePath: string;
     layerScope: LayerScope;
     layerAlias?: string;
+    /** Set when the subrule is dir-form (`subrules/<name>/`); the dir itself. */
+    subruleDir?: string;
 }
 export interface ComposeResult {
     /** Fully concatenated, no @-imports. */
@@ -76,3 +79,22 @@ export declare function composeRulesFromState(opts?: {
     preset?: string;
     cwd?: string;
 }): ComposeResult;
+/**
+ * Collect hooks declared inside the active subrule directories.
+ *
+ * Resolves the same composed subrule set as {@link composeRules} (preset-named
+ * plus auto-append, highest-layer-wins per name). For each dir-form subrule
+ * that ships a `hooks.yaml`, parses it, rewrites each hook's `script` to an
+ * ABSOLUTE path under the subrule dir, and namespaces the key as
+ * `<subruleName>__<hookName>` to avoid collisions across subrules.
+ *
+ * Returns an empty map for flat subrules and dir-form subrules without a
+ * `hooks.yaml`. A malformed hooks.yaml is skipped (try/catch) so a bad file
+ * never breaks rule composition or hook registration.
+ */
+export declare function collectSubruleHooks(layers: RulesLayer[], presetName?: string): Record<string, ManifestHook>;
+/** Convenience wrapper — discovers layers from state, then collects hooks. */
+export declare function collectSubruleHooksFromState(opts?: {
+    preset?: string;
+    cwd?: string;
+}): Record<string, ManifestHook>;

package/dist/lib/rules/compose.js

@@ -26,6 +26,28 @@ const SUBRULES_DIR_NAME = 'subrules';
 const RULES_YAML_NAME = 'rules.yaml';
 const DEFAULT_PRESET = 'default';
 const SUBRULES_README = 'README.md';
+/** Inside a dir-form subrule, the prose file. */
+const SUBRULE_RULE_FILE = 'rule.md';
+/** Inside a dir-form subrule, the optional hook manifest. */
+const SUBRULE_HOOKS_FILE = 'hooks.yaml';
+/**
+ * Resolve the prose file for a subrule named `name` under `<rulesDir>/subrules/`.
+ *
+ * A subrule resolves to the DIRECTORY form `subrules/<name>/rule.md` when that
+ * file exists, otherwise the flat form `subrules/<name>.md`. Returns the
+ * markdown path plus the dir-form subrule directory when applicable (callers
+ * that fold hooks need the dir to resolve `hooks.yaml` and relative scripts).
+ */
+function resolveSubrulePath(rulesDir, name) {
+    const dirForm = path.join(rulesDir, SUBRULES_DIR_NAME, name, SUBRULE_RULE_FILE);
+    if (fs.existsSync(dirForm)) {
+        return { sourcePath: dirForm, subruleDir: path.join(rulesDir, SUBRULES_DIR_NAME, name) };
+    }
+    const flatForm = path.join(rulesDir, SUBRULES_DIR_NAME, `${name}.md`);
+    if (fs.existsSync(flatForm))
+        return { sourcePath: flatForm };
+    return null;
+}
 function readRulesYaml(rulesDir) {
     const p = path.join(rulesDir, RULES_YAML_NAME);
     if (!fs.existsSync(p))
@@ -51,22 +73,33 @@ function resolvePreset(layers, preset) {
 }
 function findSubrule(layers, name) {
     for (const layer of layers) {
-        const p = path.join(layer.rulesDir, SUBRULES_DIR_NAME, `${name}.md`);
-        if (fs.existsSync(p))
-            return { sourcePath: p, layer };
+        const found = resolveSubrulePath(layer.rulesDir, name);
+        if (found)
+            return { ...found, layer };
     }
     return null;
 }
+/**
+ * List subrule names in a layer. A name is contributed by either the flat
+ * form `subrules/<name>.md` OR the dir form `subrules/<name>/rule.md`; a
+ * directory without `rule.md` is not a subrule and is skipped.
+ */
 function listLayerSubruleNames(layer) {
     const dir = path.join(layer.rulesDir, SUBRULES_DIR_NAME);
     if (!fs.existsSync(dir))
         return [];
     try {
-        return fs
-            .readdirSync(dir)
-            .filter((f) => f.endsWith('.md') && f !== SUBRULES_README)
-            .map((f) => f.slice(0, -3))
-            .sort();
+        const names = new Set();
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            if (entry.isDirectory()) {
+                if (fs.existsSync(path.join(dir, entry.name, SUBRULE_RULE_FILE)))
+                    names.add(entry.name);
+            }
+            else if (entry.name.endsWith('.md') && entry.name !== SUBRULES_README) {
+                names.add(entry.name.slice(0, -3));
+            }
+        }
+        return [...names].sort();
     }
     catch {
         return [];
@@ -98,6 +131,7 @@ export function composeRules(opts) {
             sourcePath: found.sourcePath,
             layerScope: found.layer.scope,
             layerAlias: found.layer.alias,
+            subruleDir: found.subruleDir,
         });
         seen.add(name);
     }
@@ -109,11 +143,15 @@ export function composeRules(opts) {
         for (const name of listLayerSubruleNames(layer)) {
             if (seen.has(name))
                 continue;
+            const resolved = resolveSubrulePath(layer.rulesDir, name);
+            if (!resolved)
+                continue;
             composed.push({
                 name,
-                sourcePath: path.join(layer.rulesDir, SUBRULES_DIR_NAME, `${name}.md`),
+                sourcePath: resolved.sourcePath,
                 layerScope: layer.scope,
                 layerAlias: layer.alias,
+                subruleDir: resolved.subruleDir,
             });
             seen.add(name);
         }
@@ -168,3 +206,70 @@ export function composeRulesFromState(opts = {}) {
     const layers = discoverRulesLayers({ cwd: opts.cwd });
     return composeRules({ preset: opts.preset, layers });
 }
+/**
+ * hooks.yaml shape (the bare-map form, chosen for brevity):
+ *
+ *   <hookName>:
+ *     script: enforce.sh        # relative to the subrule dir
+ *     events: [PreToolUse]
+ *     matcher: "Edit|Write"     # optional
+ *     timeout: 30               # optional
+ *
+ * A wrapped `{ hooks: { <hookName>: {...} } }` form is also accepted so a
+ * hooks.yaml can carry sibling keys without confusing the parser.
+ */
+function parseSubruleHooksFile(file) {
+    const parsed = yaml.parse(fs.readFileSync(file, 'utf-8'));
+    if (!parsed || typeof parsed !== 'object')
+        return {};
+    const map = parsed.hooks ?? parsed;
+    return map || {};
+}
+/**
+ * Collect hooks declared inside the active subrule directories.
+ *
+ * Resolves the same composed subrule set as {@link composeRules} (preset-named
+ * plus auto-append, highest-layer-wins per name). For each dir-form subrule
+ * that ships a `hooks.yaml`, parses it, rewrites each hook's `script` to an
+ * ABSOLUTE path under the subrule dir, and namespaces the key as
+ * `<subruleName>__<hookName>` to avoid collisions across subrules.
+ *
+ * Returns an empty map for flat subrules and dir-form subrules without a
+ * `hooks.yaml`. A malformed hooks.yaml is skipped (try/catch) so a bad file
+ * never breaks rule composition or hook registration.
+ */
+export function collectSubruleHooks(layers, presetName) {
+    const result = {};
+    let composed;
+    try {
+        composed = composeRules({ preset: presetName, layers });
+    }
+    catch {
+        return result;
+    }
+    for (const sub of composed.subrules) {
+        if (!sub.subruleDir)
+            continue; // flat subrule — no hooks
+        const hooksFile = path.join(sub.subruleDir, SUBRULE_HOOKS_FILE);
+        if (!fs.existsSync(hooksFile))
+            continue;
+        try {
+            const hooks = parseSubruleHooksFile(hooksFile);
+            for (const [hookName, def] of Object.entries(hooks)) {
+                if (!def || typeof def !== 'object' || typeof def.script !== 'string')
+                    continue;
+                const absScript = path.resolve(sub.subruleDir, def.script);
+                result[`${sub.name}__${hookName}`] = { ...def, script: absScript };
+            }
+        }
+        catch {
+            // Malformed hooks.yaml — skip this subrule's hooks, keep the rest.
+        }
+    }
+    return result;
+}
+/** Convenience wrapper — discovers layers from state, then collects hooks. */
+export function collectSubruleHooksFromState(opts = {}) {
+    const layers = discoverRulesLayers({ cwd: opts.cwd });
+    return collectSubruleHooks(layers, opts.preset);
+}

package/dist/lib/secrets/agent.d.ts

@@ -140,8 +140,10 @@ export declare function agentGetSync(name: string): {
     bundle: SecretsBundle;
     env: Record<string, string>;
 } | null;
-/** True when `secrets.agent.auto` is enabled in agents.yaml. Best-effort; a
- * missing/unreadable meta reads as off. */
+/** True unless `secrets.agent.auto` is explicitly disabled in agents.yaml. The
+ * broker is the mechanism that delivers the `daily` default policy (one Touch ID
+ * per ~24h), so auto-caching is ON by default; opt out with
+ * `secrets.agent.auto: false`. Best-effort; an unreadable meta reads as on. */
 export declare function secretsAgentAutoEnabled(): boolean;
 /**
  * Fire-and-forget: populate the broker with a freshly-resolved bundle so the

package/dist/lib/secrets/agent.js

@@ -529,14 +529,16 @@ export function agentGetSync(name) {
         return null;
     }
 }
-/** True when `secrets.agent.auto` is enabled in agents.yaml. Best-effort; a
- * missing/unreadable meta reads as off. */
+/** True unless `secrets.agent.auto` is explicitly disabled in agents.yaml. The
+ * broker is the mechanism that delivers the `daily` default policy (one Touch ID
+ * per ~24h), so auto-caching is ON by default; opt out with
+ * `secrets.agent.auto: false`. Best-effort; an unreadable meta reads as on. */
 export function secretsAgentAutoEnabled() {
     try {
-        return readMeta().secrets?.agent?.auto === true;
+        return readMeta().secrets?.agent?.auto !== false;
     }
     catch {
-        return false;
+        return true;
     }
 }
 /**

package/dist/lib/secrets/bundles.d.ts

@@ -40,18 +40,19 @@ export interface VarMeta {
 }
 /**
  * A bundle's prompt policy — how often macOS asks for Touch ID to read it:
- * - `always` (default): asks every time. Only an explicit `agents secrets
- *   unlock` ever holds it in the secrets-agent; every other read pops Touch ID.
- *   Use for high-value bundles you want to confirm every time.
- * - `daily`: ask once, then hold it silently. Eligible for the secrets-agent —
- *   `unlock` it, or (when `secrets.agent.auto` is enabled) the first real
- *   keychain read auto-loads it so concurrent runs read it silently. Held up to
- *   ~24h from that unlock (not refreshed on use); re-asks sooner after
- *   screen-lock, sleep, logout, or `agents secrets lock`.
+ * - `daily` (default): ask once, then hold it silently for up to ~24h. Eligible
+ *   for the secrets-agent — the first real keychain read auto-loads it (auto-cache
+ *   is on by default) so concurrent runs read it silently, or `unlock` it
+ *   explicitly. Held from that unlock (not refreshed on use); re-asks sooner
+ *   after screen-lock, sleep, logout, or `agents secrets lock`.
+ * - `always`: asks every time. Never auto-held — only an explicit `agents
+ *   secrets unlock` ever holds it; every other read pops Touch ID. Opt a
+ *   high-value bundle into this when you want to confirm every single read.
  *
- * Stored on disk under the legacy `tier` key (`session` == `daily`; absent ==
- * `always`) so bundles stay readable across mixed CLI versions on synced
- * machines. The in-memory and user-facing vocabulary is `policy`/`always`/`daily`.
+ * The default is configurable via `secrets.policy` in agents.yaml. Stored on disk
+ * under the legacy `tier` key (`session` == `daily`, `biometry` == explicit
+ * `always`, absent == inherit the default) so bundles stay readable across mixed
+ * CLI versions on synced machines. The user-facing vocabulary is `policy`/`always`/`daily`.
  */
 export type SecretsPolicy = 'always' | 'daily';
 /** A named set of environment variable definitions backed by various secret providers. */
@@ -61,8 +62,8 @@ export interface SecretsBundle {
     allow_exec?: boolean;
     /** Which store carries this bundle's items. Absent ⇒ `keychain` (the default). */
     backend?: SecretsBackend;
-    /** Prompt policy. Absent ⇒ `always` (the safe default). Serialized under the
-     * legacy `tier` key — see SecretsPolicy. */
+    /** Prompt policy. Absent ⇒ the configured default (`daily`). Serialized under
+     * the legacy `tier` key — see SecretsPolicy. */
     policy?: SecretsPolicy;
     /** ISO 8601 UTC timestamp. Set once on the first writeBundle() for a bundle. */
     created_at?: string;
@@ -97,7 +98,12 @@ export declare function validateSecretType(t: string): asserts t is SecretType;
 export declare function validateExpiresFutureDated(iso: string): void;
 export declare function bundleExists(name: string): boolean;
 export declare function readBundle(name: string): SecretsBundle;
-/** The effective prompt policy of a bundle (absent ⇒ `always`). */
+/** The default prompt policy applied to bundles without an explicit per-bundle
+ * policy. Configurable via `secrets.policy` in agents.yaml; `daily` (one Touch
+ * ID per ~24h) unless the user explicitly opts back into prompt-every-time with
+ * `always`. Best-effort: an unreadable config falls back to the `daily` default. */
+export declare function secretsDefaultPolicy(): SecretsPolicy;
+/** The effective prompt policy of a bundle (absent ⇒ the configured default). */
 export declare function bundlePolicy(bundle: SecretsBundle): SecretsPolicy;
 export declare function writeBundle(bundle: SecretsBundle): void;
 export declare function deleteBundle(name: string): boolean;

package/dist/lib/secrets/bundles.js

@@ -24,6 +24,7 @@ import * as yaml from 'yaml';
 import { deleteKeychainToken, getKeychainToken, getKeychainTokens, hasKeychainToken, listKeychainItems, parseBundleValue, resolveRef, secretsKeychainItem, setKeychainToken, } from './index.js';
 import { fileStore } from './filestore.js';
 import { emit } from '../events.js';
+import { readMeta } from '../state.js';
 import { agentGetSync, agentAutoLoadSync, secretsAgentAutoEnabled, DEFAULT_TTL_MS } from './agent.js';
 const keychainStore = {
     has: hasKeychainToken,
@@ -244,16 +245,34 @@ export function readBundle(name) {
     }
     return bundle;
 }
-/** Normalize the persisted prompt policy. The on-disk `tier` key uses the
- * legacy `session` token for `daily` (and `biometry`/absent for the default),
- * so accept both the legacy and current tokens. Anything but `daily`/`session`
- * ⇒ undefined (resolves to the `always` default). */
+/** Normalize the persisted prompt policy. The on-disk `tier` key uses legacy
+ * tokens for cross-version compatibility: `session` ⇒ `daily`, `biometry` ⇒ an
+ * explicit `always`. An absent token ⇒ undefined, which resolves to the
+ * configured default policy (`daily`). Persisting an explicit `always` as the
+ * legacy `biometry` token keeps older CLIs correct — they don't know `daily`,
+ * read `biometry` as undefined, and fall back to their own always default. */
 function parsePolicy(raw) {
-    return raw === 'daily' || raw === 'session' ? 'daily' : undefined;
+    if (raw === 'daily' || raw === 'session')
+        return 'daily';
+    if (raw === 'always' || raw === 'biometry')
+        return 'always';
+    return undefined;
 }
-/** The effective prompt policy of a bundle (absent ⇒ `always`). */
+/** The default prompt policy applied to bundles without an explicit per-bundle
+ * policy. Configurable via `secrets.policy` in agents.yaml; `daily` (one Touch
+ * ID per ~24h) unless the user explicitly opts back into prompt-every-time with
+ * `always`. Best-effort: an unreadable config falls back to the `daily` default. */
+export function secretsDefaultPolicy() {
+    try {
+        return readMeta().secrets?.policy === 'always' ? 'always' : 'daily';
+    }
+    catch {
+        return 'daily';
+    }
+}
+/** The effective prompt policy of a bundle (absent ⇒ the configured default). */
 export function bundlePolicy(bundle) {
-    return bundle.policy ?? 'always';
+    return bundle.policy ?? secretsDefaultPolicy();
 }
 export function writeBundle(bundle) {
     validateBundleName(bundle.name);
@@ -292,9 +311,11 @@ export function writeBundle(bundle) {
         description: bundle.description,
         allow_exec: bundle.allow_exec ? true : undefined,
         backend: backend === 'file' ? 'file' : undefined,
-        // Wire format: persist `daily` under the legacy `tier`/`session` token so
-        // older CLI versions on other synced machines keep reading the policy.
-        tier: bundle.policy === 'daily' ? 'session' : undefined,
+        // Wire format: persist the policy under the legacy `tier` token so older CLI
+        // versions on other synced machines keep reading it — `daily`⇒`session`,
+        // explicit `always`⇒`biometry`. An absent policy omits the token entirely
+        // and resolves to the configured default (`daily`) on read.
+        tier: bundle.policy === 'daily' ? 'session' : bundle.policy === 'always' ? 'biometry' : undefined,
         created_at: bundle.created_at,
         updated_at: bundle.updated_at,
         last_used: bundle.last_used,

package/dist/lib/staleness/checkers/rules.js

@@ -54,7 +54,19 @@ function activeSources(agent, version, cwd) {
             result['rules.yaml'] = yamlPath;
     }
     for (const sub of compose.subrules) {
-        result[`subrules/${sub.name}.md`] = sub.sourcePath;
+        // Key off the actual source path so dir-form subrules (subrules/<name>/rule.md)
+        // and flat ones (subrules/<name>.md) both fingerprint the file that really
+        // contributes to the output, not a hard-coded `.md` that may not exist.
+        if (sub.subruleDir) {
+            result[`subrules/${sub.name}/rule.md`] = sub.sourcePath;
+            // Fingerprint hooks.yaml too so editing a hook re-syncs the rules section.
+            const hooksFile = path.join(sub.subruleDir, 'hooks.yaml');
+            if (fs.existsSync(hooksFile))
+                result[`subrules/${sub.name}/hooks.yaml`] = hooksFile;
+        }
+        else {
+            result[`subrules/${sub.name}.md`] = sub.sourcePath;
+        }
     }
     return result;
 }

package/dist/lib/types.d.ts

@@ -563,9 +563,13 @@ export interface ExtraRepoConfig {
 export interface Meta {
     agents?: Partial<Record<AgentId, string>>;
     run?: RunConfig;
-    /** macOS secrets-agent config. `auto` makes the first real keychain read of a
-     * `session`-tier bundle populate the broker so concurrent runs read silently. */
+    /** macOS secrets-agent config. `policy` is the default prompt policy for
+     * bundles without an explicit per-bundle policy: `daily` (the default) asks
+     * once per ~24h, `always` asks every time. `auto` (default on) lets the first
+     * real keychain read of a `daily` bundle populate the broker so concurrent
+     * runs read silently — set it `false` to force a prompt on every read. */
     secrets?: {
+        policy?: 'always' | 'daily';
         agent?: {
             auto?: boolean;
         };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.20.24",
+  "version": "1.20.26",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams (now with first-class Grok Build CLI support)",
   "type": "module",
   "main": "dist/index.js",