feat(hooks): record Claude turn failures

Author: myobie

README.md

@@ -94,6 +94,13 @@ current inbox; pre-compact preserves a recovery breadcrumb when no context was w
 failure hooks surface newly arrived work or a harness failure. They fail open so hook trouble does
 not prevent the harness from starting or stopping.
 
+The Claude `StopFailure` hook appends one private JSON object per failure to
+`${XDG_STATE_HOME:-$HOME/.local/state}/st2/hook-events/stop-failure/<identity>.jsonl`. It records a
+UTC timestamp, the st2 identity, a normalized `error_type`, and the sanitized provider payload.
+The hook redacts sensitive fields and token-shaped strings before the append. It records invalid
+JSON without copying the raw input. A missing supervisor does not disable the record. Record,
+presence, and notification failures remain fail-open.
+
 The same immutable set also carries `pi-channel.ts`. pi has no hook mechanism of its own — an
 extension is where a pi session exposes that surface — so st2 ships one and `st2 driver pi-session`
 splices it into the launch from the set this binary verified. A declaration never names it, and a

docs/vrs/spec.md

@@ -916,6 +916,35 @@ and context larger than a platform argument limit without truncation. The open
 verification delta is recorded in
 [DELTA-001](./.delta/DELTA-001-session-start-hook-evidence.md).
 
+## Provider StopFailure records (R17)
+
+The Claude `StopFailure` hook reads the provider input once. It appends one
+compact JSON object to the agent's machine-local file:
+
+```text
+${XDG_STATE_HOME:-$HOME/.local/state}/st2/hook-events/stop-failure/<safe-identity>.jsonl
+```
+
+The file mode is `0600`, and its directory mode is `0700`. Each record has
+schema `1`, a UTC timestamp, event `StopFailure`, the original st2 identity,
+a normalized `error_type`, and the sanitized provider payload. The normalized
+field accepts the current provider `error` field and the legacy `error_type`
+field.
+
+The sanitizer replaces sensitive field values and token-shaped strings before
+the append. A sanitized payload larger than 16,384 characters becomes a bounded
+preview. Invalid JSON produces `payload: null` and `payload_error: invalid_json`;
+the hook never copies the invalid raw input.
+
+The hook records before it applies presence or supervisor-notification filters.
+Thus, filtered errors and agents without supervisors still produce records.
+Directory, append, permission, presence, and notification failures do not alter
+the hook's successful exit.
+
+Executable acceptance in `tests/claude_hooks.rs` covers append behavior, exact
+permissions, current and legacy error fields, redaction, invalid input, filtered
+errors, missing supervisors, and an unwritable record path.
+
 The owner updates this spec whenever implementation changes.
 Changing [vision.md](./vision.md) or [requirements.md](./requirements.md)
 requires Nathan's explicit approval.

examples/native/README.md

@@ -41,6 +41,11 @@ Hook installation is explicit and receipt-bearing. `up` and materialization only
 selected immutable hook set; they never refresh shared scripts. Managed settings resolve
 `$ST_HOOKS/<script>` into that versioned set.
 
+The Claude `StopFailure` hook records every API-error turn in the machine-local st2 state directory.
+Each agent appends to `st2/hook-events/stop-failure/<identity>.jsonl`. The hook records before it
+applies notification filters, and it records even when the declaration has no supervisor. The JSONL
+payload is redacted before it reaches disk. All record failures remain fail-open.
+
 ## Status discipline
 
 All three maintained declarations load the shipped bus contract. Agents must declare `busy` before

hooks/claude-stop-failure.sh

@@ -1,18 +1,111 @@
 #!/usr/bin/env bash
-# st2 Claude StopFailure hook: surface infrastructure wedges through presence and, when declared,
-# the agent's supervisor inbox. Fail-open; lifecycle reporting must never wedge the harness.
+# st2 Claude StopFailure hook: append one private machine-local JSONL record, then surface
+# infrastructure wedges through presence and, when declared, the agent's supervisor inbox.
+# Fail-open; lifecycle reporting must never wedge the harness.
 
 set -u
 
 identity="${ST_AGENT:-}"
 root="${ST_ROOT:-${CATALOG:-}}"
 supervisor="${ST_SUPERVISOR:-}"
+input="$(cat 2>/dev/null || true)"
+error_type="unknown"
+
+# One file per identity avoids cross-agent append contention. The complete provider payload is
+# useful for diagnosis, but sensitive keys and token-shaped strings are redacted before the line
+# reaches disk. Oversized sanitized payloads keep a bounded preview. Invalid JSON is never copied.
+if command -v jq >/dev/null 2>&1; then
+  timestamp="$(date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || printf unknown)"
+  record_identity="${identity:-unknown}"
+  record="$(
+    printf '%s' "$input" | jq -cs \
+      --arg timestamp "$timestamp" \
+      --arg identity "$record_identity" '
+      def sensitive_key:
+        ascii_downcase
+        | gsub("[^a-z0-9]"; "")
+        | test("^(authorization|proxyauthorization|cookie|setcookie|password|passwd|secret|clientsecret|credential|apikey|privatekey|token|authtoken|bearertoken|accesstoken|refreshtoken|idtoken)$");
+      def redact_string:
+        gsub("(?i)bearer[[:space:]]+[A-Za-z0-9._~+/=-]{8,}"; "Bearer [REDACTED]")
+        | gsub("(?i)(access[_-]?token|refresh[_-]?token|api[_-]?key|client[_-]?secret|password|passwd|secret)[[:space:]]*[:=][[:space:]]*[^&[:space:],;]+"; "[REDACTED]")
+        | gsub("(?i)(sk-[A-Za-z0-9_-]{12,}|github_pat_[A-Za-z0-9_]{20,}|gh[pousr]_[A-Za-z0-9_]{20,}|xox[baprs]-[A-Za-z0-9-]{10,}|AKIA[A-Z0-9]{16})"; "[REDACTED]")
+        | gsub("[A-Za-z0-9_-]{20,}\\.[A-Za-z0-9_-]{20,}\\.[A-Za-z0-9_-]{10,}"; "[REDACTED]");
+      def scrub:
+        walk(
+          if type == "object" then
+            with_entries(
+              if (.key | sensitive_key) then .value = "[REDACTED]" else . end
+            )
+          elif type == "string" then
+            redact_string
+          else
+            .
+          end
+        );
+      if length == 1 and (.[0] | type) == "object" then
+        .[0]
+      else
+        error("expected one JSON object")
+      end
+      | . as $original
+      | (($original.error_type // $original.error // "unknown") | tostring | redact_string) as $error_type
+      | (scrub) as $payload
+      | ($payload | tojson) as $encoded
+      | {
+          schema: 1,
+          timestamp: $timestamp,
+          event: "StopFailure",
+          identity: $identity,
+          error_type: $error_type,
+          payload: (
+            if ($encoded | length) <= 16384 then
+              $payload
+            else
+              {truncated: true, preview: $encoded[0:16384]}
+            end
+          )
+        }
+    ' 2>/dev/null
+  )"
+  if [[ -z "$record" ]]; then
+    record="$(jq -cn \
+      --arg timestamp "$timestamp" \
+      --arg identity "$record_identity" '
+      {
+        schema: 1,
+        timestamp: $timestamp,
+        event: "StopFailure",
+        identity: $identity,
+        error_type: "unknown",
+        payload: null,
+        payload_error: "invalid_json"
+      }
+    ' 2>/dev/null || true)"
+  fi
+  error_type="$(printf '%s' "$record" | jq -r '.error_type // "unknown"' 2>/dev/null || printf unknown)"
+
+  state_base="${XDG_STATE_HOME:-}"
+  if [[ -z "$state_base" && -n "${HOME:-}" ]]; then
+    state_base="${HOME}/.local/state"
+  fi
+  if [[ -n "$state_base" && -n "$record" ]]; then
+    safe_identity="$(printf '%s' "$record_identity" | tr -c 'A-Za-z0-9._-' '_' 2>/dev/null || printf unknown)"
+    record_dir="${state_base}/st2/hook-events/stop-failure"
+    record_file="${record_dir}/${safe_identity}.jsonl"
+    (
+      umask 077
+      mkdir -p "$record_dir" || exit 0
+      chmod 700 "$record_dir" || true
+      printf '%s\n' "$record" >> "$record_file" || exit 0
+      chmod 600 "$record_file" || true
+    ) 2>/dev/null || true
+  fi
+fi
+
 if [[ -z "$identity" || -z "$root" ]] || ! command -v st2 >/dev/null 2>&1 || ! command -v jq >/dev/null 2>&1; then
   exit 0
 fi
 
-input="$(cat)"
-error_type="$(printf '%s' "$input" | jq -r '.error_type // "unknown"' 2>/dev/null || printf unknown)"
 status="away"
 notify="yes"
 case "$error_type" in

tests/claude_hooks.rs

@@ -304,6 +304,14 @@ fn stop_failure_appends_a_private_redacted_record_without_a_supervisor() {
         fs::metadata(record_path).unwrap().permissions().mode() & 0o777,
         0o600
     );
+
+    let status = Command::new(env!("CARGO_BIN_EXE_st2"))
+        .args(["status", "Silber.cos", "--root"])
+        .arg(&fixture.catalog)
+        .output()
+        .unwrap();
+    assert!(status.status.success());
+    assert_eq!(String::from_utf8(status.stdout).unwrap(), "offline\n");
 }
 
 #[test]
@@ -337,6 +345,28 @@ fn stop_failure_records_old_and_new_error_fields_before_reaction_filtering() {
     assert_eq!(records[1]["error_type"], "overloaded");
 }
 
+#[test]
+fn stop_failure_never_copies_an_invalid_raw_payload_to_disk() {
+    if !jq_available() {
+        eprintln!("SKIP: jq is required by the shipped Claude hook");
+        return;
+    }
+    let fixture = Fixture::new();
+    let raw = "not-json Bearer raw-secret-1234567890";
+
+    let output = fixture.run_with_input("claude-stop-failure.sh", &[], raw);
+
+    assert!(output.status.success());
+    assert!(output.stdout.is_empty());
+    assert!(output.stderr.is_empty());
+    let contents = fs::read_to_string(fixture.stop_failure_record()).unwrap();
+    let record: serde_json::Value = serde_json::from_str(contents.trim()).unwrap();
+    assert_eq!(record["error_type"], "unknown");
+    assert_eq!(record["payload"], serde_json::Value::Null);
+    assert_eq!(record["payload_error"], "invalid_json");
+    assert!(!contents.contains("raw-secret"));
+}
+
 #[test]
 fn stop_failure_remains_fail_open_when_the_record_path_is_unwritable() {
     if !jq_available() {
@@ -360,4 +390,12 @@ fn stop_failure_remains_fail_open_when_the_record_path_is_unwritable() {
     );
     assert!(output.stdout.is_empty());
     assert!(output.stderr.is_empty());
+
+    let status = Command::new(env!("CARGO_BIN_EXE_st2"))
+        .args(["status", "Silber.cos", "--root"])
+        .arg(&fixture.catalog)
+        .output()
+        .unwrap();
+    assert!(status.status.success());
+    assert_eq!(String::from_utf8(status.stdout).unwrap(), "away\n");
 }