@phnx-labs/agents-cli 1.20.25 → 1.20.27

package/dist/lib/plugins.d.ts

@@ -65,7 +65,12 @@ export declare function loadPluginManifest(pluginRoot: string): PluginManifest |
 export declare function validatePluginName(name: string): boolean;
 export declare function assertPluginTargetContained(targetRoot: string, pluginsDir: string): void;
 /**
- * Get a specific plugin by name.
+ * Get a specific plugin by name. On a cross-marketplace name collision the
+ * highest-precedence scope wins (project > extra > user > system) — the same
+ * resolution the sync writer's Map(last-wins) dedupe and collectPluginScopes()
+ * use. discoverPlugins() yields low→high precedence order, so the LAST match is
+ * the winner; returning the first match would resolve to the lowest scope (e.g.
+ * a system plugin over the user's same-named one), which is exactly backwards.
  */
 export declare function getPlugin(name: string): DiscoveredPlugin | null;
 /**
@@ -212,6 +217,23 @@ export declare function installPlugin(spec: string): Promise<{
     isNew: boolean;
     capabilities: PluginCapabilities;
 }>;
+/** Parsed `.source` provenance written by install/update. `version` is the
+ *  upstream manifest version captured at the last pull (absent on pre-existing
+ *  installs from before baseline tracking). */
+export interface PluginSourceInfo {
+    source: string;
+    isGit: boolean;
+    version?: string;
+}
+/** Read a plugin's `.source` provenance, or null when absent/unreadable. */
+export declare function readPluginSourceInfo(root: string): PluginSourceInfo | null;
+/**
+ * Resolve the CURRENT upstream manifest version for a local-sourced plugin
+ * (the `.system`/local-path case). Returns null for git sources — reading their
+ * upstream version would need a network fetch, so git plugins are refreshed only
+ * via the explicit `agents plugins update`.
+ */
+export declare function getUpstreamManifestVersion(info: PluginSourceInfo): string | null;
 /**
  * Update an installed plugin by re-pulling from its original source.
  * Returns true if the update succeeded.

package/dist/lib/plugins.js

@@ -11,14 +11,14 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { execFileSync } from 'child_process';
-import { getPluginsDir, getTrashPluginsDir, getExtraPluginsDir, getProjectPluginsDir } from './state.js';
+import { getPluginsDir, getTrashPluginsDir, getExtraPluginsDir, getProjectPluginsDir, getSystemPluginsDir } from './state.js';
 import { IS_WINDOWS, isWindowsAbsolutePath, homeDir } from './platform/index.js';
 import { assertSafeGitTransport } from './git.js';
 import { listInstalledVersions, getVersionHomePath } from './versions.js';
 import { AGENTS, agentConfigDirName } from './agents.js';
 import { capableAgents, isCapable } from './capabilities.js';
 import { shouldInstallCommandAsSkill, installCommandSkillToVersion } from './command-skills.js';
-import { copyPluginToMarketplace, syncMarketplaceManifest, registerMarketplace, unregisterMarketplace, addPluginToSettings, removePluginFromSettings, removePluginFromMarketplace, marketplaceIsEmpty, removeEmptyMarketplaceDir, isInstalledInMarketplace, marketplaceRoot, discoverMarketplaces, marketplaceNameFor, MARKETPLACE_NAME, PROJECT_MARKETPLACE_NAME, } from './plugin-marketplace.js';
+import { copyPluginToMarketplace, syncMarketplaceManifest, registerMarketplace, unregisterMarketplace, addPluginToSettings, removePluginFromSettings, removePluginFromMarketplace, marketplaceIsEmpty, removeEmptyMarketplaceDir, isInstalledInMarketplace, marketplaceRoot, discoverMarketplaces, marketplaceNameFor, MARKETPLACE_NAME, PROJECT_MARKETPLACE_NAME, SYSTEM_MARKETPLACE_NAME, } from './plugin-marketplace.js';
 const PLUGIN_MANIFEST_DIR = '.claude-plugin';
 const PLUGIN_MANIFEST_FILE = 'plugin.json';
 const USER_CONFIG_FILE = '.user-config.json';
@@ -186,11 +186,20 @@ export function assertPluginTargetContained(targetRoot, pluginsDir) {
     }
 }
 /**
- * Get a specific plugin by name.
+ * Get a specific plugin by name. On a cross-marketplace name collision the
+ * highest-precedence scope wins (project > extra > user > system) — the same
+ * resolution the sync writer's Map(last-wins) dedupe and collectPluginScopes()
+ * use. discoverPlugins() yields low→high precedence order, so the LAST match is
+ * the winner; returning the first match would resolve to the lowest scope (e.g.
+ * a system plugin over the user's same-named one), which is exactly backwards.
  */
 export function getPlugin(name) {
     const plugins = discoverPlugins();
-    return plugins.find(p => p.name === name) || null;
+    for (let i = plugins.length - 1; i >= 0; i--) {
+        if (plugins[i].name === name)
+            return plugins[i];
+    }
+    return null;
 }
 /**
  * Check if an agent supports a specific plugin.
@@ -382,13 +391,18 @@ export function checkPluginDependencies(manifest) {
 /**
  * Reconstruct a MarketplaceSpec from a marketplace name. The inverse of
  * marketplaceNameFor(): "agents-cli" → user, "agents-project" → project,
- * "agents-<alias>" → extra. The per-version marketplace operations only key off
- * the name (never spec.root), but we resolve the real source root anyway so the
- * spec is honest for any caller that inspects it.
+ * "agents-system" → system, "agents-<alias>" → extra. The per-version
+ * marketplace operations only key off the name (never spec.root), but we
+ * resolve the real source root anyway so the spec is honest for any caller that
+ * inspects it (e.g. descriptionFor, which would otherwise label the system
+ * marketplace as an extra repo named "system").
  */
 function marketplaceSpecForName(name, cwd = process.cwd()) {
     if (!name || name === MARKETPLACE_NAME)
         return { kind: 'user' };
+    if (name === SYSTEM_MARKETPLACE_NAME) {
+        return { kind: 'system', root: getSystemPluginsDir() };
+    }
     if (name === PROJECT_MARKETPLACE_NAME) {
         return { kind: 'project', root: getProjectPluginsDir(cwd) ?? '' };
     }
@@ -1096,10 +1110,38 @@ export async function installPlugin(spec) {
         throw new Error(`Installed source has no valid .claude-plugin/plugin.json`);
     }
     const capabilities = inspectPluginCapabilities(targetRoot);
-    // Persist source for future updates
-    fs.writeFileSync(path.join(targetRoot, SOURCE_FILE), JSON.stringify({ source, isGit: !isLocalPath }), 'utf-8');
+    // Persist source for future updates. `version` records the manifest version
+    // at pull time — a baseline that lets the heal path tell "central is an
+    // untouched copy of upstream" (safe to fast-forward) from "the user edited
+    // it" (leave alone) without hashing the whole tree.
+    fs.writeFileSync(path.join(targetRoot, SOURCE_FILE), JSON.stringify({ source, isGit: !isLocalPath, version: manifest.version }), 'utf-8');
     return { name: manifest.name, root: targetRoot, isNew, capabilities };
 }
+/** Read a plugin's `.source` provenance, or null when absent/unreadable. */
+export function readPluginSourceInfo(root) {
+    const f = path.join(root, SOURCE_FILE);
+    if (!fs.existsSync(f))
+        return null;
+    try {
+        return JSON.parse(fs.readFileSync(f, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Resolve the CURRENT upstream manifest version for a local-sourced plugin
+ * (the `.system`/local-path case). Returns null for git sources — reading their
+ * upstream version would need a network fetch, so git plugins are refreshed only
+ * via the explicit `agents plugins update`.
+ */
+export function getUpstreamManifestVersion(info) {
+    if (info.isGit)
+        return null;
+    const resolved = info.source.replace(/^~/, homeDir());
+    const m = loadPluginManifest(resolved);
+    return m?.version ?? null;
+}
 /**
  * Update an installed plugin by re-pulling from its original source.
  * Returns true if the update succeeded.
@@ -1136,11 +1178,14 @@ export async function updatePlugin(name) {
                 : null;
             fs.rmSync(plugin.root, { recursive: true, force: true });
             fs.cpSync(resolvedSource, plugin.root, { recursive: true });
-            fs.writeFileSync(path.join(plugin.root, SOURCE_FILE), JSON.stringify(sourceInfo), 'utf-8');
             if (userConfigBackup !== null) {
                 fs.writeFileSync(userConfigPath, userConfigBackup, 'utf-8');
             }
         }
+        // Re-stamp .source with the freshly pulled manifest version so the baseline
+        // tracks what's now on disk (keeps the heal "unmodified?" check honest).
+        const freshVersion = loadPluginManifest(plugin.root)?.version;
+        fs.writeFileSync(path.join(plugin.root, SOURCE_FILE), JSON.stringify({ ...sourceInfo, version: freshVersion }), 'utf-8');
     }
     catch (err) {
         return { success: false, error: err.message };

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/session/remote.d.ts

@@ -0,0 +1,33 @@
+/**
+ * SSH target: a bare ssh-config host alias (e.g. `yosemite-s1`) or `user@host`.
+ * The strict allowlist blocks shell metacharacters and a leading `-`, so a target
+ * can never be smuggled in as an ssh argv flag.
+ */
+export declare const SSH_TARGET_RE: RegExp;
+export declare function assertValidSshTarget(host: string): void;
+/** POSIX single-quote a string for safe interpolation into a remote shell command. */
+export declare function shellQuote(s: string): string;
+/**
+ * Strip the `--host`/`-H` flag (and its value) from a raw `agents sessions` argv,
+ * leaving the args to forward to the remote unchanged. The remote runs the same
+ * binary, so every other flag (`--since`, `--last`, `--json`, query, …) carries
+ * over for free. Handles every form commander accepts: `--host h`, `--host=h`,
+ * `-H h`, `-H=h`, and the glued short form `-Hh`.
+ *
+ * @param argv full process argv; the sessions args begin at index 2
+ *             (`[runtime, script, 'sessions', ...]`).
+ */
+export declare function buildForwardedArgs(argv: string[], hosts?: Set<string>): string[];
+/**
+ * Build the single remote command string for `ssh <host> <cmd>`. Forwarded args
+ * are quoted for the inner login shell, then the whole `agents …` invocation is
+ * quoted again so it survives `bash -lc <...>`.
+ */
+export declare function buildRemoteCommand(forwardedArgs: string[]): string;
+/**
+ * Run the current `agents sessions` invocation on one or more remote machines over
+ * SSH, streaming each remote's output to the terminal. Sets `process.exitCode = 1`
+ * if any host fails. Reads the invocation from `process.argv` (override via
+ * `argv` for testing).
+ */
+export declare function runRemoteSessions(hosts: string[], argv?: string[]): void;