fix(runtime): enforce hook lifecycle bounds

Author: xxhZs

packages/runtime-host/src/server/host-hook-composition.ts

@@ -10,7 +10,9 @@ import type {
 import type { RuntimeEvent } from '@maka/core/runtime-event';
 import type { SessionHeader } from '@maka/core/session';
 import {
+  createHookExecutionLimiter,
   createPreToolUseHookDispatcher,
+  type HookExecutionLimiter,
   type PreToolUseHookDispatcher,
 } from '@maka/runtime/hooks/engine';
 import {
@@ -35,12 +37,14 @@ export function createHostHookComposition(input: {
 }): HostHookComposition {
   const userConfig = createHookConfigStore(input.stateRoot);
   const trust = createHookTrustStore(input.stateRoot);
+  const executionLimiter = createHookExecutionLimiter();
   return {
     dispatcherFor(header) {
       return createSessionHookDispatcher({
         header,
         userConfig,
         trust,
+        executionLimiter,
         runtimeEvents: input.runtimeEvents,
       });
     },
@@ -51,10 +55,12 @@ function createSessionHookDispatcher(input: {
   header: SessionHeader;
   userConfig: HookConfigStore;
   trust: HookTrustStore;
+  executionLimiter: HookExecutionLimiter;
   runtimeEvents: HookRuntimeEventWriter;
 }): PreToolUseHookDispatcher {
   return createPreToolUseHookDispatcher({
     loadSnapshot: () => loadSnapshot(input),
+    executionLimiter: input.executionLimiter,
     recordAudit: (hookInput, audit, context) =>
       recordAudit(input.runtimeEvents, hookInput, audit, context.invocationId),
   });

packages/runtime/src/__tests__/hooks-engine.test.ts

@@ -1,8 +1,12 @@
 import assert from 'node:assert/strict';
 import { describe, it } from 'node:test';
 import type { PreToolUseHookInput, ResolvedHookDefinition } from '@maka/core/hooks';
-import { createHookCommandRunner, type HookCommandRunner } from '../hooks/command-runner.js';
-import { createPreToolUseHookDispatcher } from '../hooks/engine.js';
+import {
+  createHookCommandRunner,
+  HOOK_EXECUTION_MARKER,
+  type HookCommandRunner,
+} from '../hooks/command-runner.js';
+import { createHookExecutionLimiter, createPreToolUseHookDispatcher } from '../hooks/engine.js';
 
 describe('PreToolUse Hook engine', () => {
   it('freezes one snapshot per turn and skips untrusted matching definitions', async () => {
@@ -37,6 +41,37 @@ describe('PreToolUse Hook engine', () => {
     assert.equal(first.audits[0]?.status, 'skipped_untrusted');
   });
 
+  it('retains every active Turn snapshot until that Turn is released', async () => {
+    let revision = 1;
+    let loads = 0;
+    const dispatcher = createPreToolUseHookDispatcher({
+      loadSnapshot: async () => {
+        loads += 1;
+        return [definition({ id: `revision-${revision}`, trusted: false })];
+      },
+    });
+    for (let index = 1; index <= 9; index += 1) dispatcher.prepareTurn(`turn-${index}`);
+    await Promise.resolve();
+    revision = 2;
+
+    const retained = await dispatcher.runPreToolUse(
+      hookInput('turn-1'),
+      new AbortController().signal,
+      { invocationId: 'invocation-1' },
+    );
+    assert.equal(retained.audits[0]?.handlerId, 'revision-1');
+    assert.equal(loads, 9);
+
+    dispatcher.releaseTurn('turn-1');
+    const reloaded = await dispatcher.runPreToolUse(
+      hookInput('turn-1'),
+      new AbortController().signal,
+      { invocationId: 'invocation-1-reloaded' },
+    );
+    assert.equal(reloaded.audits[0]?.handlerId, 'revision-2');
+    assert.equal(loads, 10);
+  });
+
   it('runs matching handlers concurrently and reports denials in configuration order', async () => {
     let active = 0;
     let maxActive = 0;
@@ -73,6 +108,49 @@ describe('PreToolUse Hook engine', () => {
     );
   });
 
+  it('shares one concurrency ceiling across simultaneous dispatchers and sessions', async () => {
+    let active = 0;
+    let maxActive = 0;
+    let release!: () => void;
+    const gate = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+    const runner: HookCommandRunner = {
+      run: async () => {
+        active += 1;
+        maxActive = Math.max(maxActive, active);
+        await gate;
+        active -= 1;
+        return result(0);
+      },
+    };
+    const limiter = createHookExecutionLimiter(2);
+    const createDispatcher = () =>
+      createPreToolUseHookDispatcher({
+        loadSnapshot: async () => [
+          definition({ id: 'first', definitionOrder: 0 }),
+          definition({ id: 'second', definitionOrder: 1 }),
+        ],
+        commandRunner: runner,
+        executionLimiter: limiter,
+      });
+    const first = createDispatcher().runPreToolUse(
+      hookInput('turn-1'),
+      new AbortController().signal,
+      { invocationId: 'invocation-1' },
+    );
+    const second = createDispatcher().runPreToolUse(
+      { ...hookInput('turn-2'), session_id: 'session-2' },
+      new AbortController().signal,
+      { invocationId: 'invocation-2' },
+    );
+    await new Promise<void>((resolve) => setImmediate(resolve));
+    assert.equal(maxActive, 2);
+    release();
+    await Promise.all([first, second]);
+    assert.equal(maxActive, 2);
+  });
+
   it('fails open on handler and audit failures but preserves an explicit denial', async () => {
     const dispatcher = createPreToolUseHookDispatcher({
       loadSnapshot: async () => [
@@ -133,6 +211,37 @@ describe('PreToolUse Hook engine', () => {
     assert.equal(output.reason, 'structured policy denial');
   });
 
+  it('marks Hook children and refuses execution in a Host recursively started by a Hook', async () => {
+    const runner = createHookCommandRunner();
+    const markerProbe = await runner.run(
+      definition({
+        command: process.execPath,
+        args: [
+          '-e',
+          `process.exit(process.env[${JSON.stringify(HOOK_EXECUTION_MARKER)}] === '1' ? 0 : 9)`,
+        ],
+      }),
+      hookInput('turn-1'),
+      new AbortController().signal,
+    );
+    assert.equal(markerProbe.exitCode, 0);
+
+    const previous = process.env[HOOK_EXECUTION_MARKER];
+    process.env[HOOK_EXECUTION_MARKER] = '1';
+    try {
+      const recursive = await runner.run(
+        definition({ command: process.execPath, args: ['-e', 'process.exit(99)'] }),
+        hookInput('turn-recursive'),
+        new AbortController().signal,
+      );
+      assert.equal(recursive.exitCode, null);
+      assert.equal(recursive.spawnError, 'Recursive Hook execution is not allowed');
+    } finally {
+      if (previous === undefined) delete process.env[HOOK_EXECUTION_MARKER];
+      else process.env[HOOK_EXECUTION_MARKER] = previous;
+    }
+  });
+
   it('terminates timed-out Hook process trees and fails open', async () => {
     const dispatcher = createPreToolUseHookDispatcher({
       loadSnapshot: async () => [

packages/runtime/src/__tests__/tool-runtime-sqlite-boundary.test.ts

@@ -37,6 +37,7 @@ describe('ToolRuntime with real SQLite boundary', () => {
         runtimeCommitSink: store,
         preToolUseHooks: {
           prepareTurn: () => {},
+          releaseTurn: () => {},
           runPreToolUse: async () => ({
             denied: true,
             reason: 'Policy denied this command',

packages/runtime/src/hooks/command-runner.ts

@@ -8,6 +8,7 @@ import {
 import { DEFAULT_PROCESS_TERMINATION_GRACE_MS } from '../process-tree-terminator.js';
 
 const HOOK_OUTPUT_LIMIT = 64 * 1024;
+export const HOOK_EXECUTION_MARKER = 'MAKA_HOOK_EXECUTION' as const;
 
 export interface HookCommandResult {
   exitCode: number | null;
@@ -36,6 +37,9 @@ async function runHookCommand(
   abortSignal: AbortSignal,
 ): Promise<HookCommandResult> {
   if (abortSignal.aborted) return emptyResult({ aborted: true });
+  if (process.env[HOOK_EXECUTION_MARKER] !== undefined) {
+    return emptyResult({ spawnError: 'Recursive Hook execution is not allowed' });
+  }
   let child: ReturnType<typeof spawn>;
   try {
     child = spawn(definition.command, definition.args, {
@@ -142,6 +146,7 @@ function minimalHookEnvironment(): NodeJS.ProcessEnv {
   for (const key of keep) {
     if (process.env[key] !== undefined) env[key] = process.env[key];
   }
+  env[HOOK_EXECUTION_MARKER] = '1';
   return env;
 }
 

packages/runtime/src/hooks/engine.ts

@@ -23,6 +23,7 @@ export interface HookDispatchResult {
 
 export interface PreToolUseHookDispatcher {
   prepareTurn(turnId: string): void;
+  releaseTurn(turnId: string): void;
   runPreToolUse(
     input: PreToolUseHookInput,
     abortSignal: AbortSignal,
@@ -44,6 +45,41 @@ export interface PreToolUseHookDispatcherInput {
   commandRunner?: HookCommandRunner;
   now?: () => number;
   concurrency?: number;
+  executionLimiter?: HookExecutionLimiter;
+}
+
+export interface HookExecutionLimiter {
+  run<T>(operation: () => Promise<T>): Promise<T>;
+}
+
+export function createHookExecutionLimiter(
+  concurrency = DEFAULT_CONCURRENCY,
+): HookExecutionLimiter {
+  if (!Number.isInteger(concurrency) || concurrency < 1) {
+    throw new Error('Hook concurrency must be a positive integer');
+  }
+  let active = 0;
+  const queued: Array<() => void> = [];
+  const drain = () => {
+    while (active < concurrency && queued.length > 0) queued.shift()?.();
+  };
+  return {
+    run<T>(operation: () => Promise<T>): Promise<T> {
+      return new Promise<T>((resolve, reject) => {
+        queued.push(() => {
+          active += 1;
+          void Promise.resolve()
+            .then(operation)
+            .then(resolve, reject)
+            .finally(() => {
+              active -= 1;
+              drain();
+            });
+        });
+        drain();
+      });
+    },
+  };
 }
 
 export function createPreToolUseHookDispatcher(
@@ -52,14 +88,14 @@ export function createPreToolUseHookDispatcher(
   const commandRunner = input.commandRunner ?? createHookCommandRunner();
   const now = input.now ?? Date.now;
   const concurrency = input.concurrency ?? DEFAULT_CONCURRENCY;
+  const executionLimiter = input.executionLimiter ?? createHookExecutionLimiter(concurrency);
   const snapshots = new Map<string, Promise<readonly ResolvedHookDefinition[]>>();
 
   const snapshotForTurn = (turnId: string): Promise<readonly ResolvedHookDefinition[]> => {
     let snapshot = snapshots.get(turnId);
     if (!snapshot) {
       snapshot = input.loadSnapshot(turnId);
       snapshots.set(turnId, snapshot);
-      while (snapshots.size > 8) snapshots.delete(snapshots.keys().next().value!);
     }
     return snapshot;
   };
@@ -68,6 +104,9 @@ export function createPreToolUseHookDispatcher(
     prepareTurn(turnId) {
       void snapshotForTurn(turnId).catch(() => {});
     },
+    releaseTurn(turnId) {
+      snapshots.delete(turnId);
+    },
     async runPreToolUse(hookInput, abortSignal, context) {
       const definitions = await snapshotForTurn(hookInput.turn_id);
       const matching = definitions.filter((definition) =>
@@ -78,7 +117,9 @@ export function createPreToolUseHookDispatcher(
           return auditFor(definition, hookInput, 'skipped_untrusted', 0, 'Review required');
         }
         const startedAt = now();
-        const result = await commandRunner.run(definition, hookInput, abortSignal);
+        const result = await executionLimiter.run(() =>
+          commandRunner.run(definition, hookInput, abortSignal),
+        );
         return auditFromCommandResult(
           definition,
           hookInput,

packages/runtime/src/tool-runtime.ts

@@ -593,6 +593,7 @@ export class ToolRuntime {
     // Bounded, not open-ended: every rejection above has already been
     // dispatched, and running impls observe the turn abort signal.
     await Promise.allSettled([...this.activeToolSettlements]);
+    this.input.preToolUseHooks?.releaseTurn(turnId);
     if (boundarySettlementErrors.length > 0) {
       throw new AggregateError(
         boundarySettlementErrors,