fix(core): close turn cancellation contract gaps

packages/hooks/hook-protocol/README.md

@@ -18,7 +18,7 @@ Why a shared lib at all: Codex deliberately reimplements a *subset* of the Claud
 ## Primitives
 
 - **`matchesMatcher(matcher, query, mode)`** — match-all on absent/`''`/`'*'`; `claude` mode treats a pure `[A-Za-z0-9_|]+` pattern as a literal (pipe = exact-match alternation) and anything else as a regex; `codex` mode is always an unanchored regex. An invalid regex matches nothing (never throws).
-- **`runHook(bash, hook, options, now)`** — serialize `options.payload` to the hook's stdin (with a trailing newline iff `options.trailingNewline`), merge `options.env` after the executor's credential scrub (the `dsh-bash` trusted-plugin surface), honor the hook's `timeoutSec` (else `options.defaultTimeoutMs` — the bridge owns the default, its config defaulting to the lib's `DEFAULT_HOOK_TIMEOUT_MS` 10-minute reference), and decode the result (threading `options.expectedEventName` to the codec). Never throws: an executor rejection (infra fault) becomes a `HookOutput` with `exitCode: undefined` (a non-blocking error). `now` is injected for testable durations.
+- **`runHook(bash, hook, options, now)`** — require and forward the caller-owned `options.signal`, serialize `options.payload` to the hook's stdin (with a trailing newline iff `options.trailingNewline`), merge `options.env` after the executor's credential scrub (the `dsh-bash` trusted-plugin surface), honor the hook's `timeoutSec` (else `options.defaultTimeoutMs` — the bridge owns the default, its config defaulting to the lib's `DEFAULT_HOOK_TIMEOUT_MS` 10-minute reference), and decode the result (threading `options.expectedEventName` to the codec). Cancellation therefore reaches the executor's process-group kill and join boundary. Never throws: an executor rejection (infra fault) becomes a `HookOutput` with `exitCode: undefined` (a non-blocking error). `now` is injected for testable durations.
 - **`parseHookOutput(exitCode, stdout, stderr, expectedEventName?)`** decodes exit status and structured stdout. Exit 2 blocks with stderr; other failures are non-blocking. A matching hook-specific permission decision overrides the legacy top-level decision; mismatched or missing event discriminators suppress only event-specific fields. Top-level fields remain event-agnostic, and successful non-JSON output is left to the bridge.
 - **`mergeHookOutputs(outputs)`** — fold the results of every hook that matched one point: permission precedence **deny > ask > allow**, halt sticky on the first `continue:false`, block reasons joined with `\n\n`, `additionalContext`/`systemMessages` accumulated in order.
 - **`createDetachedRuns()`** — quiescence tracking for the emit-shaped points, which run detached (no seam awaits them). The bridge tracks each run chain — the hook run PLUS its continuation — and registers `drain()` as its effect disposer: drain fires the tracker's abort `signal` (so a still-running hook process is killed via `runHook`, not awaited out to its timeout), then resolves once every tracked chain has settled. `fiber.dispose()` resolving therefore means no detached hook work is left to fire into a disposed context ([defensive patterns](../../../docs/defensive-patterns.md): dispose must reach quiescence).

packages/hooks/hook-protocol/src/runner.ts

@@ -28,7 +28,7 @@ export interface RunHookOptions {
   /** Working directory for the hook (defaults to the executor's own default when omitted). */
   cwd?: string
   /** Explicit owning-operation signal; firing it cancels the hook run. */
-  signal?: AbortSignal
+  readonly signal: AbortSignal
   /** Whether to append a trailing newline to the stdin payload (CC yes, Codex no). */
   trailingNewline: boolean
   /**
@@ -78,9 +78,9 @@ export async function runHook(
     command: hook.command,
     timeoutMs,
     stdin,
+    signal: options.signal,
     ...options.cwd !== undefined ? { workdir: options.cwd } : {},
     ...options.env !== undefined ? { env: options.env } : {},
-    ...options.signal ? { signal: options.signal } : {},
   }
 
   try {

packages/hooks/hook-protocol/tests/runner.spec.ts

@@ -1,6 +1,7 @@
-import { describe, expect, it } from 'vitest'
+import { describe, expect, expectTypeOf, it } from 'vitest'
 import type { BashExecRequest, BashExecSpec, BashExecutor, BashRunResult } from '@deepseek-ai/dsh-bash'
 import { DEFAULT_HOOK_TIMEOUT_MS, runHook } from '@deepseek-ai/dsh-hook-protocol'
+import type { RunHookOptions } from '@deepseek-ai/dsh-hook-protocol'
 
 /**
  * A minimal stand-in for the bits of {@link BashExecutor} that {@link runHook}
@@ -51,12 +52,18 @@ function result(over: Partial<BashRunResult> = {}): BashRunResult {
 }
 
 const clock = () => { let t = 0; return () => (t += 5) } // +5ms per call → duration 5
+const testSignal = (): AbortSignal => new AbortController().signal
 
 describe('runHook — payload + env + stdin plumbing', () => {
+  it('requires an explicit caller-owned abort signal', () => {
+    expectTypeOf<RunHookOptions['signal']>().toEqualTypeOf<AbortSignal>()
+  })
+
   it('serializes the payload to stdin (with trailing newline when requested)', async () => {
     const { bash, specs } = recordingBash(async () => result({ stdout: { text: '', truncated: false } }))
     await runHook(bash, { command: 'my-hook.sh' }, {
       payload: { hook_event_name: 'PreToolUse', tool_name: 'Bash' },
+      signal: testSignal(),
       defaultTimeoutMs: 60000,
       trailingNewline: true,
     }, clock())
@@ -66,14 +73,14 @@ describe('runHook — payload + env + stdin plumbing', () => {
 
   it('omits the trailing newline when trailingNewline is false (Codex)', async () => {
     const { bash, specs } = recordingBash(async () => result())
-    await runHook(bash, { command: 'h' }, { payload: { a: 1 }, defaultTimeoutMs: 1000, trailingNewline: false }, clock())
+    await runHook(bash, { command: 'h' }, { payload: { a: 1 }, signal: testSignal(), defaultTimeoutMs: 1000, trailingNewline: false }, clock())
     expect(specs[0]!.stdin).toBe('{"a":1}')
   })
 
   it('threads env and cwd into the request', async () => {
     const { bash, specs } = recordingBash(async () => result())
     await runHook(bash, { command: 'h' }, {
-      payload: {}, env: { CLAUDE_PROJECT_DIR: '/proj' }, cwd: '/work',
+      payload: {}, env: { CLAUDE_PROJECT_DIR: '/proj' }, cwd: '/work', signal: testSignal(),
       defaultTimeoutMs: 1000, trailingNewline: true,
     }, clock())
     expect(specs[0]!.env).toEqual({ CLAUDE_PROJECT_DIR: '/proj' })
@@ -82,13 +89,13 @@ describe('runHook — payload + env + stdin plumbing', () => {
 
   it('a per-hook timeoutSec (seconds) overrides the default (ms)', async () => {
     const { bash, specs } = recordingBash(async () => result())
-    await runHook(bash, { command: 'h', timeoutSec: 3 }, { payload: {}, defaultTimeoutMs: 60000, trailingNewline: true }, clock())
+    await runHook(bash, { command: 'h', timeoutSec: 3 }, { payload: {}, signal: testSignal(), defaultTimeoutMs: 60000, trailingNewline: true }, clock())
     expect(specs[0]!.timeoutMs).toBe(3000)
   })
 
   it('falls back to the default timeout when the hook sets none', async () => {
     const { bash, specs } = recordingBash(async () => result())
-    await runHook(bash, { command: 'h' }, { payload: {}, defaultTimeoutMs: 60000, trailingNewline: true }, clock())
+    await runHook(bash, { command: 'h' }, { payload: {}, signal: testSignal(), defaultTimeoutMs: 60000, trailingNewline: true }, clock())
     expect(specs[0]!.timeoutMs).toBe(60000)
     expect(DEFAULT_HOOK_TIMEOUT_MS).toBe(600_000) // the CC/Codex reference default (10 minutes)
   })
@@ -106,7 +113,7 @@ describe('runHook — outcome decoding + duration', () => {
     const { bash } = recordingBash(async () => result({
       exitCode: 0, stdout: { text: JSON.stringify({ decision: 'block', reason: 'no' }), truncated: false },
     }))
-    const { output, durationMs } = await runHook(bash, { command: 'h' }, { payload: {}, defaultTimeoutMs: 1000, trailingNewline: true }, clock())
+    const { output, durationMs } = await runHook(bash, { command: 'h' }, { payload: {}, signal: testSignal(), defaultTimeoutMs: 1000, trailingNewline: true }, clock())
     expect(output.decision).toBe('block')
     expect(output.reason).toBe('no')
     expect(durationMs).toBe(5)
@@ -114,7 +121,7 @@ describe('runHook — outcome decoding + duration', () => {
 
   it('a signal death (exitCode null) decodes as undefined exit (non-blocking error)', async () => {
     const { bash } = recordingBash(async () => result({ exitCode: null, signal: 'SIGKILL', stderr: { text: 'killed', truncated: false } }))
-    const { output } = await runHook(bash, { command: 'h' }, { payload: {}, defaultTimeoutMs: 1000, trailingNewline: true }, clock())
+    const { output } = await runHook(bash, { command: 'h' }, { payload: {}, signal: testSignal(), defaultTimeoutMs: 1000, trailingNewline: true }, clock())
     expect(output.exitCode).toBeUndefined()
     expect(output.decision).toBeUndefined()
     expect(output.stderr).toBe('killed')
@@ -122,7 +129,7 @@ describe('runHook — outcome decoding + duration', () => {
 
   it('an executor rejection (infra fault) becomes a non-blocking error, never throws', async () => {
     const { bash } = recordingBash(async () => { throw new Error('bad workdir: ENOENT') })
-    const { output } = await runHook(bash, { command: 'h' }, { payload: {}, defaultTimeoutMs: 1000, trailingNewline: true }, clock())
+    const { output } = await runHook(bash, { command: 'h' }, { payload: {}, signal: testSignal(), defaultTimeoutMs: 1000, trailingNewline: true }, clock())
     expect(output.exitCode).toBeUndefined()
     expect(output.stderr).toBe('bad workdir: ENOENT')
     expect(output.decision).toBeUndefined()
@@ -130,7 +137,7 @@ describe('runHook — outcome decoding + duration', () => {
 
   it('a non-Error rejection is stringified onto stderr', async () => {
     const { bash } = recordingBash(async () => { throw 'plain string fault' })
-    const { output } = await runHook(bash, { command: 'h' }, { payload: {}, defaultTimeoutMs: 1000, trailingNewline: true }, clock())
+    const { output } = await runHook(bash, { command: 'h' }, { payload: {}, signal: testSignal(), defaultTimeoutMs: 1000, trailingNewline: true }, clock())
     expect(output.stderr).toBe('plain string fault')
   })
 
@@ -140,7 +147,7 @@ describe('runHook — outcome decoding + duration', () => {
       stdout: { text: JSON.stringify({ hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'deny' } }), truncated: false },
     }))
     const { output } = await runHook(bash, { command: 'h' }, {
-      payload: {}, defaultTimeoutMs: 1000, trailingNewline: true, expectedEventName: 'Stop',
+      payload: {}, signal: testSignal(), defaultTimeoutMs: 1000, trailingNewline: true, expectedEventName: 'Stop',
     }, clock())
     // A PreToolUse block on a Stop hook is malformed → its decision is discarded.
     expect(output.hookEventName).toBe('PreToolUse')