@orchestrator-claude/definitions 3.36.0 → 3.37.1

package/hooks/subagent-start.ts

@@ -2,8 +2,113 @@
  * subagent-start.ts — SubagentStart hook (RFC-022 Phase 2)
  * Replaces track-agent-invocation.sh start
  * Registers agent invocation via REST API.
+ *
+ * TD-214/TD-239 TASK-004 (RF-007 core, identity point #3 of the
+ * consolidator — see packages/definitions/tests/IdentityNormalizationConsolidator.test.ts):
+ * this is the PRIMARY critical path for invocation tracking — every
+ * RF-002/RF-004 telemetry signal downstream depends on this hook correctly
+ * identifying WHICH agent was dispatched. Two defects fixed here:
+ *
+ *  1. Precedence chain used to fall back to a literal `'unknown'` string that
+ *     was then tracked via startInvocation() as if it were a genuine agent
+ *     name — a silent fallback promoted to a real identity. The chain is now
+ *     `agent_type -> tool_input.subagent_type -> subagent_type ->
+ *     tool_input.type`, with NO trailing `|| 'unknown'`; an all-absent read
+ *     resolves to `''`, which the defensive filter below treats as a read
+ *     FAILURE (not a legitimate agent), not a would-be lookup key.
+ *  2. No namespace normalization: under plugin scope the harness sends
+ *     `orchestrator:reviewer`; PHASE_MAP only has bare keys (`reviewer`), so
+ *     a namespaced dispatch silently fell through to
+ *     `PHASE_MAP[agentType] || agentType` and got the WRONG phase (the raw
+ *     namespaced string itself). `normalizeAgentName` (moved to
+ *     `lib/api-client.ts` in TASK-001) is applied immediately after the read.
+ *
+ * Defensive filter (classifyAgentType), applied to the normalized value:
+ *  - `''` or literal `'unknown'` -> the read genuinely failed (no field in
+ *    the 4-deep chain produced anything usable). Logged at [ERROR] — elevated
+ *    from [WARN] per RNF-003, because this is a signal that the upstream
+ *    payload shape changed, not an expected/everyday case. `startInvocation`
+ *    is never called.
+ *  - non-empty but NOT a member of the canonical agent set -> a real Task
+ *    dispatch that simply isn't one of THIS project's workflow agents (the
+ *    common case: `general-purpose`, or any other ad-hoc subagent_type).
+ *    Logged at [DEBUG] — this is normal, not a failure. `startInvocation` is
+ *    never called (there is nothing meaningful to track invocation-wise for
+ *    an agent this hook doesn't recognize as a workflow participant).
+ *  - a member of the canonical set -> proceeds exactly as before (phase
+ *    lookup, startInvocation, writeInvocationState).
+ *
+ * These two branches are checked in THIS order (read-failure first) — '' and
+ * 'unknown' can never be members of the canonical set, so checking set
+ * membership first would make the [ERROR] branch permanently unreachable.
+ *
+ * Canonical agent set (ADR-023 plan ADR-P2, measured empirically S433):
+ * `packages/definitions/agents/` (28 `.md` files today) — DELIBERATELY NOT
+ * the `AGENTS_DIR = join(PROJECT_ROOT, '.claude', 'agents')` pattern used by
+ * session-start.ts. In THIS repo (ADR-023 dogfood — the
+ * canonical source lives here, nothing is "installed" into `.claude/agents/`)
+ * that path resolves to a directory with 0 `.md` files, so reusing it here
+ * would make `classifyAgentType` reject every real agent (fail-closed) or,
+ * if the check were inverted defensively, accept everything (fail-open) —
+ * both wrong. That gap is TD-243, filed and explicitly OUT OF SCOPE for this
+ * task; `AGENTS_DIR`'s call site in session-start.ts is
+ * NOT touched here. `resolveCanonicalAgentsDir` below resolves the path
+ * independently, local to this file.
+ *
+ * TD-214/TD-239 TASK-005 (RF-007 instrumentation, one layer above TASK-004):
+ * captures the FULL raw stdin payload — not just the 4 fields the precedence
+ * chain above extracts — into a DEDICATED log, `hook-raw-payloads.jsonl`,
+ * kept SEPARATE from `hook-debug.log` (retention-cost requirement, not
+ * style: this log is high-volume and `hook-debug.log` is read for other
+ * purposes). Every line also carries `correlatedWithDispatchIntent`, sourced
+ * from `hasFreshDispatchIntent(workflow.id)` (TD-205) — consumed VERBATIM
+ * from `lib/api-client.ts` (hard restriction: that file is CONSUMED, not
+ * modified, here; its signature/behavior are unchanged, since
+ * `dangling-guard.ts` rule 6 already depends on both).
+ *
+ * Capture fires on EVERY hook trigger — read-failure, unrecognized-agent,
+ * no-active-workflow, and proceed branches alike — deliberately, because the
+ * RF-011/TASK-012 consumer this log is written for needs the raw payload
+ * precisely for the cases where identity extraction FAILED or produced an
+ * unexpected value (the bug class this whole workflow exists to diagnose),
+ * not only for the successful path. To support this without a duplicate
+ * `getActiveWorkflow()` round-trip, the workflow lookup that previously
+ * happened only in the `proceed` branch now happens ONCE, up front, and is
+ * reused both for the correlation flag and for the pre-existing
+ * `startInvocation` gating further down.
+ *
+ * `hook-raw-payloads.jsonl`'s location is NOT obtained from
+ * `lib/api-client.ts` (its `STATE_DIR`/`DEBUG_LOG` constants are not
+ * exported, and this task must not touch that file) — `resolveStateDir`
+ * below duplicates the same override-then-sentinel derivation
+ * (`ORCHESTRATOR_STATE_DIR` env override, else `.orchestrator/.state` under
+ * the resolved project root) that `lib/api-client.ts` uses internally for
+ * `STATE_DIR`, mirroring the `resolveCanonicalAgentsDir` "resolve locally,
+ * don't touch the lib" precedent from TASK-004.
+ *
+ * TD-214/TD-239 TASK-010 (RF-010 Fase 5 Parte 3 — wiring): once
+ * `classifyAgentType` reaches `decision.kind === 'proceed'` (RF-007
+ * successfully resolved `resolvedAgentType`), reads
+ * `<resolveAgentMemoryBaseDir(cwd)>/<resolvedAgentType>/memory-index.yaml`
+ * (same `resolveAgentMemoryBaseDir` already injected by
+ * subagent-stop.ts/TASK-006 for the identical purpose), composes via
+ * `filterRelevantMemories` (TASK-008, HIGH-001 quota fix) and
+ * `formatMemoryContext` (TASK-009, per-entry cap + aggregate budget), and
+ * injects the result via `outputContext('SubagentStart', ...)` — but ONLY
+ * when the formatted string is non-empty (an index that reads but composes
+ * to nothing, e.g. every entry stale and none is `feedback`, must not emit a
+ * hollow `[MEMORY-CONTEXT]` block).
+ *
+ * Gated SOLELY on identity resolution (the RF-007->RF-010 hard dependency —
+ * TASK-011 proves this at the integration level: a payload RF-007 rejects
+ * must produce zero `outputContext` calls anywhere in the pipeline), NOT on
+ * an active workflow existing: memory belongs to the agent's own identity,
+ * not to workflow-tracking state, so this runs BEFORE the `if (!workflow)`
+ * early-return below and independently of it.
  */
 
+import { join, dirname } from 'node:path';
+import { mkdirSync, writeFileSync } from 'node:fs';
 import {
   log,
   readStdin,
@@ -11,7 +116,20 @@ import {
   getActiveWorkflow,
   startInvocation,
   writeInvocationState,
+  normalizeAgentName,
+  resolveHookProjectRoot,
+  hasFreshDispatchIntent,
+  resolveAgentMemoryBaseDir,
+  outputContext,
 } from './lib/api-client.js';
+import {
+  scanAgentDefinitions,
+  readMemoryIndex,
+  filterRelevantMemories,
+  formatMemoryContext,
+  type MemoryEntry,
+  type MemoryIndexDiagnostic,
+} from './lib/capability-scanner.js';
 
 const HOOK = 'SUBAGENT-START';
 
@@ -24,39 +142,272 @@ const PHASE_MAP: Record<string, string> = {
   reviewer: 'review',
 };
 
-async function main(): Promise<void> {
-  const stdin = await readStdin();
-  log(HOOK, `SubagentStart triggered`);
+// ─────────────────────────────────────────────────────────────
+// Pure helpers (exported for testing)
+// ─────────────────────────────────────────────────────────────
 
-  const agentType =
+/**
+ * Reads the dispatched agent's raw (un-normalized) identity from stdin via
+ * the 4-field precedence chain. Returns `''` when none of the fields are
+ * present — deliberately NOT `'unknown'`; a silent placeholder fallback is
+ * exactly the defect this task fixes (see module doc).
+ */
+export function resolveRawAgentType(stdin: Record<string, unknown>): string {
+  return (
+    getField(stdin, 'agent_type') ||
     getField(stdin, 'tool_input.subagent_type') ||
     getField(stdin, 'subagent_type') ||
-    getField(stdin, 'tool_input.type') ||
-    'unknown';
+    getField(stdin, 'tool_input.type')
+  );
+}
+
+export type AgentTypeDecision =
+  | { kind: 'skip-read-failed' }
+  | { kind: 'skip-unrecognized'; agentType: string }
+  | { kind: 'proceed'; agentType: string };
+
+/**
+ * Builds one JSONL line for `hook-raw-payloads.jsonl` (TASK-005, RF-007):
+ * the FULL raw stdin payload (verbatim, not filtered to the 4 identity
+ * fields) plus the dispatch-intent correlation flag. Pure — no IO — so it is
+ * independently testable and reusable by whoever writes the RF-011/TASK-012
+ * consumer (economia deliberada per the dispatch: parse this file instead of
+ * re-reading stdin / re-calling `hasFreshDispatchIntent`).
+ */
+export function buildRawPayloadLogLine(
+  payload: Record<string, unknown>,
+  correlatedWithDispatchIntent: boolean,
+  nowIso: string = new Date().toISOString()
+): string {
+  return JSON.stringify({
+    timestamp: nowIso,
+    hook: HOOK,
+    payload,
+    correlatedWithDispatchIntent,
+  });
+}
 
-  const phase = PHASE_MAP[agentType] || agentType;
+/**
+ * Defensive filter over an ALREADY-NORMALIZED agent type (see module doc for
+ * branch ordering rationale). `getCanonicalAgentNames` is only invoked when
+ * `agentType` is non-empty and not the literal `'unknown'` — no need to pay
+ * for a directory scan on a read that already failed.
+ */
+export function classifyAgentType(
+  agentType: string,
+  getCanonicalAgentNames: () => string[]
+): AgentTypeDecision {
+  if (agentType === '' || agentType === 'unknown') {
+    return { kind: 'skip-read-failed' };
+  }
+  const canonicalAgents = getCanonicalAgentNames();
+  if (!canonicalAgents.includes(agentType)) {
+    return { kind: 'skip-unrecognized', agentType };
+  }
+  return { kind: 'proceed', agentType };
+}
 
-  log(HOOK, `agent=${agentType} phase=${phase}`);
+// ─────────────────────────────────────────────────────────────
+// Dependency injection interface (enables testing without IO)
+// ─────────────────────────────────────────────────────────────
+
+export interface HookDeps {
+  readStdin: () => Promise<Record<string, unknown>>;
+  log: (prefix: string, msg: string) => void;
+  getActiveWorkflow: () => Promise<{ id: string } | null>;
+  startInvocation: (agentType: string, workflowId: string, phase: string) => Promise<string | null>;
+  writeInvocationState: (workflowId: string, agentType: string, invocationId: string) => boolean;
+  /** Returns the canonical agent-name roster (see module doc, ADR-P2). */
+  getCanonicalAgentNames: () => string[];
+  /**
+   * TASK-005 (RF-007, TD-205): dispatch-intent freshness check. Wired
+   * directly to `lib/api-client.ts`'s `hasFreshDispatchIntent` — same
+   * function, same signature, same behavior as the `dangling-guard.ts` rule
+   * 6 consumer; this hook must not (and does not) alter either.
+   */
+  hasFreshDispatchIntent: (workflowId: string) => boolean;
+  /**
+   * TASK-005 (RF-007): appends one pre-built JSONL line to
+   * `hook-raw-payloads.jsonl` — a channel SEPARATE from `log`/
+   * `hook-debug.log` (see module doc for the retention-cost rationale).
+   */
+  appendRawPayloadLog: (line: string) => void;
+  /**
+   * TASK-010 (RF-010 Parte 3): resolves the `.claude/agent-memory` base dir
+   * for the CURRENT hook invocation — same function/contract already
+   * injected by subagent-stop.ts (TASK-006).
+   */
+  resolveAgentMemoryBaseDir: (cwd: string) => string;
+  /** TASK-010: reads `<baseDir>/<resolvedAgentType>/memory-index.yaml` (TASK-026 dual-shape parser, fail-open). */
+  readMemoryIndex: (indexPath: string, diag?: MemoryIndexDiagnostic) => MemoryEntry[] | null;
+  /** TASK-010: composition (TASK-008, HIGH-001 quota fix — reserves slots per non-feedback type). */
+  filterRelevantMemories: (entries: MemoryEntry[]) => MemoryEntry[];
+  /** TASK-010: formatting (TASK-009 — per-entry char cap + aggregate char budget). */
+  formatMemoryContext: (selected: MemoryEntry[], allEntries: MemoryEntry[]) => string;
+  /** TASK-010: injects the formatted memory context into the dispatched sub-agent's turn. */
+  outputContext: (hookEvent: string, context: string) => void;
+}
+
+/** `packages/definitions/agents` under the resolved project root (module doc, ADR-P2). */
+function resolveCanonicalAgentsDir(): string {
+  const root = resolveHookProjectRoot(process.cwd()) ?? process.cwd();
+  return join(root, 'packages', 'definitions', 'agents');
+}
+
+function getCanonicalAgentNamesDefault(): string[] {
+  return scanAgentDefinitions(resolveCanonicalAgentsDir());
+}
+
+/**
+ * Duplicates `lib/api-client.ts`'s internal `STATE_DIR` derivation (TD-224
+ * Achado 1: `ORCHESTRATOR_STATE_DIR` override wins outright, else
+ * `.orchestrator/.state` under the resolved project root) WITHOUT importing
+ * it — `STATE_DIR` is not exported, and this task's hard restriction forbids
+ * touching `lib/api-client.ts`. Same "resolve locally, don't touch the lib"
+ * precedent as `resolveCanonicalAgentsDir` above (TASK-004).
+ */
+function resolveStateDir(): string {
+  const override = process.env.ORCHESTRATOR_STATE_DIR;
+  if (override !== undefined && override !== '') return override;
+  const root = resolveHookProjectRoot(process.cwd()) ?? process.cwd();
+  return join(root, '.orchestrator', '.state');
+}
+
+function resolveRawPayloadLogPath(): string {
+  return join(resolveStateDir(), 'hook-raw-payloads.jsonl');
+}
+
+/** Fail-open, mirrors `lib/api-client.ts`'s `log()` posture: never throws. */
+function appendRawPayloadLogDefault(line: string): void {
+  try {
+    const path = resolveRawPayloadLogPath();
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${line}\n`, { flag: 'a' });
+  } catch {
+    // fail silently
+  }
+}
+
+const defaultDeps: HookDeps = {
+  readStdin,
+  log,
+  getActiveWorkflow,
+  startInvocation,
+  writeInvocationState,
+  getCanonicalAgentNames: getCanonicalAgentNamesDefault,
+  hasFreshDispatchIntent,
+  appendRawPayloadLog: appendRawPayloadLogDefault,
+  resolveAgentMemoryBaseDir,
+  readMemoryIndex,
+  filterRelevantMemories,
+  formatMemoryContext,
+  outputContext,
+};
+
+// ─────────────────────────────────────────────────────────────
+// Core logic (exported for testing)
+// ─────────────────────────────────────────────────────────────
+
+export async function mainWithDeps(deps: HookDeps): Promise<void> {
+  const stdin = await deps.readStdin();
+  deps.log(HOOK, `SubagentStart triggered`);
+
+  // TASK-005 (RF-007): resolve the active workflow ONCE, up front — reused
+  // both for the raw-payload correlation below and for the pre-existing
+  // startInvocation gating further down (no duplicate getActiveWorkflow call
+  // introduced by this instrumentation).
+  const workflow = await deps.getActiveWorkflow();
+  const correlatedWithDispatchIntent = workflow ? deps.hasFreshDispatchIntent(workflow.id) : false;
+  deps.appendRawPayloadLog(buildRawPayloadLogLine(stdin, correlatedWithDispatchIntent));
+
+  const rawAgentType = resolveRawAgentType(stdin);
+  const agentType = normalizeAgentName(rawAgentType);
+
+  const decision = classifyAgentType(agentType, deps.getCanonicalAgentNames);
+
+  if (decision.kind === 'skip-read-failed') {
+    deps.log(
+      HOOK,
+      `[ERROR] could not read agent identity from stdin (checked agent_type, ` +
+        `tool_input.subagent_type, subagent_type, tool_input.type — all empty or ` +
+        `literal 'unknown'; raw="${rawAgentType}") — skipping invocation tracking ` +
+        `(RNF-003: elevated from WARN)`
+    );
+    return;
+  }
+
+  if (decision.kind === 'skip-unrecognized') {
+    deps.log(
+      HOOK,
+      `[DEBUG] agent="${decision.agentType}" is not in the canonical agent set — ` +
+        `skipping invocation tracking (not a workflow agent, e.g. a general-purpose ` +
+        `Task dispatch)`
+    );
+    return;
+  }
+
+  const resolvedAgentType = decision.agentType;
+  const phase = PHASE_MAP[resolvedAgentType] || resolvedAgentType;
+
+  deps.log(HOOK, `agent=${resolvedAgentType} phase=${phase}`);
+
+  // TASK-010 (RF-010 Parte 3): memory context injection. Gated ONLY on
+  // identity resolution (this point is only reached when decision.kind ===
+  // 'proceed', above) — deliberately BEFORE the `!workflow` early return,
+  // since memory belongs to the agent's identity, not to workflow-tracking
+  // state (see module doc).
+  const memoryIndexPath = join(
+    deps.resolveAgentMemoryBaseDir(process.cwd()),
+    resolvedAgentType,
+    'memory-index.yaml'
+  );
+  // S480: o sub-agente sofria a MESMA cegueira do session-start -- mesma funcao,
+  // mesmos tres pontos mudos. Consertar so um lado deixaria o outro calado.
+  const memoryDiag: MemoryIndexDiagnostic = {};
+  const memoryEntries = deps.readMemoryIndex(memoryIndexPath, memoryDiag);
+  if (memoryDiag.reason) {
+    deps.log(HOOK, `Memory index: ${memoryDiag.reason}`);
+    if (!memoryEntries || memoryEntries.length === 0) {
+      deps.outputContext(
+        'SubagentStart',
+        `[MEMORY-CONTEXT] INDISPONÍVEL — nenhuma memória injetada. ${memoryDiag.reason}`
+      );
+    }
+  }
+  if (memoryEntries) {
+    const selectedMemories = deps.filterRelevantMemories(memoryEntries);
+    const memoryContext = deps.formatMemoryContext(selectedMemories, memoryEntries);
+    if (memoryContext) {
+      deps.outputContext('SubagentStart', memoryContext);
+    }
+  }
 
-  const workflow = await getActiveWorkflow();
   if (!workflow) {
-    log(HOOK, 'No active workflow, skipping');
+    deps.log(HOOK, 'No active workflow, skipping');
     return;
   }
 
-  const invocationId = await startInvocation(agentType, workflow.id, phase);
+  const invocationId = await deps.startInvocation(resolvedAgentType, workflow.id, phase);
   if (invocationId) {
-    const written = writeInvocationState(workflow.id, agentType, invocationId);
-    log(
+    const written = deps.writeInvocationState(workflow.id, resolvedAgentType, invocationId);
+    deps.log(
       HOOK,
-      `START: agent=${agentType} phase=${phase} workflow=${workflow.id} invocationId=${invocationId} stateWritten=${written}`
+      `START: agent=${resolvedAgentType} phase=${phase} workflow=${workflow.id} invocationId=${invocationId} stateWritten=${written}`
     );
   } else {
-    log(
+    deps.log(
       HOOK,
-      `START: agent=${agentType} phase=${phase} workflow=${workflow.id} — startInvocation returned null (POST failed or no token)`
+      `START: agent=${resolvedAgentType} phase=${phase} workflow=${workflow.id} — startInvocation returned null (POST failed or no token)`
     );
   }
 }
 
+// ─────────────────────────────────────────────────────────────
+// Entry point (production use)
+// ─────────────────────────────────────────────────────────────
+
+async function main(): Promise<void> {
+  await mainWithDeps(defaultDeps);
+}
+
 main().catch(() => process.exit(0));