[bug] A refused tool's own remedy is discarded and the agent invents "Settings → Connections" — reproduced 5/5, and the transcript truncates the real remedy away

[serge-ivo]

What the owner sees

A creator opens their own tmux Operator on the console's agent page and asks it to list tmux
sessions. The reply, verbatim from production today:

The tool came back with an error — no tmux instance is linked to this agent yet. To fix it, go to
Settings → Connections in the console and connect a tmux instance.

There is no such thing. No console screen links a tmux instance, on this page or any other, and the
action the agent describes cannot be performed. The one sentence on screen that is true — the
platform's own refusal — is cut off by the transcript four characters into the word that begins the
remedy, so the owner is left with an instruction that leads nowhere and no way to discover the real
one.

The real remedy was in the tool result the whole time: subscribe to the agent and chat with the
instance. The model was handed it in full, and replaced it.

Reproduced — 5/5, two agents, two connectors

Live POST /v1/agents/:id/chat against api.proagentstore.online, all on 2026-08-12, after the
deploy carrying the current refusal wording (156dfe2, 12:47 +1000; "Deploy API Worker" succeeded
on f79fb29 at 02:59:35Z).

when (UTC)	agent	prompt	reply
03:03:57	tmux-operator template 2dff5c62…	"List my tmux sessions now, using your tmux_list_sessions tool."	"…this agent isn't connected to a tmux instance yet. To fix this, go to the console, open Settings → Connections, and link a tmux instance."
03:11:03	same	"List my tmux sessions."	"…no tmux instance is linked to this agent yet. To fix it, go to Settings → Connections in the console and connect a tmux instance."
03:11:14	same	"What tmux sessions are running right now?"	"…go to Settings → Connections in the console and connect one."
03:11:19	same	same	"Head to Settings → Connections in the console to connect one…"
03:11:56	iterm-operator template d40dbdf6…, terminal connector, empty history	"Which terminal targets are open?"	"…head to the console's Settings → Connections and make sure this agent is running from a subscribed instance with the terminal connector properly bound."

The last row matters most: a different agent, a different connector, a conversation with zero
prior messages (GET /v1/agents/d40dbdf6…/messages returned {"messages":[]} immediately before),
and the same invention on the first turn. This is not one model getting stuck in a groove — it is
what this refusal produces.

(The 03:03:57 row is the original observation, made by a dev agent verifying #441. The other four
are mine.)

The refusal is correct, complete, and reaches the model whole

workers/api/src/lib/tool-registry.ts:614:

This agent's declared constraints for the ${connector} connector could not be resolved — this call names no subscribed instance for them to belong to — so "${name}" was refused rather than run unconstrained. A ceiling is resolved per instance (the creator's declaration, narrowed by that instance's own binding), so run this from a subscribed instance rather than from a template preview or trial chat.

405 characters, and the correct user action is the last clause of it.

Verified that the model gets all 405. agent-think.ts:1098 calls record(tc, toolResult.content, …);
record (:981-985) applies capToolResult, whose ceiling is TOOL_RESULT_MAX_CHARS = 24_000
(lib/tool-result-cap.ts:38) and which returns the input unchanged when it fits (:46-48). So this
is not a truncation bug on the model's copy. The model had the remedy and wrote a different one.

Verified that the refusal is the right answer here, not a bug to be fixed by making the call
succeed. lookupConnectorConstraints joins agent_instances only (lib/agent-capabilities.ts:590,
SQL at :598-602, if (!row) return { instance: "missing" } at :608). The agent-template chat
surface passes an agent id (agent-think.ts:1045 / :1062, instanceId: state.agentId), and an
instance DO's state.agentId is the instance id (routes/instances.ts:215). So the identical
call from POST /v1/instances/:id/chat resolves and runs. Subscribe-then-chat is the whole remedy,
and #441's follow-up (156dfe2, docs/capability-constraints.md:153-175) deliberately decided this
surface stays refused. Nothing here asks to reopen that.

The remedy the agent gave is false in every reading of it

1. On the page the call came from. The reply was produced by the creator's agent page
   (store/console/src/pages/AgentDetail.tsx:233 posts to /v1/agents/:id/chat). Its tabs are
   Chat · Knowledge · Memory · Tasks · Settings · Analytics · Ops (:319-324), and grep -c Connection AgentDetail.tsx = 0 — its Settings tab has no Connections section at all.
2. The instance Settings tab does render "Permissions & Connections"
   (store/console/src/tabs/SettingsTab.tsx:539), so the label exists — but what it offers is
   ToolPermissions (tool switches, connector write-consent, MCP grants), Drive/WorkDrive folder
   grants, and a Gmail inbox checkbox. No control links, connects, binds or names a tmux instance.
3. Preferences → Connections exists too (pages/Preferences.tsx:160 → components/AccountConnections.tsx:126)
   and tmux is structurally excluded from it: lib/connectors/registry.ts:61 declares tmux
   auth: "none", routes/connectors.ts:134 reports connected: holdsCredential ? !!row : null,
   and lib/accountConnections.ts:52 filters on e.connected !== null. There is a test pinning
   exactly this — lib/accountConnections.test.ts:35: accountConnections([entry({ id: "tmux", connected: null })]) → [].

And the one genuine Settings control in this area was never in play: tmux_list_sessions is
scope: "read" (lib/connectors/tmux.ts:36-39), so the write-consent toggle could not have applied.

So the earlier framing "a console path that does not exist" was slightly too strong about the
label and exactly right about the action. The label exists in two places; the action exists
nowhere; and on the page where it was said, the section does not exist either.

Why #493 step 1 does not cover this

TOOL_LIST_CLOSED (lib/connector-tool-prompt.ts:131-139, shipped 4031cbe) already contains the
right sentence:

"…do NOT send the owner to Settings for it, because this toolset is fixed by the agent's
definition and is not a switch they can flip."

But its stated trigger is "A system that is NOT on it". Here the system is on the list, the
tool exists, was offered, and was called — so the model is not violating that sentence, it is
outside it. The prohibition was written for the absent-tool case and this is the refused-tool case.
Confirmed empirically: every reproduction above ran against a deployment that already carries
TOOL_LIST_CLOSED.

Same class as #493, different door.

One thing the transcript makes worse (verified, cheap)

agent-think.ts:1095-1096 caps the displayed tool log at 120 characters:

const shortContent = toolResult.content.slice(0, 120);
allToolLog.push(`${icon} **${tc.name}** ${shortContent}`);

That string is persisted as a system message and rendered as a pill (AgentDetail.tsx:355). For
this refusal, 120 characters ends at:

This agent's declared constraints for the tmux connector could not be resolved — this call names no subscribed instance

…and for the terminal variant it cuts mid-word at …names no subscribed insta. The entire
remedy clause is off-screen. So the owner sees a wrong remedy from the agent and cannot read the
right one anywhere in the UI. This is a display cap, unrelated to the model's copy (#442 noted the
same 120 chars as a resumability limit; the display side was never the subject).

What to do — cheapest first

Step 1 — show a FAILED tool result in full (one line). At agent-think.ts:1095, cap on
toolResult.success: successes keep 120 (they are data), failures get ~600. Every refusal
runRegistryTool can emit is a short, platform-authored sentence written for a human; the only long
failure is the passthrough at tool-registry.ts:650 (Error: ${err.message}), which 600 bounds.
This does not stop the invention; it puts the true remedy on screen beside it, which is the
difference between a stuck user and a user who acts.

Step 2 — close the second half of the sentence that is already there. Extend TOOL_LIST_CLOSED
(or add a sibling constant in the same pure module, which already has a test file) to cover a tool
the agent does hold that was refused: the refusal text is the whole account of why and what to
do, restate it, and never name a console location, tab, section or setting that the refusal did not
name. This is the same device #493 step 1 used, pointed at the case it left open.

Step 3 — the structural one, and the only one that makes it impossible (owner's call). On a
surface where ctx.instanceId is an agent id, every tool of a connector in CONNECTOR_CONSTRAINTS
will be refused, always, by decision. Withholding exactly those tools there — scoped to
CONNECTOR_CONSTRAINTS keys, so every other agent and every unconstrained connector is byte-identical —
plus one true sentence in the prompt ("you are being previewed from the agent template; your tmux
tools run only from a subscribed instance") leaves the model with nothing to explain and nothing to
invent. resolveAgentCapabilities already knows which of the two joins matched, so the surface is
derivable rather than guessed — the same shape #441 used when it split ConnectorConstraintLookup.

I would ship steps 1 and 2 now and take step 3 if the answer to the open question below is "no".

Also verified, and probably the seed of the invention (split this out if you prefer)

On this surface the model is told about the wrong console. agent-think.ts:421 injects
selfDescriptionPrompt unconditionally, and lib/agent-self-description.ts:304-307 emits:

"Your console has exactly these tabs: … NEVER refer the user to any other tab — if a tab is not in
that list, it does not exist for you, and sending them there is a wrong answer."

tabsFor (:120-143) computes that from capabilities.surfaces, i.e. the instance console. For
tmux-operator (surfaces:["tmux"], no KB or collection tools) it yields Assistant · Board ·
Terminal · Activity · Stats · Knowledge · Behaviour · Settings. The creator is on AgentDetail, whose
tabs are Chat · Knowledge · Memory · Tasks · Settings · Analytics · Ops. Six of the eight tabs the
model is told it "exactly" has do not exist on the page it is speaking from, and five of the seven
that do exist are ones it is forbidden to name.

Inferred, not measured: "Settings" survives that mismatch as one of the only two overlapping names,
and it is the single navigation word the prompt explicitly authorises — so it is the most
authorised-looking sentence available when the model decides to give a remedy. I did not dump the
assembled prompt (no endpoint returns it), so the causal half is reasoning; the mismatch itself is
verified above. It is a live instance of the #315 class the file's own comment describes.

Alternatives considered and rejected

• Give lookupConnectorConstraints the same agents-row fallback resolveAgentCapabilities has,
  so the call succeeds. Rejected — decided against in 156dfe2 and written down at
  docs/capability-constraints.md:153-175: the permissive resolver may fall back, the boundary may
  not, or a ceiling's applicability starts depending on which kind of id a caller passed. Do not
  relitigate; this ticket is about what the agent says, not about what the gate does.
• Reword the refusal. Rejected — it already carries the correct remedy as its final clause, and
  156dfe2 rewrote it for exactly this reason six hours before the reproduction. The gap is that
  nothing requires the model to relay it.
• Audit the reply for console paths against the tab enumeration (tabsFor is already the closed
  vocabulary, and honestReply/auditReply in lib/invented-results.ts:281-303 already has the
  catch-correct-disclose machinery). Rejected as the fix because it would not catch this one:
  "Settings" is a legal tab, the invented part is the section under it, and no enumeration of
  sections exists anywhere to check against. Worth revisiting only if someone builds that
  enumeration.
• Fix it in the tmux-operator seed personality. Rejected — reproduced on iterm-operator too,
  and seed personality edits do not reach existing instances ([bug] A seed personality fix never reaches existing instances — #483's CLI protocol is in the agents row and in neither live tmux Operator #496).

Acceptance criteria

• POST /v1/agents/<a constrained-connector agent>/chat asking for a connector action produces a
  reply that either restates the refusal's own remedy (subscribe, then chat with the instance) or
  says it cannot do it here — and names no console location the refusal did not name. Check it
  on a fresh conversation, twice, on both tmux-operator and iterm-operator.
• The system pill in the transcript shows the refusal's final clause, not a cut at 120 characters.
• A unit test in the pure prompt module asserts the new clause is emitted (the module has one).
• No change to any successful tool call's transcript, and no change for an agent whose connectors are
  not in CONNECTOR_CONSTRAINTS (today: everything except terminal and tmux).

Regression risk

• Step 1 widens what a system pill can contain. A failure whose text is an upstream error body
  (tool-registry.ts:650) is now up to 600 chars in the transcript; renderMd does not run on
  system messages (AgentDetail.tsx:356-358 renders markdown for assistant messages only), so this is length, not markup.
• Step 2 is another absolute in a prompt that already carries several. It must not read as "never
  mention Settings" — TmuxTab.tsx:448 legitimately tells a user to grant kill access in Settings,
  and a write-consent refusal genuinely is fixed there. Scope the clause to "a location the
  refusal did not name" so a refusal that names Settings can still be relayed.
• Step 3 removes tools from a creator's trial chat. Everything it removes is already
  unconditionally refused, so nothing that works stops working — but a creator loses the ability to
  see the tool listed at all, which is a visible change to the preview.

Open question for the owner

Should a creator's template chat offer tools it can never run? Today it does, and the whole failure
lives in explaining why they failed. My view: no — a control wired to a guaranteed refusal is worse
than an absent one, and step 3 is the version of this fix that cannot regress into a different false
statement. But that changes what the trial chat looks like, so it is your call and not mine.

Evidence

Verified: the five live calls above (bodies quoted verbatim); the refusal string and its 405-char
length; the 24,000-char model-side cap vs the 120-char display cap and exactly where 120 lands; the
instance-only join and the agent-vs-instance id; all three "Connections" surfaces and tmux's
structural exclusion from the account one (with its test); TOOL_LIST_CLOSED's wording and its
trigger; the tab-list mismatch. Inferred and labelled: why the model reaches for "Settings", which
would need the assembled prompt to prove.

Not reproduced: whether the same invention occurs on the public trial-chat surface
(/v1/public/agents/:id/try), which takes the same path. I did not test it.

[serge-ivo]

Steps 1 and 2 shipped in 13750d2 (CI green, "Deploy API Worker" success 03:32:05Z). Step 3 not
taken — it is your call and the measurement below is the thing that decides it. Leaving this open.

What shipped

Step 1 — the pill. toolLogLine in lib/tool-result-cap.ts (beside the model-side cap it is
deliberately not), caps on success: a success keeps 120 and is byte-identical, ellipsis included;
a failure gets 600 and marks its cut. agent-think.ts is one call instead of three lines, so
the file is unchanged against its pin.

Step 2 — TOOL_REFUSAL_RELAY, a sibling constant in lib/connector-tool-prompt.ts, injected
last in the CONNECTED TOOLS block because it is the rule that narrows the other two: relay the
refusal's own reason and remedy, and name no console page, tab, section or switch the refusal did
not name. Scoped to "a location the refusal did not name", not to the string "Settings", per your
regression note. 8 new tests there, 5 in tool-result-cap.test.ts.

One correction to the issue — the invention had a verified source, not just an inferred one

Your split-out finding (the tabsFor mismatch) is not where "Settings → Connections" comes
from. The phrase is in the prompt verbatim, three lines above the tool list:

• agent-think.ts:641 reads consents with listConsents(env, state.agentId), and consent rows are
  keyed by instance id (connector-consent.ts:42, WHERE instance_id = ?1), so on the
  agent-template surface it returns [].
• writeConsentOf (instance-tool-policy.ts:100-102) therefore returns "required" for every
  write tool, so all five of tmux-operator's writes render [write — consent NOT granted: …].
• CONSENT_RULE (connector-tool-prompt.ts:82-89) then instructs: "point the owner to the console
  → Settings → Connections".

Asked to explain a refusal of the read tool, the model reached for the nearest remedy its own
prompt had already licensed. That is why the new clause ends by scoping the consent remedy to a
consent refusal — a prohibition alone would have left the same gap to fill.

Live verification — 14 turns on production after the deploy

The pill: 14/14 fixed. Every one now carries the full 405-char refusal ending in
…run this from a subscribed instance rather than from a template preview or trial chat.
(430–440 chars including the icon and tool name.)

The reply: improved, not closed. 4 of 14 still name a console location.

agent	history state	turns	named a false location
kitty-operator	no leaked reply in history	2	0
terminal-operator	no leaked reply in history	2	0
tmux-operator	carries 5 pre-fix leaked replies	5	2
iterm-operator	carries the pre-fix leaked reply	5	2

Against 5/5 before. A clean turn now reads: "The tool was refused because this agent needs to be
opened from a subscribed instance, not a template preview or trial chat." A leaking one still
restates the true remedy and appends the false one: "…Head to the console Settings →
Connections to set that up."

Measured association, not proven causation: every post-fix leak was on one of the two agents
whose stored history already contains a pre-fix reply saying "go to Settings → Connections", and
GET /v1/agents/2dff5c62…/messages shows those 30 messages are still there. Both agents that had
never produced one are 4/4 clean, first turn and second. n=14, and there is no
DELETE /v1/agents/:id/messages on this surface, so I could not run the controlled version. If it
holds, the residual is the #406 shape — a false statement written before the guard shipped, read
back and restated — and it decays as conversations turn over, but not from an agent already
carrying one.

So: your acceptance criterion 1 is NOT met, and this is the evidence for your open question

You wrote you would take step 3 if the answer to "should a creator's template chat offer tools it
can never run" is no. A prompt clause moved 5/5 to 4/14 and cannot get to 0 — which is the
difference your own framing draws between "less likely" and "impossible". My recommendation is
yes to step 3, on your reasoning rather than mine: on that surface every tool of a connector in
CONNECTOR_CONSTRAINTS is refused by decision, so withholding exactly those (scoped to those keys,
every other agent byte-identical) removes nothing that works and leaves nothing to explain. It is
about half a day with tests. Say the word and I will do it under this issue.

Two things I deliberately did not do:

• The selfDescriptionPrompt tab mismatch. Real defect — a template-surface model is told it
  "exactly" has the instance console's eight tabs, six of which do not exist on AgentDetail — but
  demoted from "probably the seed of the invention" by the finding above, and it wants its own
  ticket rather than a fix by accident.
• The public trial-chat surface (/v1/public/agents/:id/try) — still unprobed, as you recorded.

Not run: pnpm test:e2e (no store/, agents/coder/web or fixture change). Everything else in the
bar was run before the commit and again after fetching origin/main.

[serge-ivo]

Step 3 shipped in 7629d24 — owner's go-ahead on the open question. CI green, "Deploy API Worker"
success 03:49:27Z. 10/10 clean in production, including on both agents that were still leaking
after step 2.

What it does

resolveAgentCapabilities (agent-think.ts) now returns which of its two joins matched instead
of discarding it. The second join is the agent-template surface, and on it every tool of a
connector in CONNECTOR_CONSTRAINTS is refused by decision (#441,
docs/capability-constraints.md), so those tools are withheld there rather than offered and
then explained.

The lever is the one my root-cause finding pointed at: listConsents is keyed by instance id and
returns nothing on that surface, so every write tool rendered [write — consent NOT granted …] and
CONSENT_RULE three lines above instructed the model to point the owner at
console → Settings → Connections. With the tools gone, a tmux-only agent's CONNECTED TOOLS block is
empty — no labels, no Settings → Connections anywhere in the prompt, nothing to reach for.
A unit test asserts that emptiness directly, which is the "impossible rather than less likely" part.

Everything pure is in lib/template-preview-tools.ts — the filter, the sentence that replaces what
was withheld, and the trap: toolNamesFor treats an empty tools array exactly like an absent one
and resolves FULL, so a naive filter would have handed the tmux Operator every knowledge, file
and collection tool on the platform. It gets BASE explicitly instead.

One true sentence replaces the tools, because withholding in silence leaves the same vacuum the
invention grew in: previewed from the template · these tools resolve per subscribed instance · this
is not a setting or a connection anyone can switch on · there is no console page for it.

Byte-identical for everyone else, asserted not inspected: the capabilities object is returned
by reference when nothing is withheld, and a test walks every registry connector and pins the
affected set equal to Object.keys(CONNECTOR_CONSTRAINTS) — so a connector that gains a ceiling
later is covered without a second list to keep in step. agent-think.ts pin raised 1172 → 1180 with
its reason; the ratchet's own self-pin with it.

Live, after the deploy

agent	history	turns	named a false location
tmux-operator	5 pre-fix + 5 post-step-2 leaked replies	3	0
iterm-operator	pre-fix + post-step-2 leaked replies	3	0
kitty-operator	clean	2	0
terminal-operator	clean	2	0

5/5 leaking → 4/14 (step 2) → 0/10. Stored history is not re-teaching it: the two contaminated
agents are clean on new turns, which is the outcome that decides between this fix and a
history-redaction one.

The reply now reads: "I'm not able to list your tmux sessions from here because this is a template
preview, not a subscribed instance. To use this agent's tmux tools, you'll need to subscribe to and
run it from a full instance." — and no tool is called at all, so there is no refusal left to
paraphrase.

Nothing that worked stopped working, checked live: the subscribed instance
1a8486b5-… ran tmux_list_sessions and came back with its two real sessions (0 and
heartfull-tmux), pill ✅ and all.

Acceptance criteria

• ✅ Reply names no console location the refusal did not name — 10/10, twice each on both named
  agents plus the other two Operators.
• ✅ The pill shows the refusal's final clause, not a cut at 120 (step 1, 14/14; still the behaviour
  wherever a constrained refusal can still occur, e.g. from an instance whose lookup fails).
• ✅ Unit tests in the pure prompt module (8) plus the new module (11) and the cap (5).
• ✅ No change to a successful tool call's transcript; no change for an unconstrained connector —
  asserted by reference equality and confirmed live on a subscribed instance.

What is still not verified

• The public trial surface (/v1/public/agents/:id/try). Structurally it is the same path — the
  agent DO, so the same second join — but I could not exercise it end to end: it returns
  "Add an API key in Profile → API Keys" before reaching the model, so the recorded
  non-reproduction stands rather than becoming a verification.
• The tabsFor mismatch — untouched, as agreed, and being filed separately.

Closing.