deepseek-harness/website/zh-CN/api/harness/tools.md

ctx.tools

ToolRegistry — provided by @deepseek-ai/dsh-tools.

Tool registry and execution pipeline. Scoped registrations shadow globals; one visibility resolver feeds presentation, lookup, and dispatch.

Source

ctx.tools.register(definition)

register(definition: ToolDefinition): () => void

Register globally or in the calling agent scope. Scoped tools shadow globals; duplicates within one layer and the reserved run_code name fail.

• definition — the tool schema, execution, and optional presentation functions.

Returns the exact disposer that unregisters the tool.

Source

ctx.tools.restrict(filter)

restrict(filter: ToolRestriction): () => void

Restrict global tools for the calling agent scope. Empty filters, unknown names, scope-local names, and reserved transport names fail. Restrictions intersect; scoped registrations remain visible.

• filter — global-surface mask: allow (keep only) and/or deny (remove).

Returns the exact disposer that lifts this restriction.

Source

ctx.tools.guard(guard)

guard(guard: ToolGuard): () => void

Register a monotonic guard after the extensible tools/pre-execute waterfall. A plain-context guard applies globally; one registered through agent.ctx applies only to that agent. Any matching guard may deny by returning a reason, while no guard can force-allow a call another guard denied. The exact effect disposer is returned for ordered ownership and HMR cleanup.

• guard — synchronous check; a returned string denies the execution.

Returns the exact disposer that unregisters the guard.

Source

ctx.tools.get(name, scope?)

get(name: string, scope?: ScopeKey): ToolDefinition | undefined

Look up a tool as one scope sees it (scoped shadows global; a restricted-away global reads as absent). Presenters pass the calling agent so the rendered card matches the definition that actually executed.

• name — the tool name as registered.
• scope — the viewing scope (the agent); omitted = the global view.

Returns the definition the scope resolves, or undefined when none is visible.

Source

ctx.tools.schemas(scope?)

schemas(scope?: ScopeKey): ToolSchema[]

Project visible definitions onto the allowlisted model-facing schema fields, excluding execution and presentation callbacks.

• scope — the viewing scope (the agent); omitted = the global view.

Returns one deep-cloned schema per visible tool.

Source

ctx.tools.executionMode(exec)

executionMode(exec: ToolExecutionInput): ToolExecutionMode

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.

• exec — call name, parsed arguments, and optional agent scope.

Returns the fail-closed scheduling mode.

Source

ctx.tools.execute(exec)

async execute(exec: ToolExecutionInput): Promise<ToolExecutionResult>

Execute through pre-policy, guards, around-dispatch, post-policy, and final notification. Tool and listener failures resolve as materialized error results; an invisible tool reports UNKNOWN_TOOL. The returned outcome is the same lossless, frozen snapshot final observers receive.

• exec — the typed same-process call input. The registry assigns its correlation token before policy begins.

Returns the materialized final result.

Source