the-cloud-clockwork · nestorcolt · May 5, 2026 · May 5, 2026 · May 5, 2026 · May 5, 2026
diff --git a/.env.example b/.env.example
@@ -166,3 +166,37 @@
 # GITFOAM_BINARY=~/.cargo/bin/gitfoam
 # Local dev path to gitfoam repo (used if the binary is missing and you want to cargo-install from source)
 # GITFOAM_LOCAL_SOURCE=/home/iamroot/dev/tcc-ecosystem/gitfoam
+
+# =============================================================================
+# BROADCAST SYSTEM — fleet messaging
+# =============================================================================
+# Severity tiers:
+#   info      → once per session (deduped via delivered_to)
+#   alert     → every UserPromptSubmit (persistent, ack-only)
+#   critical  → every UserPromptSubmit + every PreToolUse (when enabled below)
+#
+# Defaults (changed 2026-05-05):
+#   BROADCAST_CRITICAL_ON_PRETOOL=false   (was true) — gate alerts off PreToolUse
+#   BROADCAST_PRETOOL_MIN_SEVERITY=critical (was alert) — only emergencies fire on tool calls
+# These defaults reduce hook-error contamination per Claude Code issue #34713.
+# Operators on incident response can opt back in:
+# BROADCAST_CRITICAL_ON_PRETOOL=true
+# BROADCAST_PRETOOL_MIN_SEVERITY=alert
+#
+# Per-injection byte caps. 0 (default) = no cap — full content ships through
+# whatever stdout the hook emits. Set >0 to opt in to truncation when you
+# need envelope headroom under Claude Code's 10,000-char hook output limit
+# (over → harness silently writes to a temp file and the model receives a
+# filepath instead of the body).
+#
+# Recommended values when you opt in:
+#   BROADCAST_MAX_BYTES_PRETOOL=4096   — keeps PreToolUse alerts under 4 KB
+#   BROADCAST_MAX_BYTES_PROMPT=8192    — keeps banner injects under 8 KB
+#   CI_MANIFESTO_MAX_BYTES=7500        — caps CI manifesto inject + adds a
+#                                         "Read full doctrine at <path>" footer
+#
+# To see what each event currently emits and whether anything is over the
+# 10K Claude Code cap:  agentihooks doctor --debug-hook
+# BROADCAST_MAX_BYTES_PRETOOL=0
+# BROADCAST_MAX_BYTES_PROMPT=0
+# CI_MANIFESTO_MAX_BYTES=0
diff --git a/README.md b/README.md
@@ -321,7 +321,11 @@ All configuration in `.env` files in `~/.agentihooks/`. Key variables:
 | `CONTEXT_COMPRESSION_SCOPE` | `refresh` | Scope: `refresh` or `all` |
 | `CONTEXT_REFRESH_INTERVAL` | `20` | Re-inject rules every N turns |
 | `BROADCAST_ENABLED` | `true` | Fleet messaging master switch |
-| `BROADCAST_CRITICAL_ON_PRETOOL` | `true` | Critical alerts on every tool call |
+| `BROADCAST_CRITICAL_ON_PRETOOL` | `false` | Re-inject critical broadcasts on every PreToolUse (default off — alerts still land on UserPromptSubmit) |
+| `BROADCAST_PRETOOL_MIN_SEVERITY` | `critical` | Minimum severity for PreToolUse re-injection. `alert` widens it. |
+| `BROADCAST_MAX_BYTES_PRETOOL` | `0` | PreToolUse banner byte cap. `0` = no cap. Set >0 to opt in to truncation under Claude Code's 10K hook output limit. |
+| `BROADCAST_MAX_BYTES_PROMPT` | `0` | UserPromptSubmit banner byte cap. Same semantics. |
+| `CI_MANIFESTO_MAX_BYTES` | `0` | CI manifesto inject byte cap. `0` = full doctrine ships through. Set >0 (e.g. `7500`) to truncate with a "Read full file at \<path\>" footer. |
 | `TOKEN_CONTROL_ENABLED` | `true` | Token control layer master switch |
 | `BASH_FILTER_ENABLED` | `true` | Truncate verbose bash output |
 | `FILE_READ_CACHE_ENABLED` | `true` | Block redundant file re-reads |
@@ -337,6 +341,26 @@ All configuration in `.env` files in `~/.agentihooks/`. Key variables:
 
 Complete table: [Configuration Reference](https://the-cloud-clockwork.github.io/agentihooks/docs/reference/configuration/)
 
+#### Hook output and the 10K cap
+
+Claude Code injects hook stdout (and any `hookSpecificOutput.additionalContext`)
+into the model's context up to a documented **10,000-character hard cap**.
+Beyond the cap, the harness silently writes the body to a temp file and the
+model receives a filepath instead of the content. If your SessionStart or
+UserPromptSubmit injection accumulates above 10K, it is **silently lost**.
+
+AgentiHooks does not enforce a default cap — full content ships through so
+agents have the most context possible. To audit what each event actually
+emits and whether anything is over the limit, run:
+
+```bash
+agentihooks doctor --debug-hook
+```
+
+If you stack many injections (CI manifesto + brain feed + amygdala + custom
+overlays + tool memory), use the `*_MAX_BYTES` knobs above to cap the
+biggest contributors and leave headroom for the rest.
+
 ### Remote brain quickstart
 
 To wire a Claude Code session into a brain stack you already deployed

diff --git a/docs/bundles.md b/docs/bundles.md
@@ -1,3 +1,8 @@
+---
+title: Bundles
+parent: Getting Started
+nav_order: 9
+---
 # Bundles
 
 A bundle is a single external directory containing all your personal agentihooks customizations -- custom profiles, MCP configs, skills, agents, commands, and rules. Agentihooks is the engine; the bundle is your data.

diff --git a/docs/connectors.md b/docs/connectors.md
@@ -1,3 +1,8 @@
+---
+title: Connectors
+parent: Hook System
+nav_order: 9
+---
 # Connectors
 
 {: .warning }

diff --git a/docs/cost-management.md b/docs/cost-management.md
@@ -1,7 +1,7 @@
 ---
 title: Cost Management
-nav_order: 3
-permalink: /docs/cost-management/
+parent: Reference
+nav_order: 9
 ---
 
 # Cost Management

diff --git a/docs/extending.md b/docs/extending.md
@@ -1,5 +1,6 @@
 ---
-title: Extending AgentiHooks
+title: Extending
+parent: Hook System
 nav_order: 8
 ---
 

diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md
@@ -2,7 +2,6 @@
 title: Getting Started
 nav_order: 2
 has_children: true
-permalink: /docs/getting-started/
 ---
 
 # Getting Started

diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md
@@ -1,6 +1,7 @@
 ---
 title: Installation
 nav_order: 2
+parent: Getting Started
 ---
 
 # Installation

diff --git a/docs/getting-started/profiles.md b/docs/getting-started/profiles.md
@@ -1,6 +1,7 @@
 ---
 title: Profiles
 nav_order: 3
+parent: Getting Started
 ---
 
 # Profiles

diff --git a/docs/hooks/events.md b/docs/hooks/events.md
@@ -1,6 +1,7 @@
 ---
 title: Events
 nav_order: 2
+parent: Hook System
 ---
 
 # Hook Events

diff --git a/docs/hooks/index.md b/docs/hooks/index.md
@@ -2,7 +2,6 @@
 title: Hook System
 nav_order: 4
 has_children: true
-permalink: /docs/hooks/
 ---
 
 # Hook System

diff --git a/docs/mcp-tools/aws.md b/docs/mcp-tools/aws.md
@@ -1,6 +1,7 @@
 ---
 title: AWS
 nav_order: 4
+parent: MCP Tools
 ---
 
 # AWS Tools

diff --git a/docs/mcp-tools/compute.md b/docs/mcp-tools/compute.md
@@ -1,6 +1,7 @@
 ---
 title: Compute
 nav_order: 9
+parent: MCP Tools
 ---
 
 # Compute Tools

diff --git a/docs/mcp-tools/database.md b/docs/mcp-tools/database.md
@@ -1,6 +1,7 @@
 ---
 title: Database
 nav_order: 8
+parent: MCP Tools
 ---
 
 # Database Tools

diff --git a/docs/mcp-tools/email.md b/docs/mcp-tools/email.md
@@ -1,6 +1,7 @@
 ---
 title: Email
 nav_order: 5
+parent: MCP Tools
 ---
 
 # Email Tools

diff --git a/docs/mcp-tools/index.md b/docs/mcp-tools/index.md
@@ -2,7 +2,6 @@
 title: MCP Tools
 nav_order: 5
 has_children: true
-permalink: /docs/mcp-tools/
 ---
 
 # MCP Tools

diff --git a/docs/mcp-tools/observability.md b/docs/mcp-tools/observability.md
@@ -1,6 +1,7 @@
 ---
 title: Observability
 nav_order: 10
+parent: MCP Tools
 ---
 
 # Observability Tools

diff --git a/docs/mcp-tools/storage.md b/docs/mcp-tools/storage.md
@@ -1,6 +1,7 @@
 ---
 title: Storage
 nav_order: 7
+parent: MCP Tools
 ---
 
 # Storage Tools

diff --git a/docs/mcp-tools/utilities.md b/docs/mcp-tools/utilities.md
@@ -1,6 +1,7 @@
 ---
 title: Utilities
 nav_order: 13
+parent: MCP Tools
 ---
 
 # Utilities Tools

diff --git a/docs/pillars/index.md b/docs/pillars/index.md
@@ -0,0 +1,9 @@
+---
+title: The Four Pillars
+nav_order: 3
+has_children: true
+---
+
+# The Four Pillars
+
+AgentiHooks is organised around four pillars: Identity, Guardrails, Context Intelligence, Fleet Command. Each pillar covers one axis of running Claude Code agents at scale.
diff --git a/docs/reference/cli-commands.md b/docs/reference/cli-commands.md
@@ -1,6 +1,7 @@
 ---
 title: CLI Commands
 nav_order: 3
+parent: Reference
 ---
 
 # CLI Commands

diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md
@@ -1,6 +1,7 @@
 ---
 title: Configuration
 nav_order: 2
+parent: Reference
 ---
 
 # Configuration Reference

diff --git a/docs/reference/index.md b/docs/reference/index.md
@@ -1,8 +1,7 @@
 ---
 title: Reference
-nav_order: 7
+nav_order: 6
 has_children: true
-permalink: /docs/reference/
 ---
 
 # Reference

diff --git a/hooks/config.py b/hooks/config.py
@@ -352,8 +352,15 @@ def _env_bool(key: str, default: str = "false") -> bool:
 BROADCAST_ENABLED = _env_bool("BROADCAST_ENABLED", "true")
 BROADCAST_FILE: str = os.getenv("BROADCAST_FILE", str(Path.home() / ".agentihooks" / "broadcast.json"))
 BROADCAST_MAX_MESSAGES: int = int(os.getenv("BROADCAST_MAX_MESSAGES", "50"))
-BROADCAST_CRITICAL_ON_PRETOOL = _env_bool("BROADCAST_CRITICAL_ON_PRETOOL", "true")
-BROADCAST_PRETOOL_MIN_SEVERITY: str = os.getenv("BROADCAST_PRETOOL_MIN_SEVERITY", "alert")
+# Default OFF — alert-tier broadcasts on every PreToolUse is a #34713
+# contamination vector ("Hook Error"-shaped injections erode model
+# confidence at scale). Operators on incident response can opt back in via
+# ~/.agentihooks/.env.
+BROADCAST_CRITICAL_ON_PRETOOL = _env_bool("BROADCAST_CRITICAL_ON_PRETOOL", "false")
+# PreToolUse threshold raised to "critical" so only true-emergency
+# broadcasts fire on every tool call. Routine alerts still land via
+# UserPromptSubmit.
+BROADCAST_PRETOOL_MIN_SEVERITY: str = os.getenv("BROADCAST_PRETOOL_MIN_SEVERITY", "critical")
 
 # Cadence controls — skip re-injecting identical or too-frequent broadcasts per session.
 BROADCAST_DEDUP_BY_HASH = _env_bool("BROADCAST_DEDUP_BY_HASH", "true")
@@ -365,6 +372,12 @@ def _env_bool(key: str, default: str = "false") -> bool:
 # Per-prompt cap. Raised 2→6→8 so brain feed (5 entries) + amygdala (1-2)
 # + profile transitions all land in the same prompt without contention.
 BROADCAST_MAX_PER_PROMPT: int = int(os.getenv("BROADCAST_MAX_PER_PROMPT", "8"))
+# Per-injection byte caps. Claude Code's additionalContext has a 10,000-char
+# hard limit; exceeding it makes the harness write to a temp file and the
+# model receives a filepath instead of the body. Cap below the limit with
+# envelope headroom.
+BROADCAST_MAX_BYTES_PRETOOL: int = int(os.getenv("BROADCAST_MAX_BYTES_PRETOOL", "0"))
+BROADCAST_MAX_BYTES_PROMPT: int = int(os.getenv("BROADCAST_MAX_BYTES_PROMPT", "0"))
 BROADCAST_PERSISTENT_THROTTLE = _env_bool("BROADCAST_PERSISTENT_THROTTLE", "true")
 BROADCAST_DELIVERY_STATE_FILE: str = os.getenv(
     "BROADCAST_DELIVERY_STATE_FILE",
@@ -433,6 +446,18 @@ def _resolve_manifesto_path() -> str:
 
 
 CI_MANIFESTO_PATH: str = _resolve_manifesto_path()
+# Optional cap on the bytes the manifesto inject contributes to SessionStart /
+# UserPromptSubmit. 0 (default) = no cap; full doctrine ships through. Set
+# >0 to opt in to truncation when stacking multiple injections under
+# Claude Code's documented 10,000-char hook output limit.
+CI_MANIFESTO_MAX_BYTES: int = int(os.getenv("CI_MANIFESTO_MAX_BYTES", "0"))
+# When True, ci_manifesto.inject_on_session_start fires on every session
+# start (legacy behavior — emits 36 KB+ on stdout, hits Claude Code's 2 KB
+# persisted-output preview cap, manifesto silently truncated to filepath).
+# Default False — manifesto is now appended to ~/.claude/CLAUDE.md by
+# `agentihooks init` and loaded through the memory channel (no hook cap,
+# no per-session cost). Flip to True to restore the old runtime injection.
+CI_MANIFESTO_RUNTIME_INJECT: bool = _env_bool("CI_MANIFESTO_RUNTIME_INJECT", "false")
 CI_MANIFESTO_REFRESH_EVERY: int = int(os.getenv("CI_MANIFESTO_REFRESH_EVERY", "8"))
 
 # Auto dev-switch — at SessionStart, if cwd is on main/master, switch to dev.