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.
128 lines
5.4 KiB
Markdown
128 lines
5.4 KiB
Markdown
# 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`).
|