[bug] Declare the actual shell dialect in Agent exec capabilities

[zerob13]

Summary

The Agent system prompt reports the operating-system platform, but the exec tool contract only says “shell command” and does not identify the actual shell dialect selected by the runtime. On Windows this encourages otherwise capable models to emit POSIX commands that fail and trigger avoidable retries or permission prompts.

Priority: P2 harness/tool UX

Observed behavior

During a sanitized Windows Agent tool run, the model attempted Unix-style shell syntax before adapting to PowerShell. The resulting failures were not provider transport failures; they came from an ambiguous tool capability description.

Code evidence

• src/main/agent/deepchat/resources/systemEnvPromptBuilder.ts emits a generic Platform: win32 fact.
• The exec argument schema in src/main/tool/agentTools/agentToolManager.ts describes command as “The shell command to execute.”
• The tool definition says it executes a shell command but does not name PowerShell, cmd.exe, Bash, or the dynamically resolved shell.
• src/main/tool/agentTools/agentBashHandler.ts resolves and prepares the actual shell at execution time.

The nearest instruction to the model is the tool definition, and it lacks the dialect needed to construct a valid command.

Related contracts and documentation

• docs/architecture/tool-system.md makes the Tool catalog and source mapping authoritative for model-visible capabilities.
• docs/architecture/deepchat-agent-harness-boundaries/spec.md argues that execution safety/capability should be catalog-owned rather than inferred from tool names or conventions.
• Platform information in the system prompt is useful context, but it is not a substitute for a precise per-tool runtime contract.

Impact

• Commands fail before doing useful work.
• The Agent spends extra provider rounds correcting syntax.
• Failed compound commands can generate additional approval requests.
• Users experience slower and less reliable tool execution.
• Hardcoding “PowerShell” globally would be wrong when a configured or packaged runtime uses another shell.

Proposed direction

• Add a runtime-resolved shell capability to the model-visible exec tool description, for example shell name, platform, and a short dialect hint.
• Generate the description from the same shell resolver used by execution so prompt and runtime cannot drift.
• Keep the description content-free and do not expose user environment variables or executable search paths.
• Update the capability when the selected shell changes.

Acceptance criteria

• On Windows, the model-visible exec contract identifies the actual PowerShell/cmd dialect selected by runtime.
• POSIX systems identify their actual shell contract without assuming Bash when it is not used.
• No user-specific paths, environment values, or command history are exposed.
• Tool definition and execution use one resolved source of truth.
• Tests cover Windows, POSIX, configured shell changes, and missing-shell fallback.

User benefit

Models issue valid commands on the first attempt more often, reducing tool errors, retries, latency, and unnecessary permission interactions.