refactor: apply repository naming contract

Apply the accepted pre-release package, service, type, directory, and role renames as one repository-wide change.

packages/hooks/hooks-claude-code/tests/bridge.spec.ts

@@ -0,0 +1,446 @@
+import { createUserMessage } from '@deepseek-ai/dsh-llm'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { chmodSync, existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { Context, type Fiber } from '@deepseek-ai/cordis'
+import Loader from '@deepseek-ai/cordis-plugin-loader'
+import { SessionId, type SessionEvent } from '@deepseek-ai/dsh-session'
+import { defineContentToolFixture } from '@deepseek-ai/dsh-tools'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import AgentLoop from '@deepseek-ai/dsh-agent-loop'
+import { mountAgentLoopTestDependencies } from '@deepseek-ai/dsh-agent-loop-testkit'
+import { LocalBashExecutor } from '@deepseek-ai/dsh-bash-local'
+import LocalSubprocessRuntime from '@deepseek-ai/dsh-subprocess-local'
+import { scopeTarget } from '@deepseek-ai/dsh-scope'
+import SubagentRuntime, { SubagentRunId } from '@deepseek-ai/dsh-subagent'
+import * as HooksClaude from '@deepseek-ai/dsh-hooks-claude-code'
+import { MockAdapter, textResponse, toolCallResponse } from '../../../core/agent-loop/tests/mock-adapter.ts'
+
+/**
+ * Full-loop bridge tests: a scripted mock MODEL drives the REAL agent loop + REAL
+ * bash executor, and the REAL `dsh-hooks-claude-code` bridge runs REAL shell hook
+ * scripts written to a temp dir — only the model is mocked (the "prefer the real
+ * implementation" rule). Each test writes a `hooks.json` + executable scripts,
+ * loads the bridge pointed at them, and asserts the hook's effect on the loop.
+ */
+
+const dirs: string[] = []
+afterEach(() => { for (const d of dirs.splice(0)) rmSync(d, { recursive: true, force: true }) })
+
+function subagentCarrier(ctx: Context) {
+  return scopeTarget(ctx as unknown as SubagentRuntime, undefined)
+}
+
+/** Write a hooks.json + named executable scripts into a fresh temp dir. */
+function writeConfig(hooks: unknown, scripts: Record<string, string> = {}): string {
+  const dir = mkdtempSync(join(tmpdir(), 'dsh-hooks-claude-'))
+  dirs.push(dir)
+  writeFileSync(join(dir, 'hooks.json'), JSON.stringify({ hooks }))
+  for (const [name, body] of Object.entries(scripts)) {
+    const path = join(dir, name)
+    writeFileSync(path, body)
+    chmodSync(path, 0o755)
+  }
+  return dir
+}
+
+async function harness(configDir: string, adapter: MockAdapter, beforeHooks?: (ctx: Context) => void): Promise<Context> {
+  return (await harnessWithFiber(configDir, adapter, beforeHooks)).ctx
+}
+
+/** {@link harness}, also exposing the bridge's fiber for tests that dispose it. */
+async function harnessWithFiber(
+  configDir: string,
+  adapter: MockAdapter,
+  beforeHooks?: (ctx: Context) => void,
+): Promise<{ ctx: Context; hooks: Fiber }> {
+  const ctx = new Context()
+  await mountAgentLoopTestDependencies(ctx)
+  await ctx.plugin(AgentLoop, { agents: [] })
+  await ctx.plugin(LocalSubprocessRuntime)
+  await ctx.plugin(LocalBashExecutor, { timeoutMs: 10_000 })
+  beforeHooks?.(ctx)
+  const hooks = await ctx.plugin(HooksClaude, { configPath: join(configDir, 'hooks.json') })
+  ctx.llm.registerAdapter(['mock'], adapter)
+  return { ctx, hooks }
+}
+
+function waitForIdle(_ctx: Context, agent: Agent): Promise<void> {
+  return agent.whenIdle()
+}
+
+function events(agent: Agent): SessionEvent[] {
+  return [...agent.session.events]
+}
+
+/**
+ * Poll `predicate` until it returns true or the deadline passes. Detached
+ * emit-listener hooks (session-start, subagent) fire on a `.then` the test can't
+ * await directly; polling for the observable EFFECT is robust under load, where a
+ * single fixed sleep flakes ("async state is not synchronous state").
+ */
+async function waitFor(predicate: () => boolean, timeout = 5000, interval = 10): Promise<void> {
+  const deadline = Date.now() + timeout
+  while (!predicate()) {
+    if (Date.now() > deadline) throw new Error('waitFor: condition not met before deadline')
+    await new Promise(r => setTimeout(r, interval))
+  }
+}
+
+describe('hooks-claude-code bridge — UserPromptSubmit', () => {
+  it('a UserPromptSubmit hook that exits 2 closes a blocked turn without a step', async () => {
+    // UserPromptSubmit ignores its malformed matcher field, then exit 2 blocks
+    // with the reason on stderr.
+    const dir = mkdtempSync(join(tmpdir(), 'dsh-hooks-claude-'))
+    dirs.push(dir)
+    const block = join(dir, 'block.sh')
+    writeFileSync(block, '#!/usr/bin/env bash\necho "prompt denied by policy" >&2\nexit 2\n')
+    chmodSync(block, 0o755)
+    writeFileSync(join(dir, 'hooks.json'), JSON.stringify({ hooks: { UserPromptSubmit: [{ matcher: '[', hooks: [{ type: 'command', command: block }] }] } }))
+
+    const adapter = new MockAdapter([textResponse('should not run')])
+    const ctx = await harness(dir, adapter)
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    agent.followup(createUserMessage({ content: [{ type: 'text', text: 'do something' }], source: { kind: 'user' } }))
+    await waitForIdle(ctx, agent)
+
+    // The prompt was blocked inside its turn before any model step.
+    expect(adapter.requests).toHaveLength(0)
+    expect(events(agent).filter(e => e.type === 'turn/start' || e.type === 'hook/invoked'
+      || e.type === 'hook/result' || e.type === 'turn/end').map(e => e.type))
+      .toEqual(['turn/start', 'hook/invoked', 'hook/result', 'turn/end'])
+  })
+
+  it('a UserPromptSubmit hook printing additionalContext injects it for the model', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'dsh-hooks-claude-'))
+    dirs.push(dir)
+    const ctxScript = join(dir, 'ctx.sh')
+    writeFileSync(ctxScript, '#!/usr/bin/env bash\necho \'{"hookSpecificOutput":{"hookEventName":"UserPromptSubmit","additionalContext":"remember: be brief"}}\'\n')
+    chmodSync(ctxScript, 0o755)
+    writeFileSync(join(dir, 'hooks.json'), JSON.stringify({ hooks: { UserPromptSubmit: [{ hooks: [{ type: 'command', command: ctxScript }] }] } }))
+
+    const adapter = new MockAdapter([textResponse('ok')])
+    const ctx = await harness(dir, adapter)
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
+    await waitForIdle(ctx, agent)
+
+    // The injected context reached the model and is recorded with the plugin source.
+    expect(JSON.stringify(adapter.requests[0]!.messages)).toContain('remember: be brief')
+    const ctxMsg = events(agent).find(e => e.type === 'user/message' && e.data.source.kind !== 'user')
+    expect(ctxMsg?.type === 'user/message' && ctxMsg.data.source).toEqual({ kind: 'plugin', plugin: 'hooks-claude-code' })
+  })
+})
+
+describe('hooks-claude-code bridge — PreToolUse', () => {
+  it('a matching PreToolUse hook that exits 2 denies the tool (isError result), tool never runs', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'dsh-hooks-claude-'))
+    dirs.push(dir)
+    const deny = join(dir, 'deny.sh')
+    writeFileSync(deny, '#!/usr/bin/env bash\necho "danger tool blocked" >&2\nexit 2\n')
+    chmodSync(deny, 0o755)
+    // Matcher "danger" (literal) selects only the danger tool.
+    writeFileSync(join(dir, 'hooks.json'), JSON.stringify({ hooks: { PreToolUse: [{ matcher: 'danger', hooks: [{ type: 'command', command: deny }] }] } }))
+
+    const adapter = new MockAdapter([toolCallResponse('c1', 'danger', {}), textResponse('done')])
+    const ctx = await harness(dir, adapter)
+    let ran = false
+    ctx.tools.register(defineContentToolFixture({ name: 'danger', description: 'd', parameters: {}, async execute() { ran = true; return [{ type: 'text', text: 'should not run' }] } }))
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    agent.followup(createUserMessage({ content: [{ type: 'text', text: 'use danger' }], source: { kind: 'user' } }))
+    await waitForIdle(ctx, agent)
+
+    expect(ran).toBe(false)
+    const result = events(agent).find(e => e.type === 'tool/result')
+    expect(result?.type === 'tool/result' && result.data.message.content[0].isError).toBe(true)
+    expect(result?.type === 'tool/result' && result.data.message.content[0].content.some(b => b.type === 'text' && b.text.includes('danger tool blocked'))).toBe(true)
+  })
+
+  it('a PreToolUse hook whose matcher does NOT match leaves the tool alone', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'dsh-hooks-claude-'))
+    dirs.push(dir)
+    const deny = join(dir, 'deny.sh')
+    writeFileSync(deny, '#!/usr/bin/env bash\nexit 2\n')
+    chmodSync(deny, 0o755)
+    // Matcher only targets "danger" — the "safe" tool is untouched.
+    writeFileSync(join(dir, 'hooks.json'), JSON.stringify({ hooks: { PreToolUse: [{ matcher: 'danger', hooks: [{ type: 'command', command: deny }] }] } }))
+
+    const adapter = new MockAdapter([toolCallResponse('c1', 'safe', {}), textResponse('done')])
+    const ctx = await harness(dir, adapter)
+    let ran = false
+    ctx.tools.register(defineContentToolFixture({ name: 'safe', description: 's', parameters: {}, async execute() { ran = true; return [{ type: 'text', text: 'ran ok' }] } }))
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    agent.followup(createUserMessage({ content: [{ type: 'text', text: 'use safe' }], source: { kind: 'user' } }))
+    await waitForIdle(ctx, agent)
+
+    expect(ran).toBe(true)
+    const result = events(agent).find(e => e.type === 'tool/result')
+    expect(result?.type === 'tool/result' && result.data.message.content[0].isError).toBe(false)
+  })
+})
+
+describe('hooks-claude-code bridge — PostToolUse', () => {
+  it('a PostToolUse hook that blocks (exit 2) turns the result into an isError with feedback', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'dsh-hooks-claude-'))
+    dirs.push(dir)
+    const block = join(dir, 'block.sh')
+    writeFileSync(block, '#!/usr/bin/env bash\necho "output rejected, retry" >&2\nexit 2\n')
+    chmodSync(block, 0o755)
+    writeFileSync(join(dir, 'hooks.json'), JSON.stringify({ hooks: { PostToolUse: [{ hooks: [{ type: 'command', command: block }] }] } }))
+
+    const adapter = new MockAdapter([toolCallResponse('c1', 'echo', {}), textResponse('done')])
+    const ctx = await harness(dir, adapter)
+    ctx.tools.register(defineContentToolFixture({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'raw output' }] } }))
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
+    await waitForIdle(ctx, agent)
+
+    const result = events(agent).find(e => e.type === 'tool/result')
+    // PostToolUse blocks AFTER the tool ran: the result is rewritten to isError + feedback.
+    expect(result?.type === 'tool/result' && result.data.message.content[0].isError).toBe(true)
+    expect(result?.type === 'tool/result' && result.data.message.content[0].content.some(b => b.type === 'text' && b.text.includes('output rejected, retry'))).toBe(true)
+  })
+
+  it('a PostToolUse hook printing additionalContext attaches it after the tool result', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'dsh-hooks-claude-'))
+    dirs.push(dir)
+    const s = join(dir, 'ctx.sh')
+    writeFileSync(s, '#!/usr/bin/env bash\necho \'{"hookSpecificOutput":{"hookEventName":"PostToolUse","additionalContext":"note: tool was slow"}}\'\n')
+    chmodSync(s, 0o755)
+    writeFileSync(join(dir, 'hooks.json'), JSON.stringify({ hooks: { PostToolUse: [{ hooks: [{ type: 'command', command: s }] }] } }))
+
+    const adapter = new MockAdapter([toolCallResponse('c1', 'echo', {}), textResponse('done')])
+    const ctx = await harness(dir, adapter)
+    ctx.tools.register(defineContentToolFixture({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
+    await waitForIdle(ctx, agent)
+
+    const log = events(agent)
+    const resultIdx = log.findIndex(e => e.type === 'tool/result')
+    const ctxIdx = log.findIndex(e => e.type === 'user/message' && e.data.source.kind !== 'user')
+    expect(ctxIdx).toBeGreaterThan(resultIdx) // context appended AFTER the tool result
+    const ctxMsg = log[ctxIdx]
+    expect(ctxMsg?.type === 'user/message' && ctxMsg.data.content.some(b => b.type === 'text' && b.text.includes('tool was slow'))).toBe(true)
+  })
+
+  it('a PreToolUse permissionDecision:ask fails closed without an approval service', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'dsh-hooks-claude-'))
+    dirs.push(dir)
+    const s = join(dir, 'ask.sh')
+    writeFileSync(s, '#!/usr/bin/env bash\necho \'{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"ask","permissionDecisionReason":"needs approval"}}\'\n')
+    chmodSync(s, 0o755)
+    writeFileSync(join(dir, 'hooks.json'), JSON.stringify({ hooks: { PreToolUse: [{ hooks: [{ type: 'command', command: s }] }] } }))
+
+    const adapter = new MockAdapter([toolCallResponse('c1', 'echo', {}), textResponse('done')])
+    const ctx = await harness(dir, adapter)
+    let ran = false
+    ctx.tools.register(defineContentToolFixture({ name: 'echo', description: 'e', parameters: {}, async execute() { ran = true; return [{ type: 'text', text: 'x' }] } }))
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
+    await waitForIdle(ctx, agent)
+
+    // No approval service is mounted, so `ask` fails closed: the tool does not run and the result is isError.
+    expect(ran).toBe(false)
+    const result = events(agent).find(e => e.type === 'tool/result')
+    expect(result?.type === 'tool/result' && result.data.message.content[0].isError).toBe(true)
+    expect(result?.type === 'tool/result' && result.data.message.content[0].content.some(b => b.type === 'text' && b.text.includes('needs approval'))).toBe(true)
+  })
+})
+
+describe('hooks-claude-code bridge — SessionStart', () => {
+  it('a SessionStart hook injects additionalContext the first request sees', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'dsh-hooks-claude-'))
+    dirs.push(dir)
+    const s = join(dir, 'start.sh')
+    writeFileSync(s, '#!/usr/bin/env bash\necho \'{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":"project uses tabs"}}\'\n')
+    chmodSync(s, 0o755)
+    // matcher 'startup' selects the startup source.
+    writeFileSync(join(dir, 'hooks.json'), JSON.stringify({ hooks: { SessionStart: [{ matcher: 'startup', hooks: [{ type: 'command', command: s }] }] } }))
+
+    const adapter = new MockAdapter([textResponse('ok')])
+    const ctx = await harness(dir, adapter)
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    // session-start fires async (detached .then → agent.inject); injection now
+    // enters the next-step inbox directly and becomes a user/message only after
+    // step entry, so synchronize on the pending inbox item before sending.
+    await waitFor(() => agent.inbox.nextStep.some(message =>
+      message.content.some(block => block.type === 'text' && block.text.includes('project uses tabs'))))
+    agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
+    await waitForIdle(ctx, agent)
+
+    expect(JSON.stringify(adapter.requests[0]!.messages)).toContain('project uses tabs')
+  })
+})
+
+describe('hooks-claude-code bridge — SubagentStart / SubagentStop (observe)', () => {
+  it('runs SubagentStart and SubagentStop hooks when the subagent lifecycle events fire', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'dsh-hooks-claude-'))
+    dirs.push(dir)
+    // Each hook touches a marker file so we can assert it ran (these events are
+    // observe-only — there is no decision to assert, only the side effect).
+    const startMarker = join(dir, 'start-ran')
+    const stopMarker = join(dir, 'stop-ran')
+    const startHook = join(dir, 'start.sh')
+    const stopHook = join(dir, 'stop.sh')
+    writeFileSync(startHook, `#!/usr/bin/env bash\ntouch "${startMarker}"\n`)
+    writeFileSync(stopHook, `#!/usr/bin/env bash\ntouch "${stopMarker}"\n`)
+    chmodSync(startHook, 0o755)
+    chmodSync(stopHook, 0o755)
+    writeFileSync(join(dir, 'hooks.json'), JSON.stringify({ hooks: {
+      SubagentStart: [{ hooks: [{ type: 'command', command: startHook }] }],
+      SubagentStop: [{ hooks: [{ type: 'command', command: stopHook }] }],
+    } }))
+
+    const adapter = new MockAdapter([])
+    const { ctx, hooks } = await harnessWithFiber(dir, adapter)
+    // Drive the observe-only lifecycle events directly (no real child needed — the
+    // bridge just listens). No child agent is registered, so SubagentStart's
+    // child lookup yields undefined and it simply runs the hook.
+    ctx.emit(subagentCarrier(ctx), 'subagent/start', { runId: SubagentRunId('run-1'), provider: 'inproc', id: SessionId('child-1'), local: false })
+    ctx.emit(subagentCarrier(ctx), 'subagent/end', { runId: SubagentRunId('run-1'), provider: 'inproc', id: SessionId('child-1'), local: false, stopReason: 'completed', lastAssistantMessage: [{ type: 'text', text: 'done' }] })
+
+    // Both hooks run async (detached .then); poll for their marker files rather
+    // than a fixed sleep that flakes under load.
+    await waitFor(() => existsSync(startMarker) && existsSync(stopMarker))
+    expect(existsSync(startMarker)).toBe(true)
+    expect(existsSync(stopMarker)).toBe(true)
+    // The markers prove the hook PROCESSES ran, not that the detached `.then`
+    // continuations did (`touch` lands before the process exits). Dispose drains
+    // them, so the no-context arm of the SubagentStart continuation — covered
+    // only here — executes before this file's coverage snapshot instead of
+    // racing it (the arm went uncovered on a loaded CI runner and failed the
+    // per-file 100% branch gate).
+    await hooks.dispose()
+  })
+
+  it('disposing the bridge aborts a still-running hook and drains to quiescence', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'dsh-hooks-claude-'))
+    dirs.push(dir)
+    const pidFile = join(dir, 'pid')
+    const marker = join(dir, 'started')
+    const slowHook = join(dir, 'slow.sh')
+    // 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. Dispose must KILL the process (the tracker's abort signal), not
+    // await its exit or its 10-minute default hook timeout.
+    writeFileSync(slowHook, `#!/usr/bin/env bash\necho $$ > "${pidFile}"\ntouch "${marker}"\nsleep 30\n`)
+    chmodSync(slowHook, 0o755)
+    writeFileSync(join(dir, 'hooks.json'), JSON.stringify({ hooks: {
+      SubagentStart: [{ hooks: [{ type: 'command', command: slowHook }] }],
+    } }))
+
+    const { ctx, hooks } = await harnessWithFiber(dir, new MockAdapter([]))
+    const warn = vi.fn()
+    ctx.logger.warn = warn as never
+    ctx.emit(subagentCarrier(ctx), 'subagent/start', { runId: SubagentRunId('run-1'), provider: 'inproc', id: SessionId('child-1'), local: false })
+    await waitFor(() => existsSync(marker))
+    const pid = Number(readFileSync(pidFile, 'utf8').trim())
+    await hooks.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). An untracked fire-and-forget regression would leave the
+    // process alive (or unreaped) and fail this deterministically.
+    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.
+    expect(warn).not.toHaveBeenCalledWith(expect.stringContaining('SubagentStart hook failed'))
+  })
+})
+
+describe('hooks-claude-code bridge — load resilience', () => {
+  it('a missing config file registers no hooks and does not crash the loop', async () => {
+    const adapter = new MockAdapter([textResponse('fine')])
+    const ctx = new Context()
+    await mountAgentLoopTestDependencies(ctx)
+    await ctx.plugin(AgentLoop, { agents: [] })
+    await ctx.plugin(LocalSubprocessRuntime)
+    await ctx.plugin(LocalBashExecutor, { timeoutMs: 10_000 })
+    await ctx.plugin(HooksClaude, { configPath: '/nonexistent/hooks.json' })
+    ctx.llm.registerAdapter(['mock'], adapter)
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
+    await waitForIdle(ctx, agent)
+    // The turn ran normally — no hooks, no crash.
+    expect(adapter.requests).toHaveLength(1)
+  })
+
+  it('an invalid regex matcher is reported and registers no hooks', async () => {
+    const dir = writeConfig({
+      UserPromptSubmit: [{ hooks: [{ type: 'command', command: 'exit 2' }] }],
+      PreToolUse: [{ matcher: '(', hooks: [{ type: 'command', command: 'exit 2' }] }],
+    })
+    const adapter = new MockAdapter([textResponse('fine')])
+    const warn = vi.fn()
+    const ctx = await harness(dir, adapter, (ctx) => { ctx.logger.warn = warn as never })
+    const agent = ctx.agentLoop.create(SessionId('invalid-claude-matcher'), { provider: 'mock', model: 'mock' })
+    agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
+    await waitForIdle(ctx, agent)
+    expect(adapter.requests).toHaveLength(1)
+    expect(events(agent).some(event => event.type === 'hook/invoked')).toBe(false)
+
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining(
+      'invalid claude-code regex matcher "(" on event "PreToolUse"',
+    ))
+  })
+
+  it('an invalid matcher on an unsupported event does not disable supported hooks', async () => {
+    const dir = writeConfig({
+      Setup: [{ matcher: '(', hooks: [{ type: 'command', command: 'exit 0' }] }],
+      UserPromptSubmit: [{ hooks: [{ type: 'command', command: 'exit 2' }] }],
+    })
+    const adapter = new MockAdapter([textResponse('should not run')])
+    const warn = vi.fn()
+    const ctx = await harness(dir, adapter, (ctx) => { ctx.logger.warn = warn as never })
+    const agent = ctx.agentLoop.create(SessionId('unsupported-claude-matcher'), { provider: 'mock', model: 'mock' })
+    agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
+    await waitForIdle(ctx, agent)
+
+    expect(adapter.requests).toHaveLength(0)
+    expect(events(agent).filter(event => event.type === 'turn/start' || event.type === 'hook/invoked'
+      || event.type === 'hook/result' || event.type === 'turn/end').map(event => event.type))
+      .toEqual(['turn/start', 'hook/invoked', 'hook/result', 'turn/end'])
+    expect(warn).not.toHaveBeenCalledWith(expect.stringContaining('invalid claude-code regex matcher'))
+  })
+
+  it('disposing the bridge fiber removes its listeners (HMR safety)', async () => {
+    // A BLOCKING UserPromptSubmit hook: if the listener leaked past dispose it
+    // would veto the prompt (0 model requests) and log a hook/invoked. Build the
+    // ctx WITHOUT the harness's own bridge mount so this is the ONLY mount, then
+    // dispose it — a leaked listener fails the test (a no-op `true` hook would
+    // pass even leaked, so it proved nothing).
+    const dir = writeConfig({ UserPromptSubmit: [{ hooks: [{ type: 'command', command: 'exit 2' }] }] })
+    const adapter = new MockAdapter([textResponse('ok')])
+    const ctx = new Context()
+    await mountAgentLoopTestDependencies(ctx)
+    await ctx.plugin(AgentLoop, { agents: [] })
+    await ctx.plugin(LocalSubprocessRuntime)
+    await ctx.plugin(LocalBashExecutor, { timeoutMs: 10_000 })
+    const fiber = await ctx.plugin(HooksClaude, { configPath: join(dir, 'hooks.json') })
+    await fiber.dispose()
+    ctx.llm.registerAdapter(['mock'], adapter)
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
+    await waitForIdle(ctx, agent)
+    expect(adapter.requests).toHaveLength(1) // not blocked → the listener is gone
+    expect(events(agent).some(e => e.type === 'hook/invoked')).toBe(false) // no hook ran
+  })
+
+  it('has the namespace-plugin export shape (no stray default) so the Loader keeps name/inject/apply', () => {
+    // Postmortem 0001 guard: this plugin HAS `inject = ['bash']`, so a stray
+    // `export default apply` would collapse the module via `unwrapExports`
+    // (`exports.default ?? exports`), DROP `inject`, and crash at load with
+    // "cannot get property … without inject". Guard the shape directly.
+    expect('default' in HooksClaude).toBe(false)
+    expect(HooksClaude.name).toBe('hooks-claude-code')
+    expect(HooksClaude.inject).toEqual(['shell'])
+    const loader = Object.create(Loader.prototype) as Loader
+    const unwrapped = loader.unwrapExports(HooksClaude) as Record<string, unknown>
+    expect(unwrapped).toBe(HooksClaude)
+    expect(unwrapped.name).toBe('hooks-claude-code')
+    expect(unwrapped.inject).toEqual(['shell'])
+    expect(typeof unwrapped.apply).toBe('function')
+  })
+})

packages/hooks/hooks-claude-code/tests/config.spec.ts

@@ -0,0 +1,95 @@
+import { describe, expect, it } from 'vitest'
+import { parseClaudeCodeConfig, substituteCommand } from '@deepseek-ai/dsh-hooks-claude-code/src/config.ts'
+
+describe('substituteCommand', () => {
+  it('replaces CLAUDE_PLUGIN_ROOT and CLAUDE_PROJECT_DIR (all occurrences)', () => {
+    expect(substituteCommand('${CLAUDE_PLUGIN_ROOT}/x.sh', { pluginRoot: '/p' })).toBe('/p/x.sh')
+    expect(substituteCommand('${CLAUDE_PROJECT_DIR}/a ${CLAUDE_PROJECT_DIR}/b', { projectDir: '/proj' })).toBe('/proj/a /proj/b')
+    expect(substituteCommand('${CLAUDE_PLUGIN_ROOT}-${CLAUDE_PROJECT_DIR}', { pluginRoot: '/p', projectDir: '/d' })).toBe('/p-/d')
+  })
+  it('leaves the command untouched when no vars are supplied', () => {
+    expect(substituteCommand('${CLAUDE_PLUGIN_ROOT}/x', {})).toBe('${CLAUDE_PLUGIN_ROOT}/x')
+  })
+})
+
+describe('parseClaudeCodeConfig', () => {
+  it('parses a bare event map and a settings-style { hooks: … } wrapper identically', () => {
+    const groups = { PreToolUse: [{ matcher: 'Bash', hooks: [{ type: 'command', command: 'x.sh' }] }] }
+    const bare = parseClaudeCodeConfig(groups)
+    const wrapped = parseClaudeCodeConfig({ hooks: groups })
+    expect(bare.config).toEqual(wrapped.config)
+    expect(bare.config.PreToolUse).toEqual([{ matcher: 'Bash', hooks: [{ command: 'x.sh' }] }])
+  })
+
+  it('carries timeout → timeoutSec and substitutes the command', () => {
+    const { config } = parseClaudeCodeConfig(
+      { Stop: [{ hooks: [{ type: 'command', command: '${CLAUDE_PLUGIN_ROOT}/s.sh', timeout: 30 }] }] },
+      { pluginRoot: '/p' },
+    )
+    expect(config.Stop).toEqual([{ hooks: [{ command: '/p/s.sh', timeoutSec: 30 }] }])
+  })
+
+  it('skips non-command hooks (recorded) and keeps the command ones in the same group', () => {
+    const { config, skipped } = parseClaudeCodeConfig({
+      PreToolUse: [{ hooks: [
+        { type: 'prompt', prompt: 'hi' },
+        { type: 'command', command: 'ok.sh' },
+        { type: 'http', url: 'http://x' },
+      ] }],
+    })
+    expect(config.PreToolUse).toEqual([{ hooks: [{ command: 'ok.sh' }] }])
+    expect(skipped).toEqual([{ event: 'PreToolUse', type: 'prompt' }, { event: 'PreToolUse', type: 'http' }])
+  })
+
+  it('treats a hook with no `type` as a command (CC default)', () => {
+    const { config } = parseClaudeCodeConfig({ Stop: [{ hooks: [{ command: 'd.sh' }] }] })
+    expect(config.Stop).toEqual([{ hooks: [{ command: 'd.sh' }] }])
+  })
+
+  it('drops malformed entries without throwing: non-array groups, non-object group/hook, missing command, empty groups', () => {
+    expect(parseClaudeCodeConfig({ PreToolUse: 'nope' }).config).toEqual({})
+    expect(parseClaudeCodeConfig({ PreToolUse: [42, { hooks: 'no' }, { hooks: [7, { type: 'command' }] }] }).config).toEqual({})
+    // a group whose only hook lacks a command string drops the whole (empty) group
+    expect(parseClaudeCodeConfig({ Stop: [{ hooks: [{ type: 'command', command: 5 }] }] }).config).toEqual({})
+  })
+
+  it('returns empty for a non-object / null / array top level', () => {
+    expect(parseClaudeCodeConfig(null).config).toEqual({})
+    expect(parseClaudeCodeConfig(42).config).toEqual({})
+    expect(parseClaudeCodeConfig([1, 2]).config).toEqual({})
+  })
+
+  it('omits the matcher key when the group has none (match-all)', () => {
+    const { config } = parseClaudeCodeConfig({ Stop: [{ hooks: [{ type: 'command', command: 's.sh' }] }] })
+    expect('matcher' in config.Stop![0]!).toBe(false)
+  })
+
+  it('rejects an invalid regex matcher with its event name', () => {
+    expect(() => parseClaudeCodeConfig({
+      PreToolUse: [{ matcher: '(', hooks: [{ type: 'command', command: 'x.sh' }] }],
+    })).toThrow('invalid claude-code regex matcher "(" on event "PreToolUse"')
+  })
+
+  it('discards matcher fields on events without matcher subjects before validation', () => {
+    const { config } = parseClaudeCodeConfig({
+      UserPromptSubmit: [{ matcher: '[', hooks: [{ type: 'command', command: 'prompt.sh' }] }],
+      Stop: [{ matcher: '(', hooks: [{ type: 'command', command: 'stop.sh' }] }],
+    })
+
+    expect(config).toEqual({
+      UserPromptSubmit: [{ hooks: [{ command: 'prompt.sh' }] }],
+      Stop: [{ hooks: [{ command: 'stop.sh' }] }],
+    })
+  })
+
+  it('ignores invalid matchers on unsupported events without dropping supported hooks', () => {
+    const { config } = parseClaudeCodeConfig({
+      Setup: [{ matcher: '(', hooks: [{ type: 'command', command: 'ignored.sh' }] }],
+      PreToolUse: [{ matcher: 'Bash', hooks: [{ type: 'command', command: 'kept.sh' }] }],
+    })
+
+    expect(config).toEqual({
+      PreToolUse: [{ matcher: 'Bash', hooks: [{ command: 'kept.sh' }] }],
+    })
+  })
+})

packages/hooks/hooks-claude-code/tests/coverage-cases.ts

@@ -0,0 +1,760 @@
+import { createUserMessage } from '@deepseek-ai/dsh-llm'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { mkdtempSync, rmSync, writeFileSync, chmodSync, existsSync, readFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { Context } from '@deepseek-ai/cordis'
+import { SessionId, type SessionEvent } from '@deepseek-ai/dsh-session'
+import JsonlSessionPersistence from '@deepseek-ai/dsh-session-persistence-jsonl'
+import { defineContentToolFixture } from '@deepseek-ai/dsh-tools'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import AgentLoop from '@deepseek-ai/dsh-agent-loop'
+import { mountAgentLoopTestDependencies } from '@deepseek-ai/dsh-agent-loop-testkit'
+import { LocalBashExecutor } from '@deepseek-ai/dsh-bash-local'
+import LocalSubprocessRuntime from '@deepseek-ai/dsh-subprocess-local'
+import { scopeTarget } from '@deepseek-ai/dsh-scope'
+import SubagentRuntime, { SubagentRunId } from '@deepseek-ai/dsh-subagent'
+import * as HooksClaude from '@deepseek-ai/dsh-hooks-claude-code'
+import { MockAdapter, textResponse, toolCallResponse } from '../../../core/agent-loop/tests/mock-adapter.ts'
+
+const testToolSignal = new AbortController().signal
+
+/** Targeted branch coverage for the CC bridge: option arms, warn paths, no-agent
+ * fallbacks, contextFrom-empty, and the detached-listener catch handlers. */
+
+const dirs: string[] = []
+afterEach(() => { for (const d of dirs.splice(0)) rmSync(d, { recursive: true, force: true }) })
+
+function subagentCarrier(ctx: Context) {
+  return scopeTarget(ctx as unknown as SubagentRuntime, undefined)
+}
+
+function dir(): string { const d = mkdtempSync(join(tmpdir(), 'dsh-hc-cov-')); dirs.push(d); return d }
+function sh(d: string, name: string, body: string): string {
+  const p = join(d, name); writeFileSync(p, body); chmodSync(p, 0o755); return p
+}
+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; stderrSummaryMaxChars?: number; sessionRoot?: string }
+async function harness(configPath: string, adapter: MockAdapter, opts: HarnessOpts = {}): Promise<Context> {
+  const ctx = new Context()
+  await mountAgentLoopTestDependencies(ctx)
+  if (opts.sessionRoot !== undefined) await ctx.plugin(JsonlSessionPersistence, { root: opts.sessionRoot })
+  await ctx.plugin(AgentLoop, { agents: [] })
+  await ctx.plugin(LocalSubprocessRuntime)
+  await ctx.plugin(LocalBashExecutor, { timeoutMs: 10_000 })
+  await ctx.plugin(HooksClaude, { configPath, ...opts })
+  ctx.llm.registerAdapter(['mock'], adapter)
+  return ctx
+}
+function waitForIdle(_ctx: Context, agent: Agent): Promise<void> {
+  return agent.whenIdle()
+}
+function events(agent: Agent): SessionEvent[] { return [...agent.session.events] }
+/** Poll until `predicate` holds or the deadline passes — robust to detached
+ * emit-listener hooks firing on a `.then` (a fixed sleep flakes under load). */
+async function waitFor(predicate: () => boolean, timeout = 5000, interval = 10): Promise<void> {
+  const deadline = Date.now() + timeout
+  while (!predicate()) {
+    if (Date.now() > deadline) throw new Error('waitFor: condition not met before deadline')
+    await new Promise(r => setTimeout(r, interval))
+  }
+}
+
+export type CoverageGroup = 'config' | 'stop' | 'context' | 'edge-paths'
+
+/** Register independently schedulable slices of the hooks-claude-code coverage matrix. */
+export function defineCoverageCases(group: CoverageGroup): void {
+  if (group === 'config') describe('hooks-claude-code coverage — config option arms + substitution + skip warning', () => {
+    it('uses the persistence locator for transcript_path and an empty string without one', async () => {
+      async function capture(sessionRoot?: string): Promise<{ payload: { transcript_path: string }; expected: string | undefined }> {
+        const d = dir()
+        const cap = join(d, 'payload')
+        const path = hooks(d, { PreToolUse: [{ hooks: [{ type: 'command', command: sh(d, 'capture.sh', `#!/usr/bin/env bash\ncat > "${cap}"\n`) }] }] })
+        const adapter = new MockAdapter([toolCallResponse('c1', 'echo', {}), textResponse('done')])
+        const ctx = await harness(path, adapter, { ...sessionRoot !== undefined ? { sessionRoot } : {} })
+        ctx.tools.register(defineContentToolFixture({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
+        const agent = ctx.agentLoop.create(SessionId('transcript'), { provider: 'mock', model: 'mock' })
+        agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
+        await waitForIdle(ctx, agent)
+        return {
+          payload: JSON.parse(readFileSync(cap, 'utf8')) as { transcript_path: string },
+          expected: ctx.get('sessionPersistence')?.locate(agent.session.header)?.path,
+        }
+      }
+
+      const located = await capture(dir())
+      expect(located.payload.transcript_path).toBe(located.expected)
+      expect((await capture()).payload.transcript_path).toBe('')
+    }, 15_000) // Two real agent/hook subprocess loops need process startup and teardown headroom.
+
+    it('honors pluginRoot + projectDir substitution and warns on a skipped non-command hook', async () => {
+      const d = dir()
+      // ${CLAUDE_PLUGIN_ROOT} resolves to d; the script writes its own cwd-independent marker.
+      const marker = join(d, 'ran')
+      sh(d, 'h.sh', `#!/usr/bin/env bash\ntouch "${marker}"\n`)
+      const path = hooks(d, {
+        PreToolUse: [{ hooks: [
+          { type: 'prompt', prompt: 'skipme' }, // skipped → warn loop
+          { type: 'command', command: '${CLAUDE_PLUGIN_ROOT}/h.sh' }, // substituted
+        ] }],
+      })
+      const warn = vi.fn()
+      const adapter = new MockAdapter([toolCallResponse('c1', 'echo', {}), textResponse('done')])
+      const ctx = await harness(path, adapter, { pluginRoot: d, projectDir: d })
+      ctx.logger.warn = warn as never
+      ctx.tools.register(defineContentToolFixture({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
+      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
+      await waitForIdle(ctx, agent)
+      expect(existsSync(marker)).toBe(true) // substituted command ran
+    }, 15_000) // Real agent and hook subprocess startup can exceed Vitest's default under coverage concurrency.
+
+    it('warns and honors updatedInput as a no-op (input rewrite deferred)', async () => {
+      const d = dir()
+      const s = sh(d, 'u.sh', '#!/usr/bin/env bash\necho \'{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow","updatedInput":{"command":"rewritten"}}}\'\n')
+      const path = hooks(d, { PreToolUse: [{ hooks: [{ type: 'command', command: s }] }] })
+      const warn = vi.fn()
+      const adapter = new MockAdapter([toolCallResponse('c1', 'echo', { command: 'original' }), textResponse('done')])
+      const ctx = await harness(path, adapter)
+      ctx.logger.warn = warn as never
+      let sawArgs: unknown
+      ctx.tools.register(defineContentToolFixture({ name: 'echo', description: 'e', parameters: { command: { type: 'string' } }, async execute(args) { sawArgs = args; return [{ type: 'text', text: 'ok' }] } }))
+      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
+      await waitForIdle(ctx, agent)
+      // updatedInput is NOT honored — the tool ran with the ORIGINAL args.
+      expect((sawArgs as { command?: string }).command).toBe('original')
+      expect(warn).toHaveBeenCalledWith(expect.stringContaining('updatedInput'))
+    })
+  })
+
+  if (group === 'config') describe('hooks-claude-code coverage — empty/no-op outcomes and no-agent paths', () => {
+    it('a clean exit-0 hook with no output is a no-op (contextFrom empty → next())', async () => {
+      const d = dir()
+      const s = sh(d, 'noop.sh', '#!/usr/bin/env bash\nexit 0\n')
+      const path = hooks(d, { UserPromptSubmit: [{ hooks: [{ type: 'command', command: s }] }] })
+      const adapter = new MockAdapter([textResponse('ran')])
+      const ctx = await harness(path, adapter)
+      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
+      await waitForIdle(ctx, agent)
+      // The prompt proceeded unchanged; no injected context.
+      expect(adapter.requests).toHaveLength(1)
+      expect(events(agent).some(e => e.type === 'user/message' && e.data.source.kind !== 'user')).toBe(false)
+    })
+
+    it('a PreToolUse hook fires for a no-agent direct tool call (no session/turn to record into)', async () => {
+      const d = dir()
+      const s = sh(d, 'deny.sh', '#!/usr/bin/env bash\necho "no" >&2\nexit 2\n')
+      const path = hooks(d, { PreToolUse: [{ hooks: [{ type: 'command', command: s }] }] })
+      const ctx = await harness(path, new MockAdapter([]))
+      let ran = false
+      ctx.tools.register(defineContentToolFixture({ name: 'echo', description: 'e', parameters: {}, async execute() { ran = true; return [{ type: 'text', text: 'x' }] } }))
+      const { CallId } = await import('@deepseek-ai/dsh-llm')
+      const result = await ctx.tools.execute({ signal: testToolSignal, callId: CallId('c1'), name: 'echo', arguments: {} })
+      expect(ran).toBe(false)
+      expect(result.isError).toBe(true)
+    })
+
+    it('a long stderr is truncated in the hook/result summary', 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)
+      ctx.tools.register(defineContentToolFixture({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
+      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
+      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-code: 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(defineContentToolFixture({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
+      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
+      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) + '…')
+    })
+  })
+
+  if (group === 'stop') describe('hooks-claude-code coverage — Stop continuation + subagent inject/catch', () => {
+    it('a Stop hook that blocks (exit 2) forces the turn to continue (CC dialect)', async () => {
+      const d = dir()
+      const marker = join(d, 'fired')
+      const s = sh(d, 'stop.sh', `#!/usr/bin/env bash\nif [ -e "${marker}" ]; then exit 0; fi\ntouch "${marker}"\necho "continue please" >&2\nexit 2\n`)
+      const path = hooks(d, { Stop: [{ hooks: [{ type: 'command', command: s }] }] })
+      const adapter = new MockAdapter([textResponse('one'), textResponse('two')])
+      const ctx = await harness(path, adapter)
+      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
+      await waitForIdle(ctx, agent)
+      expect(adapter.requests).toHaveLength(2)
+      expect(JSON.stringify(adapter.requests[1]!.messages)).toContain('continue please')
+    })
+
+    it('a Stop hook that blocks with EMPTY stderr still forces continuation (no reason required)', async () => {
+    // A blocking Stop hook with no stderr yields `deny` without a reason. The block still forces
+    // continuation; the script self-limits to one block to avoid a loop.
+      const d = dir()
+      const marker = join(d, 'fired')
+      const s = sh(d, 'stop.sh', `#!/usr/bin/env bash\nif [ -e "${marker}" ]; then exit 0; fi\ntouch "${marker}"\nexit 2\n`)
+      const path = hooks(d, { Stop: [{ hooks: [{ type: 'command', command: s }] }] })
+      const adapter = new MockAdapter([textResponse('one'), textResponse('two')])
+      const ctx = await harness(path, adapter)
+      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
+      await waitForIdle(ctx, agent)
+      // A second model request ran → the empty-reason block forced continuation.
+      expect(adapter.requests).toHaveLength(2)
+      // The steering carried the fallback reason (no stderr to use).
+      expect(JSON.stringify(adapter.requests[1]!.messages)).toContain('blocked by Stop hook')
+    })
+
+    it('SubagentStart additionalContext is injected into a REGISTERED live child', async () => {
+      const d = dir()
+      const s = sh(d, 'sa.sh', '#!/usr/bin/env bash\necho \'{"hookSpecificOutput":{"hookEventName":"SubagentStart","additionalContext":"child guidance"}}\'\n')
+      const path = hooks(d, { SubagentStart: [{ hooks: [{ type: 'command', command: s }] }] })
+      const ctx = await harness(path, new MockAdapter([]))
+      const injected: string[] = []
+      const child = {
+        id: SessionId('child-x'),
+        inject: (input: { content: Array<{ type: string; text?: string }> }) => {
+          injected.push(input.content.map(block => block.text ?? '').join(''))
+        },
+        session: { id: SessionId('child-x'), header: { id: 'child-x' } },
+      } as unknown as Parameters<typeof ctx.agents.register>[0]
+      ctx.agents.register(child)
+      ctx.emit(subagentCarrier(ctx), 'subagent/start', { runId: SubagentRunId('run-x'), provider: 'p', id: SessionId('child-x'), local: true })
+      await waitFor(() => injected.includes('child guidance'))
+      expect(injected).toContain('child guidance')
+    })
+
+    it('a throwing SubagentStart/SubagentStop hook run is contained (logged)', async () => {
+      const d = dir()
+      // A hook command that does not exist makes runHook resolve a non-blocking
+      // error (not a throw), so to hit the .catch we make the .then throw: register
+      // a child whose inject throws for SubagentStart.
+      const s = sh(d, 'sa.sh', '#!/usr/bin/env bash\necho \'{"hookSpecificOutput":{"hookEventName":"SubagentStart","additionalContext":"x"}}\'\n')
+      const path = hooks(d, { SubagentStart: [{ hooks: [{ type: 'command', command: s }] }] })
+      const ctx = await harness(path, new MockAdapter([]))
+      const warn = vi.fn(); ctx.logger.warn = warn as never
+      const child = { id: SessionId('child-y'), inject: () => { throw new Error('inject boom') }, session: { id: SessionId('child-y'), header: { id: 'child-y' } } } as unknown as Parameters<typeof ctx.agents.register>[0]
+      ctx.agents.register(child)
+      ctx.emit(subagentCarrier(ctx), 'subagent/start', { runId: SubagentRunId('run-y'), provider: 'p', id: SessionId('child-y'), local: true })
+      await waitFor(() => warn.mock.calls.some(c => String(c[0]).includes('SubagentStart hook failed')))
+      expect(warn).toHaveBeenCalledWith(expect.stringContaining('SubagentStart hook failed'))
+    })
+  })
+
+  if (group === 'stop') describe('hooks-claude-code coverage — default reasons + sparse payloads', () => {
+    it('PreToolUse deny with EMPTY stderr uses the default reason', async () => {
+      const d = dir()
+      const s = sh(d, 'deny.sh', '#!/usr/bin/env bash\nexit 2\n') // exit 2, no stderr
+      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)
+      ctx.tools.register(defineContentToolFixture({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'x' }] } }))
+      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
+      await waitForIdle(ctx, agent)
+      const result = events(agent).find(e => e.type === 'tool/result')
+      expect(result?.type === 'tool/result' && result.data.message.content[0].content.some(b => b.type === 'text' && b.text.includes('blocked by PreToolUse hook'))).toBe(true)
+    })
+
+    it('PostToolUse deny with EMPTY stderr + no context uses the default feedback', async () => {
+      const d = dir()
+      const s = sh(d, 'block.sh', '#!/usr/bin/env bash\nexit 2\n')
+      const path = hooks(d, { PostToolUse: [{ hooks: [{ type: 'command', command: s }] }] })
+      const adapter = new MockAdapter([toolCallResponse('c1', 'echo', {}), textResponse('done')])
+      const ctx = await harness(path, adapter)
+      ctx.tools.register(defineContentToolFixture({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
+      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
+      await waitForIdle(ctx, agent)
+      const result = events(agent).find(e => e.type === 'tool/result')
+      expect(result?.type === 'tool/result' && result.data.message.content[0].content.some(b => b.type === 'text' && b.text.includes('blocked by PostToolUse hook'))).toBe(true)
+    })
+
+    it('SubagentStop with no registered child runs the hook cleanly (fire-and-forget)', async () => {
+      const d = dir()
+      // The agents registry has no entry for the id, so the child lookup yields
+      // undefined and the payload falls back to base(undefined) — assert the
+      // observe-only SubagentStop run still executes the hook without crashing.
+      const marker = join(d, 'stopran')
+      const s = sh(d, 'stop.sh', `#!/usr/bin/env bash\ntouch "${marker}"\n`)
+      const path = hooks(d, { SubagentStop: [{ hooks: [{ type: 'command', command: s }] }] })
+      const ctx = await harness(path, new MockAdapter([]))
+      ctx.emit(subagentCarrier(ctx), 'subagent/end', { runId: SubagentRunId('run-z'), provider: 'p', id: SessionId('child-z'), local: false, stopReason: 'completed' })
+      await waitFor(() => existsSync(marker))
+      expect(existsSync(marker)).toBe(true)
+    })
+  })
+
+  if (group === 'edge-paths') describe('hooks-claude-code coverage — more default/sparse arms', () => {
+    it('UserPromptSubmit deny with EMPTY stderr uses the default block reason', async () => {
+      const d = dir()
+      const s = sh(d, 'block.sh', '#!/usr/bin/env bash\nexit 2\n')
+      const path = hooks(d, { UserPromptSubmit: [{ hooks: [{ type: 'command', command: s }] }] })
+      const adapter = new MockAdapter([textResponse('no')])
+      const ctx = await harness(path, adapter)
+      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
+      await waitForIdle(ctx, agent)
+      expect(events(agent).filter(e => e.type === 'turn/start' || e.type === 'hook/invoked'
+        || e.type === 'hook/result' || e.type === 'turn/end').map(e => e.type))
+        .toEqual(['turn/start', 'hook/invoked', 'hook/result', 'turn/end'])
+    })
+
+    it('a PreToolUse ask with NO reason omits the reason (false arm)', async () => {
+      const d = dir()
+      const s = sh(d, 'ask.sh', '#!/usr/bin/env bash\necho \'{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"ask"}}\'\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)
+      let ran = false
+      ctx.tools.register(defineContentToolFixture({ name: 'echo', description: 'e', parameters: {}, async execute() { ran = true; return [{ type: 'text', text: 'x' }] } }))
+      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
+      await waitForIdle(ctx, agent)
+      // ask (no reason) → degrades to deny with the registry's generic message.
+      expect(ran).toBe(false)
+      expect(events(agent).some(e => e.type === 'tool/result' && e.data.message.content[0].isError)).toBe(true)
+    })
+
+    it('a recorded clean exit-0 hook with no stderr omits exitCode-extra/stderrSummary fields', async () => {
+      const d = dir()
+      const s = sh(d, 'noop.sh', '#!/usr/bin/env bash\nexit 0\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)
+      ctx.tools.register(defineContentToolFixture({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
+      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
+      await waitForIdle(ctx, agent)
+      const res = events(agent).find(e => e.type === 'hook/result')
+      expect(res?.type === 'hook/result' && res.data.exitCode).toBe(0)
+      expect(res?.type === 'hook/result' && 'stderrSummary' in res.data).toBe(false)
+    })
+  })
+
+  if (group === 'edge-paths') describe('hooks-claude-code coverage — schema-bypass apply + unspawnable hook', () => {
+    it('a direct apply() (schema bypass) with only configPath runs', async () => {
+      const d = dir()
+      const marker = join(d, 'ran')
+      const s = sh(d, 'h.sh', `#!/usr/bin/env bash\ntouch "${marker}"\n`)
+      hooks(d, { UserPromptSubmit: [{ hooks: [{ type: 'command', command: s }] }] })
+      const adapter = new MockAdapter([textResponse('ok')])
+      const ctx = new Context()
+      await mountAgentLoopTestDependencies(ctx)
+      await ctx.plugin(AgentLoop, { agents: [] })
+      await ctx.plugin(LocalSubprocessRuntime)
+      await ctx.plugin(LocalBashExecutor, { timeoutMs: 10_000 })
+      // Direct apply with only configPath — bypasses schemastery's defaults, so
+      // the bridge must run on the raw minimal config (the per-hook timeout is
+      // the protocol lib's reference default, not a config knob).
+      HooksClaude.apply(ctx, { configPath: join(d, 'hooks.json') })
+      ctx.llm.registerAdapter(['mock'], adapter)
+      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
+      await waitForIdle(ctx, agent)
+      expect(existsSync(marker)).toBe(true)
+    })
+
+    it('a non-zero non-2 hook exit (e.g. a command-not-found 127) is a non-blocking error; the tool still runs', async () => {
+      const d = dir()
+      // `bash -c` of a missing program exits 127 — a non-blocking error (not 0, not
+      // 2 → no decision), so the tool proceeds; the hook/result records exit 127.
+      const path = hooks(d, { PreToolUse: [{ hooks: [{ type: 'command', command: '/nonexistent/definitely/not/a/command' }] }] })
+      const adapter = new MockAdapter([toolCallResponse('c1', 'echo', {}), textResponse('done')])
+      const ctx = await harness(path, adapter)
+      let ran = false
+      ctx.tools.register(defineContentToolFixture({ name: 'echo', description: 'e', parameters: {}, async execute() { ran = true; return [{ type: 'text', text: 'ok' }] } }))
+      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
+      await waitForIdle(ctx, agent)
+      expect(ran).toBe(true)
+      const res = events(agent).find(e => e.type === 'hook/result')
+      expect(res?.type === 'hook/result' && res.data.exitCode).toBe(127)
+    })
+
+    it('a PostToolUse deny with empty stderr + no context uses the default feedback (no context arm)', async () => {
+      const d = dir()
+      const s = sh(d, 'block.sh', '#!/usr/bin/env bash\nexit 2\n')
+      const path = hooks(d, { PostToolUse: [{ hooks: [{ type: 'command', command: s }] }] })
+      const adapter = new MockAdapter([toolCallResponse('c1', 'echo', {}), textResponse('done')])
+      const ctx = await harness(path, adapter)
+      ctx.tools.register(defineContentToolFixture({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
+      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
+      await waitForIdle(ctx, agent)
+      const result = events(agent).find(e => e.type === 'tool/result')
+      expect(result?.type === 'tool/result' && result.data.message.content[0].isError).toBe(true)
+    })
+  })
+
+  if (group === 'context') describe('hooks-claude-code coverage — continue:false, context arm, no-cwd', () => {
+    it('a {"continue":false} hook is RECORDED as decision "stop" but does not halt the run (TODO(hook-continue-false))', async () => {
+    // The extension points cannot yet honor `continue:false` as a hard halt. The log must still record the
+    // stop decision while execution and the turn continue normally.
+      const d = dir()
+      const s = sh(d, 'stop.sh', '#!/usr/bin/env bash\necho \'{"continue":false,"stopReason":"halt"}\'\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)
+      let ran = false
+      ctx.tools.register(defineContentToolFixture({ name: 'echo', description: 'e', parameters: {}, async execute() { ran = true; return [{ type: 'text', text: 'ok' }] } }))
+      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
+      await waitForIdle(ctx, agent)
+      const res = events(agent).find(e => e.type === 'hook/result')
+      expect(res?.type === 'hook/result' && res.data.decision).toBe('stop') // recorded
+      expect(ran).toBe(true) // NOT honored: the tool still ran (halt is deferred)
+      const turnEnd = events(agent).findLast(e => e.type === 'turn/end')
+      expect(turnEnd?.type === 'turn/end' && turnEnd.data.reason.kind).toBe('completed') // ran to completion
+    })
+
+    it('a PostToolUse hook that BOTH blocks AND attaches additionalContext', async () => {
+      const d = dir()
+      const s = sh(d, 'b.sh', '#!/usr/bin/env bash\necho \'{"decision":"block","reason":"bad","hookSpecificOutput":{"hookEventName":"PostToolUse","additionalContext":"context too"}}\'\n')
+      const path = hooks(d, { PostToolUse: [{ hooks: [{ type: 'command', command: s }] }] })
+      const adapter = new MockAdapter([toolCallResponse('c1', 'echo', {}), textResponse('done')])
+      const ctx = await harness(path, adapter)
+      ctx.tools.register(defineContentToolFixture({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
+      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
+      await waitForIdle(ctx, agent)
+      const result = events(agent).find(e => e.type === 'tool/result')
+      expect(result?.type === 'tool/result' && result.data.message.content[0].isError).toBe(true)
+      expect(result?.type === 'tool/result' && result.data.message.content[0].content.some(b => b.type === 'text' && b.text.includes('bad'))).toBe(true)
+      // additionalContext also injected (the block + context arm).
+      expect(events(agent).some(e => e.type === 'user/message' && e.data.source.kind !== 'user' && e.data.content.some(b => b.type === 'text' && b.text.includes('context too')))).toBe(true)
+    })
+
+    it('a PreToolUse hook whose hookSpecificOutput names a DIFFERENT event does NOT deny the tool', async () => {
+    // The block's hookEventName (UserPromptSubmit) mismatches the firing event
+    // (PreToolUse), so its permissionDecision:"deny" is discarded — the tool runs.
+      const d = dir()
+      const s = sh(d, 'x.sh', '#!/usr/bin/env bash\necho \'{"hookSpecificOutput":{"hookEventName":"UserPromptSubmit","permissionDecision":"deny"}}\'\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)
+      let ran = false
+      ctx.tools.register(defineContentToolFixture({ name: 'echo', description: 'e', parameters: {}, async execute() { ran = true; return [{ type: 'text', text: 'ok' }] } }))
+      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
+      await waitForIdle(ctx, agent)
+      expect(ran).toBe(true) // the mismatched deny was discarded → the tool ran
+    })
+
+    it('defaults CLAUDE_PROJECT_DIR to the session workspace when no projectDir is configured', async () => {
+    // The default ACP wiring sets no projectDir. A stock CC hook that references
+    // $CLAUDE_PROJECT_DIR (shell expansion) must still get the session workspace,
+    // not an empty string. The hook echoes the var as additionalContext.
+      const d = dir()
+      const workspace = dir()
+      const s = sh(d, 'ctx.sh', '#!/usr/bin/env bash\nprintf \'{"hookSpecificOutput":{"hookEventName":"UserPromptSubmit","additionalContext":"dir=%s"}}\' "$CLAUDE_PROJECT_DIR"\n')
+      const path = hooks(d, { UserPromptSubmit: [{ hooks: [{ type: 'command', command: s }] }] })
+      const adapter = new MockAdapter([textResponse('ran')])
+      const ctx = await harness(path, adapter) // NB: no projectDir
+      // The factory create() path honors meta.cwd (the plain agentLoop.create() does not).
+      const { SessionId } = await import('@deepseek-ai/dsh-session')
+      const handle = await ctx.agents.create({ sessionId: SessionId('s1'), meta: { cwd: workspace }, agentOptions: { provider: 'mock', model: 'mock' } })
+      handle.agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
+      await waitForIdle(ctx, handle.agent)
+      expect(events(handle.agent).some(e => e.type === 'user/message'
+      && e.data.content.some(b => b.type === 'text' && b.text.includes(`dir=${workspace}`)))).toBe(true)
+      await handle.dispose()
+    })
+
+    it('a context-only UserPromptSubmit hook DELEGATES so a later listener can still block', async () => {
+    // A context-only hook delegates with `next()` and folds its context, so a downstream policy
+    // listener can still veto the prompt.
+      const d = dir()
+      const s = sh(d, 'ctx.sh', '#!/usr/bin/env bash\necho \'{"hookSpecificOutput":{"hookEventName":"UserPromptSubmit","additionalContext":"bridge ctx"}}\'\n')
+      const path = hooks(d, { UserPromptSubmit: [{ hooks: [{ type: 'command', command: s }] }] })
+      const adapter = new MockAdapter([textResponse('should not run')])
+      const ctx = await harness(path, adapter)
+      // A later listener that blocks every prompt (registered AFTER the bridge).
+      ctx.on('agent/pre-step', async () => ({
+        kind: 'reject' as const,
+      }))
+      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
+      await waitForIdle(ctx, agent)
+      // the downstream block won: the model was never called, no user/message was
+      // recorded, and the (sole, fully-blocked) prompt closed the turn `rejected`
+      expect(adapter.requests).toHaveLength(0)
+      expect(events(agent).some(e => e.type === 'user/message' && e.data.source.kind !== 'user')).toBe(false)
+      expect(events(agent).filter(e => e.type === 'turn/start' || e.type === 'hook/invoked'
+        || e.type === 'hook/result' || e.type === 'turn/end').map(e => e.type))
+        .toEqual(['turn/start', 'hook/invoked', 'hook/result', 'turn/end'])
+    })
+
+    it('preserves separate bridge and downstream prompt contexts with framing and metadata', async () => {
+    // Both the bridge hook and a later pre-step listener attach context; the
+    // request must see both as separately sourced durable events.
+      const d = dir()
+      const s = sh(d, 'ctx.sh', '#!/usr/bin/env bash\necho \'{"hookSpecificOutput":{"hookEventName":"UserPromptSubmit","additionalContext":"from-bridge"}}\'\n')
+      const path = hooks(d, { UserPromptSubmit: [{ hooks: [{ type: 'command', command: s }] }] })
+      const adapter = new MockAdapter([textResponse('ok')])
+      const ctx = await harness(path, adapter)
+      ctx.on('agent/pre-step', async ({ messages }) => ({
+        kind: 'enter' as const,
+        messages: [{
+          ...messages[0]!,
+          content: [{ type: 'text' as const, text: 'rewritten-prompt' }],
+        }, createUserMessage({
+          content: [{ type: 'text' as const, text: 'from-downstream' }],
+          source: { kind: 'plugin' as const, plugin: 'policy' },
+        })],
+      }))
+      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
+      await waitForIdle(ctx, agent)
+      const req = JSON.stringify(adapter.requests[0]!.messages)
+      expect(req).toContain('from-bridge')
+      expect(req).toContain('from-downstream')
+      expect(req).toContain('rewritten-prompt') // downstream content rewrite preserved
+      // the original prompt was replaced by the downstream rewrite
+      const userMsg = events(agent).find(e => e.type === 'user/message')
+      expect(userMsg?.type === 'user/message' && userMsg.data.content.some(b => b.type === 'text' && b.text === 'rewritten-prompt')).toBe(true)
+      const contexts = events(agent).filter(event => event.type === 'user/message' && event.data.source.kind !== 'user')
+      expect(contexts.map(event => event.type === 'user/message' && event.data.source)).toEqual([
+        { kind: 'plugin', plugin: 'policy' },
+        { kind: 'plugin', plugin: 'hooks-claude-code' },
+      ])
+    })
+
+    it('folds the bridge PostToolUse context onto a downstream canonical value replacement', async () => {
+    // The bridge hook adds context; a later post-execute listener accepts with a
+    // canonical replacement. Both the replacement and the bridge context survive.
+      const d = dir()
+      const s = sh(d, 'ctx.sh', '#!/usr/bin/env bash\necho \'{"hookSpecificOutput":{"hookEventName":"PostToolUse","additionalContext":"bridge-note"}}\'\n')
+      const path = hooks(d, { PostToolUse: [{ hooks: [{ type: 'command', command: s }] }] })
+      const adapter = new MockAdapter([toolCallResponse('c1', 'echo', {}), textResponse('done')])
+      const ctx = await harness(path, adapter)
+      ctx.tools.register(defineContentToolFixture({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
+      ctx.on('tools/post-execute', async () => ({ kind: 'accept' as const, value: [{ type: 'text' as const, text: 'rewritten-result' }] }))
+      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
+      await waitForIdle(ctx, agent)
+      const result = events(agent).find(e => e.type === 'tool/result')
+      expect(result?.type === 'tool/result' && result.data.message.content[0].content.some(b => b.type === 'text' && b.text === 'rewritten-result')).toBe(true)
+      expect(events(agent).some(e => e.type === 'user/message' && e.data.source.kind !== 'user' && e.data.content.some(b => b.type === 'text' && b.text.includes('bridge-note')))).toBe(true)
+    })
+
+    it('keeps bridge and downstream PostToolUse contexts as separate sourced events', async () => {
+      const d = dir()
+      const s = sh(d, 'ctx.sh', '#!/usr/bin/env bash\necho \'{"hookSpecificOutput":{"hookEventName":"PostToolUse","additionalContext":"bridge-note"}}\'\n')
+      const path = hooks(d, { PostToolUse: [{ hooks: [{ type: 'command', command: s }] }] })
+      const adapter = new MockAdapter([toolCallResponse('c1', 'echo', {}), textResponse('done')])
+      const ctx = await harness(path, adapter)
+      ctx.tools.register(defineContentToolFixture({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
+      ctx.on('tools/post-execute', async () => ({
+        kind: 'accept' as const,
+        additionalContexts: [createUserMessage({
+          content: [{ type: 'text' as const, text: 'downstream-note' }],
+          source: { kind: 'plugin' as const, plugin: 'policy' },
+        })],
+      }))
+      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
+      await waitForIdle(ctx, agent)
+
+      const contexts = events(agent).filter(event => event.type === 'user/message' && event.data.source.kind !== 'user')
+      expect(contexts.map(event => event.type === 'user/message' && event.data.source)).toEqual([
+        { kind: 'plugin', plugin: 'hooks-claude-code' },
+        { kind: 'plugin', plugin: 'policy' },
+      ])
+    })
+
+    it('folds the bridge PostToolUse context onto a downstream listener BLOCK', async () => {
+    // The bridge hook only adds context; a later post-execute listener blocks the
+    // result. The block wins AND carries the bridge context (concatContext on the
+    // block arm).
+      const d = dir()
+      const s = sh(d, 'ctx.sh', '#!/usr/bin/env bash\necho \'{"hookSpecificOutput":{"hookEventName":"PostToolUse","additionalContext":"bridge-note"}}\'\n')
+      const path = hooks(d, { PostToolUse: [{ hooks: [{ type: 'command', command: s }] }] })
+      const adapter = new MockAdapter([toolCallResponse('c1', 'echo', {}), textResponse('done')])
+      const ctx = await harness(path, adapter)
+      ctx.tools.register(defineContentToolFixture({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
+      ctx.on('tools/post-execute', async () => ({ kind: 'block' as const, feedback: [{ type: 'text' as const, text: 'downstream-block' }] }))
+      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
+      await waitForIdle(ctx, agent)
+      const result = events(agent).find(e => e.type === 'tool/result')
+      expect(result?.type === 'tool/result' && result.data.message.content[0].isError).toBe(true)
+      expect(result?.type === 'tool/result' && result.data.message.content[0].content.some(b => b.type === 'text' && b.text.includes('downstream-block'))).toBe(true)
+      // the bridge's context still landed (folded onto the block)
+      expect(events(agent).some(e => e.type === 'user/message' && e.data.source.kind !== 'user' && e.data.content.some(b => b.type === 'text' && b.text.includes('bridge-note')))).toBe(true)
+    })
+
+  })
+
+  if (group === 'edge-paths') describe('hooks-claude-code coverage — executor reject + no-open-turn', () => {
+    it('when the bash executor REJECTS a hook run, the hook/result omits exitCode (non-blocking)', async () => {
+      const d = dir()
+      const s = sh(d, 'h.sh', '#!/usr/bin/env bash\nexit 0\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)
+      // Force the executor to reject (an infrastructure fault) so runHook's catch
+      // yields a HookOutput with exitCode undefined → the `exitCode` spread false arm.
+      const bash = ctx.shell
+      bash.run = (() => Promise.reject(new Error('executor down')))
+      ctx.tools.register(defineContentToolFixture({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
+      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
+      await waitForIdle(ctx, agent)
+      const res = events(agent).find(e => e.type === 'hook/result')
+      expect(res?.type === 'hook/result' && 'exitCode' in res.data).toBe(false)
+    })
+
+  })
+
+  if (group === 'edge-paths') describe('hooks-claude-code coverage — detached-listener catch handlers', () => {
+    it('a throwing SessionStart inject is contained (logged, agent still runs)', async () => {
+      const d = dir()
+      const s = sh(d, 'start.sh', '#!/usr/bin/env bash\necho \'{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":"x"}}\'\n')
+      const path = hooks(d, { SessionStart: [{ hooks: [{ type: 'command', command: s }] }] })
+      const adapter = new MockAdapter([textResponse('ok')])
+      const ctx = await harness(path, adapter)
+      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      // Make inject throw, forcing the SessionStart .catch path.
+      const original = agent.inject.bind(agent)
+      let threw = false
+      agent.inject = (() => { threw = true; throw new Error('inject boom') })
+      await waitFor(() => threw)
+      expect(threw).toBe(true)
+      agent.inject = original
+      agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
+      await waitForIdle(ctx, agent)
+      expect(adapter.requests).toHaveLength(1) // loop survived the thrown inject
+    })
+  })
+
+  if (group === 'stop') describe('hooks-claude-code coverage — hook runs in the session cwd, not the server cwd', () => {
+    it('runs an agent-scoped hook in the session workspace even when the executor default differs', async () => {
+    // The server launch directory and session cwd deliberately differ. The marker proves the
+    // bridge passes `session/new.cwd` instead of falling back to the executor default.
+      const serverDir = dir()
+      const sessionDir = dir()
+      const marker = join(sessionDir, 'where')
+      // The hook is invoked with cwd = session dir, so a relative marker path lands there.
+      hooks(serverDir, { PreToolUse: [{ hooks: [{ type: 'command', command: 'pwd > where' }] }] })
+      const adapter = new MockAdapter([toolCallResponse('c1', 'echo', {}), textResponse('done')])
+      const ctx = new Context()
+      await mountAgentLoopTestDependencies(ctx)
+      await ctx.plugin(AgentLoop, { agents: [] })
+      // Executor default cwd = serverDir (deliberately NOT the session cwd).
+      await ctx.plugin(LocalSubprocessRuntime)
+      await ctx.plugin(LocalBashExecutor, { timeoutMs: 10_000, cwd: serverDir })
+      await ctx.plugin(HooksClaude, { configPath: join(serverDir, 'hooks.json') })
+      ctx.llm.registerAdapter(['mock'], adapter)
+      ctx.tools.register(defineContentToolFixture({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
+
+      const { SessionId } = await import('@deepseek-ai/dsh-session')
+      const handle = await ctx.agents.create({ sessionId: SessionId('s1'), meta: { cwd: sessionDir }, agentOptions: { provider: 'mock', model: 'mock' } })
+      handle.agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
+      await waitForIdle(ctx, handle.agent)
+
+      expect(existsSync(marker)).toBe(true) // the marker landed in the SESSION dir
+      const { readFileSync } = await import('node:fs')
+      const where = readFileSync(marker, 'utf8').trim()
+      // `pwd` may resolve symlinks (/var → /private/var etc.), so compare basenames.
+      expect(where.endsWith(sessionDir.split('/').pop()!)).toBe(true)
+      await handle.dispose()
+    })
+
+    it('runs a SubagentStop hook in the CHILD session workspace, not the server cwd', async () => {
+      const serverDir = dir()
+      const childDir = dir()
+      const marker = join(childDir, 'stopwhere')
+      const payload = join(childDir, 'stoppayload')
+      hooks(serverDir, { SubagentStop: [{ hooks: [{ type: 'command', command: 'cat > stoppayload.tmp; mv stoppayload.tmp stoppayload; pwd > stopwhere' }] }] })
+      const ctx = new Context()
+      await mountAgentLoopTestDependencies(ctx)
+      await ctx.plugin(AgentLoop, { agents: [] })
+      // Executor default cwd = serverDir (deliberately NOT the child session cwd).
+      await ctx.plugin(LocalSubprocessRuntime)
+      await ctx.plugin(LocalBashExecutor, { timeoutMs: 10_000, cwd: serverDir })
+      await ctx.plugin(HooksClaude, { configPath: join(serverDir, 'hooks.json') })
+      ctx.llm.registerAdapter(['mock'], new MockAdapter([]))
+
+      const { SessionId } = await import('@deepseek-ai/dsh-session')
+      const childHandle = await ctx.agents.create({ sessionId: SessionId('child-stop-session'), meta: { cwd: childDir }, agentOptions: { provider: 'mock', model: 'mock' } })
+      const runId = SubagentRunId('run-stop')
+      const identity = { runId, provider: 'inproc', id: childHandle.agent.id, local: true }
+      // Start is the registry-backed capture edge; end deliberately follows
+      // handle disposal, matching continuable Activation settlement.
+      ctx.emit(subagentCarrier(ctx), 'subagent/start', identity)
+      await childHandle.dispose()
+      expect(ctx.agents.get(childHandle.agent.id)).toBeUndefined()
+      ctx.emit(subagentCarrier(ctx), 'subagent/end', { ...identity, stopReason: 'completed' })
+
+      await waitFor(() => existsSync(marker))
+      expect(existsSync(marker)).toBe(true) // the marker landed in the CHILD dir
+      const where = readFileSync(marker, 'utf8').trim()
+      const input = JSON.parse(readFileSync(payload, 'utf8')) as { cwd: string; session_id: string }
+      // `pwd` may resolve symlinks (/var → /private/var etc.), so compare basenames.
+      expect(where.endsWith(childDir.split('/').pop()!)).toBe(true)
+      expect(input).toMatchObject({ cwd: childDir, session_id: childHandle.agent.id })
+    })
+  })
+
+  if (group === 'config') describe('hooks-claude-code coverage — systemMessage is warned, not surfaced', () => {
+    it('a hook emitting a systemMessage is logged as not-yet-surfaced', async () => {
+      const d = dir()
+      const s = sh(d, 'sm.sh', '#!/usr/bin/env bash\necho \'{"systemMessage":"heads up"}\'\n')
+      const path = hooks(d, { UserPromptSubmit: [{ hooks: [{ type: 'command', command: s }] }] })
+      const adapter = new MockAdapter([textResponse('ok')])
+      const ctx = await harness(path, adapter)
+      const warn = vi.fn(); ctx.logger.warn = warn as never
+      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
+      await waitForIdle(ctx, agent)
+      expect(warn).toHaveBeenCalledWith(expect.stringContaining('systemMessage'))
+      // Not surfaced: the systemMessage text never reaches the model request.
+      expect(JSON.stringify(adapter.requests[0]!.messages)).not.toContain('heads up')
+    })
+  })
+
+  if (group === 'edge-paths') describe('hooks-claude-code coverage — SessionStart timing is best-effort (no-wait)', () => {
+    it('does NOT crash or block when the prompt is sent immediately (context is best-effort, may miss the first request)', async () => {
+    // Session-start injection is detached, so an immediate prompt need not observe it. Assert only
+    // the guaranteed behavior—no crash and a completed turn—without pre-waiting away the race.
+      const d = dir()
+      const s = sh(d, 'start.sh', '#!/usr/bin/env bash\necho \'{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":"late ctx"}}\'\n')
+      const path = hooks(d, { SessionStart: [{ hooks: [{ type: 'command', command: s }] }] })
+      const adapter = new MockAdapter([textResponse('ok')])
+      const ctx = await harness(path, adapter)
+      const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+      // Send immediately — do NOT wait for the session-start inject.
+      agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
+      await waitForIdle(ctx, agent)
+      expect(adapter.requests).toHaveLength(1) // the turn ran regardless of hook timing
+    })
+  })
+}

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

@@ -0,0 +1,3 @@
+import { defineCoverageCases } from './coverage-cases.ts'
+
+defineCoverageCases('config')

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

@@ -0,0 +1,3 @@
+import { defineCoverageCases } from './coverage-cases.ts'
+
+defineCoverageCases('context')

packages/hooks/hooks-claude-code/tests/coverage-edge-paths.spec.ts

@@ -0,0 +1,3 @@
+import { defineCoverageCases } from './coverage-cases.ts'
+
+defineCoverageCases('edge-paths')

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

@@ -0,0 +1,3 @@
+import { defineCoverageCases } from './coverage-cases.ts'
+
+defineCoverageCases('stop')