docs: rebalance prose cleanup and add trimming skill

packages/hooks/hooks-codex/src/config.ts

@@ -1,5 +1,7 @@
 /**
- * Parse a Codex `hooks.json` into the shared {@link MatcherGroup} shape.
+ * Parse Codex's five-event hook subset into shared {@link MatcherGroup}s. Only synchronous command
+ * hooks run; other types and `async: true` commands are recorded as skipped. Codex performs no
+ * command substitution.
  * @module @deepseek-ai/dsh-hooks-codex/config
  */
 
@@ -30,8 +32,8 @@ function asObject(value: unknown): Record<string, unknown> | undefined {
 }
 
 /**
- * Parse supported synchronous command hooks, recording skipped entries and
- * ignoring malformed configuration rather than failing boot.
+ * Parse a wrapped or bare Codex event map. Unknown events and malformed entries are ignored rather
+ * than failing boot; unsupported or asynchronous hooks are returned in `skipped`.
  * @param raw - the parsed JSON config: a `{ hooks: … }` wrapper or the bare event map.
  * @returns the runnable per-event groups plus the skipped hooks with their reasons.
  */

packages/hooks/hooks-codex/src/index.ts

@@ -1,6 +1,8 @@
 /**
- * `dsh-hooks-codex` — a bridge plugin that runs a user's existing Codex `hooks.json` on the
- * harness's canonical interception seams. The CODEX DIALECT half of the hooks subsystem.
+ * Bridge for unmodified Codex command hooks on harness interception seams. It
+ * supports five points (SessionStart, prompt/tool pre/post, Stop), regex-only
+ * matchers, snake_case payloads without a trailing newline, no hook environment
+ * or command substitution, and block-only decisions; allow/ask do not grant.
  * @module @deepseek-ai/dsh-hooks-codex
  */
 
@@ -126,8 +128,8 @@ export function apply(ctx: Context, config: Config): void {
           // Discard a `hookSpecificOutput` block naming a different event.
           expectedEventName: point,
         }, () => performance.now())
-        // Codex's SessionStart/UserPromptSubmit treat a CLEAN hook's PLAIN (non-JSON) stdout as
-        // additionalContext.
+        // Clean plain stdout becomes context only when no structured context
+        // exists; nonzero output and raw JSON never leak as prose.
         if (opts.plainStdoutAsContext === true && output.exitCode === 0
           && output.additionalContext === undefined
           && output.stdout.length > 0 && !output.stdout.startsWith('{')) {
@@ -159,7 +161,8 @@ export function apply(ctx: Context, config: Config): void {
     return { content: [...ours.content, ...theirs.content], source: ours.source }
   }
 
-  // SessionStart injects plain stdout when its detached hook resolves.
+  // SessionStart injects plain stdout when its detached hook resolves; a slow
+  // hook may miss the first request.
   // TODO(session-start-gating): add a startup gate before promising first-turn delivery.
   ctx.on('agent/session-start', (agent, source) => {
     detached.track(runPoint('SessionStart', source, { ...base(agent, 'SessionStart', model), source }, { agent, plainStdoutAsContext: true, signal: detached.signal })

packages/hooks/hooks-codex/tests/bridge.spec.ts

@@ -143,8 +143,8 @@ describe('hooks-codex bridge', () => {
 
   it('disposing the bridge fiber removes its listeners (HMR safety)', async () => {
     const dir = configDir()
-    // A BLOCKING UserPromptSubmit hook: if the listener leaked past dispose, it would veto the
-    // prompt (0 model requests) and log a hook/invoked.
+    // A leaked listener would let this blocking hook veto the prompt and log an invocation; a
+    // no-op hook would pass even when leaked.
     const deny = script(dir, 'deny.sh', '#!/usr/bin/env bash\nexit 2\n')
     writeHooks(dir, { UserPromptSubmit: [{ hooks: [{ type: 'command', command: deny }] }] })
     const adapter = new MockAdapter([textResponse('ok')])
@@ -170,8 +170,8 @@ describe('hooks-codex bridge', () => {
     const dir = configDir()
     const pidFile = join(dir, 'pid')
     const marker = join(dir, 'started')
-    // Record the hook shell's PID and touch the marker FIRST so the test can tell "the hook is
-    // genuinely mid-run", then sleep far past the suite timeout.
+    // Record the PID and marker before sleeping past the suite timeout. Disposal must abort the
+    // tracked process through `runPoint`, not await its natural exit.
     const slow = script(dir, 'slow.sh', `#!/usr/bin/env bash\necho $$ > "${pidFile}"\ntouch "${marker}"\nsleep 30\n`)
     writeHooks(dir, { SessionStart: [{ hooks: [{ type: 'command', command: slow }] }] })
     const ctx = new Context()
@@ -190,9 +190,8 @@ describe('hooks-codex bridge', () => {
     await waitFor(() => existsSync(marker))
     const pid = Number(readFileSync(pidFile, 'utf8').trim())
     await fiber.dispose()
-    // Quiescence, not just promptness: the drain resolves only after the run settled, and the
-    // run settles only after the killed process was reaped — so by the time dispose returns,
-    // the PID must be GONE (kill(pid, 0) throws ESRCH).
+    // Disposal reaches quiescence only after the aborted run settles and the process is reaped, so
+    // `kill(pid, 0)` must report ESRCH. Untracked fire-and-forget work would remain.
     expect(() => process.kill(pid, 0)).toThrow()
     // The aborted run resolves as a non-blocking error (runHook never rejects),
     // so the drained continuation must NOT have logged a failure.

packages/hooks/hooks-codex/tests/coverage.spec.ts

@@ -70,8 +70,8 @@ describe('hooks-codex coverage — decision mapping paths', () => {
   })
 
   it('a context-only UserPromptSubmit hook DELEGATES so a later listener can still block', async () => {
-    // Context alone is not a veto: a downstream agent/prompt-submit listener (a policy plugin
-    // registered after the bridge) must still get to block.
+    // Context alone is not a veto: the bridge delegates with `next()` and folds its context, so a
+    // downstream policy listener can still block.
     const d = dir()
     hooks(d, { UserPromptSubmit: [{ hooks: [{ type: 'command', command: sh(d, 'c.sh', '#!/usr/bin/env bash\necho \'{"hookSpecificOutput":{"hookEventName":"UserPromptSubmit","additionalContext":"bridge ctx"}}\'\n') }] }] })
     const adapter = new MockAdapter([textResponse('should not run')])
@@ -437,8 +437,9 @@ describe('hooks-codex coverage — decision mapping paths', () => {
   })
 
   it('a NON-clean SessionStart hook (exit 2) does NOT inject its stdout as context', async () => {
-    // The plain-stdout→context fold is gated on exitCode === 0, matching the codec's
-    // structured-stdout rule.
+    // SessionStart cannot block, but non-clean stdout still must not become context. The marker
+    // waits for detached completion; `echo stale; exit 2` then proves the exit-code gate matches
+    // the codec's structured-stdout rule.
     const d = dir()
     const marker = join(d, 'ran')
     hooks(d, { SessionStart: [{ hooks: [{ type: 'command', command: sh(d, 'b.sh', `#!/usr/bin/env bash\ntouch "${marker}"\necho "stale"\nexit 2\n`) }] }] })