Add request hook system

Author: GuthL

AGENTS.md

@@ -47,6 +47,7 @@ API response → KeyClaw Proxy → scan for {{KEYCLAW_SECRET_<prefix>_<16 hex ch
 | Module | Purpose | Key Types |
 |--------|---------|-----------|
 | `gitleaks_rules.rs` | Bundled gitleaks rule loading + compiled regex matching | `RuleSet` |
+| `hooks.rs` | Configured request-side hook parsing and execution | `HookRunner` |
 | `pipeline.rs` | Orchestrates rewrite + policy evaluation | `Processor`, `RewriteResult` |
 | `placeholder.rs` | Placeholder parsing, generation, and resolution | `make_id()`, `resolve_placeholders()` |
 | `redaction.rs` | JSON tree walker, notice injection | `walk_json_strings()`, `inject_redaction_notice()` |
@@ -87,6 +88,10 @@ Edit `src/launcher.rs` to extend the clap surface and subcommand dispatch, then
 
 Edit `src/redaction.rs` → `inject_redaction_notice_with_mode()` and `src/config.rs` for `KEYCLAW_NOTICE_MODE`. The notice is injected differently for Anthropic (appended to `system` field) vs OpenAI (added as `developer` role message), and the shipped modes are `verbose`, `minimal`, and `off`.
 
+### Adding or changing hooks
+
+Edit `src/hooks.rs` for hook parsing/execution and `src/config.rs` for `[[hooks]]` config loading. Request-side hook dispatch is wired through `src/pipeline.rs`, with call sites in `src/proxy/http.rs`, `src/proxy/websocket.rs`, and `src/launcher.rs`.
+
 ## Important Patterns
 
 ### Placeholder format
@@ -125,6 +130,7 @@ All errors use `KeyclawError` with optional deterministic codes:
 - `invalid_json` — JSON parse/rewrite failed
 - `request_timeout` — request body read timed out before inspection completed
 - `strict_resolve_failed` — placeholder resolution failed in strict mode
+- `hook_blocked` — a configured hook rejected the request
 
 Check errors with `code_of(&err)` to get the code string.
 

CLAUDE.md

@@ -47,6 +47,7 @@ API response → KeyClaw Proxy → scan for {{KEYCLAW_SECRET_<prefix>_<16 hex ch
 | Module | Purpose | Key Types |
 |--------|---------|-----------|
 | `gitleaks_rules.rs` | Bundled gitleaks rule loading + compiled regex matching | `RuleSet` |
+| `hooks.rs` | Configured request-side hook parsing and execution | `HookRunner` |
 | `pipeline.rs` | Orchestrates rewrite + policy evaluation | `Processor`, `RewriteResult` |
 | `placeholder.rs` | Placeholder parsing, generation, and resolution | `make_id()`, `resolve_placeholders()` |
 | `redaction.rs` | JSON tree walker, notice injection | `walk_json_strings()`, `inject_redaction_notice()` |
@@ -87,6 +88,10 @@ Edit `src/launcher.rs` to extend the clap surface and subcommand dispatch, then
 
 Edit `src/redaction.rs` → `inject_redaction_notice_with_mode()` and `src/config.rs` for `KEYCLAW_NOTICE_MODE`. The notice is injected differently for Anthropic (appended to `system` field) vs OpenAI (added as `developer` role message), and the shipped modes are `verbose`, `minimal`, and `off`.
 
+### Adding or changing hooks
+
+Edit `src/hooks.rs` for hook parsing/execution and `src/config.rs` for `[[hooks]]` config loading. Request-side hook dispatch is wired through `src/pipeline.rs`, with call sites in `src/proxy/http.rs`, `src/proxy/websocket.rs`, and `src/launcher.rs`.
+
 ## Important Patterns
 
 ### Placeholder format
@@ -125,6 +130,7 @@ All errors use `KeyclawError` with optional deterministic codes:
 - `invalid_json` — JSON parse/rewrite failed
 - `request_timeout` — request body read timed out before inspection completed
 - `strict_resolve_failed` — placeholder resolution failed in strict mode
+- `hook_blocked` — a configured hook rejected the request
 
 Check errors with `code_of(&err)` to get the code string.
 

README.md

@@ -366,9 +366,27 @@ include = ["*my-custom-api.com*"]
 rule_ids = ["generic-api-key"]
 patterns = ["^sk-test-"]
 secret_sha256 = ["0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"]
+
+[[hooks]]
+event = "secret_detected"
+rule_ids = ["aws-access-key", "generic-api-key"]
+action = "exec"
+command = "notify-slack --channel security"
+
+[[hooks]]
+event = "request_redacted"
+rule_ids = ["*"]
+action = "log"
+path = "~/.keyclaw/hooks.log"
+
+[[hooks]]
+event = "secret_detected"
+rule_ids = ["generic-api-key"]
+action = "block"
+message = "production key detected"
 ```
 
-Supported file sections today are `proxy`, `vault`, `logging`, `notice`, `detection`, `audit`, `hosts`, and `allowlist`. Use the file for steady-state local settings, then reach for env vars when you want a one-off override.
+Supported file sections today are `proxy`, `vault`, `logging`, `notice`, `detection`, `audit`, `hosts`, `allowlist`, and `hooks`. Use the file for steady-state local settings, then reach for env vars when you want a one-off override.
 
 Allowlist entries let you intentionally skip redaction for known-safe matches:
 
@@ -389,6 +407,16 @@ Disable persistent audit logging with:
 path = "off"
 ```
 
+Hook entries let you trigger local side effects from request-side events without exposing the raw secret:
+
+- `event = "secret_detected"` fires when a secret match is found during request rewriting
+- `event = "request_redacted"` fires after a request has been rewritten, just before it is forwarded upstream
+- `action = "exec"` runs a local command with sanitized metadata in env vars and a JSON payload on `stdin`
+- `action = "log"` appends a JSON line to the configured file
+- `action = "block"` rejects matching `secret_detected` requests with `hook_blocked`
+
+Hook payloads include only `event`, `rule_id`, `placeholder`, and `request_host`. Raw secret values are never passed to hook commands or hook log files.
+
 ### Environment Variables
 
 | Variable | Default | Description |
@@ -488,6 +516,7 @@ KeyClaw uses deterministic error codes for programmatic handling:
 | `invalid_json` | Failed to parse or rewrite request JSON |
 | `request_timeout` | Request body read timed out before inspection completed |
 | `strict_resolve_failed` | Placeholder resolution failed in strict mode |
+| `hook_blocked` | A configured hook rejected the request |
 
 ## Security Model
 
@@ -522,6 +551,7 @@ src/
 ├── config.rs          # Env + TOML configuration
 ├── entropy.rs         # High-entropy token detection
 ├── gitleaks_rules.rs  # Bundled gitleaks rule loading + native regex compilation
+├── hooks.rs           # Configured request-side hook execution
 ├── pipeline.rs        # Request rewrite pipeline
 ├── placeholder.rs     # Placeholder parsing, generation, and resolution
 ├── redaction.rs       # JSON walker + notice injection

src/config.rs

@@ -12,6 +12,7 @@ use std::time::Duration;
 use serde::Deserialize;
 
 use crate::allowlist::Allowlist;
+use crate::hooks::{Hook, RawHookConfig};
 use crate::logging::LogLevel;
 use crate::redaction::NoticeMode;
 
@@ -63,6 +64,8 @@ pub struct Config {
     pub audit_log_path: Option<PathBuf>,
     /// Operator-defined allowlist entries.
     pub allowlist: Allowlist,
+    /// Configured request-side hook actions.
+    pub hooks: Vec<Hook>,
     pub(crate) config_file_status: ConfigFileStatus,
 }
 
@@ -84,6 +87,7 @@ struct FileConfig {
     audit: FileAuditConfig,
     hosts: FileHostsConfig,
     allowlist: FileAllowlistConfig,
+    hooks: Vec<RawHookConfig>,
 }
 
 #[derive(Debug, Default, Deserialize)]
@@ -229,6 +233,7 @@ impl Config {
             entropy_min_len: 20,
             audit_log_path: Some(crate::audit::default_audit_log_path()),
             allowlist: Allowlist::default(),
+            hooks: Vec::new(),
             config_file_status: ConfigFileStatus::Missing(default_config_path()),
         }
     }
@@ -351,6 +356,8 @@ impl Config {
             &file_cfg.allowlist.secret_sha256,
         )
         .map_err(|err| format!("config file {} has invalid {err}", path.display()))?;
+        self.hooks = crate::hooks::parse_hooks(&file_cfg.hooks)
+            .map_err(|err| format!("config file {} has invalid {err}", path.display()))?;
 
         Ok(())
     }

src/errors.rs

@@ -14,6 +14,8 @@ pub const CODE_INVALID_JSON: &str = "invalid_json";
 pub const CODE_REQUEST_TIMEOUT: &str = "request_timeout";
 /// Error code returned when strict placeholder resolution cannot complete.
 pub const CODE_STRICT_RESOLVE_FAILED: &str = "strict_resolve_failed";
+/// Error code returned when a configured hook blocks request processing.
+pub const CODE_HOOK_BLOCKED: &str = "hook_blocked";
 
 #[derive(Debug, Clone)]
 pub struct KeyclawError {