Capture native Codex exec context

.changeset/capture-codex-exec-context.md

@@ -0,0 +1,7 @@
+---
+"@donadiosolutions/lcm": patch
+---
+
+Capture bounded semantic context from Codex `functions.exec` and
+`functions.exec_command` PostToolUse events, and validate the installed Codex
+hook with structural and no-write functional connector checks.

bin/lcm.ts

@@ -2380,6 +2380,7 @@ export async function runCli(
 
       const installed = listConnectors(opts.global ? homedir() : process.cwd());
       console.log("\n  Connector health:\n");
+      let failures = 0;
       for (const agent of agents) {
         const agentConnectors = installed.filter((c: any) => c.agentId === (agent as any).id);
         if ((agentConnectors as any[]).length === 0) {
@@ -2389,8 +2390,40 @@ export async function runCli(
             console.log(`  ✓ ${(agent as any).name}: ${c.type} at ${c.path}`);
           }
         }
+
+        if ((agent as any).id !== "codex" || agentName === undefined) continue;
+
+        const {
+          inspectCodexPostToolHook,
+          resolveCodexHooksPath,
+        } = await import("../src/connectors/codex-hooks.js");
+        const { codexPostToolFunctionalCoverage } = await import("../src/hooks/post-tool-normalization.js");
+        const inspection = inspectCodexPostToolHook(
+          resolveCodexHooksPath(opts.global ? homedir() : process.cwd()),
+        );
+
+        if (inspection.state === "installed") {
+          console.log("  ✓ Codex: PostToolUse hook installed");
+          let functional = false;
+          try {
+            functional = codexPostToolFunctionalCoverage();
+          } catch {
+            functional = false;
+          }
+          if (functional) {
+            console.log("  ✓ Codex: native exec capture functional");
+          } else {
+            console.log("  ✗ Codex: native exec capture functional");
+            failures += 1;
+          }
+        } else {
+          console.log(`  ✗ Codex: PostToolUse hook ${inspection.state}`);
+          console.log("  Codex: native exec capture functional check skipped");
+          failures += 1;
+        }
       }
       console.log();
+      if (failures > 0) exit(1);
     });
 
   program.addCommand(connectorsCmd);

codecov.yml

@@ -39,6 +39,7 @@ component_management:
     - component_id: "unit-hooks"
       name: "Unit - Hooks"
       paths:
+        # Includes native hook adapters under the existing hooks directory ownership.
         - "src/hooks/"
     - component_id: "unit-daemon-core"
       name: "Unit - Daemon Core"

docs/hook-protocol.md

@@ -162,6 +162,78 @@ The `daemon_port` payload field is ignored. PostToolUse never sends the daemon
 bearer token or captured event data to a payload-selected listener; queued
 events are collected by the daemon's bounded background processing instead.
 
+### Codex native PostToolUse capture
+
+The Codex connector uses the following exact hook entry in the canonical
+`~/.codex/hooks.json` file (or the equivalent path selected by the existing
+connector install scope):
+
+```json
+{
+  "PostToolUse": [
+    {
+      "matcher": "*",
+      "hooks": [
+        {
+          "type": "command",
+          "command": "lcm post-tool --client codex"
+        }
+      ]
+    }
+  ]
+}
+```
+
+The `matcher`, hook `type`, and command are structural contract values. The
+installed connector may also retain its timeout and status-message metadata,
+but the command must remain exactly `lcm post-tool --client codex`; extra
+arguments do not satisfy the contract. Install it with:
+
+```bash
+lcm connectors install codex
+lcm connectors doctor codex
+```
+
+The `--global` option selects the existing global connector scope; no new
+configuration option is required for native command capture, and the 2,000-
+character adapter bound is fixed rather than configurable.
+
+Codex sends native tool names `functions.exec` and `functions.exec_command`.
+For those names, lcm accepts only the bounded semantic command (`command`, or
+`cmd` when `command` is absent) and a direct status projection. `tool_output` is
+checked before `tool_response`; status fields are considered in this order:
+`isError`, `is_error`, `exit_code`, and `exitCode`. Boolean values are used
+directly, while finite numeric exit codes map zero to success and nonzero to an
+error. A valid false or zero value is authoritative. Nested or invalid values
+are ignored.
+
+The adapter does not persist raw Codex responses, stdout, stderr, or unknown
+fields, and it does not infer file events from shell text or unrecognized
+file-like fields. The existing event truncation and scrubbing pipeline still
+runs on derived event data. Commands whose trimmed text begins with `lcm
+store` are suppressed to prevent LCM's own writes from feeding back into
+passive learning.
+
+`lcm connectors doctor codex` performs two checks for the targeted Codex
+connector. It first verifies the exact structural hook contract above. Only
+when that check passes does it run the native-exec functional probe. The probe
+is pure and in-memory: it exercises normalization and extraction without
+invoking the PostToolUse handler, opening an EventsDb, appending sidecar
+events, writing hook files, or creating a database. A structurally absent or
+incomplete hook never reports functional success; its functional result is
+reported as:
+
+```text
+Codex: native exec capture functional check skipped
+```
+
+When the exact structure and the pure probe both pass, doctor reports:
+
+```text
+✓ Codex: PostToolUse hook installed
+✓ Codex: native exec capture functional
+```
+
 ## SessionSnapshot Hook
 
 **Command:** `lcm session-snapshot`

docs/passive-learning.md

@@ -8,7 +8,7 @@ Passive learning captures insights from your Claude Code sessions automatically
 
 Two hooks capture events during your session:
 
-- **PostToolUse** — fires after every tool call. Extracts structured metadata (tool name, command, file path) from tool inputs. Never captures raw tool output.
+- **PostToolUse** — fires after every tool call. Extracts structured metadata (tool name, command, file path) from tool inputs. Never captures raw tool output. For Codex, the native `functions.exec` and `functions.exec_command` calls are adapted into the existing Bash event semantics.
 - **UserPromptSubmit** — fires on each user prompt. Detects decisions ("always use X"), role statements ("I'm a data scientist"), and intent patterns.
 
 Events are written to a **sidecar SQLite database**
@@ -34,6 +34,36 @@ new global sequences during their transactional schema upgrade.
 
 ### What Gets Captured
 
+#### Codex native command capture
+
+The Codex connector recognizes only PostToolUse payloads marked with
+`client: "codex"` whose `tool_name` is exactly `functions.exec` or
+`functions.exec_command`. The adapter accepts the string `tool_input.command`
+first, or the string `tool_input.cmd` when `command` is not a string. Other
+command-like, path-like, and file-like fields are ignored; a blank `command`
+does not fall back to `cmd`.
+
+The adapter passes only bounded semantic information into the existing Bash
+extractor:
+
+- A command is limited to 2,000 characters at the adapter boundary; longer
+  commands are clipped with `...` before event classification.
+- The existing event-data truncation and event scrubbing still run after
+  classification, including the normal sensitive-path redaction rules.
+- Status is read only from direct, top-level fields. `tool_output` wins over
+  `tool_response` when it contains a valid status. Within either object, the
+  precedence is `isError`, `is_error`, `exit_code`, then `exitCode`; boolean
+  values are used directly and finite numeric exit codes treat zero as
+  success and any other value as an error. Invalid, nested, string, `NaN`, and
+  infinite values are ignored.
+- The raw Codex response, stdout, stderr, and unknown output fields are never
+  copied into the normalized event. Shell text is not parsed into file events.
+- A command whose trimmed text begins with `lcm store` is suppressed so LCM's
+  own storage activity cannot create a passive-learning feedback loop.
+
+Only events recognized by the existing Bash extractor are queued. The command
+itself is not stored as a transcript.
+
 | Category | Examples | Priority |
 |----------|----------|----------|
 | Decisions | User answers to AskUserQuestion, "always use TypeScript" | 1 (immediate) |
@@ -47,7 +77,9 @@ new global sequences during their transactional schema upgrade.
 
 ### What Is NOT Captured
 
-- Raw tool payload contents such as file contents and command stdout/stderr (only tool metadata and brief user answers are stored)
+- Raw tool payload contents such as file contents, command stdout/stderr, and
+  unknown Codex response fields (only bounded semantic metadata and brief user
+  answers are stored)
 - Sensitive file paths (`.env`, `.ssh/`, `credentials`, `.npmrc`)
 - LCM's own `lcm_store` calls (prevents feedback loops)
 

docs/superpowers/plans/2026-08-11-codex-post-tool-capture.md

@@ -13,8 +13,8 @@
 - Start only after the CLI PR for #602/#603 merges. Fetch updated `origin/main`, create a fresh isolated worker workspace at `UPDATED_MAIN=$(git rev-parse --verify 'origin/main^{commit}')`, require `test "$(git rev-parse HEAD)" = "$UPDATED_MAIN"`, persist it with `git update-ref refs/lcm/implementation-bases/issue-604-codex-post-tool "$UPDATED_MAIN"`, and create branch `fix/604-codex-post-tool-capture` from that durable ref; never use a `codex/` prefix.
 - Do not use, clean, stage, or modify the coordinator worktree or pre-existing files outside this branch.
 - Add no dependency and preserve exact pins and lockfile integrity.
-- Recognize only `client: "codex"` payloads with `functions.exec` or `functions.exec_command` names and explicit bounded command fields.
-- Never serialize raw `tool_input`, `tool_response`, stdout, stderr, or unknown output into an event.
+- Recognize only `client: "codex"` payloads with `functions.exec` or `functions.exec_command` names and explicit bounded command fields. Copy at most 2,000 command characters plus a literal `...` truncation marker into the canonical in-memory shape; no raw command object survives normalization.
+- Never serialize raw `tool_input`, `tool_response`, stdout, stderr, or unknown output into an event. The bounded command is used only by the allowlisted semantic extractor, and extracted event data passes through the existing built-in and project-aware scrubber before enqueue.
 - Preserve feedback-loop exclusions, built-in/project scrubbing, truncation, and append-before-project-metadata ordering.
 - Functional doctor is pure/no-write and must not touch the user's event database.
 - The existing `unit-hooks` directory path already exclusively owns the new production file. Update `codecov.yml` atomically with the count test by documenting that the directory path owns native hook adapters, but do not add a redundant exact-file path; update the literal expected production-file count in `test/codecov-config.test.ts`.
@@ -57,7 +57,7 @@ Create table-driven tests for:
 
 Normalize each fixture, pass it to `extractPostToolEvents`, and assert the existing event type/category/priority. Add negative fixtures for non-Codex clients, unknown `functions.*` names, non-string `cmd`/`command`, lcm-store feedback-loop names, and response objects containing a sentinel secret. Assert the secret never appears in normalized input or event data.
 
-Add status fixtures with this exact policy: inspect only top-level status fields in record-valued `tool_output` and `tool_response`; prefer `tool_output` over `tool_response`; within one record prefer boolean `isError`, then boolean `is_error`, then finite numeric `exit_code`, then finite numeric `exitCode`. A boolean maps directly, numeric zero maps to false, and every other finite number maps to true. Strings, nested objects, `NaN`, and infinities are ignored. An explicit higher-precedence false overrides a lower-precedence nonzero code. If no recognized field exists, omit canonical `tool_output`. Add conflict fixtures proving every precedence rule.
+Add status fixtures with this exact policy: inspect only top-level status fields in record-valued `tool_output` and `tool_response`, consulting `tool_output` first. Within one record, select the first valid field in this precedence order: boolean `isError`, boolean `is_error`, finite numeric `exit_code`, finite numeric `exitCode`. A boolean maps directly, numeric zero maps to false, and every other finite number maps to true. A valid false/zero wins. Strings, nested objects, `NaN`, and infinities are invalid and ignored. Fall back to `tool_response` only when `tool_output` contains no valid recognized field. If neither source contains one, omit canonical `tool_output`. Add conflict and invalid-field fixtures proving every source and field precedence rule.
 
 No captured structured Codex file-operation shape is available in #604. Add negative fixtures proving nested/unknown `operation`, `path`, and file-like fields cannot produce file events, and shell text such as `cat`, `sed`, `rm`, or redirects is never parsed into file events. Do not invent a structured mapping without a real captured payload.
 
@@ -93,23 +93,29 @@ export function normalizePostToolInput(input: RawPostToolInput): PostToolInput {
 }
 ```
 
-Keep command selection deterministic: prefer `command` when it is a string,
-otherwise `cmd`; trim only to decide whether a command is empty. An empty or
-missing command produces an inert canonical input and no event regardless of
-status, while the original non-empty command string is retained for existing
-bounded extractor semantics.
+Keep command selection deterministic: when `command` is a string it wins even
+when blank; only if it is not a string may a string `cmd` be selected. Trim only
+to decide whether the selected command is empty and to apply the native
+feedback-loop matcher; do not fall back from a blank string `command` to `cmd`.
+An empty or missing selected command produces an inert canonical input and no
+event regardless of status. Bound a non-empty selected command before extraction
+to its first 2,000 UTF-16 code units plus `...` when truncated. This mirrors the
+existing event-data soft cap while preventing an unbounded raw command from
+entering the extractor. Extracted data is then scrubbed by the existing
+project-aware event scrubber before any durable write.
 
 Implement functional coverage from fixed benign fixtures:
 
 ```ts
 export function codexPostToolFunctionalCoverage(): boolean {
-  return [
-    { tool_name: "functions.exec", tool_input: { command: "git branch" } },
-    { tool_name: "functions.exec_command", tool_input: { cmd: "npm install probe" } },
-  ].every(fixture => extractPostToolEvents(normalizePostToolInput({
-    client: "codex",
-    ...fixture,
-  })).length === 1);
+  const fixtures = [
+    { tool_name: "functions.exec", tool_input: { command: "git branch" }, expected: "git_branch" },
+    { tool_name: "functions.exec_command", tool_input: { cmd: "npm install probe" }, expected: "env_install" },
+  ];
+  return fixtures.every(({ expected, ...fixture }) => {
+    const events = extractPostToolEvents(normalizePostToolInput({ client: "codex", ...fixture }));
+    return events.length === 1 && events[0]?.type === expected;
+  });
 }
 ```
 
@@ -223,7 +229,7 @@ For targeted installed Codex connector doctor, require output that distinguishes
 ✓ Codex: native exec capture functional
 ```
 
-Targeted doctor must inspect the canonical `~/.codex/hooks.json` path using the same default/`--global` resolution as installation even when broad discovery finds only a partial installation. Preserve existing connector path output, then print structural and functional lines. Distinguish absent, incomplete, and installed-but-nonfunctional states; never print functional success when structure is absent/incomplete. Mock functional failure and assert actionable output plus exit 1.
+Targeted doctor must inspect the canonical `~/.codex/hooks.json` path using the same default/`--global` resolution as installation even when broad discovery finds only a partial installation. Preserve existing connector path output, then print structural and functional lines. Distinguish absent, incomplete, and installed-but-nonfunctional states; never print functional success when structure is absent/incomplete. Print `Codex: native exec capture functional check skipped` when structure is absent or incomplete. Mock functional failure and assert actionable output plus exit 1.
 
 Make the pure probe mockable before module import through an injected dependency or module mock. Assert doctor does not call `appendLocalHookEvents`, instantiate `EventsDb`, write hook files, or create an event database.
 
@@ -239,7 +245,7 @@ Expected: existing broad `hasCodexHooks` accepts partial hook files and doctor o
 
 - [ ] **Step 4: Implement exact structural inspection and no-write probe**
 
-Keep broad connector discovery compatibility unchanged. Targeted health calls the exact structural inspector and only then the in-memory functional probe. Aggregate failures and call `exit(1)` only after printing all requested agent results. Non-Codex connector behavior remains unchanged.
+Keep broad connector discovery compatibility and its existing output unchanged. Targeted health calls the exact structural inspector and only then the in-memory functional probe. Aggregate failures and call `exit(1)` only after printing all requested agent results. The probe imports only the pure normalizer/extractor path: it must not import or call `handlePostToolUse`, `appendLocalHookEvents`, `EventsDb`, or filesystem setup. Non-Codex connector behavior remains unchanged.
 
 - [ ] **Step 5: Run GREEN**