Docs: hooks that fail closed also block on answers they cannot read

Author: chandan25809-lyzr

README.md

@@ -512,7 +512,7 @@ The same shape is available from the command line: `gitagent -p "..." --output-f
 gitagent 3 replaces the TypeScript packages (1.x and 2.x) with one binary. What carries over unchanged:
 
 - **Agent folders.** `agent.yaml`, `SOUL.md`, `RULES.md`, `memory/`, `skills/`, `tools/`, `hooks/`, `schedules/`, `workflows/`, `agents/`, `config/` and `.env` are read as they were. 1.x settings such as `tools: [cli, read, write, memory]`, `runtime.timeout` and the 1.x `compliance` shape are accepted; `gitagent validate` points out the newer spelling as a warning, never an error.
-- **Hook scripts.** They get the same JSON and answer the same way; output that is not an answer, or a script that crashes, allows the action with a warning, as before.
+- **Hook scripts.** They get the same JSON and answer the same way; output that is not an answer, or a script that crashes, allows the action with a warning, as before. Only hooks marked `compliance: true` or `fail_open: false`, which are new, block in those cases.
 - **The CLI.** `gitagent`, `-p`, `-d`, `-m`, `-e`, `--repo`, `--pat`, `--session` and the REPL's slash commands work as before.
 - **SDK code.** `query()`, `tool()`, hooks, `steer()`, `abort()`, the message types and the `repo` option are the same; the TypeScript package now needs the `gitagent` binary installed.
 

docs/HOW-IT-WORKS.md

@@ -138,6 +138,6 @@ A vote from a task raises a lesson's importance only the first time that task vo
 
 **Memory** is files in `memory/`, with layers and line limits from `memory/memory.yaml`. The `memory` tool's `save` appends an addition; a save that sends the whole memory back with edits, carrying at least 60% of the existing lines, replaces the file, as gitagent 1.x did; overflow beyond a layer's limit is archived to `memory/archive/`. Each save is a git commit when the agent directory is a repository.
 
-**Hooks** are scripts in `hooks/hooks.yaml` for seven events (session start and end, before and after a tool call, a changed file, before the reply, on error) plus 1.x's `user_prompt_submit`. Each gets JSON on stdin and answers `{"action": "allow" | "block" | "modify", ...}`; a script that prints something else allows, and one that crashes or times out is a warning unless it is marked `compliance: true` or `fail_open: false`, in which case it blocks. The same protocol serves the SDKs' in-process hooks over the IPC stream.
+**Hooks** are scripts in `hooks/hooks.yaml` for seven events (session start and end, before and after a tool call, a changed file, before the reply, on error) plus 1.x's `user_prompt_submit`. Each gets JSON on stdin and answers `{"action": "allow" | "block" | "modify", ...}`; a script that prints something else allows, and one that crashes or times out is a warning. A hook marked `compliance: true` or `fail_open: false` fails closed instead: a crash, a timeout or an answer it cannot read blocks the action. The same protocol serves the SDKs' in-process hooks over the IPC stream.
 
 **Approvals** come from `agent.yaml`'s compliance section: human-in-the-loop rules, escalation triggers by tool, kill switch, segregation of duties, spending limits with a monthly ledger in `.gitagent/state.json`. A gated call pauses the run until a person answers, at the terminal, through the SDK's approver, or by a timeout policy.