DeepSeek Harness Hook 与权限插件：先 allow/deny，再 ask/guard

ctx.tools.execute(input)
        │
        ▼
tools/pre-execute  ── allow ───────────────┐
        │                                      │
        ├─ deny ──► error result               │
        │                                      ▼
        ├─ ask ──► ctx.approval ── allowed-once ──► guards
        │                    └─ rejected / cancelled / unavailable ─► deny
        │                                      │
        └──────────────────────────────────────┘
                                               │
                                  ctx.tools.guard()
                                  reason ──► deny
                                  undefined ─► tools/execute
                                                   │
                                                   ▼
                                             tool body
                                                   │
                               tools/post-execute → tools/result

mkdir -p scratch-plugin/src

scratch-plugin/
├── cordis.yml
└── src/
    ├── greet-tool.ts
    ├── greet-permission-gate.ts
    └── greet-owner-guard.ts

import type { Context } from '@deepseek-ai/cordis'
import { defineTool } from '@deepseek-ai/dsh-tools'

export const name = 'local-greet-tool'
export const inject = ['tools']

export function apply(ctx: Context) {
  ctx.tools.register(defineTool({
    name: 'greet',
    description: 'Return a deterministic greeting for a supplied name.',
    parameters: {
      name: { type: 'string', required: true, description: 'The name to greet' },
    },
    output: {
      schema: { type: 'string' },
      render: (_args, value) => [{ type: 'text', text: value }],
    },
    async execute(args) {
      return `Hello, ${args.name}!`
    },
  }))
}

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

export const name = 'local-greet-permission-gate'
export const inject = ['tools']

export interface Config {
  deniedNames: string[]
  askNames: string[]
}

export const Config: Schema<Config> = Schema.object({
  deniedNames: Schema.array(Schema.string()).default([]),
  askNames: Schema.array(Schema.string()).default([]),
})

export function apply(ctx: Context, config: Config) {
  console.log(`[local-greet-permission-gate] loaded deny=${config.deniedNames.join(',')} ask=${config.askNames.join(',')}`)

  ctx.on('tools/pre-execute', async (exec, next): Promise<PreToolDecision> => {
    if (exec.name !== 'greet') return next()
    const target = (exec.arguments as { name?: unknown }).name
    if (typeof target !== 'string') return next()
    if (config.deniedNames.includes(target)) {
      return { kind: 'deny', reason: 'blocked by local pre-execute policy' }
    }
    if (config.askNames.includes(target)) {
      return { kind: 'ask', reason: 'approval required by local pre-execute policy' }
    }
    return next()
  })

  ctx.effect(() => () => {
    console.log('[local-greet-permission-gate] unloaded')
  })
}

import type { Context } from '@deepseek-ai/cordis'
import Schema from '@deepseek-ai/schemastery'

export const name = 'local-greet-owner-guard'
export const inject = ['tools']

export interface Config {
  deniedNames: string[]
}

export const Config: Schema<Config> = Schema.object({
  deniedNames: Schema.array(Schema.string()).default([]),
})

export function apply(ctx: Context, config: Config) {
  console.log(`[local-greet-owner-guard] loaded deny=${config.deniedNames.join(',')}`)

  ctx.tools.guard((exec) => {
    if (exec.name !== 'greet') return undefined
    const target = (exec.arguments as { name?: unknown }).name
    return typeof target === 'string' && config.deniedNames.includes(target)
      ? 'blocked by local monotonic guard'
      : undefined
  })

  ctx.effect(() => () => {
    console.log('[local-greet-owner-guard] unloaded')
  })
}

- insert:
    - id: local-greet-tool
      name: '/absolute/path/to/deepseek-harness/scratch-plugin/src/greet-tool.ts'
    - id: local-greet-owner-guard
      name: '/absolute/path/to/deepseek-harness/scratch-plugin/src/greet-owner-guard.ts'
      config:
        deniedNames: ['guarded']
    - id: local-greet-permission-gate
      name: '/absolute/path/to/deepseek-harness/scratch-plugin/src/greet-permission-gate.ts'
      config:
        deniedNames: ['blocked']
        askNames: ['ask']

pnpm dsh web --patch ./scratch-plugin/cordis.yml

Use the greet tool to greet Cordis.

/**
 * Runs the same three source modules that the cordis.yml patch loads.
 * It deliberately mounts no ApprovalService, UI, agent, sandbox, or provider.
 * Run from E:/coding/deepseek-harness:
 * node --import tsx E:/coding/rex-hugo/.tmp-research/dsh-b3-hooks/practical-plugin/plugin-project-demo.ts
 */
import { Context } from '@deepseek-ai/cordis'
import { CallId } from '@deepseek-ai/dsh-llm'
import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
import ToolRuntime, { type ToolExecutionResult } from '@deepseek-ai/dsh-tools'
import * as greetTool from './src/greet-tool.ts'
import * as ownerGuard from './src/greet-owner-guard.ts'
import * as permissionGate from './src/greet-permission-gate.ts'

interface CaseSummary {
  label: string
  events: string[]
  isError: boolean
  content: ToolExecutionResult['content']
  error: ToolExecutionResult['error']
}

async function invoke(ctx: Context, label: string, name: string, events: string[]): Promise<CaseSummary> {
  events.push(`call:${name}`)
  const result = await ctx.tools.execute({
    signal: new AbortController().signal,
    callId: CallId(`project-${label}`),
    name: 'greet',
    arguments: { name },
  })
  return { label, events: [...events], isError: result.isError, content: result.content, error: result.error }
}

async function main(): Promise<void> {
  const ctx = new Context()
  await ctx.plugin(SystemPrompt)
  await ctx.plugin(ToolRuntime)
  await ctx.plugin(greetTool)
  await ctx.plugin(ownerGuard, { deniedNames: ['guarded'] })
  await ctx.plugin(permissionGate, { deniedNames: ['blocked'], askNames: ['ask'] })

  const events: string[] = []
  ctx.on('tools/execute', async (_exec, next) => {
    events.push('execute-hook')
    return next()
  })
  ctx.on('tools/post-execute', async (_exec, _result, next) => {
    events.push('post-execute')
    return next()
  })
  ctx.on('tools/result', (_exec, result) => {
    events.push(`result:${result.isError ? 'error' : 'success'}`)
  })

  for (const [label, name] of [
    ['allowed', 'Cordis'],
    ['pre-denied', 'blocked'],
    ['guard-denied', 'guarded'],
    ['ask-without-approval', 'ask'],
  ] as const) {
    console.log(`=== ${label} ===`)
    console.log(JSON.stringify(await invoke(ctx, label, name, events)))
    events.length = 0
  }

  console.log('=== dispose ===')
  await ctx.fiber.dispose()
}

main().catch((error) => { console.error(error); process.exit(1) })

node --import tsx ./scratch-plugin/plugin-project-demo.ts

[local-greet-owner-guard] loaded deny=guarded
[local-greet-permission-gate] loaded deny=blocked ask=ask
=== allowed ===
{"label":"allowed","events":["call:Cordis","execute-hook","post-execute","result:success"],"isError":false,"content":[{"type":"text","text":"Hello, Cordis!"}]}
=== pre-denied ===
{"label":"pre-denied","events":["call:blocked","post-execute","result:error"],"isError":true,"content":[{"type":"text","text":"Error: blocked by local pre-execute policy"}],"error":{"message":"blocked by local pre-execute policy"}}
=== guard-denied ===
{"label":"guard-denied","events":["call:guarded","post-execute","result:error"],"isError":true,"content":[{"type":"text","text":"Error: blocked by local monotonic guard"}],"error":{"message":"blocked by local monotonic guard"}}
=== ask-without-approval ===
{"label":"ask-without-approval","events":["call:ask","post-execute","result:error"],"isError":true,"content":[{"type":"text","text":"Error: approval required by local pre-execute policy"}],"error":{"message":"approval required by local pre-execute policy"}}
=== dispose ===
[local-greet-permission-gate] unloaded
[local-greet-owner-guard] unloaded

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()
  })
}

/**
 * Pre-dispatch decision. `allow` runs the call; `deny` materializes an error;
 * `ask` runs only after an approval service returns `allowed-once` and otherwise
 * denies. Input rewriting is excluded because arguments are already logged and
 * presented.
 */
export type PreToolDecision =
  | { kind: 'allow' }
  | { kind: 'deny'; reason: string }
  | { kind: 'ask'; reason?: string }

export function apply(ctx: Context, config: Config) {
  ctx.on('tools/pre-execute', async (exec, next): Promise<PreToolDecision> => {
    //                                          ↑ 返回类型标注：只允许三种 return
    if (exec.name !== 'greet') return next()
    // ...
    if (config.deniedNames.includes(target)) {
      return { kind: 'deny', reason: 'blocked by local pre-execute policy' }
    }
    if (config.askNames.includes(target)) {
      return { kind: 'ask', reason: 'approval required by local pre-execute policy' }
    }
    return next()   // 不做决定，交给下一个监听器或默认值
  })
}

// 反例：直接 throw 的问题
ctx.on('tools/pre-execute', async () => {
  throw new Error('denied')   // 每个监听器各抛各的，结果无法统一
})

const gate = await this.ctx.waterfall(
  carrier, 'tools/pre-execute', exec,
  () => Promise.resolve<PreToolDecision>({ kind: 'allow' }),  // ← 默认
)

      const carrier = scopeTarget(this, exec.agent)
      const gate = await this.ctx.waterfall(
        carrier, 'tools/pre-execute', exec,
        () => Promise.resolve<PreToolDecision>({ kind: 'allow' }),
      )
      const askResolution: ToolAskResolution = gate.kind === 'ask'
        ? await this.serviceAsk(exec, gate)
        : { decision: gate, approvalCancelled: false }
      const { decision } = askResolution
      if (this.callerCancelled(exec) && askResolution.approvalCancelled) {
        return await next({ kind: 'post-result', exec, result: toolAbortedBeforeDispatchResult() })
      }
      const denialReason = decision.kind === 'allow'
        ? this.guardReason(exec)
        : decision.reason
      if (denialReason !== undefined) {
        return await next({
          kind: 'post-result',
          exec,
          result: this.materializeFinalResult({
            content: [{ type: 'text', text: `Error: ${denialReason}` }],
            isError: true,
            error: { message: denialReason },
          }),
        })
      }
      if (this.callerCancelled(exec)) {
        return await next({ kind: 'post-result', exec, result: toolAbortedBeforeDispatchResult() })
      }
      return await next({ kind: 'dispatch', exec })

你的监听器返回 { kind: 'ask', reason: '...' }
        │
        ▼
registry 调 serviceAsk(exec, gate)          ← packages/core/tools/src/index.ts:1689
        │
        ├─ ① 没有 approval service？ ──► 变成 deny（带你的 reason）→ 结束
        ├─ ② 没有 agent？ ────────────► 变成 deny（"no agent to route it through"）→ 结束
        ▼
        approval.request({ agent, toolName, callId, reason, signal })
        │                                     ← 要求 open turn，记录 asked/decided 审计对
        ▼
        answerer 链（UI 弹窗 / ACP 自动化 / 无人回答）
        │
        ├─ allowed-once ──► 变成 allow → 继续到 guard
        ├─ rejected     ──► 变成 deny（"the user rejected tool ..."）
        ├─ cancelled    ──► 变成 deny（"approval ... was cancelled"）
        └─ unavailable  ──► 变成 deny（"no approval channel is available"）

import ApprovalService from '@deepseek-ai/dsh-user-approval'

await ctx.plugin(ApprovalService, { policy: 'ask' })

Error: approval required by local pre-execute policy

Error: tool "greet" requires approval, but the call has no agent to route it through

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

  /**
   * 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.
   * @param guard - synchronous check; a returned string denies the execution.
   * @returns the exact disposer that unregisters the guard.
   */
  guard(guard: ToolGuard): () => void {
    return this.layers.effect(
      this.ctx,
      layer => layer.guards.append(guard),
      { label: 'tools.guard()', notify: false },
    )
  }

/**
 * Closed approval outcomes: a one-shot grant, explicit rejection, withdrawn
 * request, or unavailable answerer. Callers fail closed on `unavailable`.
 */
type ApprovalOutcome = 'allowed-once' | 'rejected' | 'cancelled' | 'unavailable'

/**
 * A session's approval policy — what happens to an {@link ApprovalService}
 * ask BEFORE any interactive answerer sees it:
 *
 * - `'ask'` (the default) — delegate to the composed answerers; with none
 *   composed the chain falls through to the fail-closed `'unavailable'`.
 * - `'never'` — never prompt anyone: every ask resolves `'rejected'`
 *   deterministically. The strict headless stance (CI, unattended runs) and
 *   the policy whose outcome is knowable without asking.
 */
type ApprovalPolicy = 'ask' | 'never'

    const approval = this.ctx.get('approval')
    if (approval === undefined) {
      return {
        decision: { kind: 'deny', reason: ask.reason ?? `tool "${exec.name}" requires approval (not yet supported)` },
        approvalCancelled: false,
      }
    }
    if (exec.agent === undefined) {
      return {
        decision: { kind: 'deny', reason: `tool "${exec.name}" requires approval, but the call has no agent to route it through` },
        approvalCancelled: false,
      }
    }
    const outcome = await approval.request({
      agent: exec.agent,
      toolName: exec.name,
      callId: exec.callId,
      ...ask.reason !== undefined ? { reason: ask.reason } : {},
      signal: exec.signal,
    })
    switch (outcome) {
      case 'allowed-once': return { decision: { kind: 'allow' }, approvalCancelled: false }
      case 'rejected': return {
        decision: { kind: 'deny', reason: `the user rejected tool "${exec.name}"` },
        approvalCancelled: false,
      }
      case 'cancelled': return {
        decision: { kind: 'deny', reason: `approval for tool "${exec.name}" was cancelled` },
        approvalCancelled: true,
      }
      case 'unavailable': return {
        decision: { kind: 'deny', reason: `tool "${exec.name}" requires approval, but no approval channel is available` },
        approvalCancelled: false,
      }
      default: return assertNever(outcome, 'ApprovalOutcome')
    }

permission preset selection
       ├─ writes sandbox/mode knob → sandbox consumer decides execution confinement
       └─ writes approval/policy knob → approval service decides ask behavior
                                             └─ tools/pre-execute / guard still apply

Hook plugin
  -> tools/pre-execute: allow / deny / ask
  -> approval seam: allowed-once / rejected / cancelled / unavailable
  -> monotonic guard: reason / undefined
  -> execute body only when still allowed
  -> post-execute / result observe the normalized outcome