5.4 KiB
Progressive tool disclosure (bridge tools) — wiring
Status: Finalised Date: 2026-08-15 Compound: the "keep the LLM tool schema small, give full access on demand" work (issue #167)
Decision
The bridge-tool pattern is implemented and tested in
internal/tools/disclosure.go (tool_search, tool_describe, tool_call
ContextPressureGate+DisclosureMode, section 17.14/17.15) — but it is never wired into the daemon.BridgeToolsandContextPressureGateare referenced only indisclosure_test.go. This task is therefore a wiring task, not a feature build.
Wire the existing bridge into the per-chat-turn toolset:
- Compose a per-turn registry seeded from the base registry plus the
per-turn extra tools, register the bridge tools into it, and hand it to both
the bridge handlers and the
ContextPressureGate. - Run the gate in
chatGenerateOptions(internal/app/archied/main.go) so it decides full-vs-bridge disclosure per turn, and build thecore.ToolSetfrom the gate's filtered output. - Thread the model's context window into the preparation seam so the gate
has a real
ContextWindowSize(it disables itself at 0, falling back to full disclosure).
Why the naive "register extras into the base registry" is wrong
BuildToolSetFrom (internal/agentexec/toolset.go) documents the invariant:
the task tools carry the calling gateway's identity, so there is one set of them per gateway and they cannot live in the process-wide registry.
This is confirmed by wiring: gateways are per-channel
(telegram_setup.go build a TurnRunner per channel), and the extra
tools (task_*, session_*, dashboard_*) close over that channel's identity
via TurnRunnerConfig (turn.go). Registering them into b.toolReg would
let channel A's session/identity-bound tools be invoked by channel B — a real
cross-channel privilege bug. The bridge handlers iterate reg.All()
(disclosure.go), so the extras must be discoverable; the fix is a
per-turn composed registry, not a mutation of the process-wide one.
Shape of the change
1. Per-turn composed registry + gate inside chatGenerateOptions
Replace the current base-set + extra-set merge (main.go) with a single
composed-registry pass:
// new helper, in internal/tools/disclosure.go or the archied wiring package
func ComposeForTurn(reg *tools.Registry, extra []tools.ToolEntry) (*tools.Registry, error) {
composed := tools.NewRegistry()
for _, e := range reg.All() {
if err := composed.Register(e); err != nil { return nil, err }
}
for _, e := range extra {
if err := composed.Register(e); err != nil { return nil, err }
}
if _, err := composed.RegisterBatch(tools.BridgeTools(composed)); err != nil {
return nil, err
}
return composed, nil
}
chatGenerateOptions then:
composed, err := ComposeForTurn(registry, extra)
// ...
gate := tools.NewContextPressureGate(contextWindow)
gate.SetAlwaysVisible(...) // e.g. session/session_resume, task/task_list
disclosed := gate.FilterTools(composed)
toolSet, err := agentexec.BuildToolSetFrom(disclosed, toolOpts)
FilterTools (disclosure.go) already returns all in full mode and
bridge + always-visible in bridge mode, and BuildToolSetFrom re-applies
availability/approval/schema rules, so the two layers compose cleanly.
2. Thread context window through the preparation seam
ContextPressureGate disables at ContextWindowSize == 0. The model context
window is resolved in TurnRunner.prepareTurn (turn.go) but is not
passed to TurnModel.Prepare. Extend the seam:
type TurnPrepareContext struct {
Model string
Extra []tools.ToolEntry
ContextWindow int // model's context window in tokens; 0 = gate disabled
}
TurnModel.Prepare(ctx, context TurnPrepareContext); prepareTurn fills
ContextWindow from modelDetails.ContextWindow. This touches one interface
(turn.go), one production impl (chat_turn_model.go), and the test
mock (turn_test.go).
3. Bridge-handler parity note
bridgeCallHandler calls e.Handler directly (disclosure.go), bypassing
toolExecute — so a tool_call invocation does not apply CapPayload /
MaxResultSizeChars spilling or OnToolCall reporting, and it pre-refuses
RequiresApproval tools (disclosure.go). This is acceptable for the
first wiring (the bridge is read-discover/describe plus a guarded call), but a
later hardening should route the invoked tool through the same
cap/approval path the model's direct call uses. Recorded as a follow-up, not a
blocker for this task.
Files touched
internal/app/archied/main.go—chatGenerateOptionscomposes + gates.internal/app/archied/chat_turn_model.go—PrepareacceptsTurnPrepareContext.internal/gateway/turn.go—TurnModel.Preparesignature;prepareTurnfills context window.internal/gateway/turn_test.go— update theturnTestModel.Preparemock.internal/tools/disclosure.go— addComposeForTurnhelper (or place in archied).
Out of scope / follow-ups
- Delegate
tool_callthroughtoolExecutefor cap/approval/observability parity. - Cover the compose-and-gate path with tests (compressed footprint under a small window; always-visible minus bridge margin).
- Reconcile any
ContextPressureGatemode with the compression budget already computed inprepareTurn(turn.go).