cclaw-cli 0.48.2 → 0.48.4

package/README.md

@@ -97,8 +97,10 @@ scripted installs:
 npx cclaw-cli init --harnesses=claude,cursor --no-interactive
 ```
 
-That's the entire CLI interaction. Everything after install happens
-inside your harness (Claude Code, Cursor, OpenCode, or Codex).
+That's the entire required CLI interaction for the normal workflow.
+Everything day-to-day happens inside your harness (Claude Code, Cursor,
+OpenCode, or Codex); optional maintenance commands are listed in the
+CLI reference.
 
 ### What gets generated
 
@@ -140,9 +142,12 @@ Plus harness-specific shims:
 `cclaw init` writes five keys, on purpose:
 
 ```yaml
-version: 0.46.0
+version: ${CCLAW_VERSION}
 flowVersion: 1.0.0
 harnesses:
+  - claude
+  - cursor
+  - opencode
   - codex
 strictness: advisory     # advisory | strict — one knob for prompt-guard + TDD
 gitHookGuards: false     # opt in to managed .git/hooks/pre-commit + pre-push
@@ -471,7 +476,9 @@ your harness.
 ```bash
 npx cclaw-cli                   # launches interactive setup (or prints
                                 # a one-line status hint if already installed)
+npx cclaw-cli sync              # re-materialize generated runtime from config.yaml
 npx cclaw-cli upgrade           # refresh generated files; preserves .cclaw/config.yaml
+npx cclaw-cli archive           # archive current run and reset flow-state
 npx cclaw-cli uninstall         # remove .cclaw + generated harness shims
 npx cclaw-cli eval …            # maintainer surface (see docs/evals.md)
 npx cclaw-cli --version

package/dist/cli.js

@@ -48,7 +48,12 @@ Commands:
   init       Bootstrap .cclaw runtime, state, and harness shims in this project.
              Flags: --harnesses=<list>  Comma list of harnesses (claude,cursor,opencode,codex).
                     --no-interactive    Skip interactive prompts even on TTY (for CI/scripts).
+  sync       Reconcile generated runtime files with the current config.
   upgrade    Refresh generated files in .cclaw. Preserves your config.yaml.
+  archive    Archive the active run and reset flow state for next feature.
+             Flags: --name=<slug>        Override archive folder suffix.
+                    --skip-retro         Skip retro gate only when runtime allows it.
+                    --retro-reason=<txt> Required rationale with --skip-retro.
   uninstall  Remove .cclaw runtime and the generated harness shim files.
   eval       Run cclaw evals. Maintainer surface — see docs/evals.md.
              Full flag reference: \`npx cclaw-cli eval --help\` or docs/evals.md.
@@ -60,6 +65,8 @@ Global flags:
 Examples:
   npx cclaw-cli
   npx cclaw-cli init --harnesses=claude,cursor --no-interactive
+  npx cclaw-cli sync
+  npx cclaw-cli archive --name=my-feature
   npx cclaw-cli upgrade
   npx cclaw-cli eval --dry-run
 
@@ -1018,7 +1025,7 @@ async function runCommand(parsed, ctx) {
         info(ctx, `Archived active artifacts to ${archived.archivePath}. Flow state reset to brainstorm.${snapshotSummary}`);
         const k = archived.knowledge;
         if (k.overThreshold) {
-            info(ctx, `Knowledge curation recommended: ${k.knowledgePath} now has ${k.activeEntryCount} active entries (soft threshold ${k.softThreshold}). Run \`/cc-learn curate\` to plan a soft-archive of stale/duplicate entries to ${RUNTIME_ROOT}/knowledge.archive.md.`);
+            info(ctx, `Knowledge curation recommended: ${k.knowledgePath} now has ${k.activeEntryCount} active entries (soft threshold ${k.softThreshold}). Run \`/cc-learn curate\` to plan a soft-archive of stale/duplicate entries to ${RUNTIME_ROOT}/knowledge.archive.jsonl.`);
         }
         else if (k.activeEntryCount > 0) {
             info(ctx, `Knowledge: ${k.activeEntryCount}/${k.softThreshold} active entries. Run \`/cc-learn curate\` if you want a sweep before the next run.`);

package/dist/config.d.ts

@@ -1,4 +1,7 @@
 import type { CclawConfig, FlowTrack, HarnessId, LanguageRulePack } from "./types.js";
+export declare class InvalidConfigError extends Error {
+    constructor(message: string);
+}
 export declare function configPath(projectRoot: string): string;
 /**
  * Default test-path patterns used by workflow-guard.sh to classify TDD writes.

package/dist/config.js

@@ -65,8 +65,14 @@ function configFixExample() {
   - claude
   - cursor`;
 }
+export class InvalidConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "InvalidConfigError";
+    }
+}
 function configValidationError(configFilePath, reason) {
-    return new Error(`Invalid cclaw config at ${configFilePath}: ${reason}\n` +
+    return new InvalidConfigError(`Invalid cclaw config at ${configFilePath}: ${reason}\n` +
         `Supported harnesses: ${SUPPORTED_HARNESSES_TEXT}\n` +
         `Supported tracks: ${SUPPORTED_TRACKS_TEXT}\n` +
         `Supported languageRulePacks: ${SUPPORTED_LANGUAGE_RULE_PACKS_TEXT}\n` +
@@ -186,8 +192,12 @@ export async function readConfig(projectRoot) {
     try {
         parsedUnknown = parse(await fs.readFile(fullPath, "utf8"));
     }
-    catch {
-        return createDefaultConfig();
+    catch (error) {
+        const reason = error instanceof Error ? error.message : "unknown parse error";
+        throw configValidationError(fullPath, `failed to parse YAML (${reason})`);
+    }
+    if (parsedUnknown !== null && parsedUnknown !== undefined && typeof parsedUnknown !== "object") {
+        throw configValidationError(fullPath, "top-level config must be a YAML mapping/object");
     }
     const parsed = (parsedUnknown && typeof parsedUnknown === "object"
         ? parsedUnknown

package/dist/content/contracts.d.ts

@@ -1,2 +1,2 @@
-import type { FlowStage } from "../types.js";
-export declare function stageCommandContract(stage: FlowStage): string;
+import type { FlowStage, FlowTrack } from "../types.js";
+export declare function stageCommandContract(stage: FlowStage, track?: FlowTrack): string;

package/dist/content/contracts.js

@@ -1,7 +1,7 @@
 import { stageSchema } from "./stage-schema.js";
 import { stageSkillFolder } from "./skills.js";
-export function stageCommandContract(stage) {
-    const schema = stageSchema(stage);
+export function stageCommandContract(stage, track = "standard") {
+    const schema = stageSchema(stage, track);
     const skillPath = `.cclaw/skills/${stageSkillFolder(stage)}/SKILL.md`;
     const reads = schema.crossStageTrace.readsFrom;
     const readsLine = reads.length > 0 ? reads.join(", ") : "(first stage)";

package/dist/content/core-agents.d.ts

@@ -65,7 +65,7 @@ export declare const CCLAW_AGENTS: readonly [{
     readonly body: string;
 }, {
     readonly name: "doc-updater";
-    readonly description: "MANDATORY at ship and PROACTIVE when behavior/config/public API changes. Keep docs and runbooks in lockstep with shipped behavior.";
+    readonly description: "MANDATORY only at ship; PROACTIVE during tdd/review whenever behavior, config, or public API changes. Keep docs and runbooks in lockstep with shipped behavior.";
     readonly tools: ["Read", "Write", "Edit", "Grep", "Glob"];
     readonly model: "fast";
     readonly activation: "mandatory";

package/dist/content/core-agents.js

@@ -118,7 +118,7 @@ export const CCLAW_AGENTS = [
     },
     {
         name: "doc-updater",
-        description: "MANDATORY at ship and PROACTIVE when behavior/config/public API changes. Keep docs and runbooks in lockstep with shipped behavior.",
+        description: "MANDATORY only at ship; PROACTIVE during tdd/review whenever behavior, config, or public API changes. Keep docs and runbooks in lockstep with shipped behavior.",
         tools: ["Read", "Write", "Edit", "Grep", "Glob"],
         model: "fast",
         activation: "mandatory",

package/dist/content/hooks.js

@@ -845,7 +845,8 @@ if command -v cclaw >/dev/null 2>&1; then
   exec cclaw internal advance-stage "$STAGE" "$@"
 fi
 
-exec npx -y cclaw-cli internal advance-stage "$STAGE" "$@"
+printf '[cclaw] stage-complete: cclaw binary not found in PATH. Install cclaw CLI and rerun stage completion.\\n' >&2
+exit 1
 `;
 }
 export function preCompactScript() {
@@ -889,8 +890,8 @@ if [ -f "$STATE_FILE" ]; then
     COMPLETED=$(jq -r '(.completedStages // []) | length' "$STATE_FILE" 2>/dev/null || echo "0")
     SKIPPED=$(jq -r '(.skippedStages // []) | join(",")' "$STATE_FILE" 2>/dev/null || echo "")
     ACTIVE_RUN=$(jq -r '.activeRunId // "none"' "$STATE_FILE" 2>/dev/null || echo "none")
-    PASSED_GATES=$(jq -r --arg stage "$STAGE" '(.stageGates[$stage].passed // []) | join(",")' "$STATE_FILE" 2>/dev/null || echo "")
-    BLOCKED_GATES=$(jq -r --arg stage "$STAGE" '(.stageGates[$stage].blocked // []) | join(",")' "$STATE_FILE" 2>/dev/null || echo "")
+    PASSED_GATES=$(jq -r --arg stage "$STAGE" '(.stageGateCatalog[$stage].passed // []) | join(",")' "$STATE_FILE" 2>/dev/null || echo "")
+    BLOCKED_GATES=$(jq -r --arg stage "$STAGE" '(.stageGateCatalog[$stage].blocked // []) | join(",")' "$STATE_FILE" 2>/dev/null || echo "")
   elif command -v python3 >/dev/null 2>&1; then
     OUTPUT=$(python3 - "$STATE_FILE" <<'PY'
 import json, sys
@@ -904,7 +905,7 @@ track = data.get("track") or "standard"
 completed = data.get("completedStages") or []
 skipped = data.get("skippedStages") or []
 run = data.get("activeRunId") or "none"
-gates = (data.get("stageGates") or {}).get(stage) or {}
+gates = (data.get("stageGateCatalog") or {}).get(stage) or {}
 passed = gates.get("passed") or []
 blocked = gates.get("blocked") or []
 print(stage)
@@ -965,20 +966,20 @@ TS=$(date -u +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null || echo "")
   printf '# Session Digest\n'
   printf '_Generated by pre-compact hook at %s_\n\n' "$TS"
   printf '## Flow snapshot\n'
-  printf '- track: %s\n' "$TRACK"
-  printf '- current stage: %s\n' "$STAGE"
-  printf '- completed: %s stages\n' "$COMPLETED"
-  printf '- skipped: %s\n' "\${SKIPPED:-(none)}"
-  printf '- run: %s\n\n' "$ACTIVE_RUN"
+  printf -- '- track: %s\n' "$TRACK"
+  printf -- '- current stage: %s\n' "$STAGE"
+  printf -- '- completed: %s stages\n' "$COMPLETED"
+  printf -- '- skipped: %s\n' "\${SKIPPED:-(none)}"
+  printf -- '- run: %s\n\n' "$ACTIVE_RUN"
   printf '## Gates (current stage)\n'
-  printf '- passed: %s\n' "\${PASSED_GATES:-(none)}"
-  printf '- blocked: %s\n\n' "\${BLOCKED_GATES:-(none)}"
+  printf -- '- passed: %s\n' "\${PASSED_GATES:-(none)}"
+  printf -- '- blocked: %s\n\n' "\${BLOCKED_GATES:-(none)}"
   printf '## Outstanding delegations\n'
-  printf '- pending: %s\n\n' "\${DELEGATION_PENDING:-(none)}"
+  printf -- '- pending: %s\n\n' "\${DELEGATION_PENDING:-(none)}"
   printf '## Git\n'
-  printf '- branch: %s\n' "\${GIT_BRANCH:-(unknown)}"
-  printf '- head: %s\n' "\${GIT_HEAD:-(unknown)}"
-  printf '- worktree: %s\n\n' "$GIT_DIRTY"
+  printf -- '- branch: %s\n' "\${GIT_BRANCH:-(unknown)}"
+  printf -- '- head: %s\n' "\${GIT_HEAD:-(unknown)}"
+  printf -- '- worktree: %s\n\n' "$GIT_DIRTY"
   if [ -n "$KNOWLEDGE_TAIL" ]; then
     printf '## Knowledge tail\n'
     printf '%s\n' "$KNOWLEDGE_TAIL"

package/dist/content/next-command.js

@@ -50,8 +50,9 @@ This is the only progression command the user needs to drive the entire flow. St
 7. **Satisfied** for gate id \`g\`: \`g\` in \`catalog.passed\` and \`g\` not in \`catalog.blocked\`.
 8. Let \`M\` = \`mandatoryDelegations\` for \`currentStage\`.
 9. If \`M\` is non-empty, inspect **\`${delegationPath}\`**. Treat as satisfied only if each mandatory agent is **completed** or **waived**.
-10. If any mandatory delegation is missing and no waiver exists: **STOP** and ask the user whether to dispatch now or waive with rationale. Do not mark gates passed while delegation is unresolved.
-11. If \`currentStage === "review"\` and \`catalog.blocked\` includes \`review_criticals_resolved\`, treat this as a hard remediation branch: recommend \`/cc-ops rewind tdd "review_blocked_by_critical"\` with the blocking finding IDs, and do not attempt to advance toward ship.
+10. For each satisfied mandatory delegation row, verify \`evidenceRefs\` is a non-empty array (unless status is \`waived\` with rationale). Missing evidenceRefs means delegation is unresolved.
+11. If any mandatory delegation is missing and no waiver exists: **STOP** and ask the user whether to dispatch now or waive with rationale. Do not mark gates passed while delegation is unresolved.
+12. If \`currentStage === "review"\` and \`catalog.blocked\` includes \`review_criticals_resolved\`, treat this as a hard remediation branch: recommend \`/cc-ops rewind tdd "review_blocked_by_critical"\` with the blocking finding IDs, and do not attempt to advance toward ship.
 
 ### Path A: Current stage is NOT complete (any gate unmet or delegation missing)
 
@@ -161,6 +162,7 @@ For each gate id in \`requiredGates\` for \`currentStage\`:
 - **Unmet** otherwise.
 
 Check \`mandatoryDelegations\` via **\`${delegationPath}\`** — satisfied only if **completed** or **waived**.
+Also verify each completed mandatory delegation row has non-empty \`evidenceRefs\` (waived rows must include rationale).
 If a mandatory delegation is missing and no waiver exists, **STOP** and ask:
 (A) dispatch now, (B) waive with rationale, (C) cancel stage advance.
 

package/dist/content/observe.d.ts

@@ -25,8 +25,8 @@ export declare function cursorHooksJsonWithObservation(): string;
  * - `SessionStart` matcher is limited to `startup|resume` — Codex does
  *   not emit `clear` or `compact` lifecycle phases.
  * - `PreToolUse` / `PostToolUse` fire **only for the `Bash` tool**
- *   (documented Codex limitation, v0.114/v0.115). We use the `Bash`
- *   matcher verbatim so Codex doesn't silently swallow our commands.
+ *   (documented Codex limitation, v0.114/v0.115). We match both `Bash`
+ *   and `bash` variants to tolerate casing drift across Codex builds.
  * - `UserPromptSubmit` is supported and is the closest analogue to
  *   Cursor's `preToolUse` for non-Bash tooling — we run prompt-guard
  *   there so workflow/prompt checks still fire when the tool being

package/dist/content/observe.js

@@ -13,6 +13,7 @@ export function promptGuardScript(options = {}) {
 # cclaw prompt guard hook — generated by cclaw sync
 # Advisory-only guard for risky writes into ${RUNTIME_ROOT} runtime files.
 set -uo pipefail
+shopt -s globstar 2>/dev/null || true
 PROMPT_GUARD_MODE="${promptGuardMode}"
 
 HARNESS="codex"
@@ -166,6 +167,7 @@ export function workflowGuardScript(options = {}) {
 # cclaw workflow guard hook — generated by cclaw sync
 # Enforces stage-aware command discipline and recent flow-state read hygiene.
 set -uo pipefail
+shopt -s globstar 2>/dev/null || true
 WORKFLOW_GUARD_MODE="\${CCLAW_WORKFLOW_GUARD_MODE:-${workflowGuardMode}}"
 MAX_FLOW_READ_AGE_SEC="\${CCLAW_WORKFLOW_GUARD_MAX_AGE_SEC:-1800}"
 TDD_ENFORCEMENT_MODE="${tddEnforcementMode}"
@@ -408,10 +410,12 @@ verify_flow_state_candidate() {
     return 1
   }
 
-  local verify_cmd=(npx -y cclaw-cli internal verify-flow-state-diff --after-file="$tmp_file" --quiet)
-  if command -v cclaw >/dev/null 2>&1; then
-    verify_cmd=(cclaw internal verify-flow-state-diff --after-file="$tmp_file" --quiet)
+  if ! command -v cclaw >/dev/null 2>&1; then
+    rm -f "$tmp_file" 2>/dev/null || true
+    printf '[cclaw] workflow guard: cclaw binary is required to validate flow-state edits; install cclaw and re-run.\\n' >&2
+    return 1
   fi
+  local verify_cmd=(cclaw internal verify-flow-state-diff --after-file="$tmp_file" --quiet)
 
   if "\${verify_cmd[@]}" >/dev/null 2>&1; then
     rm -f "$tmp_file" 2>/dev/null || true
@@ -579,10 +583,13 @@ tdd_cycle_counts() {
   fi
   local red_count="0"
   local green_count="0"
-  if command -v jq >/dev/null 2>&1; then
+  if command -v jq >/dev/null 2>&1 && jq -n '1' >/dev/null 2>&1; then
     red_count=$(jq -r --arg run "$CURRENT_RUN" 'select((.runId // $run) == $run and .phase == "red") | .phase' "$TDD_LOG_FILE" 2>/dev/null | wc -l | tr -d ' ' || echo "0")
     green_count=$(jq -r --arg run "$CURRENT_RUN" 'select((.runId // $run) == $run and .phase == "green") | .phase' "$TDD_LOG_FILE" 2>/dev/null | wc -l | tr -d ' ' || echo "0")
-  elif command -v python3 >/dev/null 2>&1; then
+  elif command -v python3 >/dev/null 2>&1 && python3 - <<'PY' >/dev/null 2>&1
+print("ok")
+PY
+  then
     red_count=$(python3 - "$TDD_LOG_FILE" "$CURRENT_RUN" <<'PY'
 import json
 import sys
@@ -630,8 +637,36 @@ print(count)
 PY
 )
   else
-    red_count=$(grep -ci '"phase"[[:space:]]*:[[:space:]]*"red"' "$TDD_LOG_FILE" 2>/dev/null || echo "0")
-    green_count=$(grep -ci '"phase"[[:space:]]*:[[:space:]]*"green"' "$TDD_LOG_FILE" 2>/dev/null || echo "0")
+    if command -v awk >/dev/null 2>&1; then
+      local fallback_counts
+      fallback_counts=$(awk -v run="$CURRENT_RUN" '
+        BEGIN { red=0; green=0; }
+        {
+          line=$0;
+          line_run=run;
+          if (match(line, /"runId"[[:space:]]*:[[:space:]]*"[^"]+"/)) {
+            line_run=substr(line, RSTART, RLENGTH);
+            sub(/.*"/, "", line_run);
+            sub(/"$/, "", line_run);
+          }
+          if (line_run != run) next;
+          if (match(line, /"phase"[[:space:]]*:[[:space:]]*"[^"]+"/)) {
+            phase=substr(line, RSTART, RLENGTH);
+            sub(/.*"/, "", phase);
+            sub(/"$/, "", phase);
+            if (phase == "red") red += 1;
+            else if (phase == "green") green += 1;
+          }
+        }
+        END { printf "%d:%d", red, green; }
+      ' "$TDD_LOG_FILE" 2>/dev/null || true)
+      if printf '%s' "$fallback_counts" | grep -Eq '^[0-9]+:[0-9]+$'; then
+        printf '%s' "$fallback_counts"
+        return 0
+      fi
+    fi
+    printf '__UNAVAILABLE__'
+    return 0
   fi
   [ -n "$red_count" ] || red_count="0"
   [ -n "$green_count" ] || green_count="0"
@@ -641,8 +676,14 @@ PY
 has_open_red_cycle() {
   local counts
   counts=$(tdd_cycle_counts)
+  if [ "$counts" = "__UNAVAILABLE__" ]; then
+    return 2
+  fi
   local red_count="\${counts%%:*}"
   local green_count="\${counts##*:}"
+  if ! printf '%s' "$red_count:$green_count" | grep -Eq '^[0-9]+:[0-9]+$'; then
+    return 2
+  fi
   if [ "$red_count" -gt "$green_count" ]; then
     return 0
   fi
@@ -652,8 +693,16 @@ has_open_red_cycle() {
 tdd_cycle_state() {
   local counts
   counts=$(tdd_cycle_counts)
+  if [ "$counts" = "__UNAVAILABLE__" ]; then
+    printf '__UNAVAILABLE__'
+    return 0
+  fi
   local red_count="\${counts%%:*}"
   local green_count="\${counts##*:}"
+  if ! printf '%s' "$red_count:$green_count" | grep -Eq '^[0-9]+:[0-9]+$'; then
+    printf '__UNAVAILABLE__'
+    return 0
+  fi
   if [ "$red_count" -le 0 ]; then
     printf 'need_red'
     return 0
@@ -740,7 +789,17 @@ if [ "$CURRENT_STAGE" = "tdd" ] && is_mutating_tool "$TOOL_LOWER"; then
     if has_open_red_cycle; then
       TDD_CYCLE_STATE="red_open"
     else
-      TDD_CYCLE_STATE=$(tdd_cycle_state)
+      OPEN_RED_STATUS=$?
+      if [ "$OPEN_RED_STATUS" -eq 2 ]; then
+        TDD_CYCLE_STATE="counts_unavailable"
+        if [ -n "$REASONS" ]; then
+          REASONS="$REASONS,tdd_cycle_counts_unavailable"
+        else
+          REASONS="tdd_cycle_counts_unavailable"
+        fi
+      else
+        TDD_CYCLE_STATE=$(tdd_cycle_state)
+      fi
     fi
     if [ "$TDD_CYCLE_STATE" = "need_red" ]; then
       if [ -n "$REASONS" ]; then
@@ -748,6 +807,12 @@ if [ "$CURRENT_STAGE" = "tdd" ] && is_mutating_tool "$TOOL_LOWER"; then
       else
         REASONS="tdd_write_without_open_red"
       fi
+    elif [ "$TDD_CYCLE_STATE" = "__UNAVAILABLE__" ]; then
+      if [ -n "$REASONS" ]; then
+        REASONS="$REASONS,tdd_cycle_counts_unavailable"
+      else
+        REASONS="tdd_cycle_counts_unavailable"
+      fi
     fi
   fi
 fi
@@ -819,6 +884,8 @@ fi
 if [ -n "$REASONS" ]; then
   if printf '%s' "$REASONS" | grep -Eq 'tdd_write_without_open_red'; then
     NOTE="Cclaw workflow guard: Write a failing test first before editing production files during tdd stage (state=\${TDD_CYCLE_STATE})."
+  elif printf '%s' "$REASONS" | grep -Eq 'tdd_cycle_counts_unavailable'; then
+    NOTE="Cclaw workflow guard: unable to inspect run-scoped tdd-cycle counts (missing usable jq/python3/awk). Install one of these tools before writing production code in tdd."
   elif printf '%s' "$REASONS" | grep -Eq 'direct_flow_state_edit'; then
     NOTE="Cclaw workflow guard: direct flow-state edit bypasses the canonical stage-complete helper (\${REASONS}). Prefer: bash ${RUNTIME_ROOT}/hooks/stage-complete.sh <stage>. In strict mode this is blocked."
   else
@@ -846,6 +913,9 @@ if [ -n "$REASONS" ]; then
   if printf '%s' "$REASONS" | grep -Eq 'tdd_write_without_open_red' && [ "$TDD_ENFORCEMENT_MODE" = "strict" ]; then
     SHOULD_BLOCK="true"
   fi
+  if printf '%s' "$REASONS" | grep -Eq 'tdd_cycle_counts_unavailable'; then
+    SHOULD_BLOCK="true"
+  fi
   if [ "$WORKFLOW_GUARD_MODE" = "strict" ] || [ "$SHOULD_BLOCK" = "true" ]; then
     printf '[cclaw] %s (blocked by workflow guard)\n' "$NOTE" >&2
     exit 1
@@ -1177,8 +1247,8 @@ export function cursorHooksJsonWithObservation() {
  * - `SessionStart` matcher is limited to `startup|resume` — Codex does
  *   not emit `clear` or `compact` lifecycle phases.
  * - `PreToolUse` / `PostToolUse` fire **only for the `Bash` tool**
- *   (documented Codex limitation, v0.114/v0.115). We use the `Bash`
- *   matcher verbatim so Codex doesn't silently swallow our commands.
+ *   (documented Codex limitation, v0.114/v0.115). We match both `Bash`
+ *   and `bash` variants to tolerate casing drift across Codex builds.
  * - `UserPromptSubmit` is supported and is the closest analogue to
  *   Cursor's `preToolUse` for non-Bash tooling — we run prompt-guard
  *   there so workflow/prompt checks still fire when the tool being
@@ -1219,11 +1289,11 @@ export function codexHooksJsonWithObservation() {
                             command: hookDispatcherCommand("workflow-guard.sh")
                         }, {
                             type: "command",
-                            command: "bash -lc 'if command -v cclaw >/dev/null 2>&1; then cclaw internal verify-current-state --quiet >/dev/null || true; else npx -y cclaw-cli internal verify-current-state --quiet >/dev/null || true; fi'"
+                            command: "bash -lc 'if ! command -v cclaw >/dev/null 2>&1; then echo \"[cclaw] codex hook: cclaw binary is required for verify-current-state\" >&2; exit 1; fi; cclaw internal verify-current-state --quiet >/dev/null || true'"
                         }]
                 }],
             PreToolUse: [{
-                    matcher: "Bash",
+                    matcher: "Bash|bash",
                     hooks: [{
                             type: "command",
                             command: hookDispatcherCommand("prompt-guard.sh")
@@ -1233,7 +1303,7 @@ export function codexHooksJsonWithObservation() {
                         }]
                 }],
             PostToolUse: [{
-                    matcher: "Bash",
+                    matcher: "Bash|bash",
                     hooks: [{
                             type: "command",
                             command: hookDispatcherCommand("context-monitor.sh")