@ascenda-one/codex-hooks 0.1.34 → 0.1.36

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/NOTICE ADDED
@@ -0,0 +1,4 @@
1
+ @ascenda-one/codex-hooks
2
+ Copyright 2026 Ascenda One Pty Ltd
3
+
4
+ Licensed under the Apache License, Version 2.0. See LICENSE.
package/README.md CHANGED
@@ -24,7 +24,7 @@ Identity: Codex rides the canonical `cli_agent` toolType/source (the backend reg
24
24
 
25
25
  ## Hook safety contract
26
26
 
27
- Codex **awaits** command hooks and treats **exit code 2 as blocking** the user's action. This adapter therefore always exits `0` and caps every HTTP call at 3 s (`ASCENDA_HTTP_TIMEOUT_MS` to change): telemetry failures surface as a one-line `systemMessage` or stderr note and never stall or block the engineer.
27
+ Codex **awaits** command hooks and treats **exit code 2 as blocking** the user's action. This adapter therefore always exits `0`, and it doesn't send from the hook. Each hook writes its events to a local outbox, starts a background sender and returns, so the network never holds up Codex. The sender caps each HTTP call at 3 s (`ASCENDA_HTTP_TIMEOUT_MS` to change). Telemetry failures surface as a one-line `systemMessage` or stderr note. `ASCENDA_HOOK_DELIVERY=inline` sends from the hook itself, as earlier versions did.
28
28
 
29
29
  ## Install
30
30
 
@@ -60,6 +60,10 @@ Node 20 or newer itself, so hooks keep working when Codex starts without
60
60
  your shell's PATH. `--no-pair` installs without pairing: the screen saver
61
61
  and live view work, and nothing is sent.
62
62
 
63
+ With `CODEX_HOME` set, the machine-wide file is `$CODEX_HOME/hooks.json`.
64
+ If another tool has added its own command to one of our hook groups, setup
65
+ and `uninstall` take out only ours and leave theirs.
66
+
63
67
  ### 2. Check it
64
68
 
65
69
  ```bash
@@ -86,8 +90,13 @@ authorize them. Changes to a hook definition require review again. See the
86
90
  [Codex hook trust reference](https://learn.chatgpt.com/docs/hooks).
87
91
 
88
92
  The setup command registers hooks but does not write Codex trust hashes or
89
- bypass review. A successful `status` checks installation, not runtime trust
90
- or accepted delivery.
93
+ bypass review. `status` and `doctor` read the approvals Codex keeps in
94
+ `config.toml` (the `[hooks.state."…"]` tables) and name any hook that has none,
95
+ and exit non-zero for it, since Codex skips that hook without a message. They
96
+ can't compare an approved command with the current one, so after an upgrade
97
+ that changes a command they suggest re-approving when the hooks file is newer
98
+ than the last approval. A successful `status` still doesn't prove accepted
99
+ delivery.
91
100
 
92
101
  ### On a Dev backend with no phone
93
102
 
@@ -133,7 +142,9 @@ event. Check the local event log for `metadata.host: "codex"` and confirm its
133
142
  `toolInstallationId` matches `tools.codex` in the credentials file. The hook
134
143
  always exits `0`, so its exit code alone cannot prove delivery.
135
144
 
136
- Set `ASCENDA_EVENT_LOG_FILE` to also log each payload locally.
145
+ An unpaired install logs every payload to `~/.ascenda/events.jsonl`. On a
146
+ paired one, `setup --event-log` or `ASCENDA_EVENT_LOG_FILE` turns the same log
147
+ on, and `off` turns it off.
137
148
 
138
149
  ## Build from source
139
150
 
@@ -160,7 +171,12 @@ Codex's PATH, use the absolute path to the binary.
160
171
 
161
172
  ## Supported Codex hook events
162
173
 
163
- `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PreCompact`, `PostCompact`, `Stop`, `PermissionRequest`. (`SubagentStart` and `SubagentStop` have no catalog counterpart and are skipped.)
174
+ `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PreCompact`, `PostCompact`, `Stop`, `PermissionRequest`, `SessionEnd`. (`SubagentStart` and `SubagentStop` have no catalog counterpart and are skipped.)
175
+
176
+ `SessionEnd` needs Codex 0.146 or newer; an older Codex ignores the entry. Codex
177
+ gives it at most 3 seconds because the process is exiting, so it is registered
178
+ with a 3 second timeout and sends with a shorter limit than the other hooks. A
179
+ send that doesn't finish stays in the outbox for the next hook to deliver.
164
180
 
165
181
  `PermissionRequest` records that the agent stopped at an approval gate, and
166
182
  nothing about what it was asking to do — one field, `interruptionKind: