@bookedsolid/rea 0.30.0 → 0.31.0

package/dist/cli/install/settings-merge.js

@@ -380,5 +380,30 @@ export function defaultDesiredHooks() {
                 },
             ],
         },
+        {
+            // 0.31.0 delegation-telemetry completion — the *nudge*. The
+            // matcher is `Bash|Edit|Write|MultiEdit|NotebookEdit`: every
+            // write-class tool call (note this group INCLUDES Bash, unlike
+            // the architecture-review group above). The hook maintains a
+            // per-session counter and emits a one-time stderr advisory when
+            // a session crosses `policy.delegation_advisory.threshold`
+            // without dispatching a curated specialist. Advisory only — it
+            // never blocks a tool call, and `policy.delegation_advisory`
+            // defaults to disabled (only `bst-internal*` profiles pin
+            // `enabled: true`), so a vanilla install sees the hook as a
+            // silent no-op. Kept as its own matcher group rather than
+            // chained onto the architecture-review group because the
+            // matcher string differs (Bash is in this one, not that one).
+            event: 'PostToolUse',
+            matcher: 'Bash|Edit|Write|MultiEdit|NotebookEdit',
+            hooks: [
+                {
+                    type: 'command',
+                    command: `${base}/delegation-advisory.sh`,
+                    timeout: 10000,
+                    statusMessage: 'Checking delegation cadence...',
+                },
+            ],
+        },
     ];
 }

package/dist/cli/roster.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Live `.claude/agents/` roster discovery (0.31.0+).
+ *
+ * 0.29.0 shipped the delegation-telemetry observability layer. 0.31.0
+ * closes the loop with the *nudge* — and the nudge needs to know what
+ * counts as a "real" specialist delegation versus a built-in helper.
+ *
+ * # Why discovery, not a hardcoded list
+ *
+ * `src/cli/doctor.ts` already carries an `EXPECTED_AGENTS` constant,
+ * but it is a deliberately-frozen 10-entry subset — the minimum roster
+ * `rea init` guarantees, pinned so a regression that drops a curated
+ * agent from the install manifest trips a doctor failure. It is NOT
+ * the live roster: this repo ships 23 agents, consumers add their own,
+ * and the curated set grows release over release. Keying the
+ * delegation nudge off `EXPECTED_AGENTS` would mean a session that
+ * delegated exclusively to `principal-engineer` and `data-architect`
+ * (both real, curated, neither in the frozen subset) still got nudged
+ * — exactly the false positive that erodes trust in an advisory.
+ *
+ * So the roster is discovered at read time: every `*.md` file under
+ * `<baseDir>/.claude/agents/` is a curated specialist. The basename
+ * (sans `.md`) is the `subagent_type` Claude Code's `Agent` tool
+ * reports, so the mapping is direct.
+ *
+ * # The exempt set
+ *
+ * Claude Code ships built-in helpers — `general-purpose`, `Explore`,
+ * `Plan`, `output-style-setup`, `statusline-setup` — that are dispatched
+ * through the same `Agent` tool but are NOT curated specialists. A
+ * session that only ever delegated to those has not actually routed
+ * work to the engineering team. The exempt set is policy-configurable
+ * (`policy.delegation_advisory.exempt_subagents`) with a 5-entry
+ * built-in default; this module takes the resolved list as an argument
+ * rather than reading policy itself, so it stays a pure filesystem
+ * helper with no policy-loader dependency.
+ *
+ * # Skills
+ *
+ * The `Skill` delegation tool is intentionally NOT roster-gated. A
+ * skill invocation (`deep-dive`, `due-diligence`, …) is always a real
+ * delegation signal — there is no "built-in skill" equivalent of
+ * `general-purpose`. The advisory's "did this session delegate"
+ * predicate counts every `Skill` signal and every non-exempt `Agent`
+ * signal whose `subagent_type` is in the discovered roster.
+ */
+/**
+ * Default exempt subagent names — Claude Code's built-in helper agents
+ * that are dispatched through the `Agent` tool but are not curated
+ * specialists. Mirrors the schema-layer default in
+ * `DelegationAdvisoryPolicySchema` (`src/policy/loader.ts`). Exported
+ * so callers that have no policy in scope (the bash-hook fallback
+ * path) can still apply the same filter.
+ */
+export declare const DEFAULT_EXEMPT_SUBAGENTS: readonly string[];
+export interface RosterDiscoveryResult {
+    /**
+     * Sorted list of discovered curated-specialist names — the basename
+     * (sans `.md`) of every file under `.claude/agents/`. Empty when the
+     * directory is absent or unreadable.
+     */
+    roster: string[];
+    /**
+     * Absolute path actually scanned. Returned for diagnostics — doctor
+     * surfaces it, the `rea hook` subcommand echoes it in `--json` mode.
+     */
+    agentsDir: string;
+    /**
+     * `true` when `.claude/agents/` exists and was read. `false` when it
+     * is absent or a read error occurred — callers treat that as "no
+     * roster, every Agent delegation is non-exempt-but-also-unverifiable"
+     * and fall back to the exempt-list-only filter.
+     */
+    discovered: boolean;
+}
+/**
+ * Discover the curated-specialist roster by listing `*.md` files under
+ * `<baseDir>/.claude/agents/`. Pure filesystem read — never throws; an
+ * absent or unreadable directory yields `discovered: false` with an
+ * empty roster.
+ *
+ * The `.md` extension match is case-insensitive (`.MD` on a
+ * case-preserving-but-insensitive filesystem still counts) and the
+ * basename is taken verbatim — `rea-orchestrator.md` →
+ * `rea-orchestrator`. Subdirectories and non-`.md` files (READMEs,
+ * `.DS_Store`, editor swap files) are skipped.
+ */
+export declare function discoverRoster(baseDir: string): RosterDiscoveryResult;
+/**
+ * The delegation-nudge predicate, factored out so the CLI subcommand,
+ * the `audit specialists` reader, and the doctor smoke check all apply
+ * identical logic.
+ *
+ * Returns `true` when the given `(delegation_tool, subagent_type)` pair
+ * counts as a REAL delegation — i.e. the kind that should suppress the
+ * advisory nudge:
+ *
+ *   - `Skill` → always counts. There is no "built-in skill" exemption.
+ *   - `Agent` → counts when the `subagent_type` is NOT in `exempt` AND
+ *     (the roster was discovered AND contains the name, OR the roster
+ *     was NOT discovered — in which case we cannot verify and fall
+ *     back to "non-exempt name counts"). The non-discovered fallback
+ *     is deliberately permissive: a consumer who deleted
+ *     `.claude/agents/` has bigger problems than a missed nudge, and a
+ *     false negative (no nudge when one was due) is far less corrosive
+ *     than a false positive.
+ *
+ * `exempt` comparison is case-sensitive — the built-in helper names
+ * (`Explore`, `Plan`) are capitalized and the curated specialists are
+ * kebab-case, so there is no realistic collision, and a case-folded
+ * compare would risk a curated `Plan-something` agent being wrongly
+ * exempted.
+ */
+export declare function countsAsRealDelegation(args: {
+    delegationTool: 'Agent' | 'Skill';
+    subagentType: string;
+    roster: RosterDiscoveryResult;
+    exempt: readonly string[];
+}): boolean;

package/dist/cli/roster.js

@@ -0,0 +1,141 @@
+/**
+ * Live `.claude/agents/` roster discovery (0.31.0+).
+ *
+ * 0.29.0 shipped the delegation-telemetry observability layer. 0.31.0
+ * closes the loop with the *nudge* — and the nudge needs to know what
+ * counts as a "real" specialist delegation versus a built-in helper.
+ *
+ * # Why discovery, not a hardcoded list
+ *
+ * `src/cli/doctor.ts` already carries an `EXPECTED_AGENTS` constant,
+ * but it is a deliberately-frozen 10-entry subset — the minimum roster
+ * `rea init` guarantees, pinned so a regression that drops a curated
+ * agent from the install manifest trips a doctor failure. It is NOT
+ * the live roster: this repo ships 23 agents, consumers add their own,
+ * and the curated set grows release over release. Keying the
+ * delegation nudge off `EXPECTED_AGENTS` would mean a session that
+ * delegated exclusively to `principal-engineer` and `data-architect`
+ * (both real, curated, neither in the frozen subset) still got nudged
+ * — exactly the false positive that erodes trust in an advisory.
+ *
+ * So the roster is discovered at read time: every `*.md` file under
+ * `<baseDir>/.claude/agents/` is a curated specialist. The basename
+ * (sans `.md`) is the `subagent_type` Claude Code's `Agent` tool
+ * reports, so the mapping is direct.
+ *
+ * # The exempt set
+ *
+ * Claude Code ships built-in helpers — `general-purpose`, `Explore`,
+ * `Plan`, `output-style-setup`, `statusline-setup` — that are dispatched
+ * through the same `Agent` tool but are NOT curated specialists. A
+ * session that only ever delegated to those has not actually routed
+ * work to the engineering team. The exempt set is policy-configurable
+ * (`policy.delegation_advisory.exempt_subagents`) with a 5-entry
+ * built-in default; this module takes the resolved list as an argument
+ * rather than reading policy itself, so it stays a pure filesystem
+ * helper with no policy-loader dependency.
+ *
+ * # Skills
+ *
+ * The `Skill` delegation tool is intentionally NOT roster-gated. A
+ * skill invocation (`deep-dive`, `due-diligence`, …) is always a real
+ * delegation signal — there is no "built-in skill" equivalent of
+ * `general-purpose`. The advisory's "did this session delegate"
+ * predicate counts every `Skill` signal and every non-exempt `Agent`
+ * signal whose `subagent_type` is in the discovered roster.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+/**
+ * Default exempt subagent names — Claude Code's built-in helper agents
+ * that are dispatched through the `Agent` tool but are not curated
+ * specialists. Mirrors the schema-layer default in
+ * `DelegationAdvisoryPolicySchema` (`src/policy/loader.ts`). Exported
+ * so callers that have no policy in scope (the bash-hook fallback
+ * path) can still apply the same filter.
+ */
+export const DEFAULT_EXEMPT_SUBAGENTS = [
+    'general-purpose',
+    'Explore',
+    'Plan',
+    'output-style-setup',
+    'statusline-setup',
+];
+/**
+ * Discover the curated-specialist roster by listing `*.md` files under
+ * `<baseDir>/.claude/agents/`. Pure filesystem read — never throws; an
+ * absent or unreadable directory yields `discovered: false` with an
+ * empty roster.
+ *
+ * The `.md` extension match is case-insensitive (`.MD` on a
+ * case-preserving-but-insensitive filesystem still counts) and the
+ * basename is taken verbatim — `rea-orchestrator.md` →
+ * `rea-orchestrator`. Subdirectories and non-`.md` files (READMEs,
+ * `.DS_Store`, editor swap files) are skipped.
+ */
+export function discoverRoster(baseDir) {
+    const agentsDir = path.join(baseDir, '.claude', 'agents');
+    let entries;
+    try {
+        entries = fs.readdirSync(agentsDir, { withFileTypes: true });
+    }
+    catch {
+        // ENOENT (no .claude/agents/), ENOTDIR, EACCES — all collapse to
+        // "no roster discovered". The caller falls back to the exempt-list
+        // filter alone.
+        return { roster: [], agentsDir, discovered: false };
+    }
+    const roster = [];
+    for (const entry of entries) {
+        // Only regular files. A directory named `foo.md` is not an agent.
+        if (!entry.isFile())
+            continue;
+        const name = entry.name;
+        if (!name.toLowerCase().endsWith('.md'))
+            continue;
+        const base = name.slice(0, name.length - 3);
+        if (base.length === 0)
+            continue;
+        roster.push(base);
+    }
+    roster.sort();
+    return { roster, agentsDir, discovered: true };
+}
+/**
+ * The delegation-nudge predicate, factored out so the CLI subcommand,
+ * the `audit specialists` reader, and the doctor smoke check all apply
+ * identical logic.
+ *
+ * Returns `true` when the given `(delegation_tool, subagent_type)` pair
+ * counts as a REAL delegation — i.e. the kind that should suppress the
+ * advisory nudge:
+ *
+ *   - `Skill` → always counts. There is no "built-in skill" exemption.
+ *   - `Agent` → counts when the `subagent_type` is NOT in `exempt` AND
+ *     (the roster was discovered AND contains the name, OR the roster
+ *     was NOT discovered — in which case we cannot verify and fall
+ *     back to "non-exempt name counts"). The non-discovered fallback
+ *     is deliberately permissive: a consumer who deleted
+ *     `.claude/agents/` has bigger problems than a missed nudge, and a
+ *     false negative (no nudge when one was due) is far less corrosive
+ *     than a false positive.
+ *
+ * `exempt` comparison is case-sensitive — the built-in helper names
+ * (`Explore`, `Plan`) are capitalized and the curated specialists are
+ * kebab-case, so there is no realistic collision, and a case-folded
+ * compare would risk a curated `Plan-something` agent being wrongly
+ * exempted.
+ */
+export function countsAsRealDelegation(args) {
+    if (args.delegationTool === 'Skill')
+        return true;
+    // Agent path.
+    if (args.exempt.includes(args.subagentType))
+        return false;
+    if (!args.roster.discovered) {
+        // Roster unverifiable — a non-exempt Agent name is the best signal
+        // we have. Count it.
+        return true;
+    }
+    return args.roster.roster.includes(args.subagentType);
+}

package/dist/config/settings-schema.d.ts

@@ -2066,8 +2066,20 @@ export interface SettingsValidationResult {
  * best-effort scan of any `hooks: { PreToolUse: [...] }` shape we
  * recognize, so the operator still sees traversal + missing-hooks
  * findings.
+ *
+ * `strict` selects the schema:
+ *   - `false` (default) — `SettingsSchema`, top-level `.passthrough()`.
+ *     Unknown harness keys pass. Used by `rea upgrade` and advisory
+ *     `rea doctor`.
+ *   - `true` — `SettingsSchemaStrict`, top-level `.strict()`. Unknown
+ *     keys fail the parse. Used only by `rea doctor --strict` (the CI
+ *     gate path). 0.30.1 round-5 P2: the strict schema existed since
+ *     0.30.0 but `validateSettings` never accepted the selector, so
+ *     `rea doctor --strict` silently ran the lenient schema.
  */
-export declare function validateSettings(input: unknown): SettingsValidationResult;
+export declare function validateSettings(input: unknown, options?: {
+    strict?: boolean;
+}): SettingsValidationResult;
 /**
  * Cross-check: every name in `EXPECTED_HOOKS` should appear as the
  * basename of at least one `command` across PreToolUse + PostToolUse.

package/dist/config/settings-schema.js

@@ -154,8 +154,18 @@ export function validateNoTraversal(settings) {
  * best-effort scan of any `hooks: { PreToolUse: [...] }` shape we
  * recognize, so the operator still sees traversal + missing-hooks
  * findings.
+ *
+ * `strict` selects the schema:
+ *   - `false` (default) — `SettingsSchema`, top-level `.passthrough()`.
+ *     Unknown harness keys pass. Used by `rea upgrade` and advisory
+ *     `rea doctor`.
+ *   - `true` — `SettingsSchemaStrict`, top-level `.strict()`. Unknown
+ *     keys fail the parse. Used only by `rea doctor --strict` (the CI
+ *     gate path). 0.30.1 round-5 P2: the strict schema existed since
+ *     0.30.0 but `validateSettings` never accepted the selector, so
+ *     `rea doctor --strict` silently ran the lenient schema.
  */
-export function validateSettings(input) {
+export function validateSettings(input, options = {}) {
     const result = {
         parsed: false,
         settings: null,
@@ -164,7 +174,8 @@ export function validateSettings(input) {
         missingReaHooks: [],
         warnings: [],
     };
-    const parsed = SettingsSchema.safeParse(input);
+    const schema = options.strict === true ? SettingsSchemaStrict : SettingsSchema;
+    const parsed = schema.safeParse(input);
     if (parsed.success) {
         result.parsed = true;
         result.settings = parsed.data;

package/dist/policy/loader.d.ts

@@ -249,7 +249,7 @@ declare const PolicySchema: z.ZodObject<{
     attribution: z.ZodOptional<z.ZodObject<{
         co_author: z.ZodOptional<z.ZodEffects<z.ZodObject<{
             enabled: z.ZodOptional<z.ZodBoolean>;
-            name: z.ZodOptional<z.ZodString>;
+            name: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
             email: z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodLiteral<"">]>;
             skip_merge: z.ZodOptional<z.ZodBoolean>;
         }, "strict", z.ZodTypeAny, {
@@ -288,6 +288,19 @@ declare const PolicySchema: z.ZodObject<{
             skip_merge?: boolean | undefined;
         } | undefined;
     }>>;
+    delegation_advisory: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        threshold: z.ZodDefault<z.ZodNumber>;
+        exempt_subagents: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    }, "strict", z.ZodTypeAny, {
+        enabled: boolean;
+        threshold: number;
+        exempt_subagents: string[];
+    }, {
+        enabled?: boolean | undefined;
+        threshold?: number | undefined;
+        exempt_subagents?: string[] | undefined;
+    }>>;
 }, "strict", z.ZodTypeAny, {
     version: string;
     profile: string;
@@ -361,6 +374,11 @@ declare const PolicySchema: z.ZodObject<{
             skip_merge?: boolean | undefined;
         } | undefined;
     } | undefined;
+    delegation_advisory?: {
+        enabled: boolean;
+        threshold: number;
+        exempt_subagents: string[];
+    } | undefined;
 }, {
     version: string;
     profile: string;
@@ -434,6 +452,11 @@ declare const PolicySchema: z.ZodObject<{
             skip_merge?: boolean | undefined;
         } | undefined;
     } | undefined;
+    delegation_advisory?: {
+        enabled?: boolean | undefined;
+        threshold?: number | undefined;
+        exempt_subagents?: string[] | undefined;
+    } | undefined;
 }>;
 /**
  * Async policy loader with TTL cache and mtime-based invalidation.

package/dist/policy/loader.js

@@ -231,10 +231,24 @@ const GatewayPolicySchema = z
  * Stricter validation is the consumer's job — RFC 5322 is too permissive
  * for an opt-in audit footprint anyway.
  */
+// 0.30.1 round-5 P2: the `name` value lands verbatim inside a
+// `Co-Authored-By: <name> <email>` git trailer. A newline or carriage
+// return in `name` would split the trailer across lines — git's
+// `interpret-trailers` would drop the continuation and the augmenter
+// could even inject arbitrary extra trailer lines. Reject any ASCII
+// control character (newline, CR, tab, NUL, …) in `name`.
+const CONTROL_CHAR_RE = /[\x00-\x1f\x7f]/;
 const AttributionCoAuthorSchema = z
     .object({
     enabled: z.boolean().optional(),
-    name: z.string().optional(),
+    name: z
+        .string()
+        .refine((v) => !CONTROL_CHAR_RE.test(v), {
+        message: 'attribution.co_author.name must not contain control characters ' +
+            '(newlines, tabs, carriage returns) — the value is written verbatim ' +
+            'into a single-line Co-Authored-By git trailer.',
+    })
+        .optional(),
     email: z
         .string()
         .regex(/^[^\s<>@]+@[^\s<>@]+\.[^\s<>@]+$/, {
@@ -275,6 +289,45 @@ const AttributionPolicySchema = z
     co_author: AttributionCoAuthorSchema.optional(),
 })
     .strict();
+/**
+ * 0.31.0 — delegation-advisory nudge policy. Drives the
+ * `delegation-advisory.sh` PostToolUse hook (matcher
+ * `Bash|Edit|Write|MultiEdit|NotebookEdit`): when a session crosses
+ * `threshold` write-class tool calls without a `rea.delegation_signal`
+ * record (to a non-exempt subagent), the hook emits a one-time stderr
+ * advisory. The hook is advisory-only — exit 0 always except HALT.
+ *
+ * Defaults live here at the schema layer, not in the hook: a vanilla
+ * install with no `delegation_advisory` block gets `enabled: false`
+ * (silent no-op), `threshold: 25`, and the 5-entry built-in exempt
+ * list. The `bst-internal*` profiles pin `enabled: true`; OSS profiles
+ * leave it `false` so consumers opt in.
+ *
+ * `threshold` is a positive integer — a single write-class count
+ * rather than the 0.29.0 design memo's "15 edits + 5 Bash" split.
+ * Modeling the threshold as one number keeps the hook's counter file
+ * a single integer and the policy surface a single knob; the
+ * distinction between an Edit and a Bash call doesn't change the
+ * signal the nudge exists to send ("you've done a lot solo").
+ *
+ * Strict mode rejects unknown keys so a typo (`thresholds`,
+ * `exempt_subagent`) fails loudly at policy load.
+ */
+const DelegationAdvisoryPolicySchema = z
+    .object({
+    enabled: z.boolean().default(false),
+    threshold: z.number().int().positive().default(25),
+    exempt_subagents: z
+        .array(z.string())
+        .default([
+        'general-purpose',
+        'Explore',
+        'Plan',
+        'output-style-setup',
+        'statusline-setup',
+    ]),
+})
+    .strict();
 const PolicySchema = z
     .object({
     version: z.string(),
@@ -327,6 +380,13 @@ const PolicySchema = z
     // `AttributionCoAuthorSchema` fails closed when `enabled: true` but
     // `name`/`email` are empty so we never ship a half-configured trailer.
     attribution: AttributionPolicySchema.optional(),
+    // 0.31.0 delegation-advisory nudge — drives the
+    // `delegation-advisory.sh` PostToolUse hook. `.optional()` so a
+    // vanilla install with no block sees the hook as a silent no-op
+    // (the hook reads `enabled` via `rea hook policy-get` and exits 0
+    // when unset/false). When the block IS present the inner schema
+    // supplies defaults for any omitted field.
+    delegation_advisory: DelegationAdvisoryPolicySchema.optional(),
 })
     .strict();
 const DEFAULT_CACHE_TTL_MS = 30_000;

package/dist/policy/profiles.d.ts

@@ -108,6 +108,19 @@ export declare const ProfileSchema: z.ZodObject<{
             skip_merge?: boolean | undefined;
         } | undefined;
     }>>;
+    delegation_advisory: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodOptional<z.ZodBoolean>;
+        threshold: z.ZodOptional<z.ZodNumber>;
+        exempt_subagents: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strict", z.ZodTypeAny, {
+        enabled?: boolean | undefined;
+        threshold?: number | undefined;
+        exempt_subagents?: string[] | undefined;
+    }, {
+        enabled?: boolean | undefined;
+        threshold?: number | undefined;
+        exempt_subagents?: string[] | undefined;
+    }>>;
 }, "strict", z.ZodTypeAny, {
     autonomy_level?: AutonomyLevel | undefined;
     max_autonomy_level?: AutonomyLevel | undefined;
@@ -142,6 +155,11 @@ export declare const ProfileSchema: z.ZodObject<{
             skip_merge?: boolean | undefined;
         } | undefined;
     } | undefined;
+    delegation_advisory?: {
+        enabled?: boolean | undefined;
+        threshold?: number | undefined;
+        exempt_subagents?: string[] | undefined;
+    } | undefined;
 }, {
     autonomy_level?: AutonomyLevel | undefined;
     max_autonomy_level?: AutonomyLevel | undefined;
@@ -176,6 +194,11 @@ export declare const ProfileSchema: z.ZodObject<{
             skip_merge?: boolean | undefined;
         } | undefined;
     } | undefined;
+    delegation_advisory?: {
+        enabled?: boolean | undefined;
+        threshold?: number | undefined;
+        exempt_subagents?: string[] | undefined;
+    } | undefined;
 }>;
 export type Profile = z.infer<typeof ProfileSchema>;
 /** Hard defaults applied before any profile or wizard answer. */

package/dist/policy/profiles.js

@@ -100,6 +100,22 @@ export const ProfileSchema = z
     })
         .strict()
         .optional(),
+    // 0.31.0+ delegation-advisory nudge. `bst-internal*` profiles pin
+    // `enabled: true`; external profiles ship `enabled: false`. The
+    // profile-layer schema mirrors the policy-loader's
+    // `DelegationAdvisoryPolicySchema` but leaves every field optional
+    // — defaults are applied at the policy-loader layer when the
+    // materialized file is parsed, so a profile that only declares
+    // `enabled` doesn't need to also restate `threshold`. Strict mode
+    // still rejects typos at init time.
+    delegation_advisory: z
+        .object({
+        enabled: z.boolean().optional(),
+        threshold: z.number().int().positive().optional(),
+        exempt_subagents: z.array(z.string()).optional(),
+    })
+        .strict()
+        .optional(),
 })
     .strict();
 /** Hard defaults applied before any profile or wizard answer. */

package/dist/policy/types.d.ts

@@ -367,6 +367,59 @@ export interface AttributionCoAuthorPolicy {
     email?: string;
     skip_merge?: boolean;
 }
+/**
+ * Delegation-advisory nudge policy (0.31.0+).
+ *
+ * 0.29.0 shipped the delegation-telemetry *observability* layer (the
+ * `Agent|Skill` PreToolUse capture hook + `rea audit specialists`
+ * reader). 0.31.0 closes the loop with the *nudge*: the
+ * `delegation-advisory.sh` PostToolUse hook (matcher
+ * `Bash|Edit|Write|MultiEdit|NotebookEdit`) counts the current
+ * session's write-class tool calls and, when that count crosses
+ * `threshold` WITHOUT a `rea.delegation_signal` record landing in the
+ * session, prints a one-time stderr advisory: "this session has done a
+ * lot of work without delegating to a specialist".
+ *
+ * The advisory is purely informational — the hook always exits 0
+ * (except under HALT, which exits 2 to keep the kill-switch contract
+ * uniform). It NEVER blocks a tool call.
+ *
+ * Profile defaults: `enabled: true` for the `bst-internal*` profiles
+ * (BST's own delegation discipline is load-bearing); `enabled: false`
+ * for every external profile (`open-source*`, `minimal`,
+ * `client-engagement`, `lit-wc`) — OSS consumers opt in per-repo via
+ * `.rea/policy.yaml`, since "you should delegate more" is an opinion
+ * not every team shares.
+ */
+export interface DelegationAdvisoryPolicy {
+    /**
+     * Master switch. When `false` (or the whole block is omitted) the
+     * `delegation-advisory.sh` hook is a silent no-op. Default `false` at
+     * the schema layer; `bst-internal*` profiles pin `true`.
+     */
+    enabled?: boolean;
+    /**
+     * Write-class tool-call count at which the advisory fires. The
+     * `delegation-advisory.sh` hook maintains a per-session counter file
+     * and emits the nudge the first time the counter reaches this value
+     * with zero delegation signals recorded for the session. Default
+     * `25` — a session that has run 25 Bash/Edit/Write/MultiEdit/
+     * NotebookEdit calls without once dispatching a specialist is doing
+     * meaningful work solo. Must be a positive integer.
+     */
+    threshold?: number;
+    /**
+     * Subagent / skill names that do NOT count as "real delegation" for
+     * the purpose of suppressing the advisory. A session that only ever
+     * delegated to `general-purpose` / `Explore` / `Plan` (the built-in
+     * Claude Code helpers) has not actually routed work to a curated
+     * specialist, so those signals don't reset the nudge. Default:
+     * `["general-purpose", "Explore", "Plan", "output-style-setup",
+     * "statusline-setup"]`. A delegation signal whose `subagent_type` is
+     * in this list is ignored when deciding whether to fire.
+     */
+    exempt_subagents?: string[];
+}
 /**
  * G9 — injection tier escalation knobs. The classifier bucketed matches into
  * `clean` / `suspicious` / `likely_injection`; this block governs what happens
@@ -472,4 +525,12 @@ export interface Policy {
      * trailer are no-ops. See `AttributionPolicy` for the full contract.
      */
     attribution?: AttributionPolicy;
+    /**
+     * Delegation-advisory nudge (0.31.0+). When `enabled: true`, the
+     * `delegation-advisory.sh` PostToolUse hook emits a one-time stderr
+     * advisory when a session crosses `threshold` write-class tool calls
+     * without dispatching a curated specialist. Advisory only — never
+     * blocks. See `DelegationAdvisoryPolicy` for the full contract.
+     */
+    delegation_advisory?: DelegationAdvisoryPolicy;
 }