[Q&A] How can an out-of-tree plugin answer approval/request in web-profile sessions? (listeners never fire despite scopeTarget semantics)

[Nobodyanonymou-s]

Summary

We're building an out-of-tree plugin (profile bundle via node_modules + dsh.profile.bundles + bundle patch with - insert entry) that needs to answer approval/request waterfall events — e.g. to forward sandbox-escalation prompts to an external UI. Despite the scopeTarget filter semantics appearing to allow untagged listeners, our plugin's listeners never fire, in any attachment variant we could construct.

Reproduction

1. Create a plugin package with dsh.bundle.patch pointing at a patch file containing an - insert: - id/name entry (the entry is what actually registers the plugin — a [] patch silently registers nothing, we learned this the hard way).
2. Plugin apply(ctx) registers listeners, tried all of:

// variant A: root ctx
ctx.on('approval/request', (req, next) => { /* ... */ })
// variant B: global flag
ctx.on('approval/request', handler, { global: true })
// variant C: per-agent, on agent/created (schedule-style)
ctx.on('agent/created', ({ agent }) => agent.ctx.on('approval/request', handler))
// variant D: hooking the approval service's own registry
const svc = agent.ctx?.approval
;(svc.ctx.events ?? svc.ctx).on('approval/request', handler, { global: true })

3. Load it in the web profile (bundles array, before and after dsh-web-app), start dsh --profile web.
4. In a session, run a tool call that triggers a sandbox escalation (e.g. a write under read-only sandbox policy → agent escalates to workspace-write).

Current behavior

• apply() runs (confirmed via startup logs), listeners are registered (variant D even shows our hook counted in the registry's hook list).
• The approval/request event never reaches any of them: the escalation fails immediately with sandbox escalation to "workspace-write" requires approval, but no approval channel is available (the waterfall's fail-closed fallback), and our handlers' log lines never appear.
• ~20 attachment/ordering variants tried; all zero delivery. A control listener on session/event in the same plugin does fire — so the plugin's event surface is alive; only the agent-scoped waterfall is unreachable.

Our best diagnosis so far: ctx.events is not a root singleton (ctx.events !== ctx.root.events — observed at runtime), and ApprovalService.decide dispatches on the service's own fiber registry. A plugin-fiber listener (global or not) appears to live on a different registry than the one the dispatch walks — so scopeTarget's filter (which would pass untagged listeners) is never even consulted for them.

Expected behavior

Reading packages/core/scope/src/index.ts, scopeTarget's carrier filter returns true for listeners with no scope tag:

const tag = scopeOf(ctx)
if (tag === undefined) return true

From this we'd expect a root/plugin-fiber ctx.on('approval/request', ...) listener to receive the dispatch for any agent. Is that the intended contract? And if the correct pattern for out-of-tree plugins is something else entirely (a different mounting point, a service-injection contract, or "not supported yet"), we'd appreciate a pointer.

Environment

• dsh 0.1.2-rc.1 (pinned; all runtime experiments above)
• Source-consistency check against current master / 0.1.5-rc.1: core/scope scopeTarget, interaction/user-approval dispatch, and boot/app-boot bundle loading are all unchanged in the relevant parts
• Linux container (node:24-slim), plugin loaded statically via profile node_modules (no pnpm store access at runtime)

Context: we're using dsh as the runtime base for a multi-user agent workspace (SuperWhale — an agent-OS experiment for a 50-person pilot), and approval forwarding to a human UI is the one seam we couldn't bridge from the plugin side. Happy to share the full 20-variant experiment matrix and source anchors if useful. Thanks!

[argszero]

Thanks for the 20-variant matrix — it made this checkable. I rebuilt the harness against master (and diffed your pinned tag), and the measurements point somewhere other than the diagnosis in your last paragraph.

First, your tag is not the variable: I checked dsh-v0.1.2-rc.1 — both the dispatch (scopeTarget(req.agent, req.agent), user-approval) and scopeTarget itself are byte-identical to master. So the mechanism you are fighting is the same one that runs today.

1. There is one registry — ctx.events is a view, not a second bus.

same hook array?                true    // ctx.events._hooks['approval/request'] === root.events._hooks['approval/request']
same via root.events?           true
ctx.events === root.events?     false   // the object differs …
ctx.events === ctx.root.events? false
hook.ctx === pluginCtx?         true

ctx.events !== ctx.root.events is real, but it is not the mechanism: events is a per-context view over one root hook registry, and a listener registered from any context lands in the array the dispatch walks. "A plugin-fiber listener lives on a different registry than the one dispatch walks" is not what happens — worth striking from the diagnosis, because it sends the next person down a false path.

2. An untagged listener does fire — for every agent. Dispatch is

this.ctx.waterfall(scopeTarget(req.agent, req.agent), 'approval/request', req, () => 'unavailable')

and the gate (vendor/cordis/src/events.ts) is hook.global || !filter || filter.call(thisArg, hook.ctx), where the filter is scopeTarget's (packages/core/scope/src/index.ts:170-185): no base filter here, then the listener's own tag. Measured:

root listener, dispatch keyed to agentA                 hits=1
root listener, dispatch keyed to agentB                 hits=1
preset listener, dispatch keyed to agentA (child)       hits=1
preset listener, dispatch keyed to agentB (no binding)  hits=0
unscoped plugin ctx listener                            hits=1
unscoped plugin ctx listener, { global: true }          hits=1
listener on a FRESH createScope()                       hits=0

scopeOf(hook.ctx) === undefined ⇒ return true, so a profile-root row is admitted globally; a listener whose tag is a sibling/descendant of the agent key is not.

3. That is exactly why "all four variants failed" does not fit the filter. Variants A, B and D all register untagged contexts (the approval service is a root-level bundle row), and C registers on agent.ctx, whose tag is the agent itself. All four are admitted by the filter. A filter can explain some variants failing; it cannot explain all four. So the first thing to check is whether the dispatch ran at all.

ApprovalService.request() appends approval/asked before it dispatches, so the session log is the discriminator:

• no approval/asked entry in the session → decide() never ran for your call; the message you saw came from a different path, and no listener change will help. (Check with session-query, or just grep the session JSONL.)
• approval/asked present, no approval/decided for it → the dispatch ran and nobody answered; now the filter/ordering question is live and item 4 applies.

4. The shipped pattern to copy — both in-tree answerers register on the root-level plugin's own ctx and decline per request:

• packages/api/remotes/src/index.ts — ctx.on('approval/request', function (request, next) { … }), reads the routed agent via carrierKeyOf(this), forwards to the Remote client.
• packages/acp/acp/src/index.ts:155 — ctx.on('approval/request', (request, next) => { const record = ownedRecord(request.agent); if (record === undefined) return next(); … }).

And if you do want to rule the filter in or out in one line, log your own tag inside apply():

import { scopeOf } from '@deepseek-ai/dsh-scope'
ctx.logger.info('[approval-probe] scope tag =', scopeOf(ctx))

A defined tag means your row landed under a scope (a preset owner, or anything built on createScope) and only that subtree's agents reach you — that is the hits=0 row above. Profile-root rows are untagged.

Two contract details that also bear on the outcome you saw: the waterfall's fallback is 'unavailable' and absence fails closed (docs/capability-seams.md, the ctx.approval row), so the escalation message alone does not distinguish "no listener matched" from "no client answered" — in the web profile the shipped answerer is the Remote forwarder, which needs a connected client. And request() throws outside an open turn.

Happy to post the ~40-line harness (stubs the agent, drives the waterfall directly, no harness boot) if it helps you re-run your table.

[walavave]

I encountered the same problem when I tried to connect Paseo with DSH

[Nobodyanonymou-s]

Resolved — it was our plugin claiming the waterfall, not a dsh issue. Thanks for the discriminator.

@argszero — your approval/asked discriminator and the "untagged listeners fire" table were exactly right, and they led us to the answer. Closing the loop for anyone hitting the same wall (the Paseo report above, and us):

Root cause: our out-of-tree bundle plugin registered a global approval/request listener in apply() whose handler claimed the waterfall (returned an outcome without calling next(), then polled our own side-channel). A global listener is admitted regardless of scope, and our hook registered before the shipped Remote forwarder (packages/api/remotes/src/index.ts — a non-global ctx.on('approval/request', …)), so the waterfall never reached the forwarder. Our escalation "failed closed" with unavailable even though the forwarder was present and admitted — indistinguishable from "no answerer" from the outside, exactly the ambiguity you flagged.

Fix: removed our plugin's approval/request listener and let the Remote forwarder do its job. We connect a Gateway client to /api/remote.mux $events, the forwarder forwards the approval/request waterfall frame to us, we render a card, and write the decision back via $events/result. The full chain now works end-to-end: escalation → forwarder → $events → client card → approve → allowed-once (and rejected on decline).

The footgun for other out-of-tree plugin authors: don't register a claiming approval/request listener if you also want the shipped Remote forwarder to work. A global listener bypasses the scope filter and, depending on registration order, can sit ahead of the non-global forwarder and swallow every approval. Either decline via next() unless you're the intended answerer, or — the path we took — don't register a listener at all and be the connected Remote client instead. The ~40-line harness is no longer needed on our end, but thanks for offering it.