dsh-hooks-claude-code cannot be installed out-of-tree: dsh-hook-protocol is an unsatisfiable peer dependency

[sashabogi]

Setup: @deepseek-ai/dsh 0.1.0-rc.7 from npm, node 26.3, macOS (arm64).

The Claude Code hooks bridge can't be installed into a profile the documented way. Repro:

dsh --profile headless "hi"    # auto-init the profile
dsh plugin --profile headless add @deepseek-ai/dsh-hooks-claude-code
# insert the plugin row in cordis.patch.yml, pointing configPath at any hooks.json
dsh --profile headless "hi"

Boot fails with:

Error: dsh: plugin tree failed to load: failed to apply loader entry include (cordis:include):
failed to import loader entry ... (@deepseek-ai/dsh-hooks-claude-code):
Cannot find package '@deepseek-ai/dsh-hook-protocol' imported from
.../profiles/headless/node_modules/@deepseek-ai/dsh-hooks-claude-code/lib/index.js

Why: the bridge declares @deepseek-ai/dsh-hook-protocol in peerDependencies (0.0.1-rc.5), and the profile template pins autoInstallPeers: false, so dsh plugin add never brings it in. The other peers (cordis, dsh-agent, dsh-tools, ...) still resolve because they exist in the dsh installation tree and the loader's module hook finds them there. dsh-hook-protocol isn't shipped in the dist (dsh-mcp-client is, the hooks packages aren't), so there's nothing to resolve it against.

Workaround: add the protocol lib explicitly.

dsh plugin --profile headless add @deepseek-ai/dsh-hooks-claude-code @deepseek-ai/dsh-hook-protocol

Suggested fix: promote dsh-hook-protocol to dependencies (the package README describes it as a plain library, not a cordis plugin), or ship the hooks packages in the dist the way dsh-mcp-client ships.

Found while wiring the bridge to an existing hooks.json (the Trantor agent bus). The bridge itself works well once it loads, our production Claude Code hooks ran unmodified.

[ylwl1997]

Out-of-tree install failing because dsh-hook-protocol is an unsatisfiable / unpublished peer is a packaging boundary issue: the hooks bridge expects monorepo-local protocol packages that the public npm graph doesn’t expose the same way.

Workarounds people use today:

• run hooks-related work from a source checkout of deepseek-harness where workspace protocol packages resolve
• or wait for the bridge’s public dependencies to be published/versioned for out-of-tree profiles

If you paste the exact ERR_PNPM_* / peer dependency block from dsh plugin add …, it helps separate “not on npm” vs “wrong range vs rc.7”.

[sashabogi]

Thanks. Dug further and it turned out simpler than either of us had it: everything IS published, the latest dist-tags are just stale.

@deepseek-ai/dsh-hooks-claude-code  latest -> 0.0.1-rc.5   next -> 0.1.0-rc.8
@deepseek-ai/dsh-hook-protocol      latest -> 0.0.1-rc.1   next -> 0.1.0-rc.8

So an unversioned dsh plugin add installs the ancient bridge, whose peer range ^0.0.1-rc.5 predates the protocol lib the current CLI generation ships. There's no ERR_PNPM_* block to paste, the add succeeds silently (the profile template sets autoInstallPeers: false), and the failure only shows at boot:

Error: dsh: plugin tree failed to load: failed to apply loader entry include (cordis:include):
failed to import loader entry ... (@deepseek-ai/dsh-hooks-claude-code):
Cannot find package '@deepseek-ai/dsh-hook-protocol' imported from
.../profiles/headless/node_modules/@deepseek-ai/dsh-hooks-claude-code/lib/index.js

Pinning both packages to the CLI's own version resolves it with no source checkout:

dsh plugin --profile headless add @deepseek-ai/dsh-hooks-claude-code@0.1.0-rc.7 @deepseek-ai/dsh-hook-protocol@0.1.0-rc.7

Boots clean and the bridge runs our existing hooks.json faithfully after that. So the actionable fix upstream looks like moving the latest tags forward (or documenting next as the release channel).

[denial123789]

I rechecked the public package graph and rc.8 source (141eb6f). One correction to my earlier comment: @deepseek-ai/dsh-hook-protocol is published. The actual boundary is that it is a bridge peer but is not supplied through the CLI/profile fallback closure.

There is also a dist-tag trap at the current verification point:

• @deepseek-ai/dsh-hooks-claude-code: latest = 0.0.1-rc.5, next = 0.1.0-rc.8
• @deepseek-ai/dsh-hook-protocol: latest = 0.0.1-rc.1, next = 0.1.0-rc.8

So the workaround should pin both exact packages on the Host's release line, rather than use unversioned names. For rc.8:

dsh plugin --profile headless add \
  @deepseek-ai/dsh-hooks-claude-code@0.1.0-rc.8 \
  @deepseek-ai/dsh-hook-protocol@0.1.0-rc.8

For rc.7, use both exact rc.7 packages. The protocol's remaining runtime peers should resolve from the Host-owned closure; do not add Agent/Tools/Session/Shell/Cordis locally just to satisfy metadata. That creates the duplicate-core failure described in #3516.

After install, I would verify canonical realpaths for identity-bearing core packages, then test a supported hook, one native tool, one MCP tool, cancellation, and restart. Also treat hooks.json as executable policy: command hooks run shell code, can block prompts/tools, inject model-visible context, and force continuation; rc.8 implements only a documented subset of Claude Code semantics.

I wrote the exact-version install topology, config rules, trust boundary, acceptance matrix, and duplicate-runtime recovery link here:

• Visual guide: https://sandbaseai.github.io/deepseek-harness-handbook/claude-code-hooks-bridge.html
• Full guide: https://github.com/sandbaseai/deepseek-harness-handbook/blob/main/docs/en/plugin-development/install-claude-code-hooks-bridge.md

[ylwl1997]

Thanks @sashabogi — the unpublished-peer guess was wrong. I just rechecked the public dist-tags and they match what you published:

• @deepseek-ai/dsh-hooks-claude-code: latest = 0.0.1-rc.5, next = 0.1.0-rc.8
• @deepseek-ai/dsh-hook-protocol: latest = 0.0.1-rc.1, next = 0.1.0-rc.8

So the packages are on the registry; an unversioned dsh plugin add simply follows stale latest. With profile autoInstallPeers: false that add can look successful and only blow up at boot, which is the closure gap @denial123789 traced — protocol is a peer, not something the CLI/profile fallback injects.

Until those latest tags move (or the docs say to use next), pin both packages to the same generation as the CLI you actually run (dsh --version), for example on rc.8:

dsh plugin --profile headless add \
  @deepseek-ai/dsh-hooks-claude-code@0.1.0-rc.8 \
  @deepseek-ai/dsh-hook-protocol@0.1.0-rc.8

Using @next is equivalent today, but a version pin is safer if next races ahead of your installed CLI. The same stale-latest pull is what dropped rc.5 core copies into the profile in #3516.