feat: add Codex-style lifecycle hooks (#10)

* feat: add hook support

* fix: preserve hook exit code on drain timeout

* feat: add explicit hook environment forwarding

Allow hook configs to forward named parent environment variables and define literal hook environment values while preserving the cleared-env default for credentials.

* fix: close turn event channel after agent completes

Drop the outer tool runtime context before waiting for the event-drain future so the mpsc channel closes once the agent future returns. This lets turns finish, save transcripts, run stop hooks, and return to raw input mode.

* fix: keep hidden reasoning from splitting responses

Ignore reasoning deltas for response layout when the reasoning panel is disabled. This prevents models that stream thinking fields from repeatedly closing and reopening the visible response block.

* style: satisfy clippy field_reassign_with_default in session_turn test

Author: dedene

.env.example

@@ -65,3 +65,10 @@ AGENT_MAX_STEPS=20
 # Skip the background GitHub release check. Only outbound call the harness
 # makes that isn't user-initiated; opt out if you want zero network at idle.
 # SMALL_HARNESS_NO_UPDATE_CHECK=true
+
+# Ephemeral managed hooks for process-owning launchers such as terminal
+# orchestrators or agent status dashboards. These must be exported in the
+# launcher process; repo .env files are intentionally ignored for managed hooks.
+# Prefer the file form for larger hook documents to avoid shell quoting JSON.
+# SMALL_HARNESS_MANAGED_HOOKS_FILE=/tmp/agent-status-hooks.json
+# SMALL_HARNESS_MANAGED_HOOKS_JSON={"source":"terminal-orchestrator","hooks":{}}

CHANGELOG.md

@@ -6,6 +6,29 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+### Added
+
+- **Hooks.** `agent.config.json` can define trusted command hooks for session,
+  prompt, tool, permission, plan, stop, and session-end events. Hooks receive
+  JSON on stdin, can block/allow/deny/stop, add context or feedback, and are
+  traced quietly unless they warn or affect execution. Project hooks run only
+  after their current hash is trusted in user-owned state; project-controlled
+  hook state is ignored for execution safety. `/hooks` lists and manages trust
+  state stored under `~/.config/small-harness/`.
+- **Managed launch hooks.** Launchers can inject ephemeral trusted hooks with
+  `SMALL_HARNESS_MANAGED_HOOKS_JSON` or
+  `SMALL_HARNESS_MANAGED_HOOKS_FILE`, enabling terminal/orchestrator
+  status and progress integrations without mutating user config. These are
+  process-local launcher-trusted hooks, not cryptographically signed hooks or
+  Codex enterprise-managed hooks. Hook commands can now use `envVars` to
+  forward selected parent process variables and `env` for literal values,
+  while keeping parent credentials absent by default.
+- **Hook hardening.** Gating hook runner failures now fail closed, invalid
+  matchers are visible but skipped, regex matchers use full-match semantics,
+  `task` uses the dedicated subagent hook events without generic `PostToolUse`,
+  hook subprocesses use process-group cleanup on timeout, and hook-provided
+  model context is bounded and redacted before injection.
+
 ## [1.0.4] - 2026-06-20
 
 ### Added

README.md

@@ -356,6 +356,7 @@ this exact call`. The session cache resets on `/new`.
 /reasoning on|off      toggle the streaming reasoning panel
 /verbose on|off        show every tool call with its full args + result
 /trace on|off          show nested subagent/critic tool calls (indented)
+/hooks                 list, trust, enable, or disable configured hooks
 /compare [model]       re-send the last prompt against OpenRouter for A/B
 /fusion on|tool|off    use OpenRouter Fusion alias or attach Fusion to a model
 /route select|apply    select or apply a configured multi-model stack route
@@ -592,6 +593,151 @@ Small Harness spawns each server at startup, lists its tools, and exposes
 them through the same approval-gated tool layer with names like
 `mcp__fs__read_file`. JSON-RPC over stdio; no extra dependencies.
 
+### Hooks
+
+Hooks let trusted local commands observe or influence harness events. They are
+useful for terminal integrations, status tracking, policy checks, and progress
+bridges for launchers, terminal orchestrators, and agent status dashboards.
+
+Project hooks live in `agent.config.json`:
+
+```json
+{
+  "hooks": {
+    "PlanUpdated": [
+      {
+        "hooks": [
+          { "type": "command", "command": "$HOME/bin/agent-plan-hook" }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "shell|file_write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$HOME/bin/check-tool-policy",
+            "timeoutSec": 5
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Command hooks receive a JSON payload on stdin and may print JSON on stdout:
+
+```json
+{ "decision": "block", "reason": "shell command not allowed" }
+```
+
+Supported decisions are `allow`, `deny`, `block`, and `stop`. Hooks can also
+return `additionalContext`, `updatedInput`, or `feedback`. For `PreToolUse`,
+`updatedInput` is honored only with `{"decision":"allow"}` and is discarded if
+any hook blocks, denies, or stops. Exit code `2` maps to a blocking decision using
+stderr as the reason. For `PreToolUse` and `PermissionRequest`, hook runner
+failures such as timeouts, spawn/pipe failures, and shell infrastructure exits
+`126`/`127` fail closed and block gated execution; ordinary nonzero exits still
+warn unless the hook explicitly blocks. A pre-execution `stop` prevents other
+pending tool calls in the same assistant step from running; a `PostToolUse` stop
+applies after that tool has already run and stops the next model step.
+
+Hook events include `SessionStart`, `UserPromptSubmit`, `PreToolUse`,
+`PermissionRequest`, `PostToolUse`, `PreCompact`, `PostCompact`,
+`PlanUpdated`, `SubagentStart`, `SubagentStop`, `Stop`, and `SessionEnd`.
+Payloads include common fields such as `hook_event_name`, `session_id`,
+`turn_id`, `cwd`, `workspace_root`, `transcript_path`, `events_path`, `backend`,
+`model`, `approval_policy`, and `source`, plus event-specific fields like
+`tool_name`, `tool_input`, `tool_response`, and `progress`. `source` is
+`interactive`, `one-shot`, `auto`, `fix`, `iterate`, or `play` depending on
+what started the turn.
+
+Hook payload stdin is raw and unredacted so trusted hooks can make decisions on
+the actual prompt/tool data; do not log it unless your hook performs its own
+redaction. Hook child processes start with a cleared environment and receive the
+minimal inherited shell environment (`PATH`, `HOME` or Windows home/system vars),
+explicit parent process variables listed in `envVars`, literal values from
+`env`, plus `SMALL_HARNESS_HOOK_EVENT`, `SMALL_HARNESS_SESSION_ID`,
+`SMALL_HARNESS_TURN_ID`, `SMALL_HARNESS_TRANSCRIPT_PATH`, and
+`SMALL_HARNESS_EVENTS_PATH`. Parent LLM provider credentials are not passed
+through unless a hook explicitly names them in `envVars`.
+
+Matchers are Codex-style: absent, empty, or `*` matches all; exact `|`
+alternation matches tool/event names; other matchers are treated as full-match
+regexes. Use `.*` when partial regex matching is intended. Invalid matcher
+regexes are shown by `/hooks` and skipped. `UserPromptSubmit`, `PlanUpdated`,
+`Stop`, and `SessionEnd` ignore matchers. The default hook timeout is 600
+seconds for Codex parity; status/progress hooks should set a shorter
+`timeoutSec` if a slow hook would make the turn feel stuck.
+
+The `task` tool uses `SubagentStart` and `SubagentStop`; it does not also run
+generic `PostToolUse` hooks. `Stop` hook `additionalContext` and `feedback` are
+bounded, redacted, and added as context for the next turn.
+
+`PermissionRequest` runs only when the harness would otherwise ask for approval.
+Use `PreToolUse` for blanket policy gates that must also cover auto-approved or
+read-only tools.
+
+Project hooks are skipped until their current hash is trusted in user-owned
+state. Project-controlled `hooks.state` entries are ignored for execution
+safety. Manage trust with:
+
+```text
+/hooks                         list hooks and trust state
+/hooks trust <key>             trust one hook hash in user state
+/hooks trust-all               trust all new/modified hooks
+/hooks disable <key>           disable one hook
+/hooks enable <key>            enable one hook
+```
+
+Trust is stored in `$XDG_CONFIG_HOME/small-harness/hooks-state.json`, falling
+back to `~/.config/small-harness/hooks-state.json`. Trusted hook successes are
+quiet in the normal TUI; warnings, blocks, denies, stops, and feedback are
+shown. The event log records hook start/end/decision records with redacted,
+bounded stdout/stderr previews.
+
+Launchers can inject ephemeral managed launch hooks without changing user
+config:
+
+```bash
+SMALL_HARNESS_MANAGED_HOOKS_FILE="$TMPDIR/agent-status-hooks.json" small-harness
+```
+
+`SMALL_HARNESS_MANAGED_HOOKS_JSON` accepts the same document inline for small
+launchers. Managed launch hooks are not cryptographic signatures or Codex
+enterprise-managed hooks; they are process-local launcher-trusted commands for
+wrappers that own the process invocation. Small Harness intentionally reads
+these only from the real process environment, not repo `.env` files. This lets
+integrations observe status without mutating the user's config.
+
+Use `envVars` when a managed hook command needs launcher state:
+
+```json
+{
+  "source": "terminal-orchestrator",
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "zentty ipc agent-event",
+            "envVars": [
+              "ZENTTY_INSTANCE_SOCKET",
+              "ZENTTY_WORKLANE_ID",
+              "ZENTTY_PANE_ID",
+              "ZENTTY_PANE_TOKEN"
+            ]
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
 ### Image input
 
 `/image <path>` attaches an image to your next prompt. Small Harness encodes
@@ -703,6 +849,8 @@ AGENT_TOOL_SELECTION=auto                               # auto | fixed
 WARMUP=true                                             # pre-warm prompt cache at startup
 SMALL_HARNESS_NO_WIZARD=false                           # skip first-run setup
 SMALL_HARNESS_NO_UPDATE_CHECK=false                     # skip the GitHub release check
+SMALL_HARNESS_MANAGED_HOOKS_JSON='{"source":"terminal-orchestrator","hooks":{...}}'
+SMALL_HARNESS_MANAGED_HOOKS_FILE=/tmp/agent-status-hooks.json
 ```
 
 Full list with comments in [`.env.example`](.env.example).
@@ -795,6 +943,11 @@ root. Common shape:
   },
   "mcpServers": {
     "fs": { "command": "/usr/local/bin/some-mcp-server", "args": [] }
+  },
+  "hooks": {
+    "PlanUpdated": [
+      { "hooks": [{ "type": "command", "command": "$HOME/bin/plan-hook" }] }
+    ]
   }
 }
 ```