After every child agent completes, invoke_hook("subagent_stop", ...)
fires once with parent_session_id, child_role, child_summary,
child_status, and duration_ms.

Firing happens on the parent thread after as_completed() drains the
futures, not on the worker threads that ran the children. Hook
callbacks never see concurrent invocation.

child_role reads child._delegate_role via a defensive getattr so this
works without depending on the orchestrator-role work. The value is
stashed on each entry dict before child.close() runs in the finally
block, then stripped again before delegate_task serialises its result
to JSON.

Shell-script hooks declared in the hooks: block of cli-config.yaml.
Each entry becomes a plugin-hook callback via
agent.shell_hooks.register_from_config(), so every existing
invoke_hook() site dispatches to the configured script with no
additional wiring on the caller side.

Wire protocol: JSON payload on stdin, optional JSON response on
stdout. For pre_tool_call the Claude-Code-style
{"decision": "block", "reason": str} payload is translated to the
canonical Hermes {"action": "block", "message": str} shape so that
get_pre_tool_call_block_message() surfaces the block. This is the one
correctness invariant the test suite gates on.

First-use consent prompts on a TTY and persists approvals to
~/.hermes/shell-hooks-allowlist.json with the script mtime captured
at approval time (used later by `hermes hooks doctor` for drift
detection). Non-TTY runs need --accept-hooks, HERMES_ACCEPT_HOOKS=1,
or hooks_auto_accept: true.

Subprocess execution uses shlex.split + shell=False, default 60s
timeout, capped at 300s. Registration is idempotent per
(event, command) pair so CLI and gateway startup can both call
register_from_config() in the same process.

hermes_cli/main.py calls register_from_config() at startup, gated to
commands that actually run the agent (chat, gateway, acp, mcp, cron,
rl). Introspection-only commands skip registration so
`hermes hooks list` never triggers a consent prompt for a hook the
user is still inspecting.

gateway/run.py calls register_from_config() right before
self.hooks.discover_and_load() at the existing startup point.

Adds --accept-hooks on the top-level parser and the chat subparser,
following the --worktree pattern.

Adds the hermes hooks subcommand group:

- list          configured hooks with matcher, timeout, consent
- test <event>  fire matching hooks against a synthetic payload
- revoke <cmd>  drop allowlist entries
- doctor        check exec bit, allowlist, mtime drift, JSON output

Also adds a commented hooks: example block to
cli-config.yaml.example.

New Shell Hooks section covers the concept, a three-way comparison
table (shell vs plugin vs gateway), the JSON wire protocol with the
Claude-Code-to-canonical block translation, four worked examples
(auto-format, block-rm-rf, inject-cwd-context, log-orchestration),
the consent model, and the hermes hooks CLI.

New subagent_stop entry in the plugin hooks reference with the
callback signature, payload fields, and a logging example.

Also reconciles the two places that claimed pre_tool_call return
values are always ignored — get_pre_tool_call_block_message actually
acts on {"action": "block", "message": str}. Intro paragraph,
quick-reference table, and pre_tool_call detail section updated.

save_allowlist() wrote to a fixed `shell-hooks-allowlist.json.tmp`
path and _record_approval() did read-modify-write without any lock,
so two concurrent CLI / gateway processes calling the consent path
raced two ways: os.replace() hit ENOENT when one writer's temp file
got moved out from under another, and the read-modify-write clobbered
entries because whichever writer finished last overwrote the other's
snapshot. A 50-way stress run kept only 2/50 approvals before this
change.

save_allowlist() now uses tempfile.mkstemp() for a per-process unique
temp file inside ~/.hermes and cleans it up on failure, so concurrent
writers never collide on the staging path. _record_approval() and
revoke() now run their read-modify-write inside
_locked_update_approvals(), which holds an exclusive fcntl.flock on
~/.hermes/shell-hooks-allowlist.json.lock for the duration of the
update. Same 50-way stress run now preserves all 50 approvals.

The non-POSIX fallback uses a dedicated _allowlist_write_lock rather
than _registered_lock, because register_from_config() already holds
_registered_lock when it triggers _record_approval() via the consent
prompt path — reusing it would self-deadlock on threading.Lock
(non-reentrant). Regression test confirms: fails with a 3 s timeout
against the shared-lock variant, passes against the dedicated lock.

Three new tests under TestAllowlistConcurrency:

- test_parallel_record_approval_does_not_lose_entries — 32 threads
  race through _record_approval behind a Barrier, asserts all 32
  entries land.
- test_save_allowlist_uses_unique_tmp_paths — spies on
  tempfile.mkstemp and asserts successive save_allowlist() calls
  pick distinct temp paths.
- test_non_posix_fallback_does_not_self_deadlock — monkeypatches
  fcntl to None, runs _record_approval while holding
  _registered_lock in a daemon thread, bounds the wait via
  threading.Event.wait(timeout=3).

Side effect: tempfile.mkstemp defaults to 0o600, so the allowlist
file now lands with user-only permissions instead of whatever the
default umask would have given it.

`hermes hooks doctor` ran the synthetic-payload smoke test against
every configured hook regardless of allowlist status. That directly
undermined the workflow documented in hooks.md — "re-run
`hermes hooks doctor` after you pull a shared config to spot
newly-added hooks *before they register*" — because doctor itself
executed every listed script before reporting the "✗ not allowlisted"
status.

_doctor_one now skips check #4 (produces valid JSON on a synthetic
payload) for any entry without an allowlist record, and prints an
explicit "ℹ skipped JSON smoke test — not allowlisted yet" note
instead. Allowlisted entries still run the smoke test unchanged, so
the drift-detection workflow continues to work.

New test_unallowlisted_script_is_not_executed uses a sentinel-file
pattern: the hook script would touch a file on disk if spawned, and
the test asserts the file does not exist after running doctor.

`hermes hooks test pre_api_request` fed scripts a stdin carrying
only {"session_id": "test-session"}, while the real firing site at
run_agent.py passes task_id, platform, model, provider, base_url,
api_mode, api_call_count, message_count, tool_count,
approx_input_tokens, request_char_count, max_tokens — and
post_api_request additionally passes api_duration, finish_reason,
response_model, usage, assistant_content_chars, and
assistant_tool_call_count. A script validated under `hooks test`
could then break in production on a key that `hooks test` never
surfaced.

Replace the one-key synthetic dict for each of pre_api_request and
post_api_request in _DEFAULT_PAYLOADS with realistic kwargs mirroring
the invoke_hook() call sites. Uses claude-sonnet-4-6 for the model
field to match a typical Hermes provider rather than the previous
gpt-4 placeholder.

A hook command like ``python3 /path/hook.py`` or ``bash hook.sh`` is
valid: ``_spawn`` runs it via ``shlex.split`` + ``subprocess.run(...,
shell=False)`` and it executes fine.  But the inspection helpers
``script_is_executable`` and ``script_mtime_iso`` ran
``_command_script_path`` which returned only the first shlex token,
so they ended up checking ``python3`` or ``bash`` against the on-disk
path rather than the script the user actually cares about.

Consequences visible to the user:

- ``hermes hooks doctor`` reported ``✗ script missing or not
  executable`` for every interpreter-prefixed hook, even when the
  script ran successfully at runtime.
- The "modified since approval" drift check tracked the mtime of the
  interpreter (which basically never changes) instead of the script,
  so real script edits after approval went undetected.

Rewrite ``_command_script_path`` with three-step resolution:
prefer tokens ending in a known script extension
(``.sh``/``.py``/``.rb``/...), fall back to the first token
containing a path separator or leading ``~``, fall back to the first
token for bare names.  That handles the common cases — plain script
paths, ``INTERP SCRIPT`` invocations, ``/usr/bin/env INTERP SCRIPT``
shebangs, and interpreter flags like ``python3 -u /path/hook.py`` —
while preserving the existing behaviour for bare executables like
``/bin/echo hi``.

Parametric regression test in ``TestAllowlistConcurrency`` covers 15
commands spanning every resolution branch.

``register_from_config`` acquired ``_registered_lock`` per spec and
then, inside that critical section, called ``_prompt_and_record``
which issues a blocking ``input()`` on the TTY.  Any other thread
that reached ``register_from_config`` parked on the lock until the
user answered the prompt — even if it was trying to register a
completely different spec that wouldn't have prompted at all.

Single-threaded startup callers (CLI ``main()`` and
``GatewayRunner.start()``) make this benign today, but the shape of
the code defeats the very reason the lock is there.  Flagged in
three consecutive review rounds.

Split the critical section: the lock now wraps only the idempotence
check (+ allowlist read) at the top of the loop and the mutation
(appending the callback, updating ``_registered``) at the bottom.
The TTY prompt runs outside the lock.  A defensive re-check on the
idempotence key inside the second lock section keeps double
registration from landing if a future caller parallelises this path
— two threads that both clear the prompt for the same spec would
otherwise each append a duplicate callback.

Also tightens the "not allowlisted" warning message: the previous
``Run hermes hooks list`` recommendation doesn't actually approve
anything; the three real opt-in channels are ``--accept-hooks``,
``HERMES_ACCEPT_HOOKS=1``, and ``hooks_auto_accept: true``.

Two user-facing diagnostic gaps:

``matcher:`` is only consulted for ``pre_tool_call`` /
``post_tool_call`` — the runtime callback ignores it for every other
event.  Misconfigured hooks like

    pre_llm_call:
      - matcher: "terminal"
        command: ~/hook.sh

used to parse silently and then fire on every LLM call regardless of
the matcher string, which is the opposite of what the user wanted.
``hermes hooks list`` even printed the non-functional matcher back
as if it were active.  ``_parse_single_entry`` now warns and drops
the matcher at parse time so the rendered spec matches runtime
behaviour.

When ``save_allowlist`` fails (disk full, read-only ``~/.hermes``,
permission denied) the caller already logged a generic warning, but
the message didn't tell the user what that meant for the next run
— the approval lands in the in-memory ``_registered`` set and the
hook registers for the current process, yet the next startup
re-prompts because the approval never hit disk.  Without context
the symptom looks like "hermes keeps asking me about the same hook".
Expand the warning to include the allowlist path, the errno, and
the re-prompt caveat explicitly.

Tests:

- ``test_non_tool_event_matcher_warns_and_drops`` — configures a
  matcher on ``pre_llm_call`` and asserts the spec's matcher ends up
  ``None`` and a warning containing ``pre_llm_call`` and
  "only honored for pre_tool_call" is emitted.
- ``test_save_allowlist_failure_logs_actionable_warning`` —
  monkeypatches ``tempfile.mkstemp`` to raise ``OSError(28)``,
  confirms the warning names the file path, the errno message, and
  the re-prompt behaviour.