Files
archie/docs/prds/progressive-tool-disclosure.md
T
sam 65e6b2f65b docs(prds): normalise statuses and remove writing dated to its own day
Three defects the first sweep left behind, each caught by a rule the guard
did not yet have.

Statuses. RULES.md gives three; the tree had 25 values, and the free-text ones
were carrying progress. "Implemented (wiring landed)" and "Ratified (rev. 2e).
Rev. 2e adds the OpenTaskByPR lookup. Rev. 2d revised section 10..." were both
changelogs living in the one field the other rules exempt. Every PRD now
declares Draft, Approved or Finalised and nothing else; five that declared
nothing now declare one. A revision number moves to **Revision:**, a pointer
to the authoritative document to **Authority:**, and what a past revision
changed to git. CLAUDE.md's citation of state-store-contract rev. 2e still
resolves.

Stale cross-references. "Supersedes the 2026-09-03 open question", "this
bullet previously said", "an earlier draft of this document claimed" all point
at text the reader cannot see, because it was replaced. A supersede marker
survives only when it names a file, a section or a symbol that can be found.

Temporal hedges. 100 uses of today, currently and right now across 31 files.
Each dates its sentence to the day it was written: "[notify] today is one
webhook URL, read in one place" stops being true the moment this design lands,
while still reading as the premise it rests on.

The header-field exemption was also too wide. "**Date:** 2026-09-03, Channel
resolved 2026-09-22" smuggled a dated status into the one line the rules did
not read; the exemption is now a Date holding only a date and a Status holding
only one of the three.
2026-09-22 00:38:35 +10:00

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