工具执行管线与审批

143    /**144     * Allow, deny, or ask before dispatch. `next()` delegates to allow; missing145     * approval support turns `ask` into denial. Async gates must observe146     * `exec.signal`; the registry rechecks cancellation after they settle but147     * never abandons their promise.148     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's calls.149     * @param exec - the pending call (name, parsed arguments, caller agent).150     * @mode waterfall151     */152    'tools/pre-execute'(this: Scoped<ToolRuntime>, exec: ToolExecution, next: () => Promise<PreToolDecision>): Promise<PreToolDecision>

163    'tools/execute'(this: Scoped<ToolRuntime>, exec: ToolDispatchExecution, next: () => Promise<ToolExecutionResult>): Promise<ToolExecutionResult>164    /**165     * Accept, replace, enrich, or block a normalized dispatch result. `next()`166     * accepts it unchanged; thrown tools still reach this waterfall as errors. Async167     * listeners must observe `exec.signal`; after they settle, caller168     * cancellation replaces only a successful accepted outcome with the code169     * selected by whether the tool body was invoked.170     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's calls.171     * @param exec - the call that just ran (name, parsed arguments, caller agent).172     * @param result - the dispatch outcome a listener may accept, replace, or block.173     * @mode waterfall174     */175    'tools/post-execute'(this: Scoped<ToolRuntime>, exec: ToolExecution, result: Readonly<ToolExecutionResult>, next: () => Promise<PostToolDecision>): Promise<PostToolDecision>

588export type PreToolDecision =589  | { kind: 'allow' }590  | { kind: 'deny'; reason: string }591  | { kind: 'ask'; reason?: string }

597export type PostToolDecision =598  | { kind: 'accept'; content?: ContentBlock[]; value?: never; additionalContexts?: UserMessage[] }599  | { kind: 'accept'; value: JsonValue; content?: never; additionalContexts?: UserMessage[] }600  | { kind: 'block'; feedback: ContentBlock[]; additionalContexts?: UserMessage[] }

426/**427 * Scheduler-only result after ordered pre-execute and guards. A `post-result`428 * still receives post-execute; a `final-result` bypasses it.429 * @internal430 */431export type ScheduledToolPreparation =432  | { kind: 'dispatch'; exec: ToolRunContext }433  | { kind: 'post-result'; exec: ToolRunContext; result: ToolExecutionResult }434  | { kind: 'final-result'; exec: ToolRunContext; result: ToolExecutionResult }

451export interface ToolRuntimeScheduler {452  /** Materialize input, run the ordered pre-execute/guard gate, and decide what stage follows. */453  prepare(exec: ToolExecutionInput): Promise<ScheduledToolPreparation>454  /** Run only the around-dispatch/body stage. */455  dispatch(exec: ToolRunContext): Promise<ScheduledToolDispatch>456  /** Run post-execute and definition-owned content finalization, then materialize and notify. */457  finalize(exec: ToolRunContext, result: ToolExecutionResult): Promise<ToolExecutionResult>458  /** Run definition-owned content finalization, then materialize and notify without post-execute. */459  finish(exec: ToolRunContext, result: ToolExecutionResult): ToolExecutionResult460}

1346  private async completeScheduledExecution(prepared: ScheduledToolPreparation): Promise<ToolExecutionResult> {1347    switch (prepared.kind) {1348      case 'dispatch': {1349        const dispatched = await this.dispatchScheduledExecution(prepared.exec)1350        return dispatched.kind === 'post-result'1351          ? await this.finalizeScheduledExecution(prepared.exec, dispatched.result)1352          : this.finishScheduledExecution(prepared.exec, dispatched.result)1353      }1354      case 'post-result':1355        return await this.finalizeScheduledExecution(prepared.exec, prepared.result)1356      case 'final-result':1357        return this.finishScheduledExecution(prepared.exec, prepared.result)1358      /* v8 ignore next -- closed-union exhaustiveness guard */1359      default:1360        return assertNever(prepared, 'scheduled tool preparation')1361    }1362  }

1463  private async prepareExecution<T>(1464    input: ToolExecutionInput,1465    next: (prepared: ScheduledToolPreparation) => T | PromiseLike<T>,1466  ): Promise<T> {1467    const created = this.createExecution(input)1468    if (created.kind !== 'ready') return next(created)1469    const exec = created.exec1470    if (this.callerCancelled(exec)) {1471      return next({ kind: 'final-result', exec, result: toolAbortedBeforeDispatchResult() })1472    }1473    try {1474      const carrier = scopeTarget(this, exec.agent)1475      const gate = await this.ctx.waterfall(1476        carrier, 'tools/pre-execute', exec,1477        () => Promise.resolve<PreToolDecision>({ kind: 'allow' }),1478      )1479      const askResolution: ToolAskResolution = gate.kind === 'ask'1480        ? await this.serviceAsk(exec, gate)1481        : { decision: gate, approvalCancelled: false }1482      const { decision } = askResolution1483      if (this.callerCancelled(exec) && askResolution.approvalCancelled) {1484        return await next({ kind: 'post-result', exec, result: toolAbortedBeforeDispatchResult() })1485      }1486      const denialReason = decision.kind === 'allow'1487        ? this.guardReason(exec)1488        : decision.reason1489      if (denialReason !== undefined) {1490        return await next({1491          kind: 'post-result',1492          exec,1493          result: this.materializeFinalResult({1494            content: [{ type: 'text', text: `Error: ${denialReason}` }],1495            isError: true,1496            error: { message: denialReason },1497          }),1498        })1499      }1500      if (this.callerCancelled(exec)) {1501        return await next({ kind: 'post-result', exec, result: toolAbortedBeforeDispatchResult() })1502      }1503      return await next({ kind: 'dispatch', exec })1504    } catch (error: unknown) {1505      return next({ kind: 'final-result', exec, result: toolErrorResult(error) })1506    }1507  }

1569  private async dispatchScheduledExecution(exec: ToolRunContext): Promise<ScheduledToolDispatch> {1570    try {1571      const mutableExec = exec as MutableToolRunContext1572      const carrier = scopeTarget(this, exec.agent)1573      const result = await this.ctx.waterfall(1574        carrier, 'tools/execute', mutableExec,1575        () => this.dispatchToolBody(mutableExec),1576      )1577      const normalized = this.normalizeDispatchResult(exec, result)1578      const deferredContexts = this.deferredContexts.get(exec)1579      /* v8 ignore next -- dispatch only receives executions minted by this registry's prepare stage */1580      if (deferredContexts === undefined) throw new Error('tool registry scheduler invariant violated: unprepared execution')1581      const resultWithDeferredContexts: ToolExecutionResult = deferredContexts.length === 01582        ? normalized1583        : this.markCanonical(exec, {⋯          ...normalized,·          additionalContexts: [⋯            ...deferredContexts,⋯            ...normalized.additionalContexts ?? [],1588          ],1589        })1590      return {1591        kind: 'post-result',1592        result: this.callerCancelled(exec) && !resultWithDeferredContexts.isError1593          ? this.cancellationResult(exec, resultWithDeferredContexts)1594          : resultWithDeferredContexts,1595      }1596    } catch (error: unknown) {1597      return { kind: 'final-result', result: toolErrorResult(error) }1598    }1599  }

1609  private async finalizeScheduledExecution(exec: ToolRunContext, result: ToolExecutionResult): Promise<ToolExecutionResult> {1610    try {1611      const postResult = await this.postExecute(exec, result)1612      return this.finishScheduledExecution(1613        exec,1614        this.callerCancelled(exec) && !postResult.isError1615          ? this.cancellationResult(exec, postResult)1616          : postResult,1617      )1618    } catch (error: unknown) {1619      return this.finishScheduledExecution(exec, toolErrorResult(error))1620    }1621  }

1631  private finishScheduledExecution(exec: ToolRunContext, result: ToolExecutionResult): ToolExecutionResult {1632    let materializedResult: ToolExecutionResult1633    try {1634      materializedResult = this.materializeFinalResult(result)1635    } catch (error: unknown) {1636      materializedResult = this.materializeFinalResult(toolErrorResult(error))1637    }1638    let finalResult: ToolExecutionResult1639    try {1640      finalResult = this.materializeFinalResult(this.applyFinalContent(exec, materializedResult))1641    } catch (error: unknown) {1642      finalResult = this.materializeFinalResult(toolErrorResult(error))1643    }1644    this.notifyResult(exec, finalResult)1645    return finalResult1646  }

1742  private async postExecute(exec: ToolExecution, result: ToolExecutionResult): Promise<ToolExecutionResult> {1743    const decision = await this.ctx.waterfall(1744      scopeTarget(this, exec.agent), 'tools/post-execute', exec, result,1745      () => Promise.resolve<PostToolDecision>({ kind: 'accept' }),1746    )1747    const decisionContexts = decision.additionalContexts ?? []1748    if (decision.kind === 'block') {1749      const message = failureMessageFromContent(decision.feedback)1750      return this.markCanonical(exec, {1751        content: decision.feedback,1752        isError: true,1753        error: { message },⋯        ...decisionContexts.length > 0 ? { additionalContexts: decisionContexts } : {},·      })·    }·    if (Object.hasOwn(decision, 'content') && Object.hasOwn(decision, 'value')) {·      throw new TypeError('tools/post-execute accept decision cannot replace both value and content')·    }·    const additionalContexts = [⋯      ...result.additionalContexts ?? [],⋯      ...decisionContexts,·    ]·    if (Object.hasOwn(decision, 'value')) {·      if (result.isError) {·        throw new TypeError('tools/post-execute cannot replace the value of a failed result')·      }·      const tool = this.resolveExecution(exec.name, exec.agent, exec.parent !== undefined)·      if (tool === undefined) throw new ToolNotFoundError(exec.name)·      const replaced = this.createSuccessResult(exec, tool, decision.value)·      return this.markCanonical(exec, {⋯        ...replaced,⋯        ...additionalContexts.length > 0 ? { additionalContexts } : {},·      })·    }·    return this.markCanonical(exec, {⋯      ...result,⋯      ...decision.content !== undefined ? { content: decision.content } : {},⋯      ...additionalContexts.length > 0 ? { additionalContexts } : {},1780    })1781  }

624/** Derive one failure message from policy feedback without changing its rendered blocks. */625function failureMessageFromContent(content: ContentBlock[]): string {626  const text = content627    .map(block => block.type === 'text' ? block.text : `[${block.type} content]`)628    .join('\n')629  return text.length > 0 ? text : 'tool result blocked by post-execute policy'630}

1689  private async serviceAsk(1690    exec: ToolExecution,1691    ask: Extract<PreToolDecision, { kind: 'ask' }>,1692  ): Promise<ToolAskResolution> {1693    const approval = this.ctx.get('approval')1694    if (approval === undefined) {1695      return {1696        decision: { kind: 'deny', reason: ask.reason ?? `tool "${exec.name}" requires approval (not yet supported)` },1697        approvalCancelled: false,1698      }1699    }1700    if (exec.agent === undefined) {1701      return {1702        decision: { kind: 'deny', reason: `tool "${exec.name}" requires approval, but the call has no agent to route it through` },1703        approvalCancelled: false,1704      }1705    }1706    const outcome = await approval.request({1707      agent: exec.agent,1708      toolName: exec.name,1709      callId: exec.callId,⋯      ...ask.reason !== undefined ? { reason: ask.reason } : {},1711      signal: exec.signal,1712    })1713    switch (outcome) {1714      case 'allowed-once': return { decision: { kind: 'allow' }, approvalCancelled: false }1715      case 'rejected': return {1716        decision: { kind: 'deny', reason: `the user rejected tool "${exec.name}"` },1717        approvalCancelled: false,1718      }1719      case 'cancelled': return {1720        decision: { kind: 'deny', reason: `approval for tool "${exec.name}" was cancelled` },1721        approvalCancelled: true,1722      }1723      case 'unavailable': return {1724        decision: { kind: 'deny', reason: `tool "${exec.name}" requires approval, but no approval channel is available` },1725        approvalCancelled: false,1726      }1727      default: return assertNever(outcome, 'ApprovalOutcome')1728    }1729  }

44    'approval/asked': {45      id: ApprovalRequestId46      toolName: string47      callId?: CallId48      reason?: string49    }50    /**51     * The outcome of a prior `approval/asked` (same `id`) — log-only audit.52     * Exactly one per ask, appended when the outcome is known: a decision, a53     * cancellation, or the fail-closed `'unavailable'`.54     */55    'approval/decided': {56      id: ApprovalRequestId57      outcome: ApprovalOutcome58    }

10/**11 * Pairs one `approval/asked` audit event with its `approval/decided`.12 * Service-issued (one fresh id per {@link ApprovalService.request} call).13 */14export type ApprovalRequestId = Branded<'ApprovalRequestId'>1516/**17 * Brand a string as an {@link ApprovalRequestId}.18 * @param id - the raw id string to brand.19 * @returns the same string carrying the brand.20 */21export function ApprovalRequestId(id: string): ApprovalRequestId {22  return id as ApprovalRequestId23}2425/**26 * Closed approval outcomes: a one-shot grant, explicit rejection, withdrawn27 * request, or unavailable answerer. Callers fail closed on `unavailable`.28 */29export type ApprovalOutcome = 'allowed-once' | 'rejected' | 'cancelled' | 'unavailable'

257  async request(req: ApprovalRequest): Promise<ApprovalOutcome> {258    const session = req.agent.session259    if (!hasOpenTurn(session.events)) {260      throw new Error(261        'approval.request() outside an open turn: the approval/asked + approval/decided audit pair '262        + 'must be turn-enclosed (a bare event between turns is crash-tail garbage on reload). '263        + 'Ask from inside the turn that needs the decision.',264      )265    }266    const id = ApprovalRequestId(randomUUID())267    session.append('approval/asked', {268      id,269      toolName: req.toolName,⋯      ...req.callId !== undefined ? { callId: req.callId } : {},⋯      ...req.reason !== undefined ? { reason: req.reason } : {},272    })273    const outcome = await this.decide(req, session)274    session.append('approval/decided', { id, outcome })275    return outcome276  }

304  private async decide(req: ApprovalRequest, session: Session): Promise<ApprovalOutcome> {305    const signal = req.signal306    if (signal?.aborted) return 'cancelled'307    // The 'never' policy is decided HERE, before any dispatch: a listener308    // registered with `prepend: true` after this service mounts would sit309    // ahead of any gate LISTENER, so a listener-shaped gate cannot keep the310    // documented promise that 'never' rejects deterministically regardless311    // of registration order — only the service's own request path can.312    if (this.effectivePolicy(session) === 'never') return 'rejected'313    // Enter the promise chain BEFORE dispatching: a listener that throws314    // SYNCHRONOUSLY (before its first await) must land in the same rejection315    // path as an async one — `Promise.resolve(call())` would let it escape316    // the containment into the caller.317    const answer: Promise<ApprovalOutcome> = Promise.resolve().then(318      () => this.ctx.waterfall(319        scopeTarget(this, req.agent), 'approval/request', req,320        () => Promise.resolve<ApprovalOutcome>('unavailable'),321      ),322    ).then(323      // Normalize a rogue (non-vocabulary) answerer return to the fail-closed324      // outcome instead of leaking it into callers' closed-union switches.325      outcome => OUTCOMES.includes(outcome) ? outcome : 'unavailable',326      // A throwing answerer must fail the QUESTION closed, not the caller's327      // tool call open — the seam contains its callbacks.328      () => 'unavailable',329    )330    if (signal === undefined) return answer331    return await new Promise<ApprovalOutcome>((resolve) => {332      const onAbort = () => {333        signal.removeEventListener('abort', onAbort)334        resolve('cancelled')335      }336      signal.addEventListener('abort', onAbort, { once: true })337      void answer.then((outcome) => {338        signal.removeEventListener('abort', onAbort)339        // After an abort won the race this resolve is a settled-promise no-op:340        // the late answer is discarded by construction.341        resolve(outcome)342      })343    })344  }

94export type ApprovalPolicy = 'ask' | 'never'9596/** Every {@link ApprovalPolicy}, for option advertisement and runtime validation of untrusted policy strings. */97export const APPROVAL_POLICIES: readonly ApprovalPolicy[] = ['ask', 'never']9899/** Model-facing statement for the deterministic `'never'` policy. */100const NEVER_SENTENCE = 'Approval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`).'101/** Model-facing statement for an interactive policy that may still fail closed. */102const ASK_SENTENCE = 'Approval policy: ask. Operations that require approval may ask through the configured answerers; without an available answerer, the request fails closed.'

703/**704 * A monotonic execution guard evaluated after every `tools/pre-execute`705 * listener and before the tool body. Returning a reason denies the call;706 * returning `undefined` leaves it unchanged. Because guards have no allow707 * result, listener ordering cannot turn a denial back into permission.708 * @param execution - the identity-protected call after extensible pre-execute policy completed.709 * @returns a final denial reason, or `undefined` to leave the call allowed.710 */711export type ToolGuard = (execution: Readonly<ToolExecution>) => string | undefined

172`ctx.tools.execute()` accepts a caller-owned `ToolExecutionInput` with a required readonly `signal`, materializes its parsed JSON arguments once into a pipeline-owned `ToolExecution`, and runs that call through `tools/pre-execute` (the reorderable allow/deny/ask waterfall) → registered monotonic guards → `tools/execute` (around-dispatch wrappers) → `tools/post-execute` (inspect/replace the result) → optional definition-owned `finalizeContent` → `tools/result` (the immutable authoritative outcome). Only the `tools/execute` view may replace the required signal. The outcome is a `ToolExecutionResult`.

6This graph shows where policy, hooks, sandboxing, filesystem guards, result rewriting, final-outcome observation, and UI rendering run without changing the loop. The `tools/pre-execute` waterfall runs first, monotonic guards run next, and the `tools/execute` and `tools/post-execute` waterfalls follow; the three waterfalls may transform a call. Definition-owned `finalizeContent` and `tools/result` run afterward.

14- **Enforce a decision in the operation that makes it.** Schema omission, prompt filtering, facades, wrappers, and listener order are not enforcement when direct or alternate callers can bypass them; test denial through the executor.

236  /**237   * Synchronous last-mile transform for model-facing content. The registry238   * snapshots this callback when execution starts and invokes it exactly once239   * for every normalized outcome, including pipeline failures that bypass240   * `tools/post-execute`, immediately before lossless materialization.241   * Returning `undefined` preserves the content; every other result field242   * remains registry-owned. The callback must be total and must not throw.243   * @param exec - immutable execution identity and arguments.244   * @param result - complete normalized outcome before materialization.245   * @returns replacement content, or `undefined` to preserve it.246   */247  finalizeContent?(exec: Readonly<ToolExecution>, result: Readonly<ToolExecutionResult>): ContentBlock[] | undefined

13## Decision1415One package, `dsh-user-approval` (`packages/interaction/user-approval`), owns the vocabulary and the `ctx.approval` service — the mechanism. The policy — who answers, and whether a session is asked at all — lives outside it: answerers are `approval/request` waterfall listeners registered by channel-owning plugins (the ACP bridge, host adapters, and test scripts), and a per-session policy tier can decide before a channel is involved. Consumers (`dsh-tools`' ask routing and the sandbox escalation gate) resolve a question to a closed outcome and derive their own tool results from it. This is deliberately one package, not the capability-seam three (see Alternatives).

96- **A single registered provider instead of waterfall listeners** — rejected: a `registerProvider()` API forces every composition question — allowlist pre-filters, external hook deciders, scripted test answers, a policy gate in front of a human — inside one provider implementation. The waterfall gets composition, fail-closed absence, and HMR disposal from machinery the runtime already has; the seam's JSDoc pins the single-decision-slot convention instead of inventing a provider registry.97- **An inline `tools/pre-execute` permission gate in the ACP bridge** — rejected: prompting for every bridge-owned call hardwires the asking policy into the transport, cannot serve a second asker (sandbox escalation happens after execution starts, with no pre-execute moment), and leaves hook-produced `ask` decisions without a shared mechanism.98- **The generic user-questions seam (`ctx.userQuestions`)** — rejected as the approval mechanism: the two share a skeleton (route by agent, block for a human, handle absence), but approval's contract is narrower in every dimension that matters: a closed outcome vocabulary instead of free text, a protocol-native prompt attached to a tool call instead of a generic form, mandatory fail-closed absence, and audit events. Approval therefore does not ride the shipped `packages/interaction/user-questions` / `ask_user_question` elicitation path — an elicitation form is not a permission prompt, and a free-text answer is not a closed outcome; sharing provider plumbing stays open if the two ever converge.

855  private collapseSection(): { name: string; order: number; text: (context: { scope?: ScopeKey }) => string } {856    return {857      name: 'tools:code-only',858      order: COLLAPSE_SECTION_ORDER,859      // The SAME predicate the executor denies by, so the prompt cannot state860      // a rule the registry does not enforce (see `collapses`).861      text: context => this.modeFor(context.scope) === 'code' ? CODE_ONLY_INSTRUCTION : '',862    }863  }

106- Improved Bash tool permission checking for zsh-specific syntax in shell conditionals

299- Bash input redirections (`< file`) are now permission-checked like their argument spellings on all platforms

435- Fixed a Bash permission bypass where a crafted command could hide parts of itself from permission checks

13{14  "hooks": {15    "PreToolUse": [16      {17        "matcher": "Bash",18        "hooks": [19          {20            "type": "command",21            "command": "python3 /path/to/claude-code/examples/hooks/bash_command_validator_example.py"22          }23        ]24      }25    ]26  }27}

72            elif hook_event in ['PreToolUse', 'PostToolUse']:73                return {74                    "hookSpecificOutput": {75                        "hookEventName": hook_event,76                        "permissionDecision": "deny"77                    },78                    "systemMessage": combined_message79                }

237  // --- PreToolUse → PreToolDecision. Matcher subject is the tool name. ---238  ctx.on('tools/pre-execute', async (exec, next): Promise<PreToolDecision> => {239    const turn = lastTurn(exec.agent)240    const merged = await runPoint('PreToolUse', exec.name, preToolPayload(ctx, exec), { ...exec.agent ? { agent: exec.agent } : {}, turn, signal: exec.signal })241    if (merged.decision === 'deny') return { kind: 'deny', reason: merged.reason ?? 'blocked by PreToolUse hook' }242    if (merged.decision === 'ask') return { kind: 'ask', ...merged.reason !== undefined ? { reason: merged.reason } : {} }243    return next()244  })

391  set(session: Session, name: string): void {392    this.apply(session, name, (policy) =>{  setApprovalPolicy(session, policy) })393  }394395  /** Apply one preset with the caller-selected live or initialization policy writer. */396  private apply(session: Session, name: string, setApproval: (policy: ApprovalPolicy) => void): void {397    const spec = this.resolve(name)398    if (this.current(session.events) !== name) {399      session.append('permission/preset', { preset: name })400    }401    const events = session.events402    if (spec.sandbox !== (effectiveSandboxMode(events) ?? this.ctx.shell.sandboxMode)) {403      setSandboxMode(session, spec.sandbox)404    }405    if (spec.approval !== (effectiveApprovalPolicy(events) ?? this.ctx.approval.config.policy ?? 'ask')) {406      setApproval(spec.approval)407    }408  }