@event4u/agent-config 9.7.0 → 9.8.0

package/src/server/schemas/settings.ts

@@ -209,6 +209,17 @@ export const settingsSchema = z.object({
             'Consumed by the cross-source-consistency rule. When the agent works from multiple sources (ticket text, an attached image/mockup, the spec, the codebase) it checks them against each other and asks before proceeding on a discrepancy — instead of silently guessing. on (default) = surface every real cross-source contradiction / silent-scope-expansion as one question; auto = surface only high-confidence contradictions, state low-confidence as an assumption; off = no cross-source checking.',
         ),
     }).default({ cross_source: 'on' }),
+    screenshots: z.object({
+        identity_allowlist: z.array(z.string()).default([]).describe(
+            "Consumed by the doc-screenshot-hygiene rule and screenshot-hygiene skill. Public identity tokens SAFE to show unredacted in a documentation screenshot — the maintainer's own public handles plus well-known fake-data tokens. Not a general fake-data dictionary and not identity-resolution: everything not listed is treated as sensitive by default, and a public handle co-located with a real name does not whitelist the real name. Default [] = nothing auto-allowed.",
+        ),
+        forbid_terminal_capture: z.boolean().default(true).describe(
+            'Consumed by the doc-screenshot-hygiene rule. true (default) = terminal/CLI/IDE screenshots are forbidden (highest leak vector: absolute local paths, env tokens); use text code blocks with text redaction instead. false = allowed, still subject to the data-bearing human gate.',
+        ),
+        data_bearing_gate: z.enum(['on', 'off']).default('on').describe(
+            'Consumed by the doc-screenshot-hygiene rule. on (default) = a data-bearing screenshot embed is gated behind this-turn human confirmation; uncertain/unresolved regions redact-or-refuse, never ship-and-hope; illustrative/no-data screenshots may embed with a stated justification. off = no data-bearing gate (the anonymization taxonomy still applies).',
+        ),
+    }).default({ identity_allowlist: [], forbid_terminal_capture: true, data_bearing_gate: 'on' }),
     tokens: z.object({
         rich_skills: richSkillsMode.default('on').describe(
             'Whether skills marked token_budget_class: rich may load in full (exempt from telegraph-speak + thin-projector trimming), consumed by the token-budget-discipline rule. on = allowed (default); off = fall back to standard condensed behavior; ask = surface an estimated token delta (tokens, not dollars) and ask once per session before loading.',
@@ -439,6 +450,11 @@ export const settingsSchema = z.object({
                 'PreToolUse anti-slop nudge (road-to-anti-slop-detector Phase 3). Default off. When on, runs the lint_design_slop registry against about-to-be-written UI content and WARNS (never blocks) on P0/P1 aesthetic tells (side-stripe, gradient-text, magic z-index, …). Flags are rebuttable via DESIGN.md / design-slop-disable. Anti-loop: a file::rule signature surfaced 3x goes silent. Host-limited convenience layer; the universal gate is the lint_design_slop linter/CI.',
             ),
         }).default({}),
+        code_graph: z.object({
+            enabled: z.boolean().default(false).describe(
+                'PreToolUse code-graph nudge (ADR-124 Phase 4). Default off. When on AND a native code-graph cache or a consumer-shipped graph.json/SCIP index is present, warns once per session (never blocks) as the agent is about to Grep/Glob or Read a source file — query the graph first for who-calls/where-used/impact questions (or rebuild if stale, build if absent). Source G’s strict block-first-read mode is deliberately un-ported.',
+            ),
+        }).default({}),
     }),
     decision_engine: z.object({
         surface_traces: z.boolean().default(false).describe(

package/src/shared/capabilities.test.ts

@@ -0,0 +1,43 @@
+/**
+ * Unit tests for the host-facing capability advertisement.
+ *
+ * The `configRoot` and `embed` capabilities must appear in the
+ * `--version --json` readout (and, via the same module, `GET /api/v1/ping`)
+ * so a spawner can feature-detect support before relying on either.
+ */
+import { describe, expect, it } from 'vitest';
+import { CAPABILITIES, buildVersionReadout } from './capabilities.js';
+
+describe('capabilities', () => {
+    it('advertises configRoot support', () => {
+        expect(CAPABILITIES.configRoot).toBe(true);
+    });
+
+    it('advertises the embed contract (reciprocal-ecosystem Phase 3)', () => {
+        expect(CAPABILITIES.embed).toEqual({
+            supported: true,
+            version: 1,
+            features: ['theme', 'deepLink'],
+        });
+    });
+
+    it('does NOT advertise the accent feature (v2, not v1)', () => {
+        expect(CAPABILITIES.embed.features).not.toContain('accent');
+    });
+
+    it('buildVersionReadout carries the version and the full capability block', () => {
+        const readout = buildVersionReadout('9.7.0');
+        expect(readout).toEqual({
+            version: '9.7.0',
+            capabilities: {
+                configRoot: true,
+                embed: { supported: true, version: 1, features: ['theme', 'deepLink'] },
+            },
+        });
+    });
+
+    it('buildVersionReadout copies capabilities (no shared mutable reference)', () => {
+        const readout = buildVersionReadout('1.2.3');
+        expect(readout.capabilities).not.toBe(CAPABILITIES);
+    });
+});

package/src/shared/capabilities.ts

@@ -0,0 +1,75 @@
+/**
+ * Host-facing capability advertisement.
+ *
+ * A host that spawns `agent-config` (e.g. an orchestrator managing
+ * profile-scoped configuration) needs to detect, before it relies on a
+ * behaviour, whether the AC binary on `PATH` actually supports it. This
+ * module is the single source of truth for that advertisement; it is
+ * surfaced in two readouts a host can probe:
+ *
+ *   - `agent-config --version --json` — the CLI capability readout.
+ *   - `GET /api/v1/ping` — the local-server status readout.
+ *
+ * An older AC (predating a capability) omits the flag / the whole
+ * `capabilities` block, so a newer host reading `capabilities.<x> === true`
+ * degrades to a clear "not supported" instead of silently breaking.
+ *
+ * `src/shared/**` is consumed by both the Node server and the browser UI
+ * bundle, so this module stays pure — no Node built-ins, no I/O.
+ */
+
+/**
+ * Named embed features this build actually ships (reciprocal-ecosystem
+ * embed contract). A host reads the list to feature-detect instead of
+ * version-guessing. Only shipped features appear — v1 ships `theme`
+ * (the `?theme=light|dark` boot query) and `deepLink` (`#/settings` /
+ * `#/settings/<section>` deep links under `?embed=1`). `accent` is a
+ * v2 feature and is deliberately absent.
+ */
+export type EmbedFeature = 'theme' | 'deepLink';
+
+export interface EmbedCapability {
+    /** `true` when this build honours the `?embed=1` embed contract. */
+    supported: boolean;
+    /** Embed-contract version this build implements. */
+    version: number;
+    /** The embed features actually shipped by this build. */
+    features: EmbedFeature[];
+}
+
+export interface Capabilities {
+    /**
+     * `true` when the binary accepts a host-supplied config root on spawn
+     * via the `--config-root <path>` flag or the `EVENT4U_CONFIG_HOME`
+     * environment variable — letting a host scope AC's config/settings/
+     * state to a per-profile directory instead of the shared default.
+     */
+    configRoot: boolean;
+    /**
+     * Host-embed contract advertisement — a host reads `embed.supported`
+     * + `embed.version` + `embed.features` to decide whether it can render
+     * AC's settings surface inside its own window (via `?embed=1`, a
+     * `?theme=` boot query, and settings deep links) before relying on it.
+     */
+    embed: EmbedCapability;
+}
+
+/** The capabilities this build advertises. */
+export const CAPABILITIES: Capabilities = {
+    configRoot: true,
+    embed: { supported: true, version: 1, features: ['theme', 'deepLink'] },
+};
+
+export interface VersionReadout {
+    version: string;
+    capabilities: Capabilities;
+}
+
+/**
+ * Build the machine-readable `--version --json` payload. Pure — the
+ * caller supplies the version string it already resolved from
+ * `package.json`.
+ */
+export function buildVersionReadout(version: string): VersionReadout {
+    return { version, capabilities: { ...CAPABILITIES } };
+}

package/src/templates/minimal/agents-overrides-readme.md

@@ -29,6 +29,26 @@ Drop a file under `agents/overrides/rules/foo.md` to override the global
 copy. The bridge anchor at `agents/.event4u-bridge.yml` tells the loader which
 `~/.event4u/agent-config/` install to pair with.
 
+## What you cannot override
+
+The nine kernel rules — `agent-authority`, `ask-when-uncertain`, `commit-policy`,
+`direct-answers`, `language-and-tone`, `no-cheap-questions`,
+`non-destructive-by-default`, `scope-control`, `verify-before-complete` — and
+anything marked `tier: safety-floor` are **not replaceable**. You may *tighten*
+one with a `Mode: extend` override plus an entry in
+`agents/overrides/kernel-exceptions.yml` recording why. A `Mode: replace` on one
+is refused and reported.
+
+Two consequences that are easy to miss:
+
+- **"Wins on name match" is not unconditional.** An empty file at
+  `agents/overrides/rules/non-destructive-by-default.md` does not switch off the
+  Hard Floor — it is refused.
+- **Whole-file replacement freezes that file.** Later fixes to the original,
+  including security fixes, stop reaching you for as long as your copy exists,
+  and nothing announces it. Prefer `extend`, which keeps the rest of the rule in
+  the update flow.
+
 ## Adding your first override
 
 ```bash