ChatGPTClaudeGrok / X / CursorGemini

DSH plugin ToolRestriction: admission by step and scope

Plugin DevelopmentPublished 2026-11-12Author: DeepSeek Plugin Market
DSH pluginDeepSeek HarnessToolRestrictionTool admissionTool registry
DSH plugin tools: which fields reach the model, restriction filtering inherited tools only, when conditions, and ResolvedToolSet lifecycles.

"The tool registered but never appears" and "the tool appears but cannot be blocked" are two different mechanisms in DSH plugin. The first is usually ToolRestriction or when filtering; the second usually means you changed the wrong layer, because dispatch is decided by the step's admitted set, not by presence in the registry.

Which ToolDefinition fields reach the model

Only three fields are projected to the model; everything else stays host-side.(source)

ToolDefinition combines a model-facing ToolSchema, a required canonical output declaration, an execute function, scheduler metadata used only by the host, an optional final-content callback, and an optional UI presentation function. The registry holds these definitions, and the loop dispatches through them.

schemas() builds ToolSchema[] through an explicit allowlist. The fields the reference names as non-leakable are output, execute, projectContent, finalizeContent, timeoutMs, isConcurrencySafe, presentCall, and presentResult.

That allowlist explains why a field like timeoutMs must not appear in a tool description even though it looks like a parameter. Declaring it is an assertion: this tool forwards exec.signal to a cooperative implementation that reaches quiescence when the signal aborts. The constraint is enforced by @deepseek-ai/dsh-tool-call-timeout-policy, a wrapper around tools/execute rather than a protocol field.

isConcurrencySafe works the same way: a purely synchronous classifier where only true joins a parallel group; omitted, throwing, or any non-true value is treated as exclusive. Executions selected for concurrency must not mutate parent-owned state.

The two content callbacks fire at different moments, so do not swap them. projectContent installs content after execution preparation, before tools/post-execute policies; the callback is captured when the call starts and runs once on the normalized result entering post-execute, while policy replacement remains authoritative. finalizeContent is the synchronous last transform of model-facing content, invoked exactly once per normalized result by the executor, including pipeline failures that bypass post-execute, and it must be total and never throw.

Presentation callbacks are pure functions: presentCall and presentResult may run during both live streaming and log replay, so they can depend only on arguments and persisted result projections, never on external mutable state.

Required output and the raw-schema refusal

output is a mandatory contract, and render is where the model-facing content comes from.(source)

ToolOutputDefinition has three parts: schema, render, and optional presentationMeta. schema is the raw supported JSON Schema that validates every successful canonical value; render is a pure projection producing native or model content from validated arguments and value; presentationMeta is a replayable display projection.

Plugins describe arguments and output with one DSL. ValueSchemaSpec supports string, number, integer, boolean, null, array, object, author-only json, and oneOf requiring exactly one branch. Two hard rules: explicit object nodes must declare additionalProperties: true | false, and { type: 'json' } compiles to an annotation-only raw schema that imposes no constraints.

InferValue<S> preserves literal constraints and object openness within 16 levels of containers, then falls back to JsonValue so TypeScript's instantiation stack never blows up; runtime validation still walks the full schema. Mismatched arguments throw ToolArgsError (INVALID_ARGS); invalid values from the function body or post-policies throw ToolOutputError (INVALID_TOOL_OUTPUT). Both follow the ordinary tool error path.

Registration itself is a trusted in-process contract: the registry borrows definitions as readonly input, requires output, validates the raw schema, and checks semantic requirements such as a positive finite timeoutMs. Unsupported keywords are rejected rather than admitted without enforcement.

ToolRestriction filters inherited content only

It governs tools inherited from above, never the ones you register yourself.(source)

ToolRestriction applies to tools a scope inherits: the deployment-global layer plus every ancestor scope on its chain. The registry compiles readonly names into private sets, intersects multiple restrictions, then adds the scope's own registrations — which stay unconstrained, so a delegated child agent keeps the tools its reporting depends on.

The two filtering semantics differ sharply:

  • deny only — later inherited tools not listed are allowed through;
  • allow list — inherited tools not listed are excluded.

Two boundaries remain: it does not affect the scope's own registrations, and it does not affect retained PTC mode transports. If "I set a restriction but the tool is still there," first check whether that tool belongs to this scope — if so, the restriction cannot reach it by definition.

Conditional admission: when decides this step

when is not a visibility switch; it is a per-step admission decision.(source)

A registration may carry a when condition. AgentLoop calls ctx.tools.resolve() once per proposed step with the captured model selection; the returned set decides three things: the step's tool declarations, the executor partitioning, and every call in the batch, including sub-calls of PTC programs.

At execution time ctx.tools.executable() applies that set; without one, conditional registrations are excluded. A same-name replacement or new restriction blocks calls that have not started from using the admitted registration, and the loop releases the set after the step batch ends.

resolve() runs once per step, not once per tool call. So putting an expensive check inside when slows step preparation; anything reusable should be prepared during plugin activation.

ToolActivationContext has exactly three members: agent, modelSelection, and signal. Three writing rules:

  1. Omitting when means enabled;
  2. Returning false excludes the tool from declaration and dispatch alike, not merely from view;
  3. Conditions must not modify registrations or start tool work, async conditions must observe signal, and a rejecting condition fails step preparation.

Rule 3 is the easiest to violate. Issuing a network request or writing a file inside when turns step preparation into a side-effect phase, and failures surface as preparation failures rather than tool failures.

ResolvedToolSet: an admission snapshot

The admitted set has a defined lifetime and must not be reused after expiry.(source)

ResolvedToolSet exposes two methods: dispose() closes admission once the step's tool batch settles, and view(scope) reads admitted registrations still visible in the original scope.

The scope argument is strict: pass the exact requesting agent, since another scope is never admitted; the return is the original definition but excludes removed or restricted registrations. In other words it gives the set genuinely usable at this instant, not the whole registry.

This mechanism makes same-name overrides and restriction changes explainable: resolve takes one snapshot, execution honors only that snapshot, and the batch end releases it. Replace a definition mid-batch and not-yet-started calls see the new restriction instead of the old admission.

Verification: one tool under different steps

Verify three layers: declared or not, dispatchable or not, and invalidated after a restriction change.(source)

  1. Register a tool with a when that returns false, assert schemas() omits it and a call is rejected.
  2. Make the condition return true, assert it appears in that step's declarations and the batch can call it.
  3. Register a same-name tool in the same scope and assert the scope's own registration is untouched by ToolRestriction.
  4. Add deny at the parent scope, assert the child's view(scope) no longer sees the tool; remove deny and assert recovery.
  5. Replace the same-name definition mid-batch and assert not-yet-started calls follow the new restriction.
  6. Make when throw and assert step preparation fails rather than producing an empty tool set and continuing.

If the tool still appears in step 1, check whether another scope registered the same name — when only governs the registration it belongs to.

For the full execution pipeline, see tool execution contract; to write a tool with schemas, see tool plugins.

One line to close: only three fields reach the request, output is a required contract, restrictions only touch inherited tools, when only governs its own step, and the admitted set is released per batch.

ChatGPTClaudeGrok / X / CursorGemini

FAQ

Does DSH plugin send timeoutMs to the model?

No. DSH plugin's schemas() allowlists only name, description, and parameters. DSH plugin states that output, execute, timeoutMs, isConcurrencySafe, and similar fields must never leak into a model request.

Can DSH plugin ToolRestriction limit its own scope's tools?

No. DSH plugin restrictions apply to inherited content only. The registry intersects restrictions over inherited tools, then adds the scope's own registrations, which stay unconstrained.

What happens when a DSH plugin when condition returns false?

DSH plugin excludes the tool from both declaration and dispatch. DSH plugin treats an omitted condition as enabled; false means the step can neither see nor call it, and a throwing condition fails step preparation.

Does a DSH plugin same-name swap affect started calls?

DSH plugin protects calls that have not started. DSH plugin's same-name replacement or new restriction blocks not-yet-started calls from the admitted registration, and the loop releases the set after the step batch ends.

Related Terms

ToolDefinition
ToolDefinition is a registered tool: a model-facing ToolSchema, a required output declaration, execute, and host-only scheduler metadata.— packages/core/tools/src/index.ts
ToolRestriction
ToolRestriction is one scope's live filter over inherited tools, holding optional allow and deny name lists.— packages/core/tools/src/index.ts
ToolActivationContext
ToolActivationContext is the input to a when condition: the preparing step's agent, the captured model selection, and a cancellation signal.— packages/core/tools/src/index.ts
ResolvedToolSet
ResolvedToolSet is the registration set admitted for one step, exposing view for reading and dispose for closing admission.— packages/core/tools/src/index.ts

Sources