@event4u/agent-config 16.1.0 → 16.3.0

package/src/scripts/_lib/host_capability.ts

@@ -184,7 +184,7 @@ export function normalizeHostManifest(input: unknown): HostCapabilityManifest {
  *
  * `contexts/execution/host-capability-manifest.md` § Observation protocol states
  * the per-field criterion and the four-part citation (host · host version ·
- * transcript or artefact reference · date). A row without all four is not
+ * transcript or artifact reference · date). A row without all four is not
  * admissible, and no row may be filled from a host's documentation.
  *
  * ## REACHABILITY, 2026-08-22 — one of eight, and the other seven are recorded
@@ -221,7 +221,7 @@ export function normalizeHostManifest(input: unknown): HostCapabilityManifest {
  *   `duration_ms` — i.e. 420 child legs whose start and stop pair, which is the
  *   criterion (a measurable child duration, not an inferred one).
  *
- * `parallel_spawn: true` — OBSERVED. Same host, session and artefact.
+ * `parallel_spawn: true` — OBSERVED. Same host, session and artifact.
  *   **6,168** of 6,388 stop records carry `concurrent_open >= 2`, with a
  *   maximum of **30** concurrently open children. Overlapping intervals at one
  *   instant, which is the criterion — not two children in sequence.
@@ -235,25 +235,46 @@ export function normalizeHostManifest(input: unknown): HostCapabilityManifest {
  * `agent_teams` — out of scope for a row by construction; see its own field
  *   doc comment and the protocol section.
  *
- * `structured_ask: false` — OBSERVED ABSENT, not never-looked, and the
- *   difference is why it is written rather than omitted. claude (Claude Code
- *   2.1.263, Opus 5 1M session, 2026-09-07). The host delivers the session's
- *   tool surface at session start; that surface carried no structured-ask tool
- *   under any name `_lib/structured_ask.ts` matches, and no per-host shape is
- *   recorded for it in `STRUCTURED_ASK_SHAPES`. Artefact:
- *   `agents/evidence/analysis/structured-ask-host-observation-2026-09.md`.  code-comment-allow provenance-comment -- the observation protocol declares a row inadmissible without its artefact citation, so this pointer is part of the contract the row satisfies, not evidence duplicated from a roadmap
- *   The observation is about the delivered surface of one session on one
- *   version; it is not a claim that the vendor ships no such tool anywhere,
- *   and a later session observing one writes the `true` row over it.
- *
- * NO ROW ANYWHERE SETS THE STRUCTURED-ASK FIELD TRUE, and the observation
- * protocol above is the only path to the first one that does. A vendor's
- * documentation is not that path — and the phrasing here avoids the literal
- * key-value pair on purpose, because the roadmap step that ships this field
- * verifies the absence with a grep for exactly that string.
+ * `structured_ask` — OBSERVED PRESENT, and this row was `false` until
+ *   2026-10-05. claude (Claude Code, observed range 2.1.252 to 2.1.284,
+ *   2026-09-01 to 2026-10-02): 48 `AskUserQuestion` `tool_use` blocks, 47 of
+ *   them answered by a non-error `tool_result`, and the per-host shape is now
+ *   recorded in `STRUCTURED_ASK_SHAPES`. Artifact:
+ *   `agents/evidence/analysis/structured-ask-host-observation-2026-10.md`.  code-comment-allow provenance-comment -- the observation protocol declares a row inadmissible without its artifact citation, so this pointer is part of the contract the row satisfies, not evidence duplicated from a roadmap
+ *
+ *   The earlier `false` (2.1.263, 2026-09-07,
+ *   `structured-ask-host-observation-2026-09.md`) is not withdrawn as a
+ *   reading. It was taken from a SUBAGENT leg, whose delivered surface carries
+ *   no picker because a subagent has no user to ask; that artifact lists the
+ *   surface it saw and it is the subagent toolset. What it could not support
+ *   was the step from there to a claim about the host. The earliest call
+ *   recorded here is on 2.1.252, before the `false` reading on 2.1.263 — the
+ *   picker was being delivered and called while the row denying it was written.
+ *
+ *   WHICH LEG THE SURFACE WAS READ FROM IS PART OF THE OBSERVATION. A row that
+ *   does not say so invites exactly this substitution, so every row here says.
+ *
+ *   The prose this block replaced avoided writing the literal field-plus-`true`
+ *   pair on purpose, because a planning step verified that string's absence by
+ *   grep. That grep is named rather than paraphrased —
+ *   `grep -c 'structured_ask: true' src/scripts/_lib/host_capability.ts` — and
+ *   re-run against this file it returns 1 where it returned 0. So the
+ *   constraint is BROKEN, not intact, and recording that is the point: a reader
+ *   who is told only that it is dead cannot tell which. The step that owned it
+ *   is archived and its address is left in the roadmap rather than copied here.
+ *
+ *   ARCHIVAL IS NOT WHY IT IS DEAD, and the distinction is load-bearing because
+ *   the archival reading implies an ACTIVE copy of the same clause would bite.
+ *   It would not. NOTHING IN THIS TREE EXECUTES A `verify:` CLAUSE'S COMMAND,
+ *   archived or active: `_lib/verify_clause.ts` is a parser, and its four
+ *   importers — `roadmap_verify_share`, `closure_scan`, `run_continuation_hook`
+ *   and `check_verify_expectation_delta` — shell out to nothing but `git`. The
+ *   step also scoped itself to its own merge ("returns 0 at merge"), which it
+ *   did. Its stated successor was to record the first observed row with its
+ *   provenance — which is what this block now is.
  */
 const HOST_CAPABILITY_REGISTRY: Readonly<Record<string, Partial<HostCapabilityManifest>>> = {
-    claude: { subagent_spawn: true, parallel_spawn: true, structured_ask: false },
+    claude: { subagent_spawn: true, parallel_spawn: true, structured_ask: true },
 };
 
 /**

package/src/scripts/_lib/host_env_write.ts

@@ -0,0 +1,111 @@
+/**
+ * The only host environment variables this package will ever write.
+ *
+ * WHY ITS OWN MODULE. One place owns the question "which host variable may this
+ * package write", and the answer is a two-row allow table rather than a rule
+ * applied at a call site. `install.ts` imports it; nothing else writes host env.
+ * The move out of `install.ts` also keeps that file, already far over its size
+ * cap, from paying for this feature — the same reason the doctor's
+ * network-posture block moved into its own module.
+ *
+ * THE GUARANTEE IS THE SHAPE, not a check. Both traffic variables —
+ * `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` and `DISABLE_AUTOUPDATER` — reach
+ * the host's update-disabled resolver, the blanket one as its THIRD RUNG
+ * (measured on Claude Code 2.1.284, `docs/setup/host-traffic-environment.md`).
+ * A writer able to express either could disable a consumer's security updates.
+ * Owner-decided 2026-09-30 that it never may, and an allow table of two holds
+ * that where a deny list of two would have to stay complete as the host grows
+ * more variables.
+ *
+ * Both writable entries are request SIZE caps. Neither suppresses a call, an
+ * update check or a download — they bound how big a request is, never how many.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import * as YAML from 'yaml';
+
+/** The allow table. Two rows, and adding a third is a governance change. */
+export const WRITABLE_HOST_ENV: readonly { readonly variable: string; readonly settingsKey: string }[] = [
+    { variable: 'BASH_MAX_OUTPUT_LENGTH', settingsKey: 'bash_max_output_length' },
+    { variable: 'MAX_MCP_OUTPUT_TOKENS', settingsKey: 'max_mcp_output_tokens' },
+];
+
+/** Where a project's settings document lives, canonical first. */
+const SETTINGS_CANDIDATES: readonly string[][] = [
+    ['agents', 'settings', '.agent-settings.yml'],
+    ['.agent-settings.yml'],
+];
+
+/**
+ * The project settings document, or `null` when there is none to read.
+ *
+ * `null` on an absent or unparseable file rather than `{}`: the caller reads a
+ * key whose ABSENCE means "write nothing", and collapsing an unreadable file to
+ * an empty object would give the same answer as a readable file with the key
+ * unset. Both write nothing, but only one of them is a fact.
+ */
+export function readSettingsDoc(projectRoot: string): unknown | null {
+    for (const parts of SETTINGS_CANDIDATES) {
+        const p = path.join(projectRoot, ...parts);
+        let text: string;
+        try {
+            text = fs.readFileSync(p, 'utf-8');
+        } catch {
+            continue;
+        }
+        let doc: unknown;
+        try {
+            doc = YAML.parse(text, { version: '1.1' });
+        } catch {
+            return null;
+        }
+        return doc === null || doc === undefined || typeof doc !== 'object' ? null : doc;
+    }
+    return null;
+}
+
+/**
+ * The `env` block for the host settings file, or `null` when nothing is set.
+ *
+ * `null` rather than `{}`: an empty object would still be merged into the
+ * consumer's file, leaving an `env: {}` nobody asked for and making "this
+ * package wrote nothing" indistinguishable from "this package wrote a blank".
+ *
+ * A non-integer or non-positive value is IGNORED rather than written. The schema
+ * already refuses it; this branch is for a hand-edited settings file, where
+ * writing a value the host would silently reinterpret is worse than writing none.
+ */
+export function hostEnvBlock(settings: unknown): Record<string, string> | null {
+    const root = settings as Record<string, unknown> | null | undefined;
+    const he = root?.['host_environment'] as Record<string, unknown> | undefined;
+    const caps = he?.['request_size_caps'] as Record<string, unknown> | undefined;
+    if (caps === undefined) return null;
+    const out: Record<string, string> = {};
+    for (const { variable, settingsKey } of WRITABLE_HOST_ENV) {
+        const v = caps[settingsKey];
+        if (typeof v === 'number' && Number.isInteger(v) && v > 0) out[variable] = String(v);
+    }
+    return Object.keys(out).length === 0 ? null : out;
+}
+
+/**
+ * The host bridge object with the `env` block merged in, if there is one.
+ *
+ * Takes the bridge and returns it rather than being called for its side effect,
+ * so the caller is one expression and `install.ts` — already far over its size
+ * cap — pays one line for this feature instead of six. `announce` is injected
+ * rather than imported: this module has no opinion about how a caller reports,
+ * and importing the installer's logger would make a leaf depend on its consumer.
+ */
+export function withHostEnv(
+    bridge: Record<string, unknown>,
+    projectRoot: string,
+    announce: (msg: string) => void,
+): Record<string, unknown> {
+    const env = hostEnvBlock(readSettingsDoc(projectRoot));
+    if (env === null) return bridge;
+    announce(`.claude/settings.json: wrote ${Object.keys(env).join(', ')} (request-size caps)`);
+    return { ...bridge, env };
+}

package/src/scripts/_lib/host_hook_merge.ts

@@ -0,0 +1,165 @@
+/**
+ * Per-event hook merging that keeps a neighbour package's entries.
+ *
+ * The defect this closes:
+ * `install.ts` wrote every host hook file through `deep_merge`, which REPLACES
+ * an array wholesale. Seven call sites write a `hooks.<event>` array — augment
+ * user, cursor project + user, windsurf project + user, gemini project + user —
+ * so any hook another agent package had registered on those events was silently
+ * destroyed at install time. Only the Claude path was safe, because
+ * `_lib/claude_settings_hooks.ts` already merges per event by signature; that
+ * module's contract is the one generalised here.
+ *
+ * The rule, for each event present in the patch:
+ *
+ * 1. keep, in order and byte-identical, every existing entry that does NOT
+ *    carry this package's signature;
+ * 2. drop every existing entry that DOES carry it (ours, possibly from an older
+ *    version with a different command string);
+ * 3. append the patch's entries for that event.
+ *
+ * Events the patch does not mention are left exactly as they are — a host file
+ * may legitimately carry foreign events this package never binds.
+ *
+ * Step 2 is what keeps an upgrade idempotent: a migration that changes our own
+ * command string replaces the old entry rather than leaving a stale duplicate
+ * beside it. That is risk 1 of this lane's register, and the lifecycle fixture
+ * asserts exactly one managed entry per event after install → upgrade.
+ *
+ * Identity is content-derived, never an added field.
+ * An entry is ours when its command string contains the caller's `signature`.
+ * No marker key is written into the host's file: a host that dedupes identical
+ * command strings (Claude Code does) must keep seeing a byte-identical command,
+ * and a marker field would also be a key the host did not ask for. The
+ * signature a call site passes is the stable fragment of the command it writes —
+ * `dispatch:hook --platform <host>` for the project-level bridges, the
+ * dispatcher trampoline's filename for the user-level ones, which is the part
+ * that survives a change of home directory or binary path.
+ *
+ * Shape awareness:
+ * hosts disagree about what an entry looks like, so the command extractor
+ * covers all three shapes this package writes and reads:
+ *
+ * - `{ command: "…" }`                       — cursor, windsurf
+ * - `{ hooks: [{ type, command }] }`          — augment
+ * - `{ matcher, hooks: [{ type, command }] }` — gemini, claude
+ *
+ * An entry of none of those shapes is foreign by construction: it carries no
+ * command we can read, so it cannot be ours, so it is kept. Unreadable means
+ * kept, never deleted — the asymmetry is deliberate.
+ */
+
+import { deepcopy, isPlainObject } from './json_merge.js';
+
+/**
+ * The stable command fragment that identifies this package's entry, per writer.
+ *
+ * Keyed by the label `merge_json_file` already prints, so a call site names its
+ * signature with the string it is holding anyway. Two families, for one reason:
+ * a project-level bridge invokes the repo-local binary, so the verb and platform
+ * flag are the stable part; a user-level writer invokes an absolute trampoline
+ * path, where the only fragment that survives a different `$HOME`, a renamed
+ * checkout or a reinstall is the script's filename.
+ *
+ * A signature MUST NOT change between releases. If it does, entries written by
+ * the previous version stop being recognised as ours and accumulate beside the
+ * new one instead of being replaced — the stale-duplicate failure this module's
+ * step 2 exists to prevent. A new command shape is therefore a new entry under
+ * an unchanged signature, never a new signature.
+ */
+export const HOOK_SIGNATURES: Readonly<Record<string, string>> = {
+    '~/.augment/settings.json': 'augment-dispatcher.sh',
+    '.cursor/hooks.json': 'dispatch:hook --platform cursor',
+    '~/.cursor/hooks.json': 'cursor-dispatcher.sh',
+    '.windsurf/hooks.json': 'dispatch:hook --platform windsurf',
+    '~/.codeium/windsurf/hooks.json': 'windsurf-dispatcher.sh',
+    '.gemini/settings.json': 'dispatch:hook --platform gemini',
+    '~/.gemini/settings.json': 'gemini-dispatcher.sh',
+};
+
+/** Every command string reachable inside one hook entry, in document order. */
+export function entryCommands(entry: unknown): string[] {
+    if (!isPlainObject(entry)) return [];
+    const out: string[] = [];
+    if (typeof entry['command'] === 'string') out.push(entry['command']);
+    const nested = entry['hooks'];
+    if (Array.isArray(nested)) {
+        for (const inner of nested) {
+            if (isPlainObject(inner) && typeof inner['command'] === 'string') {
+                out.push(inner['command']);
+            }
+        }
+    }
+    return out;
+}
+
+/** True when `entry` was written by this package, per the content signature. */
+export function isManagedEntry(entry: unknown, signature: string): boolean {
+    if (signature === '') return false;
+    return entryCommands(entry).some((cmd) => cmd.includes(signature));
+}
+
+/**
+ * Merge one event's entry list: foreign entries kept in order, ours replaced.
+ *
+ * Exported for the fixture, which asserts the foreign entry is byte-identical
+ * and that exactly one managed entry survives a repeated install.
+ */
+export function mergeEventEntries(
+    existing: readonly unknown[],
+    incoming: readonly unknown[],
+    signature: string,
+): unknown[] {
+    const kept = existing.filter((entry) => !isManagedEntry(entry, signature));
+    return [...kept.map((e) => deepcopy(e)), ...incoming.map((e) => deepcopy(e))];
+}
+
+/**
+ * Merge the `hooks` object of a host config.
+ *
+ * `existingHooks` may be absent or a non-object (a corrupt or foreign-shaped
+ * file) — then the patch is returned on its own, which is what `deep_merge`
+ * did and is the only answer available: there is no array to preserve.
+ */
+export function mergeHookEvents(
+    existingHooks: unknown,
+    patchHooks: Record<string, unknown>,
+    signature: string,
+): Record<string, unknown> {
+    if (!isPlainObject(existingHooks)) return deepcopy(patchHooks);
+    const out: Record<string, unknown> = deepcopy(existingHooks);
+    for (const event of Object.keys(patchHooks)) {
+        const incoming = patchHooks[event];
+        const current = out[event];
+        if (!Array.isArray(incoming)) {
+            // Not an entry list — nothing array-shaped to preserve, overlay wins.
+            out[event] = deepcopy(incoming);
+            continue;
+        }
+        out[event] = mergeEventEntries(Array.isArray(current) ? current : [], incoming, signature);
+    }
+    return out;
+}
+
+/**
+ * Apply a host-config patch, routing the `hooks` key through per-event merging.
+ *
+ * Every other key keeps `deepMerge` semantics — only the shared hook lists need
+ * coexistence, and widening array-append to all keys would corrupt, for example,
+ * an `enabledPlugins` list or a settings array the host expects to own.
+ *
+ * `deepMergeFn` is injected rather than imported so the installer keeps passing
+ * its own function and this module stays independent of that file's internals.
+ */
+export function mergeHostConfig(
+    existing: Record<string, unknown>,
+    patch: Record<string, unknown>,
+    signature: string,
+    deepMergeFn: (a: Record<string, unknown>, b: Record<string, unknown>) => Record<string, unknown>,
+): Record<string, unknown> {
+    const merged = deepMergeFn(existing, patch);
+    const patchHooks = patch['hooks'];
+    if (signature === '' || !isPlainObject(patchHooks)) return merged;
+    merged['hooks'] = mergeHookEvents(existing['hooks'], patchHooks, signature);
+    return merged;
+}