projmux 0.16.0 → 0.16.1

package/docs/hooks.md

@@ -15,7 +15,7 @@ projmux-owned internal tmux hooks such as `pane-focus-in`, `pane-focus-out`,
 | `pre-create` | Before projmux creates a missing persistent or ephemeral session | Non-zero exit, exec error, or timeout aborts creation | Logged with `[pre-create] ` |
 | `post-create` | After projmux creates a brand-new persistent or ephemeral session | Logged and ignored; creation continues | Logged with `[post-create] ` |
 | `post-attach` | After projmux switches the current tmux client to an existing session/target from inside tmux | Logged and ignored | Logged with `[post-attach] ` |
-| `send-noti` | After `projmux create notification` (or the in-process AI notify producer) successfully writes a queue entry | Fired asynchronously and best-effort; queue write and desktop notifications continue even if the hook fails or times out | Receives JSON on stdin; stdout/stderr are logged with `[send-noti] ` |
+| `send-noti` | After `projmux create notification` (or the in-process AI notify producer) successfully writes a queue entry | Runs after the queue entry is written; the command waits until the hook exits or is killed at its timeout, and a failure or timeout is only a warning that changes neither the queue entry nor the exit code | Receives JSON on stdin; stdout/stderr are logged with `[send-noti] ` |
 
 Deferred Phase A candidates remain future work until their behavior can be
 specified without exposing projmux's internal tmux hook machinery: pane exit,
@@ -35,9 +35,18 @@ Project-local hooks are discovered from the lifecycle context's `PROJMUX_CWD`:
 <repo>/.projmux/config.toml
 ```
 
-File-form hooks from the historical `.projmux/<event>` and
-`.projmux/hooks/<event>` layouts are no longer executed. Use declarative
-`[hooks.<event>] run` entries instead.
+projmux reads `.projmux/config.toml` directly in that directory. It does not
+look in parent directories.
+
+For `send-noti`, that directory is resolved as described in
+[Send Noti](#send-noti-working-directory): when `PROJMUX_CWD` is not inherited, it is the nearest
+`.projmux` or `.git` root above the notifying process's working directory.
+
+File-form hooks from the historical global
+`${XDG_CONFIG_HOME:-$HOME/.config}/projmux/hooks/<event>` layout and the project
+`.projmux/<event>` and `.projmux/hooks/<event>` layouts are no longer executed.
+Use declarative `[hooks.<event>] run` entries instead. projmux converts or warns
+about these files; see [Troubleshooting](#troubleshooting).
 
 If both a global hook and a project-local hook exist for an event, projmux runs
 the global hook first, then the project-local hook.
@@ -145,8 +154,9 @@ session-level tmux environment before the startup command is sent. It does not
 run when projmux attaches to an existing session or target.
 
 Before sending the startup command, projmux polls tmux `pane_current_command`
-for the new pane and waits until it reports a shell command. This avoids fixed
-sleeps as the primary readiness mechanism.
+for the new pane and waits up to 2 seconds for it to report a shell command. If
+no shell appears in that time, the startup command is not sent. This avoids
+fixed sleeps as the primary readiness mechanism.
 
 The configured string is sent into the new pane:
 
@@ -162,9 +172,10 @@ An empty `[startup] run` is a no-op.
 already durable before the hook starts, so a failing or slow hook cannot drop
 the notification or block the normal desktop notification flow.
 
-The hook runs asynchronously with the same default timeout (`5s`) as other
-hooks. projmux does not wait for completion before returning from
-`projmux create notification`.
+The hook runs with the same default timeout (`5s`) as other hooks. projmux
+waits until the hook exits or is killed at that timeout before returning from
+`projmux create notification`; a failure or timeout is logged as a warning and
+does not change the exit code.
 
 stdin receives one JSON object:
 
@@ -204,6 +215,33 @@ If a `send-noti` hook itself calls `projmux create notification`, projmux sees
 `PROJMUX_NOTIFY_HOOK_DEPTH=1` in the child environment and skips another
 `send-noti` hook fire. The queue write itself still succeeds.
 
+### Send Noti Working Directory
+
+The `PROJMUX_CWD` a `send-noti` hook receives is resolved by the projmux
+process that queues the notification, whether that is
+`projmux create notification` or projmux queuing an AI agent notification, in
+this order:
+
+1. If that process's environment has a `PROJMUX_CWD` that is non-empty after
+   trimming whitespace, projmux uses the trimmed value as is. It does not walk
+   up for markers or check that the directory exists.
+2. Otherwise projmux reads its working directory and uses the nearest
+   directory, starting at the working directory itself and walking up to the
+   filesystem root, that contains a `.projmux` or `.git` entry (file or
+   directory).
+3. If no such directory exists, projmux uses the working directory itself.
+4. If the working directory cannot be read or is empty, the value is empty.
+
+The same value is the hook command's working directory and the only directory
+whose `.projmux/config.toml` is read for a project `send-noti` hook; projmux
+does not look in its parents. From a subdirectory of a repository, the project
+hook therefore comes from the repository root's `.projmux/config.toml`. When
+the value is empty, no project config is read and the hook runs in the
+dispatching process's working directory.
+
+A `projmux create notification` run from inside another hook inherits that
+hook's `PROJMUX_CWD`, so it takes rule 1.
+
 `Settings > Notifications > Delivery sources` surfaces the active Codex,
 Claude, Antigravity, and tmux AI notify diagnostics: status, conflicts, config
 paths, and copyable CLI install/remove/dry-run commands. It also shows whether
@@ -280,7 +318,7 @@ not semantic overrides.
 | `PreToolUse` | marks the matched pane hook-active and writes a quiet ingest diagnostic; no notify queue entry is pushed |
 | `UserPromptSubmit` | marks the matched pane hook-active and sets AI state to thinking/busy; no notify queue entry is pushed |
 | `PermissionRequest` | pushes a critical approval row with the tool name and a concise tool/action summary |
-| `PostToolUse` | marks the matched pane hook-active and writes a quiet ingest diagnostic; no notify queue entry is pushed |
+| `PostToolUse` | marks the matched pane hook-active and writes a quiet ingest diagnostic; no notify queue entry is pushed; while `agent-approval-answering` is `projmux` it also closes the one waiting permission request the terminal answered (see [below](#answering-claude-permission-requests-in-projmux)) |
 | `PreCompact` | marks the matched pane hook-active and writes a quiet ingest diagnostic; no notify queue entry is pushed |
 | `PostCompact` | marks the matched pane hook-active and writes a quiet ingest diagnostic; no notify queue entry is pushed |
 | `SessionStart` | marks the matched pane hook-active and writes a quiet ingest diagnostic; for an exact managed initial-task binding it records `pending` startup readiness and opens the separately bounded acknowledgement window, but never acknowledges the task; no notify queue entry is pushed |
@@ -495,7 +533,7 @@ default install catalog is based on Claude Code 2.1.140 and represents the
 | --- | --- |
 | `PreToolUse` | marks the matched pane hook-active and writes a quiet ingest diagnostic; no notify queue entry is pushed |
 | `PostToolUse` | marks the matched pane hook-active and writes a quiet ingest diagnostic; no notify queue entry is pushed |
-| `PostToolUseFailure` | marks the matched pane hook-active and writes a quiet ingest diagnostic; no notify queue entry is pushed |
+| `PostToolUseFailure` | marks the matched pane hook-active and writes a quiet ingest diagnostic; no notify queue entry is pushed; while `agent-approval-answering` is `projmux` it also closes the one waiting permission request the terminal answered (see [below](#answering-claude-permission-requests-in-projmux)) |
 | `PostToolBatch` | marks the matched pane hook-active and writes a quiet ingest diagnostic; no notify queue entry is pushed |
 | `PermissionDenied` | marks the matched pane hook-active and writes a quiet ingest diagnostic; no notify queue entry is pushed |
 | `Notification` | pushes a Claude notify row for response-ready, approval-required, or input-ready based on `notification_type` |
@@ -523,6 +561,15 @@ default install catalog is based on Claude Code 2.1.140 and represents the
 | `CwdChanged` | marks the matched pane hook-active and writes a quiet ingest diagnostic; no notify queue entry is pushed |
 | `FileChanged` | marks the matched pane hook-active and writes a quiet ingest diagnostic; no notify queue entry is pushed |
 
+`Stop` is the first transcript tail reader. It opens the `transcript_path` its
+own payload reports, reads at most the last 256 KiB, and keeps one string: the
+text of the last assistant line in that tail. That text becomes the completion
+row's text, so it goes wherever the row goes: the notify queue, the desktop
+notification (whose duplicate check keeps a normalized copy in a tmux pane
+option), and the `send-noti` payload. It is not written to the Registry or to
+the Agent session history, and nothing else the read saw is kept. With no
+readable path or no assistant text, the row text is `Ready`.
+
 Current Claude Code (2.1.277) sends no hook when the operator denies a
 permission dialog, so neither `PermissionDenied` nor `Stop` closes it and the
 Agent keeps its `approval_required` observation. The held coordination message
@@ -533,6 +580,17 @@ at each line's type, subtype, and timestamp and whether an assistant line has a
 `tool_use` item. Nothing it reads is stored, logged, or forwarded. See
 [held messages](claude-coordination-endpoints.md#held-while-the-target-awaits-its-operator).
 
+A permission dialog or an elicitation raises its Agent once, so the Agent's
+pane supervisor is a third transcript tail reader. While the Agent's
+interaction is a provider-hook `approval_required` or `input_required`, about
+every ten minutes it reads the same bounded tail of the Agent's own recorded
+`transcript_path`. While the turn has not ended and an assistant `tool_use`
+still has no `tool_result`, it recommits the same interaction, so an open
+dialog does not decay to `unknown` after thirty minutes. It looks only at each
+line's type, subtype, and timestamp, the `tool_use` ids, and the `tool_result`
+`tool_use_id`s. Nothing it reads is stored, logged, or forwarded. A denied or
+dismissed dialog ends the turn, and it stops.
+
 Hook-generated queue rows use the same compact body catalog: agent label,
 event category, then the best available summary (Codex assistant text, Claude
 tool/action summary, transcript summary, error, or teammate labels). Structured
@@ -546,9 +604,12 @@ Pane matching follows the shared AI ingest order: inherited `$TMUX_PANE`, then
 payload `cwd`, then cached session id pane options. A matched pane is marked
 with `@projmux_ai_hook_active=1`, so `projmux internal agent-hook watch-title` skips the pane
 after a minimal hook-active gate instead of polling pane title/capture output;
-hook payloads become the primary signal. The tmux bell fallback does not mark
-panes hook-active, so title/capture fallback remains available for panes that
-only emit bells.
+hook payloads become the primary signal. The hook reads the pane's current
+markers once and writes only the ones that differ, so a hook on an already
+marked pane sends tmux no `set-option`: every option write redraws all clients,
+and the first redraw of a second re-runs the status line's `#()` jobs. The tmux
+bell fallback does not mark panes hook-active, so title/capture fallback
+remains available for panes that only emit bells.
 
 The Claude hook payload is intentionally accepted directly at the ingest
 boundary. Core identity fields accept `hook_event_name`/`event_name`,
@@ -697,36 +758,131 @@ Codex and are managed from `Settings > Notifications > Agent event behavior`.
 They only affect ingest delivery; `projmux agent integrate claude` still uses the
 catalog `install` field for installed hook events.
 
-### Answering AskUserQuestion From The Command Line
+### Answering AskUserQuestion In projmux
 
 `projmux agent integrate claude` also installs one `PreToolUse` entry with
 `"matcher": "AskUserQuestion"` that runs
 `projmux internal claude-question-hook` (marker
-`projmux-managed:claude-question:v1`, `"timeout": 315`). Unlike the ingest
-command its stdout is not discarded, because that is where an answer is handed
-to Claude Code. Re-running the integration keeps exactly one such entry,
-`--remove` deletes it, and `config apply` never adds or changes it.
-
-The hook does nothing unless the Claude Agent that asks was opted in:
+`projmux-managed:claude-question:v1`, `"timeout"` the fixed ceiling `604800`
+seconds (7 days), which outlasts every answer window including `unlimited`;
+it is the safety net for a stuck hook, which has no recover, and is 7 times
+the longest bounded window, so it never cuts a normal one). Unlike the
+ingest command its stdout is not discarded, because that is where an answer is
+handed to Claude Code. Re-running the integration keeps exactly one such entry,
+`--remove` deletes it, and `config apply` never adds or changes it. An entry
+installed by an older projmux carries an old timeout, the window plus 15
+seconds (`915` by default) or the earlier, longer ceiling of about 25 days;
+run `projmux agent integrate claude` once after upgrading
+to rewrite it to the ceiling.
+
+A question is answered one of two ways:
+
+| Way | When | What happens |
+| --- | --- | --- |
+| 1: Claude Code's prompt (default) | the Agent is not opted in and `agent-question-answering` is not `projmux` | the hook prints nothing and exits at once; Claude Code shows its usual question prompt |
+| 2: projmux | the Agent is opted in, or `agent-question-answering` is `projmux` | the hook records the question, opens a projmux picker popup, and takes the first answer from the popup or the command line |
+
+The Agent's own switch wins over the setting, so an opted-in Agent is always
+way 2:
 
 ```sh
 projmux agent question enable <agent-ref>
 projmux agent question disable <agent-ref>
 ```
 
-For every other Agent, and for a subagent's question, the hook prints nothing
-and exits at once, so Claude Code shows its usual question prompt.
-
-For an opted-in Agent the hook records the question and holds the tool call
-open for up to 300 seconds. While it waits, Claude Code shows the hook's status
-message instead of the question prompt; pressing Esc cancels the wait and
-declines the question. Answer it from any shell:
+The setting is the central
+`${XDG_CONFIG_HOME:-$HOME/.config}/projmux/agent-question-answering` file (see
+[configuration.md](configuration.md#agent-question-answering)). The hook reads
+it only after the Registry shows that the question comes from a projmux
+Claude Agent's own conversation; a session projmux did not start, and a
+subagent's question, are always way 1 and never read it.
+
+In way 2 the hook holds the tool call open for the answer window: 900 seconds
+unless `${XDG_CONFIG_HOME:-$HOME/.config}/projmux/agent-question-window-seconds`
+holds another value in 60–86400 (see
+[configuration.md](configuration.md#agent-question-window)). The window binds
+only in way 2; way 1 never waits. While it waits, Claude Code shows the hook's
+status message instead of the question prompt.
+A question projmux holds also shows the Agent as `input_required` until the tool runs, however long it waits.
+
+The hook opens a tmux popup right away on the terminal you are looking at: the
+client of the Agent's tmux server that you used most recently, whatever
+Session, Window, or Pane it shows. Clients of other tmux servers are not
+considered. The popup's title names the asking Agent and its Project/Window,
+for example `Agent question from reviewer (alpha/main)`, and it runs the projmux
+picker, one question at a time. Enter picks an option of a single-select
+question; on a multi-select question Enter toggles an option and `Done`
+finishes, with at least one option chosen; `Other / type an answer` takes free
+text. When no client is attached the hook keeps waiting and looks again about
+once a second, and opens the popup when one attaches. Nothing is drawn on
+Claude Code's own terminal.
+
+Questions show one at a time per client. tmux does not draw a popup over
+another one, so a question that arrives while that client already shows a
+popup (another Agent's question, or any other popup) keeps waiting and shows
+once that popup closes. A popup that tmux did not draw is tried again, never
+counted as ended.
+
+A long question wraps inside the popup instead of being cut, and a line break
+in the question starts a new line. The popup is 80% × 70% of the client, but at
+least 72 columns × 22 rows (or the whole client if that is smaller). Only on a
+client smaller than that is the question shortened with `…` so the options stay
+reachable; the full text is available from `projmux agent question list`.
+
+Pressing Esc in the popup gives the question back: the record is closed and
+Claude Code shows its own prompt. So does a picker that fails. A popup that
+ends any other way while the question still waits, most often because its
+client detached, does not give the question back: the question stays in
+projmux, and the next look, within about a second, opens the popup again on the
+client you used most recently, or on the first client to attach when none is
+left. Only a popup that keeps failing gives the question back: three popups in
+a row that each ended within 2 seconds of opening, a popup that failed to open
+among them. A popup that stayed up longer starts that count again, so leaving
+clients never runs it out. Pressing Esc in Claude Code itself cancels the wait
+and declines the question.
+
+A question is given back only once its record is written `closed`. While the
+question store cannot be written (the disk is full, or its lock is held), Esc
+in the popup cannot close the record, which still waits, so the popup opens
+again. When the hook gives the question back after popups that kept failing,
+the record stays `waiting` and the hook keeps holding the question, so it is in
+neither a popup nor Claude Code's prompt; the hook tries again every 250
+milliseconds (each try waits up to 2 seconds for the store lock) and hands the
+question back as soon as the write succeeds, so the record's `updatedAt` is
+that moment, not the moment the last popup ended.
+
+A `closed` record says why it closed in its `disposition`, and that reason
+tells whether the provider still asks the question in its own prompt:
+
+| Disposition | Written when | Provider still asks |
+| --- | --- | --- |
+| `popup-dismissed` | Esc in the popup | yes |
+| `popup-failed` | the picker failed; for a Claude question, three popups in a row failed to open or ended within 2 seconds of opening; for a Codex question, the popup failed to open or ended without an answer (its client detached) | yes |
+| `hook-canceled` | Claude Code canceled the hook (Esc in Claude Code, or its hook timeout), which declines the question | no |
+| `hook-failed` | the hook crashed after it recorded the question | yes |
+| `channel-off` | `agent question disable` | yes |
+| `turn-ended` | the Codex turn that asked it ended | no |
+| `watch-stopped` | projmux's Codex observer stopped watching the request (its connection to Codex ended, or the observer stopped) | yes |
+| `answered-elsewhere` | Codex's own input surface answered it first | no |
+
+`agent question list` shows the reason and says whether the provider still
+asks, for example `closed (popup-failed; Claude Code still asks it in its own
+prompt)` or `closed (hook-canceled; Claude Code no longer asks it)`; `-o json`
+has the reason in `disposition`. A record closed by an older projmux has no
+reason, and a reason this projmux does not know is shown as written. The
+`question-closed` refusal of `answer` carries the same words after the reason.
+
+The same question can be answered from any shell:
 
 ```sh
 projmux agent question list <agent-ref> [-o json]
 projmux agent question answer <agent-ref> <question-id> --option 1=<label> --index 2=<n> --text 3=<free text>
 ```
 
+Whichever answer lands first wins. An answer from the command line closes the
+popup, and a popup answer that arrives after it is refused as
+`question-not-pending`.
+
 Questions are numbered from 1 in the order Claude asked them, and so are the
 options of each question. `--option <n>=<label>` picks an option by its exact
 label, `--index <n>=<k>` by its number, and `--text <n>=<text>` answers with
@@ -736,13 +892,165 @@ occurrences, which are joined with `", "` in option order; a single-select
 question takes exactly one. Every question needs an answer. A refused answer
 changes nothing and names one reason token: `question-not-found`,
 `question-not-pending` (already answered), `question-expired`,
-`question-closed`, `question-invalid-answer`, `question-channel-off`, or
-`question-provider-unsupported`.
+`question-closed`, `question-invalid-answer`, `question-channel-off` (way 1),
+or `question-provider-unsupported`.
+
+If nobody answers within the window, the question expires, the popup closes,
+and Claude Code shows its own prompt as usual. The hook reads the window for
+every question and the installed timeout is the fixed ceiling, so a window
+changed with `projmux config agent-questions` or in the file applies to the
+next question without re-running `projmux agent integrate claude`. `agent
+question disable` also hands every question the Agent is still holding back to that
+prompt immediately. Records live in `<state dir>/agent-questions/` and settled
+ones are kept for a day.
+
+The hook never blocks the tool: every failure, and even a crash inside the
+hook, ends with no output and exit status 0, which Claude Code reads as no
+decision.
+
+### Answering Claude Permission Requests In projmux
+
+`projmux agent integrate claude` also installs one more `PermissionRequest`
+entry, separate from the ingest entry on the same event, that runs
+`projmux internal claude-permission-hook` (marker
+`projmux-managed:claude-permission:v1`, no matcher, `"timeout"` the fixed
+ceiling `3615` seconds, the longest window plus 15 seconds). Unlike the ingest
+command its stdout is not discarded, because that is where a decision is handed
+to Claude Code. The ingest entry, and the `approval_required` row and badge it
+raises, are unchanged. Re-running the integration keeps exactly one such entry,
+`--remove` deletes it, and `config apply` never adds or changes it.
+
+The hook decides nothing unless the central `agent-approval-answering` setting
+is `projmux` (see
+[configuration.md](configuration.md#agent-approval-answering)). The hook
+captures Claude permission requests only; Codex approvals are held by the
+Codex app-server and never captured (see [Codex answers](#codex-answers)
+below). In the default `claude` way the
+hook reads the payload and the Registry, and only once the Registry confirms a
+projmux Claude Agent the one setting file; it prints nothing, records nothing,
+and touches no tmux. A session projmux did not start never reads the setting.
+A request in `bypassPermissions` or `dontAsk` mode is never captured. A
+subagent's request is captured, and its `agent_type` is shown by `agent
+approval list` and written to the audit log.
+
+In way `projmux` the hook records the request and waits up to the answer
+window (900 seconds unless `agent-approval-window-seconds` holds another value
+in 60–3600). Claude Code shows its own prompt at the same time, and that prompt
+stays fully usable: whichever answer comes first wins.
+
+```sh
+projmux agent approval list <agent-ref> [-o json]
+projmux agent approval answer <agent-ref> <request-id> --allow|--deny [--via popup|cli|<client>]
+```
 
-If nobody answers within 300 seconds, the question expires and Claude Code
-shows its own prompt as usual. `agent question disable` also hands every
-question the Agent is still holding back to that prompt immediately. Records
-live in `<state dir>/agent-questions/` and settled ones are kept for a day.
+`list` shows each waiting request with its id, tool name, subagent type, full
+tool input, and created and deadline times. A listed request may already have
+been answered in the terminal. `answer` takes exactly one of `--allow` or
+`--deny`:
+
+- `--allow` prints `{"hookSpecificOutput":{"hookEventName":"PermissionRequest","decision":{"behavior":"allow"}}}`.
+  It allows that one tool call once, exactly as requested: it never carries
+  `updatedInput` or `updatedPermissions`, so no permission rule changes, and the
+  request's `permission_suggestions` are never applied.
+- `--deny` prints a deny decision with the message `denied by the operator in
+  projmux` and `"interrupt": false`.
+
+The hook is deny-by-default: it prints the allow decision only for a request
+the store settled as allowed under its lock. Everything else prints nothing
+and exits 0, which Claude Code reads as no decision: no answer before the
+window ends (the request expires), a store that cannot be opened, written, or
+read, a cancellation (SIGTERM, SIGINT, SIGHUP), a crash inside the hook, and a
+malformed or oversized payload. It never exits 2.
+
+A second or late answer is refused and changes nothing, with one reason token:
+`permission-not-pending` (already allowed or denied, or already answered in
+Claude Code's own prompt), `permission-expired`, `permission-not-found`,
+`permission-answering-off` (the setting is `claude`), or
+`permission-provider-unsupported` (neither a Claude nor a Codex Agent; nothing
+is written).
+
+Answering in the terminal: "No" or Esc sends the waiting hook SIGTERM, which
+closes its record. "Yes" does not tell the hook at all, so the Claude ingest of
+the `PostToolUse` or `PostToolUseFailure` that follows closes the one waiting
+record of the same session, tool, and tool input (compared as canonical JSON)
+with the reason `answered-in-terminal`; the hook then exits with no output.
+When no record or more than one matches, nothing is closed and the window
+expiry ends the wait. In the default way that ingest reads only the setting,
+and with no store file it opens nothing. Known limit: an answer from projmux
+that the store records after the terminal "Yes" but before its `PostToolUse`
+is still accepted and printed. Claude Code has already run the tool by then
+and ignores the late output, but the audit log shows that projmux answer.
+
+`--via` is reported by the caller and recorded as given; projmux does not
+verify it. Every event (`requested`, `allowed`, `denied`, `expired`, `closed`,
+`refused` for a late or invalid answer, and `uncommitted` for an answer that
+did not take effect) is appended as one JSON line to
+`<state dir>/agent-approvals/audit.jsonl` (mode 0600, rotated to one `.1`
+generation at 1 MiB) with the request id, Agent, Pane, session, subagent type,
+tool name, a bounded one-line input summary (Bash `command`, a file tool's
+path, otherwise only the input's key names), request and decision times in
+UTC, and `via`. The full tool input lives only in the request record under
+`<state dir>/agent-approvals/`, and settled records are kept for a day.
+
+An answer's `allowed` or `denied` line is written and synced before the answer
+takes effect. If that line cannot be written, `answer` fails with an error
+naming the audit log and the request stays waiting: fix the log and answer
+again, or answer in Claude Code. The other events stay best effort and never
+fail the transition they describe. If the line was written but the request
+record write then fails before the new record replaces the old one, the answer
+did not take effect: `answer` fails, the request stays waiting, and an
+`uncommitted` line with `reason` `record-write-failed` follows the answer line
+for the same request id. If that `uncommitted` line cannot be written either,
+`answer` says so and the log keeps the `allowed` or `denied` line alone. If
+the new record is already in place and only the sync of its directory fails,
+the write took effect: `answer` succeeds with a warning on stderr, the hook
+keeps waiting on a request it recorded, and the `requested`, `expired`, and
+`closed` lines are written as usual, but that write may not survive a power
+loss. No `uncommitted` line is written when the answer took effect, or when its
+outcome is unknown, such as a crash between the line and the record write. No
+line marks that crash afterwards: the request stays waiting, and a later
+`expired`, `closed`, `allowed`, or `denied` line for the same request id shows
+how it actually ended. For example, `requested`, `allowed`, `denied` for one
+request id means the first answer never took effect and the request was denied;
+`requested`, `allowed`, `expired` means it expired without a decision. If the
+hook died too, as when the machine went down, no later line may follow and the
+answer's outcome stays unknown. A write killed before its rename can leave a
+`.requests.tmp-*` file in `<state dir>/agent-approvals/`; the next write of the
+store removes it. Read the log this way: an `allowed` or `denied` line followed
+by an `uncommitted` line for the same request id did not take effect, and
+otherwise the last `expired`, `closed`, `allowed`, or `denied` line for a
+request id shows how it ended. The log may over-report an answer, never
+under-report one.
+
+#### Codex Answers
+
+The same `list` and `answer` also work for a Codex Agent with an exact native
+control binding (see [cli-guide.md](cli-guide.md)). projmux stores no Codex
+request: the provider holds it, so the audit log gets only the `allowed` or
+`denied` line of an answer sent from projmux and, when that answer is
+confirmed not to have reached Codex, its `uncommitted` line; never
+`requested`, `expired`, `closed`, or `refused`. That line carries the normalized request id, Agent,
+Pane, the approval kind as the tool name, a bounded input summary (a command
+approval's command, otherwise only the detail key names), `via`, the decision
+time, and the provider decision actually sent in `reason` as
+`decision=accept`, `decision=decline`, or `decision=cancel`. `--deny` sends
+`decline` when the request offers it and otherwise `cancel`, which also
+interrupts the turn; nothing runs either way. The line is written and synced
+before that one decision is sent; if it cannot be written nothing is sent and the request stays
+pending. If the send then fails and the decision is confirmed not to have
+reached Codex, an `uncommitted` line with `reason` `send-failed` follows the
+answer line and `answer` says the answer did not take effect. That is the case
+when the request never left projmux (the binding fence refused it, or the
+control socket could not be reached) or when the control server refused it
+before claiming the approval (`stale-epoch`, `stale-binding`, `unavailable`,
+`invalid-frame`, `ambiguous-request`, or `unsafe-decision`). Any other send
+failure may have reached Codex: the line stays alone and `answer` says the
+decision may or may not have reached Codex, so the log may over-report a Codex
+answer too. If the `uncommitted` line cannot be written, `answer` says so and
+the log keeps the answer line alone. A crash of `answer` between the line and
+the send also leaves the answer line alone, and no later line follows it: read
+it like a send that may or may not have reached Codex. An answer given in the
+Codex TUI or with `agent approval review` is not logged.
 
 ## Antigravity Hook Ingest
 
@@ -872,7 +1180,7 @@ empty.
 | Variable | `pre-create` | `post-create` | `post-attach` | `send-noti` |
 | --- | --- | --- | --- | --- |
 | `PROJMUX_SESSION` | new session name | new session name | target session name | target session when known; otherwise empty |
-| `PROJMUX_CWD` | requested session directory | created session directory | resolved target directory; may be empty if lookup fails | dispatcher working directory |
+| `PROJMUX_CWD` | requested session directory | created session directory | resolved target directory; may be empty if lookup fails | `PROJMUX_CWD` inherited by the dispatching process; otherwise the nearest `.projmux` or `.git` root above its working directory, else that directory; empty if it cannot be read — see [Send Noti](#send-noti-working-directory) |
 | `PROJMUX_SESSION_KIND` | `persistent` or `ephemeral` | `persistent` or `ephemeral` | empty | empty |
 | `PROJMUX_VERSION` | projmux version | projmux version | projmux version | projmux version |
 | `PROJMUX_SOCKET` | app socket metadata (`projmux`) | app socket metadata (`projmux`) | app socket metadata (`projmux`) | queue-entry socket when known; otherwise omitted |
@@ -889,14 +1197,29 @@ context to either event.
 
 ## Examples
 
+Save hook scripts outside the legacy paths (`projmux/hooks/<event>`,
+`.projmux/<event>`, `.projmux/hooks/<event>`). projmux rewrites or ignores
+files at those paths. Make each script executable and name it in a `run` line.
+`run` goes through `sh -c`, so `$HOME` expands.
+
 ### Global Post Create Stub
 
+Save this as `~/.local/bin/projmux-post-create`:
+
 ```bash
 #!/usr/bin/env bash
 echo "session=$PROJMUX_SESSION cwd=$PROJMUX_CWD kind=$PROJMUX_SESSION_KIND"
 tmux -L "$PROJMUX_SOCKET" set-option -p -t "$PROJMUX_PANE" @projmux_initialized 1
 ```
 
+Make it executable with `chmod +x ~/.local/bin/projmux-post-create`, then add
+this to `${XDG_CONFIG_HOME:-$HOME/.config}/projmux/config.toml`:
+
+```toml
+[hooks.post-create]
+run = "$HOME/.local/bin/projmux-post-create"
+```
+
 ### Project Startup Command
 
 ```toml
@@ -906,6 +1229,8 @@ run = "git status --short"
 
 ### Per Session GH_TOKEN By Repo
 
+Save this as `~/.local/bin/projmux-gh-token`:
+
 ```bash
 #!/usr/bin/env bash
 set -euo pipefail
@@ -919,28 +1244,119 @@ esac
 tmux -L "$PROJMUX_SOCKET" set-environment -t "$PROJMUX_SESSION" GH_TOKEN "$token"
 ```
 
+Make it executable with `chmod +x ~/.local/bin/projmux-gh-token`, then add this
+to `${XDG_CONFIG_HOME:-$HOME/.config}/projmux/config.toml`:
+
+```toml
+[hooks.post-create]
+run = "$HOME/.local/bin/projmux-gh-token"
+```
+
 `set-environment` only seeds the session env that newly-spawned panes inherit;
 it does not retroactively change the current shell. Open new panes via tmux
 (`Ctrl-b c`, `Ctrl-b "`, etc.) to pick up the value.
 
+Both examples use `post-create`, and an event has one `run` line. To use both,
+call them from one line:
+
+```toml
+[hooks.post-create]
+run = "$HOME/.local/bin/projmux-post-create; $HOME/.local/bin/projmux-gh-token"
+```
+
 ## Troubleshooting
 
-- **Nothing happens.** Check the execute bit on the global hook
-  (`ls -l ~/.config/projmux/hooks/<event>`) or the project hook
-  (`ls -l .projmux/<event> .projmux/hooks/<event>`). A missing bit makes
-  projmux skip hook files silently by design. `.projmux/config.toml` does not
-  need an execute bit.
-- **`project hook ... requires trust; skipping in non-interactive context`** or
-  **`project config ... requires trust; skipping in non-interactive context`.**
+- **Nothing happens.** Work through these checks in order:
+  1. Check that a `run` line exists for the event. `projmux hook list` shows
+     the global and project entries. A project hook must be in
+     `.projmux/config.toml` directly in the hook's `PROJMUX_CWD` directory,
+     which is the session directory for `pre-create`, `post-create`, and
+     `post-attach`. For `send-noti` it is the inherited `PROJMUX_CWD`,
+     otherwise the nearest `.projmux` or `.git` root above the notifying
+     process's working directory; see [Send Noti](#send-noti-working-directory).
+     The runner does not look in parent directories. Without
+     `PROJMUX_CWD`, `projmux hook list` uses `.projmux/config.toml` in the
+     current directory, or walks up to the nearest `.projmux` or `.git`. When
+     it shows a parent file, it says that sessions created in the current
+     directory do not run it:
+     `note: sessions created in <dir> do not run this file's pre-create, post-create, or post-attach hooks, [startup], or [env]; only sessions created in <root> do`.
+     `projmux hook validate` prints the same note. `projmux hook trust` and
+     `projmux hook untrust` without `<project>`, and `projmux hook edit
+     <event>` without `--global` (inline or `--editor`), still act on the
+     `<root>` file from such a directory and print the same note after their
+     result line. The note is not printed from `<root>` itself, under
+     `PROJMUX_CWD`, or when you name `<project>` or `--global`. It follows the
+     UI locale; the text above is the `en-US` form. Move the file into the
+     session directory, or create the session in `<root>`.
+  2. Check for parse errors. If a file cannot be parsed, the whole file is
+     ignored for that run and stderr shows
+     `projmux: <event> hook: global config "<path>" could not be parsed: <reason>`
+     or
+     `projmux: <event> hook: project config ".projmux/config.toml" could not be parsed: <reason>`.
+     `projmux hook validate` prints each file's status, for example
+     `global   <path>   PARSE ERROR: line 2: value must be a quoted string`,
+     and exits 1.
+  3. Check that project hooks are on. `PROJMUX_PROJECT_HOOKS=off` or
+     Settings > Labs > Project Hooks turns them off with no warning. Global
+     hooks still run.
+  4. Check trust. An untrusted or changed project config is skipped; see the
+     trust item below.
+  5. `post-attach` runs only when projmux switches a client from inside tmux.
+     An attach from outside tmux does not run it.
+  6. Check for legacy script files. Legacy files are never executed, whatever
+     their execute bit: global
+     `${XDG_CONFIG_HOME:-$HOME/.config}/projmux/hooks/<event>`, and project
+     `.projmux/<event>` and `.projmux/hooks/<event>`. Most projmux commands,
+     such as `projmux hook list`, scan them when they start. Help and
+     read-only commands such as `doctor`, `get`, and `describe` do not:
+     - A one-command script is moved into `[hooks.<event>] run` in the
+       matching `config.toml` and renamed to `<path>.bak`. stderr shows
+       `projmux: migrated legacy <global|project> hook <path> -> [hooks.<event>] run; original kept at <path>.bak`.
+       An existing `run` for that event wins; the script is still renamed.
+     - A multi-line script is left in place and not run. Every scanning
+       command prints
+       `projmux: legacy <global|project> hook <path> has <N> non-trivial lines; declarative migration skipped (multi-line scripts are no longer executed; rewrite manually as run = "bash -c '...'" or run = "./scripts/foo.sh")`.
+     - A symlink is left in place and not run:
+       `projmux: legacy <global|project> hook <path> is a symlink; declarative migration skipped (clean up via the source dotfiles repo)`.
+
+     The project scan runs only when the projmux process has `PROJMUX_CWD` set
+     to the repository, for example
+     `PROJMUX_CWD="$PWD" projmux hook list --project`. Without it, project
+     legacy files are ignored silently. A migrated `.projmux/config.toml` has
+     new content, so it needs trust again.
+  7. Check the execute bit of the program named in `run`. It needs its own
+     execute bit, or use `run = "bash /path/script"`. Without it, stderr shows
+     `[<event>] sh: 1: <path>: Permission denied` and then
+     `projmux: <event> hook: global config hook: exited with status 126`.
+     `.projmux/config.toml` itself does not need an execute bit.
+- **`projmux: <event> hook: project config ".projmux/config.toml" requires trust; skipping in non-interactive context`**
+  or
+  **`projmux: <event> hook: project config ".projmux/config.toml" hash changed; trusted sha256=<old> current sha256=<new>; skipping in non-interactive context`.**
   Run the same projmux command from an interactive terminal to approve the file,
-  or set `PROJMUX_PROJECT_HOOKS=off` if project-local execution should be
+  or run `projmux hook trust [<project>]`, which prints `trusted <repo>` and
+  the sha256. Without `<project>` from a subdirectory, it trusts the nearest
+  project root and prints the scope note from check 1 of "Nothing happens".
+  Set `PROJMUX_PROJECT_HOOKS=off` if project-local execution should be
   disabled.
 - **`projmux: <event> hook: ... timed out after 5s`.** Long-running work
   belongs in a backgrounded child (`(slow-thing &) >/dev/null 2>&1`). The hook
-  itself must return within 5s or projmux kills it.
-- **`projmux: <event> hook: hook ... exited with status N`.** The script
-  returned non-zero. For `pre-create`, creation aborts; for other events,
-  projmux logs once and moves on.
-- **Lines appear with `[post-create] `, `[pre-create] `, or `[post-attach] `
-  prefixes.** Expected; hook stdout/stderr are multiplexed into projmux's
-  stderr stream.
+  itself must return within 5s or projmux kills it. projmux runs the hook in
+  its own process group and on timeout sends SIGKILL to that whole group, so
+  children and grandchildren started by the hook stop too; if projmux itself
+  receives SIGINT, SIGTERM, or SIGHUP while a hook runs, it kills the hook's
+  group the same way before exiting. A process that left the group or session
+  (for example via `setsid` or by daemonizing) is not killed, and SIGKILL gives
+  no chance to clean up, so residue such as a stale `.git/index.lock` can
+  remain; remove it by hand. Because the hook runs outside the terminal's
+  foreground process group, a hook that reads `/dev/tty` directly is stopped
+  (SIGTTIN) until the timeout. For `pre-create`, creation stops and the command
+  fails with `pre-create hook for tmux session "<name>": timed out after 5s`.
+- **`projmux: <event> hook: ... exited with status N`.** The hook returned
+  non-zero. projmux logs once and moves on. A global hook shows
+  `global config hook: exited with status N`; a project hook shows
+  `project config ".projmux/config.toml": exited with status N`. For
+  `pre-create`, this warning is not logged. Creation stops and the command
+  fails with `pre-create hook for tmux session "<name>": exited with status N`.
+- **Lines appear with `[post-create] `, `[pre-create] `, `[post-attach] `, or
+  `[send-noti] ` prefixes.** Expected; hook stdout/stderr are multiplexed into
+  projmux's stderr stream.