@bookedsolid/rea 0.28.2 → 0.30.0

package/.husky/prepare-commit-msg

@@ -0,0 +1,295 @@
+#!/bin/sh
+# rea:prepare-commit-msg v1
+# rea:augment-body-v1
+#
+# Husky prepare-commit-msg hook installed by `rea init` / `rea upgrade`.
+# Do NOT edit by hand — the file is refreshed on every rea upgrade.
+#
+# Governance contract: when policy.attribution.co_author.enabled is
+# `true`, append a `Co-Authored-By: <name> <email>` trailer to the
+# commit message file. Idempotent on email match (case-insensitive,
+# line-anchored). Skips merge commits when policy.attribution.co_author
+# .skip_merge is true.
+#
+# Triggers under all five commit sources git delivers:
+#   - $2 unset / empty   (`git commit` with no body provided)
+#   - $2 = 'message'     (`git commit -m "..."`)
+#   - $2 = 'template'    (commit.template configured)
+#   - $2 = 'merge'       (merge commit; honored by skip_merge: true)
+#   - $2 = 'squash'      (squash merge / rebase)
+#   - $2 = 'commit'      (`git commit --amend`)
+#
+# Skip conditions:
+#   - REA_SKIP_ATTRIBUTION=1 in env (per-invocation override)
+#   - .rea/HALT present (kill switch active)
+#   - $1 (message file path) missing or not a file
+#   - policy.attribution.co_author.enabled !== true
+#
+# Coexistence: this hook does NOT block on anything. The companion
+# `commit-msg` hook (which runs AFTER prepare-commit-msg in git's
+# lifecycle) still enforces `block_ai_attribution`. A human trailer
+# `Co-Authored-By: Real Name <real@email.tld>` is NOT AI attribution
+# (no AI noreply domain, no AI name keyword) and is not blocked.
+
+set -u
+
+COMMIT_MSG_FILE="${1:-}"
+COMMIT_SOURCE="${2:-}"
+
+# Skip conditions: any missing precondition exits 0 silently. The hook
+# is purely additive; refusing here would break commits with no upside.
+
+# Missing message file → nothing to augment.
+if [ -z "$COMMIT_MSG_FILE" ] || [ ! -f "$COMMIT_MSG_FILE" ]; then
+  exit 0
+fi
+
+# Per-invocation override.
+if [ -n "${REA_SKIP_ATTRIBUTION:-}" ]; then
+  exit 0
+fi
+
+REA_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
+
+# HALT kill switch — refuse to mutate anything while frozen.
+if [ -f "${REA_ROOT}/.rea/HALT" ]; then
+  exit 0
+fi
+
+POLICY_FILE="${REA_ROOT}/.rea/policy.yaml"
+if [ ! -f "$POLICY_FILE" ]; then
+  exit 0
+fi
+
+# Delegate policy reads to the canonical rea CLI when available so we
+# get the zod-validated document regardless of whether the operator
+# wrote block-form (`attribution:\n  co_author:\n    enabled: true`)
+# or inline-form (`attribution: { co_author: { enabled: true } }`)
+# YAML. Codex round 1 P2: the prior Python inline parser only handled
+# block form. When the CLI is unreachable (fresh consumer install
+# pre-`pnpm i`, foreign dev environment, …) we fall back to the
+# embedded Python state machine — it correctly handles block-form
+# YAML, which is what `rea init` writes.
+#
+# Locator priority mirrors `.husky/pre-push`: project node_modules →
+# dogfood dist → PATH.
+rea_invoke() {
+  if [ -x "${REA_ROOT}/node_modules/.bin/rea" ]; then
+    "${REA_ROOT}/node_modules/.bin/rea" "$@"
+  elif [ -f "${REA_ROOT}/dist/cli/index.js" ] && [ -f "${REA_ROOT}/package.json" ] && grep -q '"name": *"@bookedsolid/rea"' "${REA_ROOT}/package.json" 2>/dev/null; then
+    node "${REA_ROOT}/dist/cli/index.js" "$@"
+  elif command -v rea >/dev/null 2>&1; then
+    rea "$@"
+  else
+    return 127
+  fi
+}
+
+ENABLED=$(rea_invoke hook policy-get attribution.co_author.enabled 2>/dev/null)
+REA_RC=$?
+
+if [ "$REA_RC" = "0" ]; then
+  CO_NAME=$(rea_invoke hook policy-get attribution.co_author.name 2>/dev/null || printf '')
+  CO_EMAIL=$(rea_invoke hook policy-get attribution.co_author.email 2>/dev/null || printf '')
+  SKIP_MERGE=$(rea_invoke hook policy-get attribution.co_author.skip_merge 2>/dev/null || printf 'false')
+elif command -v python3 >/dev/null 2>&1; then
+  # rea CLI unreachable — fall back to Python block-form parser.
+  CO_AUTHOR_PARSE=$(python3 - "$POLICY_FILE" <<'PY' 2>/dev/null
+import re
+import sys
+
+path = sys.argv[1]
+try:
+    with open(path, 'r', encoding='utf-8') as fh:
+        lines = fh.readlines()
+except OSError:
+    print('false'); print(''); print(''); print('false'); sys.exit(0)
+
+in_attr = False
+in_co = False
+enabled = 'false'
+name = ''
+email = ''
+skip_merge = 'false'
+
+def strip_value(raw):
+    raw = raw.rstrip('\n').rstrip()
+    if len(raw) >= 2 and raw[0] == raw[-1] and raw[0] in ("'", '"'):
+        return raw[1:-1]
+    if '#' in raw:
+        raw = raw.split('#', 1)[0].rstrip()
+    return raw
+
+for line in lines:
+    stripped_line = line.rstrip('\n')
+    if re.match(r'^\s*#', stripped_line):
+        continue
+    if re.match(r'^attribution:\s*(#.*)?$', stripped_line):
+        in_attr = True; in_co = False; continue
+    if in_attr and re.match(r'^\S', stripped_line):
+        in_attr = False; in_co = False
+    if in_attr and re.match(r'^\s+co_author:\s*(#.*)?$', stripped_line):
+        in_co = True; continue
+    if in_co:
+        m = re.match(r'^(\s*)\S', stripped_line)
+        if m and len(m.group(1)) <= 2:
+            in_co = False; continue
+        if re.search(r'enabled:\s*true(\s|$)', stripped_line):
+            enabled = 'true'
+        elif re.search(r'enabled:\s*false(\s|$)', stripped_line):
+            enabled = 'false'
+        if re.search(r'skip_merge:\s*true(\s|$)', stripped_line):
+            skip_merge = 'true'
+        elif re.search(r'skip_merge:\s*false(\s|$)', stripped_line):
+            skip_merge = 'false'
+        m = re.search(r'name:\s*(.*)$', stripped_line)
+        if m:
+            name = strip_value(m.group(1))
+        m = re.search(r'email:\s*(.*)$', stripped_line)
+        if m:
+            email = strip_value(m.group(1))
+
+print(enabled); print(name); print(email); print(skip_merge)
+PY
+)
+  if [ -z "$CO_AUTHOR_PARSE" ]; then
+    exit 0
+  fi
+  ENABLED=$(printf '%s\n' "$CO_AUTHOR_PARSE" | sed -n '1p')
+  CO_NAME=$(printf '%s\n' "$CO_AUTHOR_PARSE" | sed -n '2p')
+  CO_EMAIL=$(printf '%s\n' "$CO_AUTHOR_PARSE" | sed -n '3p')
+  SKIP_MERGE=$(printf '%s\n' "$CO_AUTHOR_PARSE" | sed -n '4p')
+else
+  # Neither rea CLI nor python3 reachable — silent no-op.
+  exit 0
+fi
+
+if [ "$ENABLED" != "true" ]; then
+  exit 0
+fi
+
+# Defense-in-depth: if we got here with enabled=true but no identity,
+# the policy loader's cross-field refinement was bypassed (or someone
+# edited the YAML around the load path). Bail without augmenting and
+# emit a stderr advisory so the operator sees the misconfig at commit
+# time. We deliberately do NOT exit non-zero — refusing the commit
+# would be more disruptive than the silent no-op (the loader + doctor
+# already surface the misconfig at policy load and at `rea doctor`).
+#
+# When `rea audit record <topic>` lands in a future release this
+# branch should emit a `rea.attribution_augmented_invalid_config`
+# record instead of stderr. Tracked as a 0.31.0+ item.
+if [ -z "$CO_NAME" ] || [ -z "$CO_EMAIL" ]; then
+  printf 'rea: attribution.co_author.enabled=true but %s%s%s is empty — augmenter no-op.\n' \
+    "$([ -z "$CO_NAME" ] && printf name)" \
+    "$([ -z "$CO_NAME" ] && [ -z "$CO_EMAIL" ] && printf '+')" \
+    "$([ -z "$CO_EMAIL" ] && printf email)" >&2
+  printf 'rea: edit .rea/policy.yaml — set name + email, OR set enabled: false.\n' >&2
+  exit 0
+fi
+
+# skip_merge: true → skip when commit source is 'merge'.
+if [ "$SKIP_MERGE" = "true" ] && [ "$COMMIT_SOURCE" = "merge" ]; then
+  exit 0
+fi
+
+# Idempotency: scan the current message file for a Co-Authored-By line
+# that names the same email (case-insensitive). Line-anchored — body
+# prose mentioning the email in passing does NOT count.
+LOWER_EMAIL=$(printf '%s' "$CO_EMAIL" | tr '[:upper:]' '[:lower:]')
+# grep -E with case-insensitive flag; portable across BSD + GNU grep.
+# The pattern: ^co-authored-by: <anything> <EMAIL>[ws]*$
+# Email is regex-escaped via the conservative approach: assume the
+# email passed policy validation (only safe chars per loader regex
+# /^[^\s<>@]+@[^\s<>@]+\.[^\s<>@]+$/), so the only metachars present
+# are `.` and possibly `+` / `-`. We escape `.` and rely on the
+# permissive char set.
+ESCAPED_EMAIL=$(printf '%s' "$LOWER_EMAIL" | sed 's/[.[\*^$(){}+?|]/\\&/g')
+if grep -iE "^co-authored-by:[[:space:]]*[^<]*<${ESCAPED_EMAIL}>[[:space:]]*$" \
+  "$COMMIT_MSG_FILE" >/dev/null 2>&1; then
+  exit 0
+fi
+
+# Build the trailer line. Idempotency above already lower-cased the
+# email for comparison; we ship the trailer with the policy-supplied
+# casing so the user's preferred display name + email render verbatim.
+TRAILER="Co-Authored-By: ${CO_NAME} <${CO_EMAIL}>"
+
+# Find the insert point: at the bottom of the message, after stripping
+# trailing blank/comment lines (git's scissors line `# -- >8 --` and
+# everything below is appended verbatim to preserve git's own view).
+TMP_BODY=$(mktemp "${TMPDIR:-/tmp}/rea-pcm.XXXXXX") || exit 0
+TMP_TAIL=$(mktemp "${TMPDIR:-/tmp}/rea-pcm.XXXXXX") || { rm -f "$TMP_BODY"; exit 0; }
+trap 'rm -f "$TMP_BODY" "$TMP_TAIL"' EXIT INT TERM
+
+# Split the file: body (above the scissors marker) vs. tail (scissors
+# and everything below). Codex round 2 P1: previously used python3
+# unconditionally — on environments where rea CLI is reachable but
+# python3 is missing, the split silently failed and the user's commit
+# body got dropped. awk is universally available on POSIX systems and
+# does the same work.
+SCISSORS='# ------------------------ >8 ------------------------'
+awk -v scissors="$SCISSORS" -v body_dst="$TMP_BODY" -v tail_dst="$TMP_TAIL" '
+  BEGIN { found = 0 }
+  {
+    if (!found && $0 == scissors) found = 1
+    if (found) print > tail_dst
+    else        print > body_dst
+  }
+' "$COMMIT_MSG_FILE"
+
+# Determine whether the body's last non-blank/non-comment line is a
+# real git trailer (`Key: value` where Key matches `[A-Za-z][-A-Za-z0-9]*`)
+# AND part of a multi-line trailer block (not the subject of a single-line
+# conventional commit). Codex round 3 P1: the round-2 fix correctly
+# rejected commit-prose `: ` patterns but still matched the conventional
+# commit subject form `feat: add x` because that line is ALSO
+# `[A-Za-z][-A-Za-z0-9]*: <value>`. The right distinguisher: a real
+# trailer block has at least one preceding non-blank body line; a bare
+# `feat: x` commit is just a subject and always needs a separator.
+LAST_BODY_LINE=$(awk '
+  /^[[:space:]]*#/ { next }
+  /^[[:space:]]*$/ { next }
+  { lastline = $0 }
+  END { if (lastline != "") print lastline }
+' "$TMP_BODY")
+BODY_LINE_COUNT=$(awk '
+  /^[[:space:]]*#/ { next }
+  /^[[:space:]]*$/ { next }
+  { count++ }
+  END { print count + 0 }
+' "$TMP_BODY")
+
+SEPARATOR_NEEDED=1
+if [ -z "$LAST_BODY_LINE" ]; then
+  SEPARATOR_NEEDED=0
+elif [ "$BODY_LINE_COUNT" -gt 1 ] && printf '%s' "$LAST_BODY_LINE" | grep -qE '^[A-Za-z][-A-Za-z0-9]*: '; then
+  SEPARATOR_NEEDED=0
+fi
+
+# Trim trailing blank lines from the body so the trailer lands cleanly
+# (without leaving a triple-newline before it).
+TMP_BODY_TRIMMED=$(mktemp "${TMPDIR:-/tmp}/rea-pcm.XXXXXX") || exit 0
+awk '
+  { lines[NR] = $0; total = NR }
+  END {
+    end = total
+    while (end > 0 && lines[end] ~ /^[[:space:]]*$/) { end-- }
+    for (i = 1; i <= end; i++) print lines[i]
+  }
+' "$TMP_BODY" > "$TMP_BODY_TRIMMED"
+
+# Compose the new file: trimmed body + (optional blank) + trailer + tail.
+{
+  cat "$TMP_BODY_TRIMMED"
+  if [ "$SEPARATOR_NEEDED" -eq 1 ]; then
+    printf '\n'
+  fi
+  printf '%s\n' "$TRAILER"
+  if [ -s "$TMP_TAIL" ]; then
+    cat "$TMP_TAIL"
+  fi
+} > "${COMMIT_MSG_FILE}.rea-tmp" && mv "${COMMIT_MSG_FILE}.rea-tmp" "$COMMIT_MSG_FILE"
+
+rm -f "$TMP_BODY_TRIMMED"
+exit 0

package/MIGRATING.md

@@ -59,6 +59,10 @@ are on the vanilla-git path — install husky first.
 - `.husky/pre-push` — package-managed; **do not edit**. Refreshed on every
   `rea upgrade`.
 - `.husky/commit-msg` — package-managed; **do not edit**. Same.
+- `.husky/prepare-commit-msg` — package-managed (added in 0.30.0).
+  Drives the optional `attribution.co_author` augmenter; **do not edit**.
+  No-op when `policy.attribution.co_author.enabled !== true`, so it is
+  safe to ship under every profile (default disabled).
 - `.git/hooks/pre-push` (fallback when `core.hooksPath` is unset).
 - `.claude/hooks/*.sh` — protection + audit + advisory hooks.
 - `.claude/agents/*.md`, `.claude/commands/*.md`.
@@ -125,6 +129,77 @@ Re-run `rea upgrade`. The package-managed `.husky/commit-msg` body now
 runs first (HALT check, AI-attribution block when policy enables it),
 then runs your fragment.
 
+## Conflict pattern: existing prepare-commit-msg (rea 0.30.0+)
+
+You probably have a hook that templates the message, adds a Jira
+ticket prefix, or inserts a branch name:
+
+```sh
+#!/bin/sh
+# .husky/prepare-commit-msg — user-authored
+COMMIT_MSG_FILE=$1
+BRANCH=$(git rev-parse --abbrev-ref HEAD)
+echo "[$BRANCH] $(cat "$COMMIT_MSG_FILE")" > "$COMMIT_MSG_FILE"
+```
+
+**rea 0.30.0+ refuses to overwrite a foreign `.husky/prepare-commit-msg`.**
+On `rea init` you'll see a `[fail]` from `rea doctor`:
+
+```
+[fail] prepare-commit-msg hook (attribution augmenter)
+       (attribution.co_author.enabled: true but the prepare-commit-msg
+        hook is foreign (no rea marker) — remove the existing hook
+        and re-run `rea init`, or set enabled: false.)
+```
+
+### Migration
+
+Two paths, depending on whether you intend to use the rea augmenter.
+
+**Path A — you want the augmenter (Co-Authored-By trailer)**
+
+Move your branch-prefix logic into rea's chained body. As of 0.30.0
+rea's prepare-commit-msg body does NOT support `.husky/prepare-commit-msg.d/*`
+fragments yet (it's on the 0.31.0 roadmap). For now, port the logic
+into a wrapper invoked by `commit-msg.d` instead:
+
+```bash
+mkdir -p .husky/commit-msg.d
+cat > .husky/commit-msg.d/00-branch-prefix <<'EOF'
+#!/bin/sh
+# Branch-prefix logic moved from prepare-commit-msg to commit-msg.d
+# (runs AFTER rea's augmenter, before the commit is finalized).
+BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo unknown)
+case $(head -1 "$1") in
+  "[$BRANCH]"*) ;;  # already prefixed
+  *) printf '[%s] %s' "$BRANCH" "$(cat "$1")" > "$1" ;;
+esac
+EOF
+chmod +x .husky/commit-msg.d/00-branch-prefix
+```
+
+Then remove the old `.husky/prepare-commit-msg`:
+
+```bash
+rm .husky/prepare-commit-msg .git/hooks/prepare-commit-msg
+```
+
+Re-run `rea init`. rea's prepare-commit-msg now installs cleanly.
+
+**Path B — you do NOT want the augmenter**
+
+Leave your existing hook in place. Set the augmenter off explicitly:
+
+```yaml
+# .rea/policy.yaml
+attribution:
+  co_author:
+    enabled: false
+```
+
+`rea doctor` reports `[warn]` (not fail) for the foreign hook —
+your commits keep going through your existing logic.
+
 ## Conflict pattern: lint-staged on pre-push
 
 You probably have:

package/dist/audit/append.d.ts

@@ -83,3 +83,4 @@ export type { AuditRecord, EmissionSource } from '../gateway/middleware/audit-ty
 export { Tier, InvocationStatus } from '../policy/types.js';
 export { CODEX_REVIEW_TOOL_NAME, CODEX_REVIEW_SERVER_NAME, type CodexVerdict, type CodexReviewMetadata, } from './codex-event.js';
 export { LOCAL_REVIEW_TOOL_NAME, LOCAL_REVIEW_SKIPPED_OVERRIDE_TOOL_NAME, LOCAL_REVIEW_SKIPPED_UNAVAILABLE_TOOL_NAME, LOCAL_REVIEW_PREFLIGHT_SKIPPED_TOOL_NAME, LOCAL_REVIEW_SERVER_NAME, type LocalReviewVerdict, type LocalReviewMetadata, type LocalReviewSkippedOverrideMetadata, type LocalReviewSkippedUnavailableMetadata, } from './local-review-event.js';
+export { DELEGATION_SIGNAL_TOOL_NAME, DELEGATION_SIGNAL_SERVER_NAME, DELEGATION_SIGNAL_SCHEMA_VERSION, DelegationSignalMetadataSchema, type DelegationTool, type DelegationSignalMetadata, type DelegationSignalMetadataParsed, } from './delegation-event.js';

package/dist/audit/append.js

@@ -204,3 +204,4 @@ export async function appendAuditRecord(baseDir, input) {
 export { Tier, InvocationStatus } from '../policy/types.js';
 export { CODEX_REVIEW_TOOL_NAME, CODEX_REVIEW_SERVER_NAME, } from './codex-event.js';
 export { LOCAL_REVIEW_TOOL_NAME, LOCAL_REVIEW_SKIPPED_OVERRIDE_TOOL_NAME, LOCAL_REVIEW_SKIPPED_UNAVAILABLE_TOOL_NAME, LOCAL_REVIEW_PREFLIGHT_SKIPPED_TOOL_NAME, LOCAL_REVIEW_SERVER_NAME, } from './local-review-event.js';
+export { DELEGATION_SIGNAL_TOOL_NAME, DELEGATION_SIGNAL_SERVER_NAME, DELEGATION_SIGNAL_SCHEMA_VERSION, DelegationSignalMetadataSchema, } from './delegation-event.js';

package/dist/audit/delegation-event.d.ts

@@ -0,0 +1,215 @@
+/**
+ * Single source of truth for the `rea.delegation_signal` audit event shape
+ * (0.29.0+).
+ *
+ * 0.29.0 — delegation-telemetry MVP. Claude Code's PreToolUse hook tree
+ * gains a new matcher (`Agent|Skill`) that pipes a redacted, hashed
+ * record of every subagent dispatch and skill invocation into
+ * `.rea/audit.jsonl`. The signal is observational, not gating — it
+ * answers "which specialists is this session actually delegating to,
+ * and how often" without altering the autonomy tree.
+ *
+ * # The two delegation tools
+ *
+ * Current Claude Code exposes exactly two delegation surfaces:
+ *
+ *   - `Agent` — dispatches a curated subagent (rea-orchestrator,
+ *     code-reviewer, …). The agent name is at
+ *     `tool_input.subagent_type`.
+ *   - `Skill` — invokes a named skill (deep-dive, /loop, …). The skill
+ *     name is at `tool_input.skill`.
+ *
+ * mcp-protocol-specialist verified BOTH payload paths against current
+ * Claude Code. A Skill that internally forks an Agent fires PreToolUse
+ * TWICE (Skill then Agent) for the same logical action; v1 records
+ * both — deduplication lives in the reader, not the writer.
+ *
+ * # Not `Task`
+ *
+ * In current Claude Code the tools are `Agent` and `Skill`. The names
+ * `TaskCreate`/`TaskList`/`TaskUpdate` belong to the unrelated todo-list
+ * tool surface and MUST NOT match. The settings.json matcher is
+ * `Agent|Skill` everywhere — anchored on a `^…$` boundary by the hook
+ * runtime, so `Agent` doesn't accidentally collide with hypothetical
+ * future tools named `Agentic…`.
+ *
+ * # Privacy invariant
+ *
+ * The raw `description` / `prompt` payload NEVER touches `.rea/audit.jsonl`
+ * — only its SHA-256 hash. The hash is collision-resistant identification
+ * (two identical prompts produce identical hashes, enabling
+ * delegation-pattern discovery) without persisting prompt content.
+ *
+ * The agent / skill name field DOES land in the audit log, but is run
+ * through `redactSecrets` first. A subagent_type that contains a
+ * planted credential string (synthetic AWS key, GitHub token, …) is
+ * replaced with `[REDACTED]` and the matching pattern names are
+ * appended to the record's `redacted_fields` envelope.
+ *
+ * # Provider seam (kept tiny)
+ *
+ * Unlike `rea.local_review`, this event does NOT have a `provider`
+ * field. The producer is always Claude Code's hook runtime and the
+ * `emission_source: 'rea-cli'` envelope is sufficient. If a future
+ * runtime (e.g. another agent host) wants to emit signals through the
+ * same channel, it writes the same shape with the same tool_name and
+ * relies on `session_id_observed` / `delegation_tool` for
+ * disambiguation.
+ *
+ * # Schema version
+ *
+ * The literal `schema_version: 1` is part of the metadata payload. Zod
+ * strict-mode rejects unknown fields, so a future v2 producer writing
+ * v2-only fields against a v1 consumer fails-loud rather than silently
+ * dropping data. Readers filter by `tool_name === 'rea.delegation_signal'`
+ * AND `metadata.schema_version === 1`.
+ */
+import { z } from 'zod';
+/**
+ * Canonical `tool_name` on the audit record envelope. Readers filter on
+ * this exact literal — anything else is a different event class.
+ */
+export declare const DELEGATION_SIGNAL_TOOL_NAME: "rea.delegation_signal";
+/**
+ * `server_name` envelope value. The signal originates from Claude Code's
+ * hook runtime, captured by `rea hook delegation-signal` and appended
+ * via the public audit-record API. Naming it `claude-code-hooks` makes
+ * the producer surface unambiguous in forensic queries (vs.
+ * `'rea'` which is used for first-party rea CLI events like
+ * `rea.local_review`).
+ */
+export declare const DELEGATION_SIGNAL_SERVER_NAME: "claude-code-hooks";
+/**
+ * Schema version literal. Bumped only when the metadata shape gains a
+ * non-backwards-compatible change. Adding optional fields does NOT bump
+ * the version — zod's strict mode rejects them, so any new field MUST
+ * either ship with a major-version bump OR have its zod parser updated
+ * in lockstep.
+ */
+export declare const DELEGATION_SIGNAL_SCHEMA_VERSION: 1;
+/**
+ * The two valid delegation-tool values. `Agent` and `Skill` are the
+ * exact tool names emitted by Claude Code's PreToolUse hook payload —
+ * anything else is a misclassification at the hook layer.
+ */
+export type DelegationTool = 'Agent' | 'Skill';
+/**
+ * Canonical metadata payload for `rea.delegation_signal`. Embedded
+ * under `metadata` on the audit record. The audit-record envelope
+ * itself supplies `tool_name`, `server_name`, `session_id`, `timestamp`,
+ * `prev_hash`, `hash`, `redacted_fields`, etc. — keep those out of
+ * metadata.
+ */
+export interface DelegationSignalMetadata {
+    /**
+     * Always `1` for the 0.29.0 shape. Carried as a literal so future
+     * v2-aware readers can distinguish records they understand from
+     * records they don't.
+     */
+    schema_version: typeof DELEGATION_SIGNAL_SCHEMA_VERSION;
+    /**
+     * Which Claude Code surface fired the hook — `'Agent'` for the
+     * subagent dispatch tool, `'Skill'` for the skill invocation tool.
+     * The reader CLI groups records on `subagent_type` regardless of
+     * `delegation_tool` (a `deep-dive` skill and a `deep-dive` agent
+     * roll into the same bucket), but the field is retained for forensic
+     * queries that want to distinguish the two.
+     */
+    delegation_tool: DelegationTool;
+    /**
+     * For `Agent`: the value of `tool_input.subagent_type` at the hook
+     * (e.g. `'rea-orchestrator'`).
+     *
+     * For `Skill`: the value of `tool_input.skill` (e.g. `'deep-dive'`).
+     *
+     * Always passed through `redactSecrets` before landing here. If a
+     * planted secret pattern fires, this field is `'[REDACTED]'` and
+     * the matching pattern name appears in the record's
+     * `redacted_fields` envelope.
+     *
+     * Reader CLI groups records on this field.
+     */
+    subagent_type: string;
+    /**
+     * The session id Claude Code attached to the hook payload — the same
+     * value the harness uses for its own correlation. Captured verbatim
+     * so a future per-session breakdown (deferred to 0.29.1) can group
+     * records without scanning the entire chain.
+     *
+     * Distinct from the audit envelope's `session_id`, which uses the
+     * caller's session ("external" for the CLI subcommand). The
+     * envelope's `session_id` says WHO wrote the record; this field says
+     * WHO Claude Code thinks is delegating.
+     */
+    session_id_observed: string;
+    /**
+     * When the dispatching agent is itself a subagent, this is the
+     * parent's subagent_type at hook-fire time. Drawn from
+     * `CLAUDE_PARENT_SUBAGENT` / `tool_input.parent_subagent_type` when
+     * present; `null` for top-level dispatches.
+     *
+     * Like `subagent_type`, redacted before landing here.
+     */
+    parent_subagent_type: string | null;
+    /**
+     * SHA-256 hex digest of `tool_input.description` (Agent) or
+     * `tool_input.prompt` (Skill). When neither is present an empty
+     * string is hashed — the resulting digest is the well-known
+     * `e3b0c4...` constant, which readers can recognize as "no prompt".
+     *
+     * # Why hash, not redact
+     *
+     * The prompt is the actionable content of the delegation — it
+     * routinely names files, customers, internal URLs, half-finished
+     * thoughts. Redacting it via pattern-matching is best-effort; hashing
+     * it is total. The collision-resistance of SHA-256 still lets two
+     * identical prompts produce identical hashes, which is enough for
+     * the delegation-pattern queries this telemetry exists to support.
+     */
+    invocation_description_sha256: string;
+    /**
+     * ISO-8601 timestamp Claude Code attached to the hook event, when
+     * present. Distinct from the audit-record envelope's `timestamp`
+     * (which is the moment the CLI subcommand wrote the line). Both
+     * fields are useful: the envelope timestamp orders the chain,
+     * `hook_event_timestamp` orders the underlying events.
+     */
+    hook_event_timestamp?: string;
+}
+/**
+ * Strict-mode zod schema for the metadata payload. Unknown fields are
+ * rejected — a future v2 producer must bump `DELEGATION_SIGNAL_SCHEMA_VERSION`
+ * AND update this schema in the same commit, otherwise v1 readers fail
+ * loud rather than silently dropping new fields.
+ *
+ * The schema is exported so the CLI subcommand validates its OWN
+ * emitted metadata before passing it to `appendAuditRecord` — defense
+ * in depth against a future refactor that wires the field set
+ * incorrectly. (Same posture as `loadPolicy` self-validation.)
+ */
+export declare const DelegationSignalMetadataSchema: z.ZodObject<{
+    schema_version: z.ZodLiteral<1>;
+    delegation_tool: z.ZodUnion<[z.ZodLiteral<"Agent">, z.ZodLiteral<"Skill">]>;
+    subagent_type: z.ZodString;
+    session_id_observed: z.ZodString;
+    parent_subagent_type: z.ZodUnion<[z.ZodString, z.ZodNull]>;
+    invocation_description_sha256: z.ZodString;
+    hook_event_timestamp: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    schema_version: 1;
+    delegation_tool: "Agent" | "Skill";
+    subagent_type: string;
+    session_id_observed: string;
+    parent_subagent_type: string | null;
+    invocation_description_sha256: string;
+    hook_event_timestamp?: string | undefined;
+}, {
+    schema_version: 1;
+    delegation_tool: "Agent" | "Skill";
+    subagent_type: string;
+    session_id_observed: string;
+    parent_subagent_type: string | null;
+    invocation_description_sha256: string;
+    hook_event_timestamp?: string | undefined;
+}>;
+export type DelegationSignalMetadataParsed = z.infer<typeof DelegationSignalMetadataSchema>;