[mostafa-binesh]

Summary

Fixes #4971.

OpenCode builds its shell tool description from process.platform:

// packages/core/src/tool/plugin/shell.ts:28-46
const OS = process.platform === "darwin" ? "macOS"
  : process.platform === "win32" ? "Windows"
  : process.platform === "linux" ? "Linux" : process.platform
const description = (shell) => [
  "Execute a shell command and return its output.",
  ...(shell ? [`Commands run on ${OS} using ${shell}.`] : []),
  "Quote file paths containing spaces or special characters.", ...
].join(" ")

The fingerprint in open-sse/utils/opencodeFingerprint.js is a frozen capture of the Linux CLI (Commands run on Linux using bash.) and isFingerprintDefinition() compares with ===. So a caller shell from any non-Linux client never matches, and the pass treats a platform wording difference as a conflicting tool: it renames shell to shell_client, appends a placeholder, and injects "do not call the `shell` tool…" into the system prompt.

And because the alias is numbered off the caller's own names (taken), a client that already declares shell_client/shell_client2 pushes the alias to shell_client3 — four shell-ish names on the wire for one real tool, and a call to the advertised name can arrive at the client as a tool it does not have.

Change

concealFingerprintToolNames() now tries in-place normalization before falling back to the alias:

• Compatible arguments (every caller parameter is a fingerprint parameter, and every required fingerprint parameter is declared) → replace description + parameters with the fingerprint's and keep the caller's name.
• Different arguments → the alias + response-side restore path is untouched.

read still passes through untouched on every platform, and so does shell on Linux: both are byte-identical, so nothing is rewritten.

The guard is deliberately name-level. Overwriting parameters unconditionally would silently drop arguments the caller's handler expects — which is the reason the alias path exists at all:

function canNormalizeInPlace(tool, key) {
  const props = (chatFunctionOf(tool) || tool)?.parameters?.properties;
  if (!props || typeof props !== "object" || Array.isArray(props)) return false;
  const wanted = Object.keys(FINGERPRINT_TOOL_DEFINITIONS[key].parameters.properties || {});
  const declared = Object.keys(props);
  if (declared.some((name) => !wanted.includes(name))) return false;
  return FINGERPRINT_TOOL_DEFINITIONS[key].parameters.required.every((name) => declared.includes(name));
}

Result

For a real OpenCode client the wire is exactly what the gate asks for:

caller tools	before	after
read (exact), shell (Windows/pwsh)	read, shell_client, shell + placeholder note	read, shell — no alias, no map, no note
read, shell, shell_client, shell_client2	read, shell_client3, shell_client, shell_client2, shell	read, shell, shell_client, shell_client2
caller shell declaring only {cmd}	shell_client, read, shell + note	unchanged (schema differs)

The placeholder note is not dead code: it still fires whenever a fingerprint name is genuinely absent and has to be appended.

Tests

Adds an opencodeFingerprint — in-place normalization block covering:

• in-place adoption for both the flat ({name}) and nested ({function:{name}}) shapes
• a real OpenCode tool set collapsing to exactly read, shell
• the plugin alias collision (no shell_client3 fabricated)
• three schema-incompatible shapes that must still conceal and still emit the note

All pre-existing assertions in tests/unit/opencode-fingerprint.test.js and tests/unit/opencode-free-tool-choice.test.js are unaffected — every existing aliasing case uses a tool with no parameters at all, which the compatibility guard rejects by design.

npx vitest run unit/opencode-fingerprint.test.js unit/opencode-free-tool-choice.test.js

Security notes

• No new data enters the request: the pass only rewrites string fields already on the wire. The parameter guard reduces how much of a caller's schema can be replaced (previously any conflicting tool was renamed wholesale).
• No auth, credential, header, or URL handling is touched; the alias map stays request-local in the existing WeakMap.
• The in-place branch reuses the frozen FINGERPRINT_TOOL_DEFINITIONS object references exactly as appendMissingFingerprintTools() already does — no new mutation surface is introduced.
• Behaviour for genuinely conflicting schemas is unchanged, so this cannot widen what a caller reaches upstream.

Docs

docs/ARCHITECTURE.md gains a Known Architectural Notes entry describing the pass and the frozen-capture platform caveat.

[luqman-v1]

LGTM: normalizes colliding OpenCode fingerprint tool definitions in place when arguments match, avoiding unnecessary tool aliasing. Clean unit tests.

[decolua]

Thanks @mostafa-binesh for the careful write-up — merged into master. 🙏

One thing worth flagging for the record: this had to be merged manually. The PR base is 87a74e1 (v0.5.104) and ce060c79b has since rewritten the same file to add the CLI <env> marker and the Claude /messages shape, so a plain cherry-pick conflicted. I resolved it by keeping all of master's newer work and layering your in-place normalization on top. One assertion in your suite expected body.instructions to be undefined; on current master the env marker always rides along on that field, so I widened it to check both halves.

Also noted in the commit message, as reviewers should know: normalizing in place replaces the caller's own shell description with OpenCode's, so safety instructions a client embeds there no longer reach the model, and a caller that declares a subset of the parameters gets its schema widened on the wire. Both follow from the upstream gate, and a tool declaring an unknown property still takes the alias path.

This supersedes #5157 (closed), which fixed only the powershell wording and left pwsh and macOS renamed.