@darkhunt-security/endpoint-codex 0.9.2 → 0.9.4

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "darkhunt-guard",
-  "version": "0.9.2",
+  "version": "0.9.4",
   "hooks": "./hooks/hooks.json",
   "description": "Darkhunt endpoint plugin for Codex CLI \u2014 full session trace capture and PreToolUse guardrails.",
   "author": {

package/README.md

@@ -44,11 +44,24 @@ to write. Enrolment writes them; a pasted config cannot. Run this once after pas
 `/darkhunt-guard:status` reports the launchers, so you never have to take this on trust —
 a machine missing them looks perfectly configured everywhere else and captures nothing.
 
+## Upgrade
+
+```
+codex plugin add darkhunt-guard@darkhunt
+```
+
+Re-adding re-resolves the published version. The new one loads on your **next** Codex
+CLI session, and the launchers need no attention — they resolve the newest installed
+version at run time. `/darkhunt-guard:status` prints the version actually running,
+which is the only reliable answer: an update that resolved against a registry without
+the new version reports success and changes nothing.
+
 ## What it captures
 
 The session transcript, mapped to spans: user and assistant messages, thinking blocks,
 tool calls paired with their results, token usage, attachment metadata (never the bytes),
-and the subagent topology as linked child traces.
+and every subagent's own rollout — Codex writes one per subagent, linked to its
+parent through `parent_thread_id` and labelled with the agent.
 
 Reading the transcript rather than instrumenting the agent is what makes this complete:
 there is no code path in Codex CLI we could have missed.

package/dist/bin/backfill.mjs

@@ -18350,7 +18350,7 @@ var SessionEmitter = class {
   seeded(parts, create) {
     if (!this.options.ids)
       return create();
-    return this.options.ids.under(seed(this.options.sessionId, ...parts), create);
+    return this.options.ids.under(seed(this.options.seedKey ?? this.options.sessionId, ...parts), create);
   }
   ingest(record) {
     if (record.kind === "session_meta") {
@@ -18358,6 +18358,9 @@ var SessionEmitter = class {
         this.title = record.meta.title;
       if (record.meta?.model)
         this.model = record.meta.model;
+      if (record.meta?.parentSessionId && !this.trace) {
+        this.grouping = record.meta.parentSessionId;
+      }
       for (const [key, value] of Object.entries(record.meta ?? {})) {
         if (typeof value === "string" && key !== "title")
           this.meta[key] = value;
@@ -18471,14 +18474,31 @@ var SessionEmitter = class {
     }
     await this.client.flush();
   }
+  defaultTraceName() {
+    const agentType = this.options.agentType ?? this.meta["agentType"];
+    if (agentType)
+      return `subagent: ${agentType}`;
+    if (this.options.agentId === void 0) {
+      return this.grouping ? "subagent" : `${this.options.vendor} session`;
+    }
+    return this.options.agentType ? `subagent: ${this.options.agentType}` : `subagent ${this.options.agentId}`;
+  }
+  /** The session traces group under. Set from the path, or from `session_meta`. */
+  grouping;
   ensureTrace(ts) {
     if (!this.trace) {
       this.trace = this.seeded(["trace", this.options.passKey ?? "0"], () => this.client.trace({
-        name: this.title ?? `${this.options.vendor} session`,
-        sessionId: this.options.sessionId,
+        // A subagent's transcript has no title of its own, and "claude-code session"
+        // beside its parent reads as a second session rather than part of one.
+        name: this.title ?? this.defaultTraceName(),
+        sessionId: this.grouping ?? this.options.sessionId,
         startTime: ts,
-        tags: [this.options.vendor],
-        metadata: this.meta,
+        tags: [this.options.vendor, ...this.options.agentId ? ["subagent"] : []],
+        metadata: {
+          ...this.meta,
+          ...this.options.agentId !== void 0 ? { agentId: this.options.agentId } : {},
+          ...this.options.agentType !== void 0 ? { agentType: this.options.agentType } : {}
+        },
         ...this.options.userId !== void 0 ? { userId: this.options.userId } : {},
         ...this.options.userEmail !== void 0 ? { userEmail: this.options.userEmail } : {},
         ...this.options.environment !== void 0 ? { environment: this.options.environment } : {}
@@ -21585,7 +21605,8 @@ async function runForwarder(mapper, options = {}) {
       }
     }
     const drain = options.paths ? { paths: options.paths } : drainSpool(mapper, checkpoints);
-    const paths2 = options.paths ? drain.paths : [.../* @__PURE__ */ new Set([...drain.paths, ...liveTranscripts(loadBeat(config.scope))])];
+    const named = options.paths ? drain.paths : [.../* @__PURE__ */ new Set([...drain.paths, ...liveTranscripts(loadBeat(config.scope))])];
+    const paths2 = [...new Set(named.flatMap((path) => [path, ...related(mapper, path)]))];
     if (paths2.length === 0) {
       if (drain.checkpoint)
         checkpoints[SPOOL_KEY] = drain.checkpoint;
@@ -21620,10 +21641,15 @@ async function runForwarder(mapper, options = {}) {
         try {
           const from = resumeOffset(checkpoints, path);
           const carried = resumeTurn(checkpoints, path, from);
+          const own = mapper.sessionIdFor(path);
+          const sub = subagentOf(mapper, path);
           const emitter = new SessionEmitter(client, {
-            sessionId: mapper.sessionIdFor(path),
+            sessionId: sub?.sessionId ?? own,
+            seedKey: own,
             vendor: mapper.vendor,
             passKey: String(from),
+            ...sub?.agentId !== void 0 ? { agentId: sub.agentId } : {},
+            ...sub?.agentType !== void 0 ? { agentType: sub.agentType } : {},
             ...ids !== void 0 ? { ids } : {},
             ...userId !== void 0 ? { userId } : {},
             ...carried !== void 0 ? { resumeTurn: carried } : {}
@@ -21707,6 +21733,20 @@ function withinDays(paths2, days) {
     }
   });
 }
+function related(mapper, path) {
+  try {
+    return mapper.relatedTranscripts?.(path) ?? [];
+  } catch {
+    return [];
+  }
+}
+function subagentOf(mapper, path) {
+  try {
+    return mapper.subagentOf?.(path);
+  } catch {
+    return void 0;
+  }
+}
 function discoverTranscripts(mapper) {
   const found = [];
   const walk = (dir) => {
@@ -21814,7 +21854,14 @@ var codexTranscript = {
           meta: {
             ...str(payload["cwd"]) !== void 0 ? { cwd: str(payload["cwd"]) } : {},
             ...str(payload["cli_version"]) !== void 0 ? { version: str(payload["cli_version"]) } : {},
-            ...str(payload["originator"]) !== void 0 ? { entrypoint: str(payload["originator"]) } : {}
+            ...str(payload["originator"]) !== void 0 ? { entrypoint: str(payload["originator"]) } : {},
+            // A Codex subagent is a rollout of its own, a peer of its parent in the
+            // same date directory — nothing in the path says whose it is. These three
+            // are the only link, and unlike Claude Code's layout they are the vendor's
+            // own documented session metadata rather than a guess.
+            ...str(payload["parent_thread_id"]) !== void 0 ? { parentSessionId: str(payload["parent_thread_id"]) } : {},
+            ...str(payload["agent_nickname"]) !== void 0 ? { agentType: str(payload["agent_nickname"]) } : {},
+            ...str(payload["agent_path"]) !== void 0 ? { agentPath: str(payload["agent_path"]) } : {}
           }
         }
       ];

package/dist/bin/forwarder.mjs

@@ -18350,7 +18350,7 @@ var SessionEmitter = class {
   seeded(parts, create) {
     if (!this.options.ids)
       return create();
-    return this.options.ids.under(seed(this.options.sessionId, ...parts), create);
+    return this.options.ids.under(seed(this.options.seedKey ?? this.options.sessionId, ...parts), create);
   }
   ingest(record) {
     if (record.kind === "session_meta") {
@@ -18358,6 +18358,9 @@ var SessionEmitter = class {
         this.title = record.meta.title;
       if (record.meta?.model)
         this.model = record.meta.model;
+      if (record.meta?.parentSessionId && !this.trace) {
+        this.grouping = record.meta.parentSessionId;
+      }
       for (const [key, value] of Object.entries(record.meta ?? {})) {
         if (typeof value === "string" && key !== "title")
           this.meta[key] = value;
@@ -18471,14 +18474,31 @@ var SessionEmitter = class {
     }
     await this.client.flush();
   }
+  defaultTraceName() {
+    const agentType = this.options.agentType ?? this.meta["agentType"];
+    if (agentType)
+      return `subagent: ${agentType}`;
+    if (this.options.agentId === void 0) {
+      return this.grouping ? "subagent" : `${this.options.vendor} session`;
+    }
+    return this.options.agentType ? `subagent: ${this.options.agentType}` : `subagent ${this.options.agentId}`;
+  }
+  /** The session traces group under. Set from the path, or from `session_meta`. */
+  grouping;
   ensureTrace(ts) {
     if (!this.trace) {
       this.trace = this.seeded(["trace", this.options.passKey ?? "0"], () => this.client.trace({
-        name: this.title ?? `${this.options.vendor} session`,
-        sessionId: this.options.sessionId,
+        // A subagent's transcript has no title of its own, and "claude-code session"
+        // beside its parent reads as a second session rather than part of one.
+        name: this.title ?? this.defaultTraceName(),
+        sessionId: this.grouping ?? this.options.sessionId,
         startTime: ts,
-        tags: [this.options.vendor],
-        metadata: this.meta,
+        tags: [this.options.vendor, ...this.options.agentId ? ["subagent"] : []],
+        metadata: {
+          ...this.meta,
+          ...this.options.agentId !== void 0 ? { agentId: this.options.agentId } : {},
+          ...this.options.agentType !== void 0 ? { agentType: this.options.agentType } : {}
+        },
         ...this.options.userId !== void 0 ? { userId: this.options.userId } : {},
         ...this.options.userEmail !== void 0 ? { userEmail: this.options.userEmail } : {},
         ...this.options.environment !== void 0 ? { environment: this.options.environment } : {}
@@ -21585,7 +21605,8 @@ async function runForwarder(mapper, options = {}) {
       }
     }
     const drain = options.paths ? { paths: options.paths } : drainSpool(mapper, checkpoints);
-    const paths = options.paths ? drain.paths : [.../* @__PURE__ */ new Set([...drain.paths, ...liveTranscripts(loadBeat(config.scope))])];
+    const named = options.paths ? drain.paths : [.../* @__PURE__ */ new Set([...drain.paths, ...liveTranscripts(loadBeat(config.scope))])];
+    const paths = [...new Set(named.flatMap((path) => [path, ...related(mapper, path)]))];
     if (paths.length === 0) {
       if (drain.checkpoint)
         checkpoints[SPOOL_KEY] = drain.checkpoint;
@@ -21620,10 +21641,15 @@ async function runForwarder(mapper, options = {}) {
         try {
           const from = resumeOffset(checkpoints, path);
           const carried = resumeTurn(checkpoints, path, from);
+          const own = mapper.sessionIdFor(path);
+          const sub = subagentOf(mapper, path);
           const emitter = new SessionEmitter(client, {
-            sessionId: mapper.sessionIdFor(path),
+            sessionId: sub?.sessionId ?? own,
+            seedKey: own,
             vendor: mapper.vendor,
             passKey: String(from),
+            ...sub?.agentId !== void 0 ? { agentId: sub.agentId } : {},
+            ...sub?.agentType !== void 0 ? { agentType: sub.agentType } : {},
             ...ids !== void 0 ? { ids } : {},
             ...userId !== void 0 ? { userId } : {},
             ...carried !== void 0 ? { resumeTurn: carried } : {}
@@ -21694,6 +21720,20 @@ async function runForwarder(mapper, options = {}) {
     release();
   }
 }
+function related(mapper, path) {
+  try {
+    return mapper.relatedTranscripts?.(path) ?? [];
+  } catch {
+    return [];
+  }
+}
+function subagentOf(mapper, path) {
+  try {
+    return mapper.subagentOf?.(path);
+  } catch {
+    return void 0;
+  }
+}
 function discoverTranscripts(mapper) {
   const found = [];
   const walk = (dir) => {
@@ -21801,7 +21841,14 @@ var codexTranscript = {
           meta: {
             ...str(payload["cwd"]) !== void 0 ? { cwd: str(payload["cwd"]) } : {},
             ...str(payload["cli_version"]) !== void 0 ? { version: str(payload["cli_version"]) } : {},
-            ...str(payload["originator"]) !== void 0 ? { entrypoint: str(payload["originator"]) } : {}
+            ...str(payload["originator"]) !== void 0 ? { entrypoint: str(payload["originator"]) } : {},
+            // A Codex subagent is a rollout of its own, a peer of its parent in the
+            // same date directory — nothing in the path says whose it is. These three
+            // are the only link, and unlike Claude Code's layout they are the vendor's
+            // own documented session metadata rather than a guess.
+            ...str(payload["parent_thread_id"]) !== void 0 ? { parentSessionId: str(payload["parent_thread_id"]) } : {},
+            ...str(payload["agent_nickname"]) !== void 0 ? { agentType: str(payload["agent_nickname"]) } : {},
+            ...str(payload["agent_path"]) !== void 0 ? { agentPath: str(payload["agent_path"]) } : {}
           }
         }
       ];

package/dist/bin/status.mjs

@@ -2,6 +2,11 @@
 import { createRequire as __dhCreateRequire } from 'node:module';
 const require = __dhCreateRequire(import.meta.url);
 
+// adapters/codex/bin/status.mjs
+import { readFileSync as readFileSync7 } from "node:fs";
+import { dirname, join as join12 } from "node:path";
+import { fileURLToPath } from "node:url";
+
 // packages/core/dist/config/local.js
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { join as join3 } from "node:path";
@@ -1119,8 +1124,40 @@ var VALIDATORS = Object.freeze({
 var LIB_VERSION = package_default.version;
 
 // packages/core/dist/cli/status.js
-import { existsSync as existsSync2, readFileSync as readFileSync5, statSync as statSync3 } from "node:fs";
+import { existsSync as existsSync2, readFileSync as readFileSync5, readdirSync as readdirSync2, statSync as statSync3 } from "node:fs";
+import { join as join8 } from "node:path";
 var SESSION_HOOK_STALE_MS = 30 * 60 * 1e3;
+function countSubagents(mapper, checkpoints) {
+  if (!mapper?.subagentOf || !mapper.sessionRoots)
+    return void 0;
+  let found = 0;
+  let shipped = 0;
+  const walk = (dir) => {
+    let entries;
+    try {
+      entries = readdirSync2(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const full = join8(dir, entry.name);
+      if (entry.isDirectory()) {
+        walk(full);
+        continue;
+      }
+      if (!entry.name.endsWith(".jsonl"))
+        continue;
+      if (!mapper.subagentOf?.(full))
+        continue;
+      found++;
+      if (checkpoints[full])
+        shipped++;
+    }
+  };
+  for (const root of mapper.sessionRoots())
+    walk(root);
+  return { found, shipped };
+}
 function status(vendor, mapper) {
   const config = loadLocalConfig(vendor);
   const checkpoints = loadCheckpoints(config.scope);
@@ -1131,6 +1168,7 @@ function status(vendor, mapper) {
     const size = existsSync2(path) ? statSync3(path).size : 0;
     transcripts.push({ path, shipped: cp.offset, size, lag: Math.max(0, size - cp.offset) });
   }
+  const subagents = countSubagents(mapper, checkpoints);
   const lastPass = loadHealth(config.scope);
   const spool = spoolPath(vendor);
   let spoolEvents = 0;
@@ -1171,17 +1209,18 @@ function status(vendor, mapper) {
     transcripts,
     totalLag: transcripts.reduce((sum, t) => sum + t.lag, 0),
     ...lastPass !== void 0 ? { lastPass } : {},
+    ...subagents !== void 0 ? { subagents } : {},
     lockHeld: existsSync2(spool.replace(/spool\/.*$/, `${config.scope}.forwarder.lock`))
   };
 }
 
 // packages/core/dist/cli/enroll.js
 import { homedir as homedir3 } from "node:os";
-import { join as join8 } from "node:path";
-var CLI_CREDENTIALS_PATH = join8(homedir3(), ".darkhunt", "credentials.json");
+import { join as join9 } from "node:path";
+var CLI_CREDENTIALS_PATH = join9(homedir3(), ".darkhunt", "credentials.json");
 
 // adapters/codex/dist/transcript.js
-import { basename, join as join9 } from "node:path";
+import { basename, join as join10 } from "node:path";
 import { homedir as homedir4 } from "node:os";
 function str(value) {
   return typeof value === "string" ? value : void 0;
@@ -1220,7 +1259,7 @@ function textOf(content) {
 var codexTranscript = {
   vendor: "codex",
   sessionRoots() {
-    return [join9(homedir4(), ".codex", "sessions")];
+    return [join10(homedir4(), ".codex", "sessions")];
   },
   // No `resolveUserId` yet, so Codex traces fall back to the configured `userId`.
   // The identity exists but not as a plain field: `~/.codex/auth.json` holds
@@ -1257,7 +1296,14 @@ var codexTranscript = {
           meta: {
             ...str(payload["cwd"]) !== void 0 ? { cwd: str(payload["cwd"]) } : {},
             ...str(payload["cli_version"]) !== void 0 ? { version: str(payload["cli_version"]) } : {},
-            ...str(payload["originator"]) !== void 0 ? { entrypoint: str(payload["originator"]) } : {}
+            ...str(payload["originator"]) !== void 0 ? { entrypoint: str(payload["originator"]) } : {},
+            // A Codex subagent is a rollout of its own, a peer of its parent in the
+            // same date directory — nothing in the path says whose it is. These three
+            // are the only link, and unlike Claude Code's layout they are the vendor's
+            // own documented session metadata rather than a guess.
+            ...str(payload["parent_thread_id"]) !== void 0 ? { parentSessionId: str(payload["parent_thread_id"]) } : {},
+            ...str(payload["agent_nickname"]) !== void 0 ? { agentType: str(payload["agent_nickname"]) } : {},
+            ...str(payload["agent_path"]) !== void 0 ? { agentPath: str(payload["agent_path"]) } : {}
           }
         }
       ];
@@ -1321,12 +1367,12 @@ var codexTranscript = {
 // adapters/codex/bin/lib/launchers.mjs
 import { chmodSync, existsSync as existsSync3, mkdirSync as mkdirSync4, readFileSync as readFileSync6, writeFileSync as writeFileSync4 } from "node:fs";
 import { homedir as homedir5 } from "node:os";
-import { join as join10 } from "node:path";
+import { join as join11 } from "node:path";
 var LAUNCHERS = {
   "darkhunt-codex-spool": "spool.mjs",
   "darkhunt-codex-guard": "guard.mjs"
 };
-var BIN_DIR = join10(homedir5(), ".local", "bin");
+var BIN_DIR = join11(homedir5(), ".local", "bin");
 var script = (target) => `#!/bin/sh
 # Installed by darkhunt endpoint-plugins. Resolves the newest installed
 # plugin version at run time; do not hard-code a version here.
@@ -1338,7 +1384,7 @@ function launcherState(binDir = BIN_DIR, path = process.env["PATH"] ?? "") {
   const missing = [];
   const stale = [];
   for (const [name, target] of Object.entries(LAUNCHERS)) {
-    const file = join10(binDir, name);
+    const file = join11(binDir, name);
     if (!existsSync3(file)) {
       missing.push(name);
       continue;
@@ -1380,12 +1426,25 @@ try {
   const s = status("codex", codexTranscript);
   const n = (x) => x.toLocaleString();
   console.log(`darkhunt endpoint status \u2014 codex`);
+  const root = join12(dirname(fileURLToPath(import.meta.url)), "..", "..");
+  let installed = "unknown";
+  try {
+    installed = JSON.parse(readFileSync7(join12(root, "package.json"), "utf8")).version;
+  } catch {
+  }
+  console.log(`  plugin       ${installed}   ${root}`);
   console.log(`  profile      ${s.profile}  ->  ${s.baseUrl}`);
   console.log(`  tenant       ${s.tenantId}   workspace ${s.workspaceId}`);
   console.log(
     `  user         ${s.userId ?? "(none \u2014 traces are unattributed)"}` + (s.userIdSource === "none" ? "" : `  [from ${s.userIdSource}]`)
   );
   console.log(`  capture      ${s.capture ? "ON" : "OFF"}      enforce ${s.enforce}`);
+  if (s.subagents && s.subagents.found > 0) {
+    const { found, shipped } = s.subagents;
+    console.log(
+      `  subagents    ${shipped} of ${found} shipped` + (shipped < found ? `  \u2014 ${found - shipped} not captured; run backfill.mjs` : "")
+    );
+  }
   const launchers = launcherState();
   const launcherProblems = launcherWarnings(launchers);
   console.log(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@darkhunt-security/endpoint-codex",
-  "version": "0.9.2",
+  "version": "0.9.4",
   "type": "module",
   "description": "Darkhunt endpoint adapter for Codex CLI: hook codec, rollout transcript mapper, plugin manifest.",
   "bin": {