Merge branch 'codex/simp-agent-entry-state' into codex/simp-unify-agent-session-id

# Conflicts:
#	docs/config-catalog.md
#	docs/cordis-catalog/services.md
#	packages/core/agent-loop/README.md
#	packages/core/agent-loop/src/agent.ts
#	packages/core/agent-loop/src/index.ts
#	packages/core/agent-loop/tests/agent.spec.ts
#	packages/core/agent-loop/tests/contract-regressions.spec.ts
#	website/zh-CN/api/harness/agent-loop.md

packages/core/tools/README.md

@@ -21,6 +21,7 @@ tools:
 - `ctx.tools.schemas(scope?: ScopeKey): ToolSchema[]` Schemas of everything the scope can see (without the `execute` functions). The shipped tools' schemas are catalogued in [docs/tool-catalog.md](../../../docs/tool-catalog.md), generated by booting each tool plugin and harvesting this method (see [the tool-schema-catalog RFC](../../../docs/rfc/implemented/process/2026-07-02-tool-schema-catalog.md)).
 - `ctx.tools.guard(guard: ToolGuard): () => void` Register a monotonic synchronous execution guard after `tools/pre-execute`: returning a reason denies the call, while `undefined` leaves it unchanged. A plain-context guard applies globally; an `agent.ctx` guard applies only to that agent. Later waterfall listeners cannot turn a guard denial back into permission. Disposed with the calling fiber.
 - `ctx.tools.execute(exec)` losslessly snapshots and freezes arguments, assigns an opaque token, runs the complete policy/dispatch/result pipeline, then independently snapshots the authoritative outcome before final observation. Invalid arguments use the same result path without reaching policy or the body; around wrappers may replace only `signal`.
+- `ctx.tools.executionMode(exec)` returns `parallel` only when the visible definition's `isConcurrencySafe(exec.arguments)` classifier returns exactly `true`; unknown, hidden, undeclared, invalid, or throwing classifications are exclusive.
 
 ### Injected services
 
@@ -32,7 +33,7 @@ The live registry pipeline has three transformable waterfalls followed by the ob
 
 ### Key types
 
-- `ToolDefinition` — `ToolSchema` + `execute(args, exec)`, optional presentation callbacks, and cooperative `timeoutMs`.
+- `ToolDefinition` — `ToolSchema` + `execute(args, exec)`, optional presentation callbacks, cooperative `timeoutMs`, and optional per-call `isConcurrencySafe(args)` classification.
 - `ToolExecutionInput` — the caller-supplied call description: `{ callId, name, arguments, agent?, parent?, signal? }`; callers may pass an enclosing execution's opaque token as `parent` but never choose the new execution's own token.
 - `ToolExecutionToken` — a fresh branded `Symbol` assigned by the registry. It supports equality correlation only and never crosses a model, log, or worker boundary.
 - `ToolExecution` — the pipeline-owned call: immutable `{ token, callId, name, arguments, agent?, parent? }` identity plus optional operational `signal`, which an around wrapper may add, replace, remove, and restore. A nested call's `parent` is a `ToolExecutionToken`, not an execution object.
@@ -87,6 +88,8 @@ See `defineTool`, `validateArgs`, `ToolArgsError`, `SchemaSpec`, `InferArgs`, an
 
 Optional `timeoutMs` must be positive and finite; it is policy metadata, not model-visible schema.
 
+Optional `isConcurrencySafe(args)` receives typed, softly validated arguments. Exact `true` permits concurrent dispatch/body execution; invalid input and all other outcomes remain exclusive. Opted-in bodies do not mutate parent-owned state, and shared-state races must commute or fail closed. The [parallel tool-call RFC](../../../docs/rfc/implemented/feature/2026-07-10-parallel-tool-call-execution.md) owns the full safety contract.
+
 ### Structured-output schema subset
 
 `StructuredOutputSchema` is the object-rooted raw JSON Schema subset used by subagents and workflows for machine-readable results. It accepts one scalar `type`, object `properties`/`required`/boolean `additionalProperties`, array `items`, and scalar `enum`/`const`. The annotations `description`, `title`, `default`, and `examples` are ignored but must remain JSON data. Type arrays, undeclared required keys, and unsupported keywords fail through `OutputSchemaError` rather than being ignored; `validateStructuredValue()` returns path-qualified violations without throwing.
@@ -108,6 +111,10 @@ Under `code` or `both`, the registry exposes the reserved `run_code` transport a
 - **The dispatch bridge** (`run_code`'s execute): every binding call is JSON-normalized before dispatch (a value that does not survive — `BigInt`, circulars — rejects that one call, so the dispatched form and logged form are the same JSON value by construction), serialized through a per-run queue (even `Promise.all` executes underlying calls one at a time in submission order), given the outer execution's opaque token as `parent`, and run through the complete pre-execute → guards → execute → post-execute → result pipeline. A denial reaches the program as a binding rejection, and each sub-call is logged as a `tool/code-dispatch` session event with deterministic id `<parent>:code:<n>`; `deriveMessages()` does not surface that event. Token correlation lets commit-style observers defer an inner success until the final `run_code` result without exposing the live outer execution; ordinary tool side effects are not rolled back. Every sub-call `additionalContexts` entry is deferred through the outer `ToolRunContext` in dispatch order; the loop appends those contexts only after the parent `run_code` result, preserving adjacency and retaining each source/envelope/meta even when the program later fails.
 - **Settlement discipline**: the bridge owns a run-scoped abort that follows the outer signal in and fires when the run settles for any reason, so a budget expiry aborts an in-flight sub-tool instead of orphaning it; the bridge then drains its queue BEFORE returning, so every `tool/code-dispatch` lands inside the open turn. A failed run throws `CodeRunFailedError` (`code: 'CODE_RUN_FAILED'`, message = the failure kind + captured logs), which the pipeline converts to a structured `isError` the model self-corrects from.
 
+### Parallel execution
+
+The agent loop groups consecutive `parallel` calls into a bounded rolling pool and treats each `exclusive` call as an ordering barrier. Only dispatch/body overlaps; policy, durable results, and context retain model order. Code Mode bindings remain serial. The [parallel tool-call RFC](../../../docs/rfc/implemented/feature/2026-07-10-parallel-tool-call-execution.md) owns the shipped declarations and rationale.
+
 ## Model Experience
 
 ### Normal tool schemas
@@ -145,7 +152,7 @@ The available tools:
 
 ## Known Limitations and Deferred Work
 
-- **Native tool calls execute sequentially** — `ToolDefinition` carries no concurrency-safety metadata; adding it (and parallel execution in the loop) waits on the deferred tool-shapes review (`TODO(review)`).
+- **Concurrency policy is not an event seam** — `executionMode()` reads the resolved tool definition directly; plugins can only declare a classifier on definitions they own.
 - **`tools/pre-execute` deliberately cannot rewrite `exec.arguments`** — logged and rendered args would desync from what ran; the rewrite design is [a proposed RFC](../../../docs/rfc/proposed/feature/2026-06-30-pre-tool-input-rewrite.md).
 - **`defineTool`'s schema DSL is a deliberate subset** — string/number/boolean/object/array with string-only `enum`; `validateArgs` tolerates extra keys and never applies `default` (`XXX(unused-default)` flags removing that field); raw-registered JSON-Schema tools validate their own input.
 - **`timeoutMs` on a definition is declarative only** — the registry never enforces deadlines; enforcement requires the `@deepseek-ai/dsh-timeout-policy` wrapper.

packages/core/tools/src/index.ts

@@ -117,9 +117,6 @@ declare module 'cordis' {
   }
 }
 
-// TODO(concurrency): revisit these shapes when concurrency metadata becomes useful
-// (for example, a read-only hint that would permit safe parallel execution).
-
 /** Tool output, optionally with lossless-JSON presentation metadata persisted for replay. */
 export type ToolExecuteReturn = ContentBlock[] | { content: ContentBlock[]; meta?: unknown }
 
@@ -134,6 +131,20 @@ export interface ToolDefinition extends ToolSchema {
    * cooperative implementation that can reach quiescence when the signal aborts.
    */
   timeoutMs?: number
+  /**
+   * Pure synchronous classifier for overlap with sibling tool calls. Only
+   * `true` opts in; omission, exceptions, non-`true` returns, and invalid
+   * `defineTool` arguments are exclusive. This metadata is never model-visible.
+   *
+   * Opted-in executions must not mutate parent-owned state. Shared state must
+   * tolerate concurrent dispatch; recorder races are permitted only when they
+   * commute or fail closed. See the
+   * [parallel-tool-call RFC](../../../../docs/rfc/implemented/feature/2026-07-10-parallel-tool-call-execution.md)
+   * for the full contract.
+   * @param args - parsed arguments; `defineTool` validates before calling.
+   * @returns Whether this call may join a parallel group.
+   */
+  isConcurrencySafe?(args: unknown): boolean
   /**
    * Optional: how to present the PENDING state of one call in a UI, derived from
    * the call's `args` (parsed arguments, `unknown` — the tool validates/narrows
@@ -195,6 +206,14 @@ export interface ToolExecutionInput {
   signal?: AbortSignal
 }
 
+/**
+ * Scheduling mode for one pending call. `parallel` may overlap with siblings;
+ * `exclusive` runs alone and forms an ordering barrier.
+ */
+export type ToolExecutionMode =
+  | { kind: 'parallel' }
+  | { kind: 'exclusive' }
+
 /**
  * One pending tool call inside the registry pipeline. Parsed arguments cross
  * one lossless-JSON materialization boundary before policy and are deep-frozen;
@@ -222,6 +241,47 @@ export interface ToolRunContext extends ToolExecution {
   deferContext(context: HookContext): void
 }
 
+/**
+ * Scheduler-only result after ordered pre-execute and guards. A `post-result`
+ * still receives post-execute; a `final-result` bypasses it.
+ * @internal
+ */
+export type ScheduledToolPreparation =
+  | { kind: 'dispatch'; exec: ToolRunContext }
+  | { kind: 'post-result'; exec: ToolRunContext; result: ToolExecutionResult }
+  | { kind: 'final-result'; exec: ToolRunContext; result: ToolExecutionResult }
+
+/**
+ * Scheduler-only dispatch result. A `post-result` still receives post-execute;
+ * a `final-result` already matches {@link ToolRegistry.execute} failure semantics.
+ * @internal
+ */
+export type ScheduledToolDispatch =
+  | { kind: 'post-result'; result: ToolExecutionResult }
+  | { kind: 'final-result'; result: ToolExecutionResult }
+
+/**
+ * Symbol-keyed scheduler view that keeps pre/post policy ordered while
+ * overlapping dispatch. Ordinary callers use {@link ToolRegistry.execute};
+ * this is not a plugin seam.
+ * @internal
+ */
+export interface ToolRegistryScheduler {
+  /** Materialize input, run the ordered pre-execute/guard gate, and decide what stage follows. */
+  prepare(exec: ToolExecutionInput): Promise<ScheduledToolPreparation>
+  /** Run only the around-dispatch/body stage. */
+  dispatch(exec: ToolRunContext): Promise<ScheduledToolDispatch>
+  /** Run ordered post-execute finalization, then materialize and notify the final outcome. */
+  finalize(exec: ToolRunContext, result: ToolExecutionResult): Promise<ToolExecutionResult>
+  /** Materialize and notify a final outcome that must bypass post-execute. */
+  finish(exec: ToolRunContext, result: ToolExecutionResult): ToolExecutionResult
+}
+
+/**
+ * Scheduler entry point omitted from the generated named service API.
+ * @internal
+ */
+export const TOOL_REGISTRY_SCHEDULER: unique symbol = Symbol('@deepseek-ai/dsh-tools.scheduler')
 /** Structured error metadata for a failed tool call (alongside the model-facing text). */
 export interface ToolErrorInfo {
   name: string
@@ -382,6 +442,16 @@ export class ToolRegistry extends Service {
     mode: z.union(['native', 'code', 'both'] as const).default('native'),
   })
 
+  /** Internal staged view consumed by `dsh-agent-loop`'s parallel scheduler. */
+  readonly [TOOL_REGISTRY_SCHEDULER]: ToolRegistryScheduler = {
+    prepare: exec => this.prepareScheduledExecution(exec),
+    dispatch: exec => this.dispatchScheduledExecution(exec),
+    finalize: (exec, result) => this.finalizeScheduledExecution(exec, result),
+    finish: (exec, result) => this.finishScheduledExecution(exec, result),
+  }
+
+  /** Context deferred by a running tool body, keyed by its scheduler-owned execution. */
+  private deferredContexts = new WeakMap<ToolRunContext, HookContext[]>()
   private global = new Map<string, ToolDefinition>()
   private scoped = new Map<ScopeKey, Map<string, ToolDefinition>>()
   /** Compiled restriction filters, per scope (see {@link restrict}). */
@@ -682,6 +752,24 @@ export class ToolRegistry extends Service {
     }
   }
 
+  /**
+   * Classify a pending call through the caller's visible tool definition. Only
+   * an exact `true` is parallel; unknown, hidden, undeclared, invalid, or
+   * throwing classifiers are exclusive.
+   * @param exec - call name, parsed arguments, and optional agent scope.
+   * @returns the fail-closed scheduling mode.
+   */
+  executionMode(exec: ToolExecutionInput): ToolExecutionMode {
+    const tool = this.get(exec.name, exec.agent)
+    if (!tool?.isConcurrencySafe) return { kind: 'exclusive' }
+    try {
+      const concurrencySafe: unknown = tool.isConcurrencySafe(exec.arguments)
+      return concurrencySafe === true ? { kind: 'parallel' } : { kind: 'exclusive' }
+    } catch {
+      return { kind: 'exclusive' }
+    }
+  }
+
   /**
    * Execute through pre-policy, guards, around-dispatch, post-policy, and final
    * notification. Tool and listener failures resolve as materialized error
@@ -692,6 +780,28 @@ export class ToolRegistry extends Service {
    * @returns the materialized final result.
    */
   async execute(exec: ToolExecutionInput): Promise<ToolExecutionResult> {
+    return this.prepareExecution(exec, prepared => this.completeScheduledExecution(prepared))
+  }
+
+  private async completeScheduledExecution(prepared: ScheduledToolPreparation): Promise<ToolExecutionResult> {
+    switch (prepared.kind) {
+      case 'dispatch': {
+        const dispatched = await this.dispatchScheduledExecution(prepared.exec)
+        return dispatched.kind === 'post-result'
+          ? await this.finalizeScheduledExecution(prepared.exec, dispatched.result)
+          : this.finishScheduledExecution(prepared.exec, dispatched.result)
+      }
+      case 'post-result':
+        return await this.finalizeScheduledExecution(prepared.exec, prepared.result)
+      case 'final-result':
+        return this.finishScheduledExecution(prepared.exec, prepared.result)
+      /* v8 ignore next -- closed-union exhaustiveness guard */
+      default:
+        return assertNever(prepared, 'scheduled tool preparation')
+    }
+  }
+
+  private createExecution(exec: ToolExecutionInput): ScheduledToolPreparation | { kind: 'ready'; exec: ToolRunContext } {
     const deferredContexts: HookContext[] = []
     const token = createExecutionToken()
     const callId = exec.callId
@@ -710,105 +820,143 @@ export class ToolRegistry extends Service {
         deferredContexts.push(context)
       },
     }
-    let execution: ToolRunContext
     try {
       const detached = snapshotJsonValue(exec.arguments)
       if (detached === undefined) {
         throw new TypeError('tool execution arguments must be losslessly JSON-serializable')
       }
-      execution = {
-        ...base,
-        arguments: deepFreeze(detached),
-      }
+      const execution: ToolRunContext = { ...base, arguments: deepFreeze(detached) }
+      this.deferredContexts.set(execution, deferredContexts)
+      return { kind: 'ready', exec: execution }
     } catch (error: unknown) {
-      execution = { ...base, arguments: undefined }
-      const result = this.materializeFinalResult(toolErrorResult(error))
-      this.notifyResult(execution, result)
-      return result
+      const execution: ToolRunContext = { ...base, arguments: undefined }
+      return { kind: 'final-result', exec: execution, result: toolErrorResult(error) }
     }
-    let result: ToolExecutionResult
+  }
+
+  /**
+   * Run the ordered pre-execute and monotonic guard stages for the scheduler.
+   * @param input - the caller-supplied execution input.
+   * @returns the prepared execution plus the next scheduler stage.
+   * @internal
+   */
+  private async prepareScheduledExecution(input: ToolExecutionInput): Promise<ScheduledToolPreparation> {
+    return this.prepareExecution(input, prepared => prepared)
+  }
+
+  private async prepareExecution<T>(
+    input: ToolExecutionInput,
+    next: (prepared: ScheduledToolPreparation) => T | PromiseLike<T>,
+  ): Promise<T> {
+    const created = this.createExecution(input)
+    if (created.kind !== 'ready') return next(created)
+    const exec = created.exec
     try {
-      result = this.materializeFinalResult(await this.executePipeline(execution, deferredContexts))
+      const carrier = scopeTarget(this, exec.agent)
+      const gate = await this.ctx.waterfall(
+        carrier, 'tools/pre-execute', exec,
+        () => Promise.resolve<PreToolDecision>({ kind: 'allow' }),
+      )
+      const decision = gate.kind === 'ask' ? await this.serviceAsk(exec, gate) : gate
+      const denialReason = decision.kind === 'allow'
+        ? this.guardReason(exec)
+        : decision.reason
+      if (denialReason !== undefined) {
+        return await next({
+          kind: 'post-result',
+          exec,
+          result: {
+            content: [{ type: 'text', text: `Error: ${denialReason}` }],
+            isError: true,
+          },
+        })
+      }
+      return await next({ kind: 'dispatch', exec })
     } catch (error: unknown) {
-      // Outer backstop: a throwing pre/post-execute listener, guard, or the
-      // waterfall machinery becomes an isError result, never a turn failure.
-      result = this.materializeFinalResult(toolErrorResult(error))
+      return next({ kind: 'final-result', exec, result: toolErrorResult(error) })
     }
-    this.notifyResult(execution, result)
-    return result
   }
 
-  /** Run the transformable pipeline; {@link execute} owns final normalization and notification. */
-  private async executePipeline(exec: ToolRunContext, deferredContexts: HookContext[]): Promise<ToolExecutionResult> {
-    // --- Gate: tools/pre-execute. An `ask` resolves through the optional
-    // approval seam (or degrades to deny) before the monotonic guards run. The
-    // carrier keys dispatch by exec.agent, so an `agent.ctx` listener gates only
-    // its own agent's calls (agent-less calls are subject-less).
-    const carrier = scopeTarget(this, exec.agent)
-    const gate = await this.ctx.waterfall(
-      carrier, 'tools/pre-execute', exec,
-      () => Promise.resolve<PreToolDecision>({ kind: 'allow' }),
-    )
-    const decision = gate.kind === 'ask' ? await this.serviceAsk(exec, gate) : gate
-    const denialReason = decision.kind === 'allow'
-      ? this.guardReason(exec)
-      : decision.reason
-    if (denialReason !== undefined) {
-      // Every non-grant, including a failed/unavailable approval request, takes
-      // the same deny path and still reaches post-policy plus result observers.
-      const denied: ToolExecutionResult = {
-        content: [{ type: 'text', text: `Error: ${denialReason}` }],
-        isError: true,
-      }
-      return await this.postExecute(exec, denied)
-    }
-
-    // --- Around-dispatch: tools/execute. The base `next` is the dispatch-
-    // with-normalization thunk — the tool body's own try/catch turns a throw
-    // into an isError result so a wrapper (and post-execute) can inspect it;
-    // an unknown tool routes through the same catch. A `tools/execute` listener
-    // (e.g. a timeout plugin) wraps this thunk: it may replace `exec.signal`
-    // before delegating and inspect the normalized result after. Dispatched with the
-    // same carrier as the gate, so an `agent.ctx` wrapper wraps only its own
-    // agent's calls. ---
-    const result = await this.ctx.waterfall(
-      carrier, 'tools/execute', exec,
-      async (): Promise<ToolExecutionResult> => {
-        try {
-          // Resolve through the CALLER's visible view ({@link get}): a scoped
-          // tool shadows its global name-twin for that agent, and a
-          // restricted-away global tool is exactly as absent as a nonexistent
-          // one — same UNKNOWN_TOOL result, no capability leak in the error.
-          const tool = this.get(exec.name, exec.agent)
-          if (!tool) throw new ToolNotFoundError(exec.name)
-          // Normalize the two `execute` return shapes: a bare ContentBlock[] (no
-          // meta) or a { content, meta } object (a tool attaching a private
-          // presentation payload). An array IS the content; the object carries it.
-          const returned = await tool.execute(exec.arguments, exec)
-          const content = Array.isArray(returned) ? returned : returned.content
-          const meta = Array.isArray(returned) ? undefined : returned.meta
-          return { content, isError: false, ...meta !== undefined ? { meta } : {} }
-        } catch (error: unknown) {
-          return toolErrorResult(error)
+  /**
+   * Run around-dispatch and the tool body. Tool and unknown-tool failures still
+   * receive post-execute; pipeline failures are already final.
+   * @param exec - the prepared execution.
+   * @returns whether the result still needs post-execute.
+   * @internal
+   */
+  private async dispatchScheduledExecution(exec: ToolRunContext): Promise<ScheduledToolDispatch> {
+    try {
+      const carrier = scopeTarget(this, exec.agent)
+      const result = await this.ctx.waterfall(
+        carrier, 'tools/execute', exec,
+        async (): Promise<ToolExecutionResult> => {
+          try {
+            const tool = this.get(exec.name, exec.agent)
+            if (!tool) throw new ToolNotFoundError(exec.name)
+            const returned = await tool.execute(exec.arguments, exec)
+            const content = Array.isArray(returned) ? returned : returned.content
+            const meta = Array.isArray(returned) ? undefined : returned.meta
+            return { content, isError: false, ...meta !== undefined ? { meta } : {} }
+          } catch (error: unknown) {
+            return toolErrorResult(error)
+          }
+        },
+      )
+      const deferredContexts = this.deferredContexts.get(exec)
+      /* v8 ignore next -- dispatch only receives executions minted by this registry's prepare stage */
+      if (deferredContexts === undefined) throw new Error('tool registry scheduler invariant violated: unprepared execution')
+      const resultWithDeferredContexts: ToolExecutionResult = deferredContexts.length === 0
+        ? result
+        : {
+          ...result,
+          additionalContexts: [
+            ...deferredContexts,
+            ...result.additionalContexts ?? [],
+          ],
         }
-      },
-    )
-    const resultWithDeferredContexts: ToolExecutionResult = deferredContexts.length === 0
-      ? result
-      : {
-        ...result,
-        additionalContexts: [
-          ...deferredContexts,
-          ...result.additionalContexts ?? [],
-        ],
-      }
-    return await this.postExecute(exec, resultWithDeferredContexts)
+      return { kind: 'post-result', result: resultWithDeferredContexts }
+    } catch (error: unknown) {
+      return { kind: 'final-result', result: toolErrorResult(error) }
+    }
   }
 
-  /** Notify final-result observers without giving them a mutation/error channel into the outcome. */
+  /**
+   * Run ordered post-execute, then materialize and notify the final outcome.
+   * @param exec - the prepared execution.
+   * @param result - dispatch/pre result that still needs post-execute.
+   * @returns the materialized final result.
+   * @internal
+   */
+  private async finalizeScheduledExecution(exec: ToolRunContext, result: ToolExecutionResult): Promise<ToolExecutionResult> {
+    try {
+      return this.finishScheduledExecution(exec, await this.postExecute(exec, result))
+    } catch (error: unknown) {
+      return this.finishScheduledExecution(exec, toolErrorResult(error))
+    }
+  }
+
+  /**
+   * Materialize and notify a final result that must bypass post-execute.
+   * @param exec - the prepared execution.
+   * @param result - final result.
+   * @returns the materialized final result.
+   * @internal
+   */
+  private finishScheduledExecution(exec: ToolRunContext, result: ToolExecutionResult): ToolExecutionResult {
+    let finalResult: ToolExecutionResult
+    try {
+      finalResult = this.materializeFinalResult(result)
+    } catch (error: unknown) {
+      finalResult = this.materializeFinalResult(toolErrorResult(error))
+    }
+    this.notifyResult(exec, finalResult)
+    return finalResult
+  }
+
+  /** Notify observers without exposing a mutation or error channel into the outcome. */
   private notifyResult(exec: ToolExecution, result: ToolExecutionResult): void {
-    // The pipeline is over: freeze the remaining mutable signal slot so every
-    // observer sees the SAME WeakMap-keyable execution without a mutation race.
+    // Freeze the remaining mutable signal slot before observers receive the
+    // shared WeakMap-keyable execution object.
     Object.freeze(exec)
     const callbacks = this.ctx.events.dispatch('emit', [
       scopeTarget(this, exec.agent), 'tools/result', exec, result,

packages/core/tools/src/schema.ts

@@ -283,6 +283,14 @@ export interface DefineToolOptions<S extends SchemaSpec> {
    * is never sent to the model.
    */
   readonly timeoutMs?: number
+  /**
+   * Optional pure synchronous classifier for sibling overlap. It receives typed
+   * arguments after soft validation; invalid input returns `false` without
+   * invoking it. See {@link ToolDefinition.isConcurrencySafe}.
+   * @param args - typed validated arguments.
+   * @returns whether this call may join a parallel group.
+   */
+  isConcurrencySafe?(args: InferArgs<S>): boolean
   /**
    * Tool execution function. `args` is typed as {@link InferArgs<S>} — zero
    * casts needed. Returns either a bare {@link ContentBlock}`[]` (model-facing
@@ -315,7 +323,7 @@ export interface DefineToolOptions<S extends SchemaSpec> {
  * @param options - the tool's name, description, typed parameter schema,
  *   execute body, and optional presenters.
  * @returns a registry-ready definition with strict execution validation and
- *   soft presenter validation for replay compatibility.
+ *   soft presenter and classifier validation for replay compatibility.
  */
 export function defineTool<S extends SchemaSpec>(options: DefineToolOptions<S>): ToolDefinition {
   // Object-literal execute methods don't use `this`; the reference is safe.
@@ -325,6 +333,8 @@ export function defineTool<S extends SchemaSpec>(options: DefineToolOptions<S>):
   const userPresentCall = options.presentCall
   // eslint-disable-next-line @typescript-eslint/unbound-method
   const userPresentResult = options.presentResult
+  // eslint-disable-next-line @typescript-eslint/unbound-method
+  const userIsConcurrencySafe = options.isConcurrencySafe
   if (options.timeoutMs !== undefined && (!Number.isFinite(options.timeoutMs) || options.timeoutMs <= 0)) {
     throw new Error(`defineTool(${options.name}): timeoutMs must be a positive finite number`)
   }
@@ -359,5 +369,12 @@ export function defineTool<S extends SchemaSpec>(options: DefineToolOptions<S>):
       return userPresentResult(args as InferArgs<S>, result)
     }
   }
+  // Invalid arguments fail closed without invoking the typed classifier.
+  if (userIsConcurrencySafe) {
+    tool.isConcurrencySafe = (args: unknown): boolean => {
+      if (validateArgs(options.parameters, args).length > 0) return false
+      return userIsConcurrencySafe(args as InferArgs<S>)
+    }
+  }
   return tool
 }

packages/core/tools/tests/execution-mode.spec.ts

@@ -0,0 +1,136 @@
+/** Covers fail-closed per-call classification and model-schema isolation. */
+
+import { describe, expect, expectTypeOf, it } from 'vitest'
+import { Context } from 'cordis'
+import { CallId } from '@deepseek-ai/dsh-llm'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import ToolRegistry, {
+  defineTool,
+  type ToolDefinition,
+  type ToolExecutionInput,
+  type ToolExecutionMode,
+} from '@deepseek-ai/dsh-tools'
+
+async function setup() {
+  const ctx = new Context()
+  await ctx.plugin(SystemPrompt)
+  await ctx.plugin(ToolRegistry)
+  return ctx
+}
+
+function exec(name: string, args: unknown): ToolExecutionInput {
+  return { callId: CallId('c1'), name, arguments: args }
+}
+
+describe('ToolRegistry.executionMode', () => {
+  it('returns parallel only for an explicit true classifier', async () => {
+    const ctx = await setup()
+    ctx.tools.register(defineTool({
+      name: 'safe',
+      description: 'parallel-safe',
+      parameters: {},
+      isConcurrencySafe: () => true,
+      async execute() { return [] },
+    }))
+    expect(ctx.tools.executionMode(exec('safe', {}))).toEqual({ kind: 'parallel' })
+  })
+
+  it('defaults to exclusive for a tool with no isConcurrencySafe declaration', async () => {
+    const ctx = await setup()
+    ctx.tools.register(defineTool({
+      name: 'plain',
+      description: 'no declaration',
+      parameters: {},
+      async execute() { return [] },
+    }))
+    expect(ctx.tools.executionMode(exec('plain', {}))).toEqual({ kind: 'exclusive' })
+  })
+
+  it('returns exclusive for an unknown tool', async () => {
+    const ctx = await setup()
+    expect(ctx.tools.executionMode(exec('nonexistent', {}))).toEqual({ kind: 'exclusive' })
+  })
+
+  it('returns exclusive when the classifier returns false for these args', async () => {
+    const ctx = await setup()
+    ctx.tools.register(defineTool({
+      name: 'rw',
+      description: 'read or write',
+      parameters: { mode: { type: 'string', required: true } },
+      isConcurrencySafe: args => args.mode === 'read',
+      async execute() { return [] },
+    }))
+    expect(ctx.tools.executionMode(exec('rw', { mode: 'read' }))).toEqual({ kind: 'parallel' })
+    expect(ctx.tools.executionMode(exec('rw', { mode: 'write' }))).toEqual({ kind: 'exclusive' })
+  })
+
+  it('classifies invalid defineTool arguments as exclusive without throwing', async () => {
+    const ctx = await setup()
+    ctx.tools.register(defineTool({
+      name: 'needs-mode',
+      description: 'requires mode',
+      parameters: { mode: { type: 'string', required: true } },
+      isConcurrencySafe: () => true,
+      async execute() { return [] },
+    }))
+    expect(ctx.tools.executionMode(exec('needs-mode', {}))).toEqual({ kind: 'exclusive' })
+  })
+
+  it('treats a throwing raw classifier as exclusive', async () => {
+    const ctx = await setup()
+    const raw: ToolDefinition = {
+      name: 'thrower',
+      description: 'classifier throws',
+      parameters: { type: 'object', properties: {} },
+      isConcurrencySafe() { throw new Error('boom') },
+      async execute() { return [] },
+    }
+    ctx.tools.register(raw)
+    expect(ctx.tools.executionMode(exec('thrower', {}))).toEqual({ kind: 'exclusive' })
+  })
+
+  it('treats a truthy non-boolean raw result as exclusive', async () => {
+    const ctx = await setup()
+    const raw = {
+      name: 'truthy',
+      description: 'classifier returns a truthy string',
+      parameters: { type: 'object', properties: {} },
+      isConcurrencySafe() { return 'yes' },
+      async execute() { return [] },
+    } as unknown as ToolDefinition
+    ctx.tools.register(raw)
+    expect(ctx.tools.executionMode(exec('truthy', {}))).toEqual({ kind: 'exclusive' })
+  })
+
+  it('passes parsed arguments directly to a raw definition', async () => {
+    const ctx = await setup()
+    let seen: unknown
+    ctx.tools.register({
+      name: 'raw-safe',
+      description: 'raw',
+      parameters: { type: 'object', properties: {} },
+      isConcurrencySafe(args) { seen = args; return true },
+      async execute() { return [] },
+    })
+    expect(ctx.tools.executionMode(exec('raw-safe', { anything: 1 }))).toEqual({ kind: 'parallel' })
+    expect(seen).toEqual({ anything: 1 })
+  })
+
+  it('isConcurrencySafe never reaches the model-facing schemas() projection', async () => {
+    const ctx = await setup()
+    ctx.tools.register(defineTool({
+      name: 'safe',
+      description: 'parallel-safe',
+      parameters: { x: { type: 'string', required: true } },
+      isConcurrencySafe: () => true,
+      async execute() { return [] },
+    }))
+    const schema = ctx.tools.schemas()[0] as unknown as Record<string, unknown>
+    expect(Object.keys(schema).sort()).toEqual(['description', 'name', 'parameters'])
+    expect(schema.isConcurrencySafe).toBeUndefined()
+  })
+
+  it('ToolExecutionMode is the object-tagged union', () => {
+    expectTypeOf<ToolExecutionMode>().toEqualTypeOf<{ kind: 'parallel' } | { kind: 'exclusive' }>()
+  })
+})