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 })