Files
archie/docs/prds/progressive-tool-disclosure.md
T
sam e832b8ef0c 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

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