docs(agent-tool): non-tool-calling models fail every send; no safe client-side fix - #2787

… support

OpenChamber injects its `openchamber` control tool into every managed OpenCode
process. Injection happens at process start, before any model is known, so the
tool is declared even when the selected model cannot call tools. Providers that
reject function calling outright then fail every send — Vertex Gemini image
models ("Nano Banana") return:

  Unable to submit request because the model does not support function calling

The model's own `tool_call: false` does not help: OpenCode assigns
`capabilities.toolcall` but never reads it to gate a request. Tools are filtered
only by permission name, and no built-in agent denies `openchamber`, so the
injected tool survives every stock agent. Today the only workaround is a
hand-written agent with a wildcard `permission: {"*": deny}`, which no ordinary
user discovers.

Shared UI now sends OpenCode's per-send `tools` map, derived from the selected
model's `capabilities.toolcall`.

Two constraints shape the contract, both verified against opencode 1.18.15:

- `tools` does not filter one request. OpenCode converts it into the session's
  permission ruleset and persists it, replacing whatever was there. A one-shot
  deny would strand the tool off for the rest of the session, so the complete
  desired map is sent on every send and model switches self-correct.
- When `agentControlToolEnabled` is false the tool was never injected, so no
  `tools` field is sent and session permissions are left untouched.

Unknown capability is treated as tool-capable: model metadata may not have
loaded yet, and defaulting to disabled would silently remove the tool from
models that support it.

The tool ID is now exported as `OPENCHAMBER_AGENT_TOOL_NAME` and interpolated
into the generated plugin, so the name the client gates and the name the plugin
registers cannot drift.

Verified end to end against a recording proxy with the real generated plugin
loaded: with the gate, `openchamber` is absent from the Vertex request's
`functionDeclarations`; sending the map with the tool enabled restores it in the
same session.

Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>

Review follow-ups to the per-send tool gate.

Behavior fix — the gate no longer consults `agentControlToolEnabled`. That
setting only takes effect on the next managed OpenCode restart, so between
toggling it off and restarting, the tool is still injected while the gate went
silent — reintroducing the provider rejection on exactly the configuration the
user believes is disabled, with no restart badge to hint at it. Naming a tool
that was never injected is inert (OpenCode filters the tools that exist and
matches rule names as literal wildcards), so sending the map unconditionally is
safe and keeps the gate honest when intent and process disagree. This also
resolves the contradiction with the module's documented runtime parity, where
VS Code and external OpenCode never receive the tool.

Documentation fix — the previous claim that `tools` "does not filter one
request" was wrong. It is stored on the user message and filters that request
(`session/llm/request.ts` `resolveTools` checks `user.tools?.[k] !== false`) and
it also replaces the persisted session ruleset. The operative guidance is
unchanged, but the load-bearing rationale was inaccurate.

Also documented, all verified against opencode 1.18.15:
- Ruleset replacement is wholesale, so OpenChamber assumes sole ownership of
  that slot; a rule set by another OpenCode client is discarded by the next send.
- Subagent sessions inherit `deny` rules from the parent, so a subagent spawned
  while an image model was selected starts without the control tool.
- Slash-command and shell routes accept no `tools` field at all, and a command's
  pinned model outranks the client's, so those paths stay ungated pending an
  upstream API change.
- Upstream marks `tools` `@deprecated`; the non-deprecated path merges instead of
  replacing and so could never flip a deny back to allow.

Tests — adds the missing call-site coverage. Deleting the `tools:` block from
`routeMessage` previously left every test passing; `agent-tool-gate-wiring.test.ts`
now fails without it, and covers the model-switch sequence that justifies sending
the complete map. Drops a tautological `Object.keys` assertion that could only
fail when a stronger assertion in the same file already had.

Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>

Adversarial review found the previous approach did not fix the reported bug.

Vertex rejects a request because it carries function declarations at all, not
because it carries `openchamber`. Denying one tool removed one declaration and
left the ~11 stock built-ins in place, so the send still failed. My own
end-to-end capture showed this and I misread it: I asserted `openchamber` was
absent from `functionDeclarations` and treated that as success, when the field
was still present with `bash, edit, glob, grep, question, read, skill, task,
todowrite, webfetch, write`. Agent `permission` config cannot close the gap
either — stock agents begin with `"*": "allow"`.

The gate now sends `{"*": false}` for models that cannot call tools, which drops
the `tools` field from the provider request entirely, and `{"*": true}`
otherwise. Verified by request capture against the real generated plugin: 0
declarations when denied, all 12 restored on the next send when allowed, in the
same session.

Because the gate now governs every tool rather than OpenChamber's own, it no
longer depends on whether this module injected anything, so it is correct in
runtimes where the control tool is absent. That also removes the cross-package
duplication of the tool name — `OPENCHAMBER_AGENT_TOOL_NAME` is now only used
inside the server module that owns the plugin.

Documented, all verified against opencode 1.18.15:
- This is a client-side mitigation for the paths OpenChamber controls, not a
  complete fix. Server-side dispatchers (scheduled tasks, goal continuations,
  obligatory context) post `prompt_async` directly and stay ungated, though they
  inherit whatever ruleset the last gated send persisted.
- The complete fix belongs upstream: OpenCode has `capabilities.toolcall` and
  never reads it in the request path.
- `session.update` does accept `permission` (contrary to my earlier claim), but
  it merges rather than replaces, so it could never flip a deny back to allow.
  The deprecated `tools` field is the only lever that self-corrects.

Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>

…annot work

Review found no safe client-side fix exists, so the gate is removed and the
findings are documented instead. What remains is the module doc plus an exported
tool-name constant used by the plugin generator.

The lever OpenCode exposes is the per-send `tools` map, which it converts into
the session permission ruleset and persists, replacing prior contents. Every
variant fails, each verified against opencode 1.18.15 by request capture:

- `{"openchamber": false}` — the original approach — removes one declaration
  while ~11 stock built-ins still reach the provider. Vertex rejects on the
  presence of any function declaration, so the send still fails. My earlier
  end-to-end check asserted only that `openchamber` was absent and I read that
  as success; the captured request still carried `tools` with 11 entries.
- `{"*": false}` does suppress the whole set (0 declarations, confirmed), but the
  deny persists: a later send on a tool-calling model in the same session also
  gets no tools.
- `{"*": true}` to recover is a privilege escalation, not a no-op. Permission
  rules are evaluated for approval as well as for tool filtering
  (`permission/index.ts` returns early on `action === "allow"`), so a wildcard
  allow converts an agent's `edit: deny` into `allow` and `bash: ask` into
  `allow`, suppressing the approval prompt. Confirmed by simulating the real
  evaluator against a restrictive agent. Suppressing tools must never widen
  permissions.
- `session.update` does accept `permission` (contrary to my earlier claim) but
  merges rather than replaces, so it cannot clear a deny either.

`session.command` and `session.shell` could not have been covered regardless —
the OpenCode API has no `tools` field on either route.

The fix belongs upstream, where the capability is already known: return no tools
when `!model.capabilities.toolcall`. That covers every send path for every client
with no permission side effects.

Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>

Points at anomalyco/opencode#41463 and issue #41464 so a future maintainer can
tell whether the constraint still applies, and notes that the section becomes
history once a release carrying the fix ships.

Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>

Image generation needs two OpenCode fixes, not one: the toolcall gate (#41463)
lets the request through, and a `case "file"` in SessionProcessor makes the
result visible. Fixing only the first yields a billed request whose image is
silently dropped.

Also records that OpenChamber needs no change to display generated images — the
receive path is type-agnostic — while flagging that the render leg is a code read
rather than an executed test, since there is no component-render harness.

Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>