Merge remote-tracking branch 'origin/master' into simpl-g-hook-contract

# Conflicts:
#	packages/hooks/hook-protocol/src/events.ts
#	packages/hooks/hook-protocol/tests/events.spec.ts
#	packages/hooks/hooks-claude/README.md
#	packages/hooks/hooks-claude/src/index.ts
#	packages/hooks/hooks-codex/README.md
#	packages/hooks/hooks-codex/src/index.ts

packages/hooks/hooks-claude/README.md

@@ -12,6 +12,8 @@ const config: Config = {
   configPath: '/path/to/hooks.json', // required: a hooks.json or a settings file with a `hooks` key
   pluginRoot: '/path/to/plugin',     // optional: replaces ${CLAUDE_PLUGIN_ROOT} in command strings
   projectDir: '/path/to/project',    // optional: replaces ${CLAUDE_PROJECT_DIR} AND sets the hook env var; defaults to the session cwd when omitted
+  defaultTimeoutMs: 600_000,         // optional: per-hook timeout when a hook sets none (CC default)
+  stderrSummaryMaxChars: 500,        // optional: char cap on the hook/result event's persisted stderr summary
 }
 ```
 

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

@@ -31,6 +31,8 @@ import type { PostToolDecision, PreToolDecision, ToolExecution, ToolExecutionRes
 import {
   appendHookInvoked,
   appendHookResult,
+  DEFAULT_HOOK_TIMEOUT_MS,
+  DEFAULT_STDERR_SUMMARY_MAX_CHARS,
   matchesMatcher,
   mergeHookOutputs,
   runHook,
@@ -71,12 +73,18 @@ export interface Config {
    * unmodified hooks reference `$CLAUDE_PROJECT_DIR` for project-relative paths.
    */
   projectDir?: string
+  /** Default per-hook timeout in ms when a hook sets none (CC default: 600000). */
+  defaultTimeoutMs?: number
+  /** Character cap for the `hook/result` event's persisted stderr summary. */
+  stderrSummaryMaxChars?: number
 }
 
 export const Config: z<Config> = z.object({
   configPath: z.string().required(),
   pluginRoot: z.string(),
   projectDir: z.string(),
+  defaultTimeoutMs: z.number().default(DEFAULT_HOOK_TIMEOUT_MS),
+  stderrSummaryMaxChars: z.number().default(DEFAULT_STDERR_SUMMARY_MAX_CHARS),
 })
 
 /** A stable per-handler id so an invoked/result pair correlates in the log. */
@@ -88,7 +96,19 @@ function nextHandlerId(point: string): string {
 /** The `{kind:'plugin'}` source stamped on every context this bridge injects. */
 const PLUGIN_SOURCE: MessageSource = { kind: 'plugin', plugin: 'hooks-claude' }
 
+/** The summary cap bounds a persisted event field — a positive integer or the slice misbehaves silently. */
+function assertPositiveInteger(name: string, value: number): void {
+  if (!Number.isInteger(value) || value < 1) {
+    throw new Error(`hooks-claude: ${name} must be a positive integer`)
+  }
+}
+
 export function apply(ctx: Context, config: Config): void {
+  // Validate the cap BEFORE the config-file parse: a bad value must fail the
+  // load loudly, not be skipped by the parse-failure early return.
+  const stderrSummaryMaxChars = config.stderrSummaryMaxChars ?? DEFAULT_STDERR_SUMMARY_MAX_CHARS
+  assertPositiveInteger('stderrSummaryMaxChars', stderrSummaryMaxChars)
+  const defaultTimeoutMs = config.defaultTimeoutMs ?? DEFAULT_HOOK_TIMEOUT_MS
   // --- Parse the config ONCE at load. A read/parse failure is contained: the
   // bridge logs and registers nothing rather than crashing boot (a typo'd path
   // must not take the agent down). ---
@@ -153,6 +173,7 @@ export function apply(ctx: Context, config: Config): void {
         }
         const output = await runHook(ctx.bash, hook, {
           payload,
+          defaultTimeoutMs,
           ...hookEnv ? { env: hookEnv } : {},
           ...workdir !== undefined ? { cwd: workdir } : {},
           ...opts.signal ? { signal: opts.signal } : {},
@@ -169,7 +190,7 @@ export function apply(ctx: Context, config: Config): void {
           ctx.logger.warn(`hooks-claude: ${point} hook emitted a systemMessage, which is not yet surfaced (ignored)`)
         }
         if (session && opts.turn !== undefined) {
-          appendHookResult(session, { turn: opts.turn, point, handlerId, output })
+          appendHookResult(session, { turn: opts.turn, point, handlerId, output, stderrSummaryMaxChars })
         }
       }
     }

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

@@ -27,7 +27,7 @@ function hooks(d: string, h: unknown): string {
   writeFileSync(join(d, 'hooks.json'), JSON.stringify({ hooks: h })); return join(d, 'hooks.json')
 }
 
-type HarnessOpts = { pluginRoot?: string; projectDir?: string }
+type HarnessOpts = { pluginRoot?: string; projectDir?: string; stderrSummaryMaxChars?: number }
 async function harness(configPath: string, adapter: MockAdapter, opts: HarnessOpts = {}): Promise<Context> {
   const ctx = new Context()
   await ctx.plugin(LlmService)
@@ -139,6 +139,31 @@ describe('hooks-claude coverage — empty/no-op outcomes and no-agent paths', ()
     await waitForIdle(ctx, agent)
     const res = events(agent).find(e => e.type === 'hook/result')
     expect(res?.type === 'hook/result' && res.data.stderrSummary?.endsWith('…')).toBe(true)
+    expect(res?.type === 'hook/result' && res.data.stderrSummary?.length).toBe(501) // default 500-char cap + ellipsis
+  })
+
+  it('rejects a non-positive or fractional stderrSummaryMaxChars at load', async () => {
+    const d = dir()
+    const path = hooks(d, {})
+    for (const bad of [0, -5, 1.5, Number.NaN]) {
+      const adapter = new MockAdapter([])
+      await expect(harness(path, adapter, { stderrSummaryMaxChars: bad }))
+        .rejects.toThrow(/hooks-claude: stderrSummaryMaxChars must be a positive integer/)
+    }
+  })
+
+  it('the stderr summary cap is plugin config (stderrSummaryMaxChars)', async () => {
+    const d = dir()
+    const s = sh(d, 'long.sh', '#!/usr/bin/env bash\nprintf "x%.0s" {1..600} >&2\nexit 2\n')
+    const path = hooks(d, { PreToolUse: [{ hooks: [{ type: 'command', command: s }] }] })
+    const adapter = new MockAdapter([toolCallResponse('c1', 'echo', {}), textResponse('done')])
+    const ctx = await harness(path, adapter, { stderrSummaryMaxChars: 40 })
+    ctx.tools.register(defineTool({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
+    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    agent.send([{ type: 'text', text: 'go' }])
+    await waitForIdle(ctx, agent)
+    const res = events(agent).find(e => e.type === 'hook/result')
+    expect(res?.type === 'hook/result' && res.data.stderrSummary).toBe('x'.repeat(40) + '…')
   })
 })