# 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**. `BridgeTools` and `ContextPressureGate` are referenced only in `disclosure_test.go`. This task is therefore a **wiring** task, not a feature build. Wire the existing bridge into the per-chat-turn toolset: 1. **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`. 2. **Run the gate in `chatGenerateOptions`** (`internal/app/archied/main.go`) so it decides full-vs-bridge disclosure per turn, and build the `core.ToolSet` from the gate's filtered output. 3. **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: ```go // 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: ```go 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: ```go 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` — `chatGenerateOptions` composes + gates. - `internal/app/archied/chat_turn_model.go` — `Prepare` accepts `TurnPrepareContext`. - `internal/gateway/turn.go` — `TurnModel.Prepare` signature; `prepareTurn` fills context window. - `internal/gateway/turn_test.go` — update the `turnTestModel.Prepare` mock. - `internal/tools/disclosure.go` — add `ComposeForTurn` helper (or place in archied). ## Out of scope / follow-ups - Delegate `tool_call` through `toolExecute` for 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 `ContextPressureGate` mode with the compression budget already computed in `prepareTurn` (`turn.go`).