dsh-tool-deny 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hhuangpanda
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,112 @@
-# Temporary Holding Version
+# dsh-tool-deny
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+English | [中文](README.zh.md)
+
+Choose which tools each agent preset gets in [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (dsh).
+
+A plugin loaded at the root of a profile registers its tools globally, so every preset inherits them. A preset can add plugins, but it has no setting to remove a global tool. dsh-tool-deny fills that gap with a few lines of YAML.
+
+## Features
+
+| Option | Where | Value | What it does |
+|---|---|---|---|
+| `hideByPreset` | Root row | Map of preset id to tool names | Removes tools from the model's tool list for the presets you name |
+| `hide` | Inside a preset | Tool names | Same, for the preset that mounts the plugin |
+| `deny` | Inside a preset | Tool names | Keeps tools listed, but refuses every call |
+| `hideSections` | Either | Section names | Blanks global system prompt sections for those agents |
+
+Use `hideByPreset` in a root row, and `hide` and `deny` in a preset row. If a row sets `hideByPreset`, `hide` and `deny` are ignored and a warning is logged.
+
+Hidden tools cost no tokens, because their definitions are never sent to the model. Other presets are unaffected. Subagents, automation runs and resumed sessions are covered too.
+
+## Requirements
+
+Tested on dsh 0.2.1-rc.4.
+
+## Install
+
+```sh
+dsh plugin --profile web add dsh-tool-deny
+```
+
+The plugin does nothing until you configure it.
+
+## Quick start
+
+Say you installed a plugin that adds `image_search` and `translate`, and you want to keep them away from your `minimal` and `reviewer` presets. Add this to your profile's `cordis.patch.yml`:
+
+```yaml
+- insert:
+    - id: tool-deny-root
+      name: dsh-tool-deny
+      config:
+        hideByPreset:
+          minimal:
+            - image_search
+            - translate
+          reviewer:
+            - translate
+```
+
+Restart dsh. New `minimal` sessions no longer see either tool, `reviewer` sessions no longer see `translate`, and every other preset keeps both.
+
+If several presets share a list, a YAML anchor avoids repeating it:
+
+```yaml
+hideByPreset:
+  minimal: &extra-tools
+    - image_search
+    - translate
+  reviewer: *extra-tools
+```
+
+## Use inside a preset
+
+Use this when a preset should carry its own rules, or when you need `deny`. Add the row to the preset's `plugins` list:
+
+```yaml
+- id: tool-deny
+  name: dsh-tool-deny
+  config:
+    hide:
+      - image_search
+    deny:
+      - delete_records
+```
+
+`image_search` disappears from the list. `delete_records` stays listed, and calling it returns `"delete_records" is not available to this agent.`
+
+## Hide or refuse?
+
+Prefer hiding: the model never sees the tool, and you save its tokens. Use `deny` for tools that hiding can't reach, which are the ones a plugin registers on each agent directly (through `agent.ctx`) instead of globally. If you try to hide one, it stays visible.
+
+## Hide prompt sections
+
+Some plugins add a global section to the system prompt. Blank it by name for the same agents:
+
+```yaml
+config:
+  hideByPreset:
+    minimal:
+      - image_search
+  hideSections:
+    - my-plugin:notes
+```
+
+At the root, `hideSections` applies to every preset named in `hideByPreset`. The section name is defined by the plugin that registers it.
+
+## Limitations
+
+- **Failures are quiet.** If you remove the row or the plugin stops loading, the tools come back with no error. Don't rely on it as your only safeguard for a sensitive agent.
+- **Lists are by name.** A new tool added by a plugin update stays visible until you add it.
+- **Unknown names are skipped.** A tool name that doesn't exist logs a warning and is otherwise ignored, so check your spelling.
+- **It hides tools, not plugins.** The plugin keeps running. Anything it does beyond its tools, such as acting as the provider behind `web_search`, is unchanged.
+- **Preset switches can drop tools.** Switching a new session to another preset and back can leave out `subagent`, which is dsh behavior. Starting a fresh session restores it.
+
+## How it works
+
+In root mode, the plugin listens for `agent/created` and `agent-preset/selected`, looks up the agent's preset, and calls `ctx.tools.restrict({ deny })` on that agent. dsh then filters those tools whenever it builds the agent's tool list. The tools stay registered, so other agents are unaffected. `deny` uses `ctx.tools.guard`, which rejects the call at execution time.
+
+## License
+
+[MIT](LICENSE)

package/README.zh.md

@@ -0,0 +1,112 @@
+# dsh-tool-deny
+
+[English](README.md) | 中文
+
+为 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（dsh）中的每个智能体预设（preset）选择可用的工具。
+
+在 profile 根部加载的插件会全局注册其工具，因此所有预设都会继承这些工具。预设可以添加插件，却没有移除全局工具的设置。dsh-tool-deny 用几行 YAML 补上了这个空缺。
+
+## 功能
+
+| 选项 | 位置 | 值 | 作用 |
+|---|---|---|---|
+| `hideByPreset` | 根行 | 预设 id 到工具名的映射 | 从指定预设的模型工具列表中移除工具 |
+| `hide` | 预设内 | 工具名 | 同上，作用于挂载该插件的预设 |
+| `deny` | 预设内 | 工具名 | 工具仍在列表中，但拒绝每一次调用 |
+| `hideSections` | 两处皆可 | 段落名 | 为这些智能体清空全局系统提示词中的指定段落 |
+
+在根行使用 `hideByPreset`，在预设行使用 `hide` 和 `deny`。如果某一行设置了 `hideByPreset`，则 `hide` 和 `deny` 会被忽略，并记录一条警告。
+
+被隐藏的工具不消耗 token，因为其定义不会发送给模型。其他预设不受影响。子智能体、自动化运行和恢复的会话同样适用。
+
+## 环境要求
+
+已在 dsh 0.2.1-rc.4 上测试。
+
+## 安装
+
+```sh
+dsh plugin --profile web add dsh-tool-deny
+```
+
+配置之前，插件不会产生任何效果。
+
+## 快速开始
+
+假设你安装了一个添加 `image_search` 和 `translate` 的插件，并希望 `minimal` 和 `reviewer` 预设用不到它们。将以下内容添加到 profile 的 `cordis.patch.yml`：
+
+```yaml
+- insert:
+    - id: tool-deny-root
+      name: dsh-tool-deny
+      config:
+        hideByPreset:
+          minimal:
+            - image_search
+            - translate
+          reviewer:
+            - translate
+```
+
+重启 dsh。新的 `minimal` 会话将看不到这两个工具，`reviewer` 会话将看不到 `translate`，其他预设仍保留两者。
+
+如果多个预设共用同一份列表，可以用 YAML 锚点避免重复：
+
+```yaml
+hideByPreset:
+  minimal: &extra-tools
+    - image_search
+    - translate
+  reviewer: *extra-tools
+```
+
+## 在预设内使用
+
+当预设需要自带规则，或需要使用 `deny` 时，请这样做。将该行添加到预设的 `plugins` 列表：
+
+```yaml
+- id: tool-deny
+  name: dsh-tool-deny
+  config:
+    hide:
+      - image_search
+    deny:
+      - delete_records
+```
+
+`image_search` 会从列表中消失。`delete_records` 仍在列表中，调用它会返回 `"delete_records" is not available to this agent.`。
+
+## 隐藏还是拒绝？
+
+优先使用隐藏：模型看不到该工具，还能节省它占用的 token。对于隐藏无法覆盖的工具，请使用 `deny`。这类工具由插件直接注册在每个智能体上（通过 `agent.ctx`），而不是全局注册。若尝试隐藏它们，它们仍然可见。
+
+## 隐藏提示词段落
+
+有些插件会向系统提示词中添加全局段落。可以按名称为相同的智能体清空它：
+
+```yaml
+config:
+  hideByPreset:
+    minimal:
+      - image_search
+  hideSections:
+    - my-plugin:notes
+```
+
+在根部，`hideSections` 适用于 `hideByPreset` 中列出的每个预设。段落名由注册它的插件定义。
+
+## 局限性
+
+- **失效时不会报错。** 如果移除了该行，或插件无法加载，工具会悄悄恢复。不要把它作为敏感智能体的唯一保护措施。
+- **按名称列出。** 插件更新新增的工具在你添加之前仍然可见。
+- **未知名称会被跳过。** 不存在的工具名只会记录一条警告，其余情况下被忽略，请仔细检查拼写。
+- **隐藏的是工具，而不是插件。** 插件仍在运行。它在工具之外的行为（例如作为 `web_search` 背后的提供方）不会改变。
+- **切换预设可能丢失工具。** 将新会话切换到另一个预设再切回来，可能会丢失 `subagent`，这是 dsh 本身的行为。开启新会话即可恢复。
+
+## 工作原理
+
+在根模式下，插件监听 `agent/created` 和 `agent-preset/selected`，查找该智能体的预设，并对该智能体调用 `ctx.tools.restrict({ deny })`。之后 dsh 在构建该智能体的工具列表时会过滤这些工具。工具仍保持注册状态，因此其他智能体不受影响。`deny` 使用 `ctx.tools.guard`，在执行时拒绝调用。
+
+## 许可证
+
+[MIT](LICENSE)

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+# Empty on purpose: this plugin does nothing until you configure it.
+# Add a row to your profile's cordis.patch.yml, or mount it in a preset. See README.md.
+[]

package/index.js

@@ -0,0 +1,81 @@
+/**
+ * Limits which tools an agent gets. See README.md for the config options.
+ */
+export const name = "dsh-tool-deny"
+export const inject = ["tools", "systemPrompt"]
+
+function refuseCalls(ctx, toolNames) {
+  if (toolNames.length === 0) return
+  const refused = new Set(toolNames)
+  ctx.tools.guard((execution) =>
+    refused.has(execution?.name)
+      ? `"${execution.name}" is not available to this agent.`
+      : undefined,
+  )
+}
+
+// dsh names this filter "deny", but it hides the tool. It is unrelated to our `deny` option.
+function removeFromToolList(ctx, toolName) {
+  return ctx.tools.restrict({ deny: [toolName] })
+}
+
+function hide(ctx, logger, toolNames, sectionNames) {
+  const undo = []
+  for (const toolName of toolNames) {
+    // One call per name: restrict() throws on an unknown tool, which would fail the agent.
+    try {
+      undo.push(removeFromToolList(ctx, toolName))
+    } catch (error) {
+      logger?.warn?.(`dsh-tool-deny: cannot hide "${toolName}": ${error}`)
+    }
+  }
+  for (const sectionName of sectionNames) {
+    undo.push(ctx.systemPrompt.section({ name: sectionName, order: 500, text: "" }))
+  }
+  return undo
+}
+
+function hideByPreset(ctx, toolNamesByPreset, sectionNames) {
+  ctx.inject(["agents", "agentPresets"], (sctx) => {
+    const undoByAgent = new Map()
+
+    const unhide = (agent) => {
+      for (const undo of undoByAgent.get(agent) ?? []) undo()
+      undoByAgent.delete(agent)
+    }
+    const refresh = (agent) => {
+      unhide(agent)
+      const preset = sctx.agentPresets.composedPreset(agent.ctx)
+      const toolNames = toolNamesByPreset[preset]
+      if (toolNames) undoByAgent.set(agent, hide(agent.ctx, sctx.logger, toolNames, sectionNames))
+    }
+
+    for (const agent of sctx.agents.roots()) refresh(agent)
+    sctx.on("agent/created", ({ agent }) => {
+      refresh(agent)
+      return undefined
+    })
+    // A session can change preset before its first turn, after agent/created fired.
+    sctx.on("agent-preset/selected", (sessionId) => {
+      const agent = sctx.agents.get(sessionId)
+      if (agent) refresh(agent)
+    })
+    sctx.on("agent/disposed", ({ agent }) => unhide(agent))
+    sctx.effect(() => () => {
+      for (const agent of [...undoByAgent.keys()]) unhide(agent)
+    }, "dsh-tool-deny: hide by preset")
+  })
+}
+
+export function apply(ctx, config = {}) {
+  const sectionNames = config.hideSections ?? []
+  if (config.hideByPreset) {
+    if (config.hide || config.deny) {
+      ctx.logger?.warn?.("dsh-tool-deny: hide and deny only work inside a preset; ignoring them")
+    }
+    hideByPreset(ctx, config.hideByPreset, sectionNames)
+    return
+  }
+  refuseCalls(ctx, config.deny ?? [])
+  hide(ctx, ctx.logger, config.hide ?? [], sectionNames)
+}

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "dsh-tool-deny",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Hide or refuse named tools per agent preset in DeepSeek Harness. Can also hide system prompts added by tools. Useful when plugins force tools on all agent presets.",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js",
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=22",
+    "dsh": ">=0.2.1-rc.1 <0.3.0-0"
+  },
+  "files": [
+    "index.js",
+    "cordis.patch.yml",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "deepseek-harness",
+    "dsh",
+    "dsh-plugin",
+    "tools",
+    "agent-preset"
+  ],
+  "scripts": {
+    "test": "node --test \"test/*.test.mjs\""
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hhuangpanda/dsh-tool-deny.git"
+  },
+  "bugs": "https://github.com/hhuangpanda/dsh-tool-deny/issues",
+  "homepage": "https://github.com/hhuangpanda/dsh-tool-deny#readme",
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "engines": {
+      "dsh": ">=0.2.1-rc.1 <0.3.0-0"
+    }
+  }
+}