Files
archie/docs/prds/progressive-tool-disclosure.md
T

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. 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:

// 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 — 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).