@uluops/setup 0.13.1 → 0.14.0

package/CHANGELOG.md

@@ -4,6 +4,21 @@ All notable changes to `@uluops/setup` will be documented in this file.
 
 ## [Unreleased]
 
+## [0.14.0] - 2026-10-04
+
+### Changed
+
+- **Claude Code: the metrics hook is also registered on `SubagentStart`** (definition-version-dispositions checklist X4-1a). agent-metrics 0.12.0 records which agent definition each subagent was spawned with at SubagentStart and confirms it at SubagentStop. Claude Code loads a subagent's definition at spawn, so a stop-time read alone would record a definition reinstalled mid-run.
+  - The same command serves both events; the hook dispatches on `hook_event_name`.
+  - The start entry is added only with the default `SubagentStop` event. A `ULUOPS_HOOK_TYPE` override installs exactly the overridden event.
+  - `--uninstall` removes UluOps hook entries from every event type present in `settings.json`, not just the ones the current environment would install, so an install made under a different `ULUOPS_HOOK_TYPE` still comes out. User hooks are left in place.
+  - The installed-hook check now requires both events, so an install from before 0.14.0 reads as out of date and re-running setup upgrades it.
+- **Pin tracker MCP to 0.27.1 (was 0.20.1) and registry MCP to 0.11.4 (was 0.8.0).** Both pins had fallen several releases behind; under the bump rule in `src/lib/mcp-packages.ts` a setup release stamps whatever it pins, so the old pair would have shipped again. Tracker MCP 0.27.1 uses ops-sdk 6.14.0.
+  - The Codex read-only auto-approve lists were checked against the `sideEffects: 'read'` entries in each pinned package's published `dist/config/tool-registry.js` (33 tracker, 32 registry): both already matched, so no change.
+  - Tracker MCP ≥ 0.22.0 gates 12 destructive tools behind `ULUOPS_ALLOW_DESTRUCTIVE`. Setup does not write it, so they stay enabled (the pre-0.22 behaviour) and the server logs a boot warning. Setting it is the operator's call, not setup's.
+- `prepublishOnly` now runs `npm test && npm run typecheck && npm run build` (was build only).
+- Bundle `@uluops/agent-metrics` **0.12.0** (previously 0.11.0). Tracker output from the hook buffer now carries `definition_version`, and contended buffer writes are spilled rather than dropped.
+
 ## [0.13.1] - 2026-09-17
 
 ### Changed

package/README.md

@@ -18,9 +18,9 @@ npx @uluops/setup
 
 ## Supported harnesses
 
-Setup 0.13.1 bundles agent-metrics **0.11.0** for hook installation and pins
-tracker MCP **0.20.1** and registry MCP **0.8.0** in generated configs. Tracker
-MCP uses ops-sdk **6.5.2**. Re-run setup to refresh existing configs and hook
+Setup 0.14.0 bundles agent-metrics **0.12.0** for hook installation and pins
+tracker MCP **0.27.1** and registry MCP **0.11.4** in generated configs. Tracker
+MCP uses ops-sdk **6.14.0**. Re-run setup to refresh existing configs and hook
 files, then restart the affected MCP connections in your harness.
 
 Optional global CLI installs resolve npm's current release when the CLI is
@@ -122,7 +122,7 @@ The installer runs these steps in sequence:
 2. **Registry username** *(optional)* — Offers to set your registry username, the one-time prerequisite for creating or publishing definitions. Never forced: consumers who only run definitions don't need one, and non-interactive runs skip it silently unless `--username <name>` is supplied.
 3. **MCP config** — Writes tracker and registry server entries to the harness config
 4. **Definitions** — Copies pre-rendered agent definition files
-5. **Metrics hook** — Configures a post-agent hook for automatic run capture (Claude Code and Gemini CLI)
+5. **Metrics hook** — Configures a post-agent hook for automatic run capture (Claude Code and Gemini CLI). On Claude Code it registers the same command on `SubagentStart` and `SubagentStop`. The start event records which agent definition each subagent was spawned with, so saved runs carry each agent's own `definition_version`. A setup from before 0.14.0 is detected and upgraded on re-run.
 6. **`ulu` CLI** *(optional)* — Offers to install `@uluops/cli` globally. Interactive runs are prompted (default Y); non-interactive runs skip unless `--with-cli` is passed. `--no-cli` always skips. The install is best-effort: if `npm install -g` fails (permissions, nvm prefix, etc.) the rest of setup still completes and a manual install command is printed.
 7. **Health check** — Verifies both API endpoints are reachable
 
@@ -327,8 +327,9 @@ Removes only UluOps-managed files: agents, commands, MCP config entries, shell p
 ## Data & privacy
 
 The metrics hook (step 5) captures **agent execution metadata only** — token
-counts, durations, model and agent names — into a **local buffer** on your
-machine. The hook itself sends nothing anywhere: data reaches the UluOps
+counts, durations, model and agent names, and (from agent-metrics 0.12.0) the
+version, path and content hash of the agent definition file that ran — into a
+**local buffer** on your machine. The hook itself sends nothing anywhere: data reaches the UluOps
 tracker only when a run is explicitly saved (by you, or by tooling you run).
 Artifact content being validated is never stored — only validation results.
 

package/dist/harnesses/claude-code.js

@@ -7,7 +7,7 @@
 import { join } from "node:path";
 import { ULUOPS_SERVERS, } from "./types.js";
 import { readConfig, mergeUluopsMcp, removeUluopsMcp, writeConfig, } from "../lib/config-merger.js";
-import { readSettings, writeSettings, mergeUluopsHook, removeUluopsHook, hasUluopsHook, } from "../lib/settings-merger.js";
+import { readSettings, writeSettings, mergeUluopsHook, removeUluopsHook, hasUluopsHook, claudeManagedHookTypes, } from "../lib/settings-merger.js";
 import { getClaudeHome, getClaudeJsonPath } from "../lib/paths.js";
 import { serialize } from "../lib/write-coordinator.js";
 class ClaudeCodeMcpConfig {
@@ -39,8 +39,9 @@ class ClaudeCodeHooks {
         // collide today".
         await serialize(settingsPath, async () => {
             const settings = await readSettings(settingsPath);
-            // Claude Code uses SubagentStop as the default event for auto-save
-            const merged = mergeUluopsHook(settings, hookCommand);
+            // Claude Code uses SubagentStop as the default event for auto-save, plus
+            // SubagentStart for definition capture (agent-metrics 0.12.0).
+            const merged = claudeManagedHookTypes().reduce((acc, type) => mergeUluopsHook(acc, hookCommand, type), settings);
             await writeSettings(settingsPath, merged);
         });
         return true;
@@ -50,13 +51,19 @@ class ClaudeCodeHooks {
             return;
         await serialize(settingsPath, async () => {
             const settings = await readSettings(settingsPath);
-            const cleaned = removeUluopsHook(settings);
+            // Every event type present, not just the ones the current env would install:
+            // an install made under a different ULUOPS_HOOK_TYPE (or before SubagentStart was
+            // managed) must still come out. isUluopsMatcher identifies ours; user hooks stay.
+            const types = new Set([...claudeManagedHookTypes(), ...Object.keys(settings.hooks ?? {})]);
+            const cleaned = [...types].reduce((acc, type) => removeUluopsHook(acc, type), settings);
             await writeSettings(settingsPath, cleaned);
         });
     }
     async check(settingsPath) {
         const settings = await readSettings(settingsPath);
-        return hasUluopsHook(settings);
+        // Every managed event must be present: an install from before 0.14.0 has
+        // SubagentStop only, and reads as needing the upgrade.
+        return claudeManagedHookTypes().every((type) => hasUluopsHook(settings, type));
     }
 }
 const home = getClaudeHome();

package/dist/lib/mcp-packages.d.ts

@@ -22,11 +22,11 @@
  * MCP launch. A pin is not a publish; the probe is what enforces that here.
  */
 export declare const OPS_MCP_PACKAGE = "@uluops/ops-mcp";
-export declare const OPS_MCP_VERSION = "0.20.1";
-export declare const OPS_MCP_SPEC: "@uluops/ops-mcp@0.20.1";
+export declare const OPS_MCP_VERSION = "0.27.1";
+export declare const OPS_MCP_SPEC: "@uluops/ops-mcp@0.27.1";
 export declare const REGISTRY_MCP_PACKAGE = "@uluops/registry-mcp";
-export declare const REGISTRY_MCP_VERSION = "0.8.0";
-export declare const REGISTRY_MCP_SPEC: "@uluops/registry-mcp@0.8.0";
+export declare const REGISTRY_MCP_VERSION = "0.11.4";
+export declare const REGISTRY_MCP_SPEC: "@uluops/registry-mcp@0.11.4";
 /** Probe targets: the pinned versions the harness will actually resolve. */
 export declare const MCP_PROBE_TARGETS: readonly {
     pkg: string;

package/dist/lib/mcp-packages.js

@@ -22,10 +22,10 @@
  * MCP launch. A pin is not a publish; the probe is what enforces that here.
  */
 export const OPS_MCP_PACKAGE = "@uluops/ops-mcp";
-export const OPS_MCP_VERSION = "0.20.1";
+export const OPS_MCP_VERSION = "0.27.1";
 export const OPS_MCP_SPEC = `${OPS_MCP_PACKAGE}@${OPS_MCP_VERSION}`;
 export const REGISTRY_MCP_PACKAGE = "@uluops/registry-mcp";
-export const REGISTRY_MCP_VERSION = "0.8.0";
+export const REGISTRY_MCP_VERSION = "0.11.4";
 export const REGISTRY_MCP_SPEC = `${REGISTRY_MCP_PACKAGE}@${REGISTRY_MCP_VERSION}`;
 /** Probe targets: the pinned versions the harness will actually resolve. */
 export const MCP_PROBE_TARGETS = [

package/dist/lib/settings-merger.d.ts

@@ -33,6 +33,18 @@ export interface HarnessSettings {
 export declare const CLAUDE_HOOK_TYPES: Set<string>;
 /** Default Claude Code hook event used when no override is configured. */
 export declare const DEFAULT_CLAUDE_HOOK_TYPE = "SubagentStop";
+/**
+ * The companion event installed beside the default one (agent-metrics 0.12.0,
+ * dvc checklist X4-1). agent-metrics records which agent definition a subagent was
+ * spawned with at SubagentStart and confirms it at SubagentStop; Claude Code loads a
+ * subagent's definition at spawn, so a stop-time read alone would record a
+ * definition reinstalled mid-run. Same command: the hook dispatches on
+ * `hook_event_name`. Installed only with the default event — a user who overrode
+ * the event type (ULUOPS_HOOK_TYPE) gets exactly what they asked for.
+ */
+export declare const CLAUDE_SPAWN_HOOK_TYPE = "SubagentStart";
+/** The hook event types setup manages for Claude Code, given the resolved primary type. */
+export declare function claudeManagedHookTypes(primary?: string): string[];
 export interface HookProbeResult {
     hookType: string;
     supported: boolean;

package/dist/lib/settings-merger.js

@@ -37,6 +37,7 @@ const HOOK_OWNERSHIP_SIGNATURE = "agent-metrics/dist/hook.js";
  * Exported for that test only — runtime callers should use `probeHookSupport`.
  */
 export const CLAUDE_HOOK_TYPES = new Set([
+    "SubagentStart",
     "SubagentStop",
     "PreToolUse",
     "PostToolUse",
@@ -45,6 +46,20 @@ export const CLAUDE_HOOK_TYPES = new Set([
 ]);
 /** Default Claude Code hook event used when no override is configured. */
 export const DEFAULT_CLAUDE_HOOK_TYPE = "SubagentStop";
+/**
+ * The companion event installed beside the default one (agent-metrics 0.12.0,
+ * dvc checklist X4-1). agent-metrics records which agent definition a subagent was
+ * spawned with at SubagentStart and confirms it at SubagentStop; Claude Code loads a
+ * subagent's definition at spawn, so a stop-time read alone would record a
+ * definition reinstalled mid-run. Same command: the hook dispatches on
+ * `hook_event_name`. Installed only with the default event — a user who overrode
+ * the event type (ULUOPS_HOOK_TYPE) gets exactly what they asked for.
+ */
+export const CLAUDE_SPAWN_HOOK_TYPE = "SubagentStart";
+/** The hook event types setup manages for Claude Code, given the resolved primary type. */
+export function claudeManagedHookTypes(primary = getDefaultHookEventType()) {
+    return primary === DEFAULT_CLAUDE_HOOK_TYPE ? [primary, CLAUDE_SPAWN_HOOK_TYPE] : [primary];
+}
 /** Configurable hook type via env var. Falls back to SubagentStop. */
 function getDefaultHookEventType() {
     return process.env["ULUOPS_HOOK_TYPE"] ?? DEFAULT_CLAUDE_HOOK_TYPE;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uluops/setup",
-  "version": "0.13.1",
+  "version": "0.14.0",
   "description": "Zero-friction installer for UluOps agentic harnesses",
   "license": "MIT",
   "repository": {
@@ -13,6 +13,7 @@
     "mcp",
     "agents",
     "claude",
+    "codex",
     "opencode",
     "agentic",
     "harness",
@@ -45,11 +46,11 @@
     "typecheck": "tsc -p tsconfig.build.json --noEmit && tsc -p tsconfig.test.json --noEmit",
     "test": "vitest run",
     "test:watch": "vitest watch",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm test && npm run typecheck && npm run build"
   },
   "dependencies": {
     "@inquirer/prompts": "8.6.0",
-    "@uluops/agent-metrics": "0.11.0",
+    "@uluops/agent-metrics": "0.12.0",
     "chalk": "5.6.2",
     "commander": "15.0.0",
     "jsonc-parser": "3.3.1"