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