@event4u/agent-config 9.35.0 → 10.0.0

package/src/config/agent-settings.template.yml

@@ -355,6 +355,24 @@ project:
   # Branch prefix for improvement PRs
   improvement_pr_branch_prefix: "improve/agent-"
 
+  # Who this project is built for. Read by the demand gate
+  # (docs/guidelines/agent-infra/agent-interaction-and-decision-quality.md
+  # § 8-pre), whose L0-L4 ladder measures MARKET demand and is therefore
+  # meaningless where no market is intended.
+  #   self     -> a tool its maintainer builds for themselves. The demand gate
+  #               is inert; work is classified L-self (build), never deferred
+  #               for lack of a user population that is not wanted.
+  #   internal -> a team / company internal tool. Only "what breaks without
+  #               it?" survives; the requester is known.
+  #   client   -> built for a named client. The client is the requester, not a
+  #               market segment.
+  #   public   -> a product with an intended market. Full three-question gate
+  #               and the full ladder.
+  # Default `public` = the behaviour every install had before this key existed.
+  # Absent resolves to `public` for the same reason: this package has no
+  # defaults layer, so absent means nobody said.
+  audience: public
+
 # --- GitHub integration ---
 github:
   # API method for replying to PR review comments
@@ -1190,42 +1208,12 @@ hooks:
   injection_scan:
     enabled: false
 
-  # Stop-slot turn-end gate (road-to-conformance-round5 Phase 3). Default-OFF,
-  # and it is the only concern in this file that can REFUSE a turn-end rather
-  # than a tool call — so it soaks behind an explicit opt-in before it binds.
-  #
-  # Round 5 measured what it is for: both BLOCKING carriers reached zero
-  # violations, neither ADVISORY carrier did, and 19 wrong-language replies
-  # survived a pin that had fired 26-35 seconds earlier. A reminder at higher
-  # frequency is the same failed mechanism running more often; a check at
-  # delivery that can say no is a different one.
-  #
-  # enabled     — master switch. false = the concern is a no-op costing one
-  #               settings read per turn-end.
-  # promissory  — detector A: the closing paragraph promises work not yet
-  #               performed while asking the user nothing (20 measured).
-  # language    — detector B: the user-visible prose is not in the pinned
-  #               language, with code, quotes, paths and identifiers already
-  #               excluded (19 measured).
-  # verification — detector C: the turn changed a file and then ran nothing that
-  #               could have checked it — no test, type-check, lint or build call
-  #               follows the LAST edit. Ordering is the point: a run before the
-  #               final edit did not exercise it, which is the freshness clause
-  #               verify-before-complete states. Reads the turn's tool calls, not
-  #               the prose. Deliberately narrow on what counts as verification —
-  #               a missed detection costs one unguarded turn, a false refusal
-  #               teaches you to switch the gate off.
-  #
-  # All three detectors default ON *within* the master switch, so opting in needs
-  # one line, and any one can be silenced without editing the hook manifest.
-  # A refused turn continues in the same turn and is never refused twice —
-  # re-entrancy is `stop_hook_active` plus a marker keyed on the last user
-  # message, never on the reply.
-  turn_end_gate:
-    enabled: false
-    promissory: true
-    language: true
-    verification: true
+  # NOTE — `turn_end_gate` has no keys here any more. The stop-slot turn-end
+  # gate is ALWAYS ARMED (2026-08-12); `hooks.turn_end_gate.*` was removed and
+  # a leftover block warns once on stderr and is ignored. Whether it fires is
+  # decided by each detector's own trigger — no promise in the closing
+  # paragraph, no language-pin mismatch, no unverified edit ⇒ the turn ends.
+  # See `src/scripts/hooks/turn_end_gate_hook.ts` § "Always armed".
 
   # PreToolUse RTK-wrap nudge (token-saving Phase 3). Default-OFF. When enabled
   # AND `rtk` is on PATH (a live probe — not a self-reported flag), warns (exit
@@ -1248,6 +1236,20 @@ hooks:
   design_slop:
     enabled: false
 
+  # PreToolUse UI-route nudge (road-to-frontend-skill-application Phase 4).
+  # Default-OFF. When enabled, a Write/Edit to a UI surface with no design
+  # consultation latched this session WARNS (exit 2, never blocks) naming the
+  # route: run existing-ui-audit, then the fe-design loop. A read or search
+  # touching fe-design / existing-ui-audit / design-review / design-intelligence
+  # latches consultation and silences it for the rest of the session, so the
+  # agent that did the right thing is never nagged. Anti-loop: at most 2 nudges
+  # per session. It does NOT read the two UI rules: the UI-surface decision
+  # comes from _lib/ui_surface.ts, so this runs parallel to them rather than
+  # consuming their triggers. Host-limited (pre_tool_use fires on ~2-3 hosts) —
+  # elsewhere the obligation stays model-carried, as the two UI rules declare.
+  ui_route_nudge:
+    enabled: false
+
   # PreToolUse code-graph nudge (ADR-124 Phase 4). Default-OFF. When enabled
   # AND a native code-graph engine has built a cache (or the repo ships a
   # graph.json / SCIP index), WARNS once per session (exit 2, never blocks) as

package/src/config/ci-local-parity.yml

@@ -20,6 +20,38 @@
 # plus the checker makes each direction a declared, reviewable choice instead of an
 # accident.
 #
+# THE THIRD DIMENSION — `preflight`, added round 7, REPORT-ONLY
+# ------------------------------------------------------------
+# The two directions above compare CI against the local MIRROR (`task ci` +
+# `task consistency` + the pre-push hook). `task ci` INCLUDES `preflight`, so
+# neither direction can see the gap that actually costs push cycles: the pass a
+# contributor is TOLD to run before pushing is `task preflight`, a deliberate
+# subset of `ci`.
+#
+# Measured 2026-08-12: preflight reaches **22** gates; **209** CI-enforced gates
+# are locally reachable and run in NEITHER preflight nor anywhere else the
+# pre-push hook reaches — i.e. the set that can only fail after a push. Round 7
+# traced three "green locally, red remotely" cycles to it (the Thin-Root char cap,
+# the ratchet in the Node-Tests shard, derived-page freshness).
+#
+# The first reading said 221 and subtracted preflight alone, which counted gates
+# the pre-push hook already runs and therefore cannot fail remotely — corrected
+# by the round's own completion review (finding 4). Both figures are kept because
+# the correction is the point: a number published as "the deliverable" was
+# computed over a superset.
+#
+# It is REPORT-ONLY, and deliberately not a declared list, for two reasons:
+#   1. The subset is intentional. preflight's own docstring excludes
+#      check_enforcement_coverage at a measured 30.7 s because "a pre-push gate
+#      that doubles the hook teaches people to skip it". Failing on the gap would
+#      demand preflight grow into ci — the opposite of that decision.
+#   2. 209 per-entry declarations would BE the allowlist-growth antipattern the
+#      `autonomous-execution` rule caps at 20: past that count, the list is the
+#      problem and not the exemption.
+#
+# What the report removes is the IMPLICATION that a green preflight predicts a
+# green CI. It does not, and now it says so on every run.
+#
 # THE CONTRACT
 # ------------
 # The checker DERIVES both sides — it never trusts a hand-maintained list of gates:
@@ -152,6 +184,18 @@ ci_only:
 # worth remote enforcement, OR it should simply be added to a workflow. Prefer
 # adding it: a local-only gate is the direction that let real defects merge.
 local_only:
+  - id: roadmap_progress_hook
+    class: git-hook-scoped
+    reason: >
+      A git PRE-COMMIT hook script, invoked by the installed hook that
+      `install-hooks.sh` writes. CI has no commit to intercept — the commit has
+      already happened by the time a workflow runs — so there is no remote
+      equivalent to wire it into. Undeclared since main's `fd8c56512`
+      ("point the pre-commit roadmap gate at the live script path"), which moved
+      the hook onto the real script path and thereby made it visible to this
+      checker for the first time; it turned the gate red on the trunk, where
+      round 7 found it. Declared rather than wired: the committed-tree equivalent
+      is `roadmap:progress-check`, which already runs remotely.
   - id: check_knowledge_sharing
     class: staging-scoped
     reason: >

package/src/config/gate-coverage.yml

@@ -168,6 +168,18 @@ gates:
     corpus: "src/rules/*.md frontmatters (111 at baseline)"
     status: enforced
 
+  - id: lint_rule_skill_pack_reach
+    argv: ["--quiet"]
+    min_scanned: 90
+    corpus: "src/rules/*.md frontmatters joined against src/skills packs and the pack registry (116 rules at baseline)"
+    status: enforced
+    note: >
+      Advisory on findings, enforced on COVERAGE: the gate exits 0 while its
+      unreachable-route set is non-empty (12 at introduction), so only this
+      floor can catch it going blind. A collapse below 90 would mean it stopped
+      reading src/rules, which is exactly the shape that would make "0 findings"
+      read as clean.
+
   - id: check_condensation
     argv: []
     min_scanned: 380

package/src/scripts/_cli/cmd_doctor.ts

@@ -3591,10 +3591,42 @@ function main(argv: string[] | null = null): number {
 
 // --- CLI entry ---
 
+/**
+ * Defined by `build:cli-delegate` only — see `cmd_session_recycle.ts` for why a
+ * single "am I inside a bundle" flag cannot answer "may I run".
+ */
+declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
+declare const __AGENT_CONFIG_CLI_DELEGATE__: boolean | undefined;
+
 function _isCliEntry(): boolean {
+    const bundled = typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' && __AGENT_CONFIG_BUNDLE__;
+    const cliDelegate =
+        typeof __AGENT_CONFIG_CLI_DELEGATE__ !== 'undefined' && __AGENT_CONFIG_CLI_DELEGATE__;
+    // Inlined into the installer / hook / MCP bundle: never auto-run. This
+    // file previously carried no such guard while its comment described the
+    // pairing, so the four siblings documented one mechanism and implemented
+    // two.
+    if (bundled && !cliDelegate) {
+        return false;
+    }
     if (process.argv[1] === undefined) {
         return false;
     }
+    if (cliDelegate) {
+        // `--splitting` moves this module's body into a shared chunk, so the URL
+        // comparison below weighs the CHUNK against `argv[1]` and never matches.
+        // `agent-config doctor` shipped producing zero bytes and exit 0 for
+        // exactly that reason — a diagnostic reporting success while saying
+        // nothing. The invoked file name is the reliable signal inside this
+        // bundle; the delegate smoke test keeps the literal honest.
+        if (path.basename(process.argv[1], '.js') === 'cmd_doctor') {
+            return true;
+        }
+        // A miss falls THROUGH to the realpath comparison below rather than
+        // returning false: a symlinked or renamed invocation is exactly the
+        // case that fallback exists for, and swallowing it here would rebuild
+        // the silent no-op this change removes.
+    }
     const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
     if (import.meta.url === argvUrl) {
         return true;

package/src/scripts/_cli/cmd_migrate.ts

@@ -932,14 +932,37 @@ export function main(argv: string[] | null = null, options: MainOptions = {}): n
 // build's `--define`) disables the auto-run there; under tsx/node it is
 // undefined, so `typeof` short-circuits and the standalone CLI guard fires
 // normally.
+// The sentinel above is true in EVERY esbuild target, `build:cli-delegate`
+// included — and there this file is the entry, so refusing on it refused to run
+// the bundle built to run it: `dist/cli-delegate/cmd_migrate.js` produced zero
+// bytes and exit 0, and `agent-config migrate` reported success while doing
+// nothing. `__AGENT_CONFIG_CLI_DELEGATE__` is defined by that one build only, so
+// the pair distinguishes "inlined into the installer" (never run) from "this
+// bundle's own target" (run, subject to the entry check below).
 declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
-const _bundled =
-    typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' && __AGENT_CONFIG_BUNDLE__;
+declare const __AGENT_CONFIG_CLI_DELEGATE__: boolean | undefined;
+const _inForeignBundle =
+    typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' &&
+    __AGENT_CONFIG_BUNDLE__ &&
+    !(typeof __AGENT_CONFIG_CLI_DELEGATE__ !== 'undefined' && __AGENT_CONFIG_CLI_DELEGATE__);
 const _HERE = fileURLToPath(import.meta.url);
 function _isCliEntry(): boolean {
     if (process.argv[1] === undefined) {
         return false;
     }
+    if (typeof __AGENT_CONFIG_CLI_DELEGATE__ !== 'undefined' && __AGENT_CONFIG_CLI_DELEGATE__) {
+        // `--splitting` moves this module's body into a shared chunk, so the URL
+        // comparison below weighs the CHUNK against `argv[1]` and never matches —
+        // `agent-config migrate` shipped producing zero bytes and exit 0. The
+        // invoked file name is the reliable signal inside this bundle.
+        if (path.basename(process.argv[1], '.js') === 'cmd_migrate') {
+            return true;
+        }
+        // A miss falls THROUGH to the realpath comparison below rather than
+        // returning false: a symlinked or renamed invocation is exactly the
+        // case that fallback exists for, and swallowing it here would rebuild
+        // the silent no-op this change removes.
+    }
     const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
     if (import.meta.url === argvUrl) {
         return true;
@@ -958,7 +981,7 @@ function _isCliEntry(): boolean {
     }
 }
 
-if (!_bundled && (_isCliEntry() || process.argv[1] === _HERE)) {
+if (!_inForeignBundle && (_isCliEntry() || process.argv[1] === _HERE)) {
     try {
         process.exitCode = main(process.argv.slice(2));
     } catch (exc) {

package/src/scripts/_cli/cmd_refresh.ts

@@ -449,10 +449,39 @@ export function main(argv: string[] | null = null, options: MainOptions = {}): n
 
 // --- CLI entry ---
 
+/**
+ * Defined by `build:cli-delegate` only — see `cmd_session_recycle.ts` for why the
+ * URL comparison below cannot decide this inside that bundle.
+ */
+declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
+declare const __AGENT_CONFIG_CLI_DELEGATE__: boolean | undefined;
+
 function _isCliEntry(): boolean {
+    const bundled = typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' && __AGENT_CONFIG_BUNDLE__;
+    const cliDelegate =
+        typeof __AGENT_CONFIG_CLI_DELEGATE__ !== 'undefined' && __AGENT_CONFIG_CLI_DELEGATE__;
+    // Inlined into the installer / hook / MCP bundle: never auto-run. This
+    // file previously carried no such guard while its comment described the
+    // pairing, so the four siblings documented one mechanism and implemented
+    // two.
+    if (bundled && !cliDelegate) {
+        return false;
+    }
     if (process.argv[1] === undefined) {
         return false;
     }
+    if (cliDelegate) {
+        // Found by running every delegate bundle, not by reading: `--splitting`
+        // had moved this body into a shared chunk too, so `agent-config refresh`
+        // was a silent exit 0 like doctor, migrate and session:recycle.
+        if (path.basename(process.argv[1], '.js') === 'cmd_refresh') {
+            return true;
+        }
+        // A miss falls THROUGH to the realpath comparison below rather than
+        // returning false: a symlinked or renamed invocation is exactly the
+        // case that fallback exists for, and swallowing it here would rebuild
+        // the silent no-op this change removes.
+    }
     const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
     if (import.meta.url === argvUrl) {
         return true;

package/src/scripts/_cli/cmd_session_recycle.ts

@@ -252,11 +252,49 @@ export function main(argv: string[] = process.argv.slice(2)): number {
     return result.code;
 }
 
-// Bundle-safety: never auto-run when inlined into an esbuild bundle.
+/**
+ * Bundle-safety: never auto-run when inlined into SOMEONE ELSE'S bundle.
+ *
+ * `__AGENT_CONFIG_BUNDLE__` alone cannot express that. All four esbuild targets
+ * define it, `build:cli-delegate` included — and that bundle's entry points ARE
+ * these files, so a guard refusing on the flag refuses to run the very bundle
+ * built to run it. That shipped: `dist/cli-delegate/cmd_session_recycle.js`
+ * produced zero bytes and exit 0 on every installed copy, so
+ * `agent-config session:recycle` reported success while writing no envelope.
+ * `cmd_doctor` and `cmd_migrate` carried the same guard and were dead the same
+ * way.
+ *
+ * `__AGENT_CONFIG_CLI_DELEGATE__` is defined by that one build only, so the pair
+ * says what a single flag could not: inlined elsewhere (install / hook / MCP
+ * bundle) → never run; this bundle's own target → run, and let the `argv[1]`
+ * comparison below decide whether THIS module is the entry or a shared chunk
+ * pulled in beside it.
+ */
 declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
+declare const __AGENT_CONFIG_CLI_DELEGATE__: boolean | undefined;
 function _isCliEntry(): boolean {
-    if (typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' && __AGENT_CONFIG_BUNDLE__) return false;
+    const bundled = typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' && __AGENT_CONFIG_BUNDLE__;
+    const cliDelegate =
+        typeof __AGENT_CONFIG_CLI_DELEGATE__ !== 'undefined' && __AGENT_CONFIG_CLI_DELEGATE__;
+    if (bundled && !cliDelegate) return false;
     if (process.argv[1] === undefined) return false;
+    if (cliDelegate) {
+        // `--splitting` turns the entry file into a re-export shim and moves this
+        // module's body into a shared chunk, where `import.meta.url` is the
+        // CHUNK's url and can never equal `argv[1]`. The comparison below then
+        // silently never fires — which is why two sibling commands shipped dead
+        // while others worked by accident, purely by where esbuild happened to
+        // place their code. Inside this bundle the invoked file name is the only
+        // reliable signal; the smoke test over every delegate bundle is what
+        // keeps this literal honest if the file is ever renamed.
+        if (path.basename(process.argv[1], '.js') === 'cmd_session_recycle') {
+            return true;
+        }
+        // A miss falls THROUGH to the realpath comparison below rather than
+        // returning false: a symlinked or renamed invocation is exactly the
+        // case that fallback exists for, and swallowing it here would rebuild
+        // the silent no-op this change removes.
+    }
     if (import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) return true;
     try {
         return (

package/src/scripts/_lib/agent_settings.ts

@@ -884,31 +884,45 @@ export function load_agent_settings(
 }
 
 /**
- * Settings keys deleted by the always-on-orchestration doctrine
- * (road-to-always-on-orchestration Phase 1 for the `subagents.*` keys;
- * Phase 1 Step 1.3 for `ai_team.enabled`). A leftover value from an older
+ * Settings keys this package has DELETED. A leftover value from an older
  * install is ignored — never applied by any reader — and surfaced with ONE
  * deprecation line per key per process run (stderr; the exit code never
  * changes).
  *
- * `ai_team.enabled` joined this list in Step 1.3: the `/team` family's
- * availability is now a codex-CLI/auth FACT
- * (`src/scripts/ai_team/availability.ts`), the same doctrine already
- * applied to `subagents.*` below, not a settings flag. The `ai_team`
- * config loader (`src/scripts/ai_team/config.ts`) separately accepts a
- * leftover `enabled` key without failing closed, so this warning is the
- * only surfaced signal of the deletion.
+ * The map carries a per-key REASON rather than one shared sentence, because
+ * the list now spans more than one deletion doctrine and a single blanket
+ * phrase would mis-attribute every future entry. A reader who hits the line
+ * should learn why the key went, not just that it did.
+ *
+ * `subagents.*` — the always-on-orchestration doctrine
+ * (road-to-always-on-orchestration Phase 1): the layer has no per-layer
+ * on/off setting any more. `ai_team.enabled` joined in Step 1.3 — the
+ * `/team` family's availability is a codex-CLI/auth FACT
+ * (`src/scripts/ai_team/availability.ts`), not a flag; the `ai_team` config
+ * loader (`src/scripts/ai_team/config.ts`) separately accepts a leftover
+ * `enabled` key without failing closed, so this warning is the only surfaced
+ * signal of that deletion.
+ *
+ * `hooks.turn_end_gate.*` — the turn-end gate is always armed (2026-08-12).
+ * A default-off safety gate cannot soak, so the switch protecting the soak
+ * made the soak impossible; whether the gate fires is now decided by each
+ * detector's own trigger conditions. See `turn_end_gate_hook.ts` § "Always
+ * armed".
  */
-const REMOVED_ALWAYS_ON_KEYS: readonly string[] = [
-    'subagents.enabled',
-    'subagents.auto',
-    'subagents.host_capabilities',
-    'subagents.budget_routing',
-    'ai_team.enabled',
-];
+const REMOVED_KEYS: ReadonlyMap<string, string> = new Map([
+    ['subagents.enabled', 'always-on orchestration'],
+    ['subagents.auto', 'always-on orchestration'],
+    ['subagents.host_capabilities', 'always-on orchestration'],
+    ['subagents.budget_routing', 'always-on orchestration'],
+    ['ai_team.enabled', 'always-on orchestration'],
+    ['hooks.turn_end_gate.enabled', 'the turn-end gate is always armed'],
+    ['hooks.turn_end_gate.promissory', 'the turn-end gate is always armed'],
+    ['hooks.turn_end_gate.language', 'the turn-end gate is always armed'],
+    ['hooks.turn_end_gate.verification', 'the turn-end gate is always armed'],
+]);
 
 /** Keys already warned about in THIS process — the "once per run" dedupe. */
-const _warnedRemovedAlwaysOnKeys = new Set<string>();
+const _warnedRemovedKeys = new Set<string>();
 
 /** Read one dotted path out of a merged settings tree; `undefined` when absent. */
 function _readDottedSettingsPath(root: SettingsDict, dotted: string): SettingsValue {
@@ -923,20 +937,20 @@ function _readDottedSettingsPath(root: SettingsDict, dotted: string): SettingsVa
 }
 
 /**
- * Warn once per process, on stderr, for every {@link REMOVED_ALWAYS_ON_KEYS}
- * still present in a resolved settings tree. Never throws, never changes
- * what the caller does with `merged` — a pure notification side effect.
+ * Warn once per process, on stderr, for every {@link REMOVED_KEYS} entry still
+ * present in a resolved settings tree. Never throws, never changes what the
+ * caller does with `merged` — a pure notification side effect.
  */
 function _warn_removed_always_on_keys(merged: SettingsDict): void {
-    for (const key of REMOVED_ALWAYS_ON_KEYS) {
-        if (_warnedRemovedAlwaysOnKeys.has(key)) {
+    for (const [key, reason] of REMOVED_KEYS) {
+        if (_warnedRemovedKeys.has(key)) {
             continue;
         }
         if (_readDottedSettingsPath(merged, key) === undefined) {
             continue;
         }
-        _warnedRemovedAlwaysOnKeys.add(key);
-        process.stderr.write(`${key} was removed (always-on orchestration); ignored.\n`);
+        _warnedRemovedKeys.add(key);
+        process.stderr.write(`${key} was removed (${reason}); ignored.\n`);
     }
 }
 

package/src/scripts/_lib/environment_detector.ts

@@ -220,6 +220,50 @@ export interface DetectEnvironmentOptions {
      * hardened env and a 2s timeout; pass `() => null` to skip probing.
      */
     readonly probeVersion?: VersionProbe;
+    /**
+     * macOS Keychain presence probe for the Claude Code subscription
+     * credential. Omit to shell out to `security find-generic-password`;
+     * pass `() => false` to skip it entirely — every test that is not
+     * specifically about this probe should, so a developer machine's real
+     * Keychain never decides a test outcome.
+     */
+    readonly probeKeychain?: KeychainProbe;
+}
+
+/** `(service) => present?` — never returns the secret, only whether it exists. */
+export type KeychainProbe = (service: string) => boolean;
+
+/** Keychain service name Claude Code writes its subscription credential under. */
+export const CLAUDE_KEYCHAIN_SERVICE = 'Claude Code-credentials';
+
+/**
+ * Is the Claude Code subscription credential in the macOS login Keychain?
+ *
+ * Claude Code stores its OAuth credential in the Keychain on macOS and only
+ * falls back to `~/.claude/.credentials.json` elsewhere. Looking for the file
+ * alone therefore reports "no subscription" on the platform where the
+ * subscription is most likely to exist — which sent every macOS anthropic
+ * member down the metered `api` rung while a paid Claude subscription sat
+ * unused on the same machine. That is the defect this probe closes.
+ *
+ * `-w` is deliberately NOT passed: without it `security` prints attributes and
+ * never the password, so the secret cannot reach a log, a report, or a crash
+ * dump. Presence is read from the exit code alone.
+ */
+function defaultProbeKeychain(service: string): boolean {
+    if (process.platform !== 'darwin') return false;
+    try {
+        const res = spawnSync('security', ['find-generic-password', '-s', service], {
+            timeout: VERSION_PROBE_TIMEOUT_MS,
+            encoding: 'utf-8',
+            windowsHide: true,
+            env: hardenedSpawnEnv(),
+        });
+        if (res.error !== undefined || res.signal !== null) return false;
+        return res.status === 0;
+    } catch {
+        return false;
+    }
 }
 
 /**
@@ -298,6 +342,7 @@ function cliSubscriptionEvidence(
     home: string,
     env: EnvMap,
     claudeConfigDir: string,
+    probeKeychain: KeychainProbe,
 ): { source: AuthSource; evidence: string } | null {
     if (provider === 'anthropic') {
         const configDir = claudeConfigDir;
@@ -305,6 +350,11 @@ function cliSubscriptionEvidence(
             const p = path.join(configDir, rel);
             if (isFile(p)) return { source: 'cli-subscription', evidence: p };
         }
+        // macOS keeps the credential in the Keychain instead of the file above.
+        // The evidence string is a locator, never the secret.
+        if (probeKeychain(CLAUDE_KEYCHAIN_SERVICE)) {
+            return { source: 'cli-subscription', evidence: `keychain:${CLAUDE_KEYCHAIN_SERVICE}` };
+        }
         return null;
     }
     if (provider === 'openai') {
@@ -359,11 +409,12 @@ function detectAuth(opts: DetectEnvironmentOptions): {
         opts.home === undefined && opts.env === undefined
             ? claude_config_dir()
             : ((env['CLAUDE_CONFIG_DIR'] ?? '').trim() || path.join(home, '.claude'));
+    const probeKeychain = opts.probeKeychain ?? defaultProbeKeychain;
     const auth: DetectedAuth[] = [];
     const keys: DetectedKey[] = [];
 
     for (const provider of knownProviders()) {
-        const cli = cliSubscriptionEvidence(provider, home, env, claudeConfigDir);
+        const cli = cliSubscriptionEvidence(provider, home, env, claudeConfigDir, probeKeychain);
         if (cli !== null) {
             auth.push({ provider, source: cli.source, evidence: cli.evidence });
         }

package/src/scripts/_lib/hook_settings.ts

@@ -0,0 +1,79 @@
+/**
+ * hook_settings — read a `hooks.<section>.enabled` flag out of
+ * `.agent-settings.yml` without dragging a YAML parser into a hook.
+ *
+ * Every default-OFF hook needs the same two-level lookup, and the tree already
+ * carries two hand-rolled copies of it (`code_graph_nudge_hook.enabled` and the
+ * equivalent inside `design_slop_hook`). Adding a third copy for the route
+ * nudge is what this file prevents; the two existing copies are pre-existing
+ * duplication and are deliberately left alone — folding them in is a separate,
+ * behaviour-neutral change, not something to smuggle into a feature diff.
+ *
+ * Fail-closed on the flag, fail-open on the read: an unreadable or malformed
+ * settings file returns `false`, which keeps a default-OFF hook off. A hook
+ * that turned itself ON because it could not read a file would be the worst
+ * possible failure mode for an opt-in nudge.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+const SETTINGS_FILE = '.agent-settings.yml';
+
+/**
+ * True when `.agent-settings.yml` under `root` carries
+ * `hooks:\n  <section>:\n    enabled: true`.
+ *
+ * Deliberately indentation-shaped rather than a real parse: the same shape the
+ * existing hooks rely on, and a hook must never fail a tool call because a
+ * dependency could not load.
+ */
+export function hookSectionEnabled(root: string, section: string): boolean {
+    const file = path.join(root, SETTINGS_FILE);
+    let text: string;
+    try {
+        if (!fs.statSync(file).isFile()) return false;
+        text = fs.readFileSync(file, 'utf-8');
+    } catch {
+        return false;
+    }
+
+    const escaped = section.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const sectionPattern = new RegExp(`^(\\s+)${escaped}\\s*:\\s*$`);
+    let inHooks = false;
+    /** Indent width of the matched section header; null while outside it. */
+    let sectionIndent: number | null = null;
+
+    const indentOf = (line: string): number => line.length - line.replace(/^\s+/, '').length;
+
+    for (const raw of text.split(/\r\n|\r|\n/)) {
+        const line = raw.replace(/\s+$/, '');
+        if (!line || line.replace(/^\s+/, '').startsWith('#')) continue;
+
+        // A non-indented line closes both scopes and may open `hooks:`.
+        if (!(line.startsWith(' ') || line.startsWith('\t'))) {
+            inHooks = /^hooks\s*:\s*$/.test(line);
+            sectionIndent = null;
+            continue;
+        }
+
+        if (inHooks) {
+            const opened = sectionPattern.exec(line);
+            if (opened) {
+                // Remember the ACTUAL indent rather than assuming two spaces.
+                // The previous version closed the section on any line indented
+                // <= 3, so on a 4-space file a sibling section never closed and
+                // a default-OFF hook could read another section's enabled: true.
+                sectionIndent = opened[1]!.length;
+                continue;
+            }
+            // A key at or above the section header's own depth closes it.
+            if (sectionIndent !== null && indentOf(line) <= sectionIndent) {
+                sectionIndent = null;
+            }
+        }
+
+        if (sectionIndent !== null && /^\s+enabled\s*:\s*true\b/.test(line)) return true;
+    }
+
+    return false;
+}