DSH plugin hooks: a tools/pre-execute permission gate

A DeepSeek Harness (DSH) plugin hook is an ordinary Cordis plugin that runs at an interception point: it listens to tools/pre-execute, receives the pending tool call, returns { kind: 'deny', reason } to deny, or returns next() to allow. A permission gate is only one example; sandbox, permission, and plan-mode plugins reuse the same extension point. It needs no external protocol, which the docs call a native hook.

What a DSH plugin hook is: an ordinary Cordis plugin at an interception point

A hook plugin is not the same thing as a permission gate — it is an ordinary Cordis plugin that runs at an interception point, and DSH plugins can intercept several extension points (source). The minimal official example is a permission gate that returns a typed decision from tools/pre-execute to allow or deny a call:

import type { Context } from '@deepseek-ai/cordis'
import type { PreToolDecision, ToolExecution } from '@deepseek-ai/dsh-tools'

declare function isAllowed(exec: ToolExecution): Promise<boolean>

export const name = 'permission-gate'

export function apply(ctx: Context) {
  ctx.on('tools/pre-execute', async (exec, next): Promise<PreToolDecision> => {
    if (!(await isAllowed(exec))) {
      return { kind: 'deny', reason: 'Denied by policy.' }
    }
    return next()
  })
}

It relies on a waterfall event: tools/pre-execute is a reorderable policy layer, each listener receives exec and next(), and it can return a decision or call next() to hand off downstream. This is the same rule as the "you must call next()" discipline in the DSH plugin event system.

How to write a DSH plugin gate: allow and deny at tools/pre-execute

On tools/pre-execute, returning { kind: 'deny', reason } denies that call, and calling next() allows it or forwards it downstream (source). Write a minimal gate in three steps:

1. Declare the hook plugin — export name at module top level, for example permission-gate. Expect: it takes effect as an independent plugin once loaded.
2. Register the listener inside apply — ctx.on('tools/pre-execute', async (exec, next) => { ... }). Expect: your handler runs before every tool execution.
3. Return a decision — return { kind: 'deny', reason: '...' } when not allowed, and return next() when allowed. Expect: the denied call does not execute and carries the reason.

Return ask when you need user confirmation, then answer through ctx.approval. The official permission system / AskUserQuestion works this way: it returns ask from tools/pre-execute and registers a separate model-facing ask tool. To learn the values and outcomes of approval policy, see permission presets and approval.

Choosing DSH plugin interception points: pre-execute, guard, execute, result

The criterion for the four interception points is "do you need to change the result, and must it be enforced": use tools/pre-execute for a policy layer, ctx.tools.guard() for hard invariants, tools/execute to wrap dispatch, tools/post-execute to transform results, and tools/result to observe without changing anything (source). The comparison:

1. tools/pre-execute — a reorderable policy layer that returns allow / deny / ask. Expect: fits composable policy such as permission, sandbox, and plan-mode.
2. ctx.tools.guard() — enforces invariants and provides a monotonic final denial. Expect: fits hard constraints that later listeners cannot overturn.
3. tools/execute — wraps the dispatch lifecycle, useful for timeout / retry / metrics (only exec.signal is replaceable). Expect: fits a generic wrapper around a tool call.
4. tools/post-execute — explicit result transforms; use tools/result if you only want to observe the immutable final result. Expect: do not use post-execute when you are not changing the result.

A practical reminder: when a hook plugin intercepts a tool call, do not casually change the tool's own implementation — the tool contract belongs to ctx.tools.register() and defineTool, see tool plugin development. Self-check three things after writing: does the handler return a decision or next() on every branch; do hard constraints use guard(); does deny carry a diagnosable reason. To find an existing sandbox / permission plugin for comparison, search the DSH Plugin Hub.