ADFA-6339 | Let the agent run, read and stop shell commands in the Terminal

[jatezzz]

Description

This PR allows the AI agent to execute shell commands directly within the IDE's visible Terminal rather than making the user manually run them. It introduces three new tools: run_shell_command, read_terminal_command, and stop_terminal_command. Running or stopping a command always asks the user first, with no Always Allow. The dialog shows the full uncut command and its working directory, with hidden characters spelled out. The agent gets back the exit code and up to 8000 characters of terminal output. A command still running after 30 seconds, such as a server, is left running, and the agent can check on it later by its command id.

Details

• run_shell_command: Runs a command or script with bash in the Terminal. The working directory must be inside the project. Any exit code is returned as a result, not a failure, since grep exits 1 when nothing matches. A command still running after 30 seconds is reported as not exited yet, not as succeeded. The agent checks whether it is waiting for input and, if so, tells the user to answer it in that session.
• read_terminal_command: Reads the state, exit code and latest output of a command the agent started, by command id. It needs no approval. The progress guard treats a poll whose output changed as progress.
• stop_terminal_command: Stops a command the agent started with Ctrl-C. It asks every time, and the dialog shows the command being stopped and its Terminal session.
• Approval dialog: ApprovalPreview (SHELL_COMMAND, STOP_COMMAND) chooses how arguments are shown. Control, bidi and zero-width characters appear as <U+XXXX> with a warning, and each command line is forced left to right. Shell approvals have their own Run Now tooltip.
• run_shell_command marks the project as changed, so earlier file reads count as new again.
• Tool names are resolved once in AgentLoop, so a loosely named call still gets the shell output limit.
• HostServiceCall holds the host-service lookup and error handling shared by the shell and Gradle tools.

Screen_Recording_20261007_161740_Code.on.the.Go.mp4

Ticket

ADFA-6339

Observation

The new shell tools are only registered and offered to the AI if the host provides IdeTerminalService. Older IDE versions work as before, without these tools.

Depends on (both merged):

• ADFA-6385 | Reuse plugin terminal sessions and track running commands CodeOnTheGo#2113
• ADFA-6337 | Add run_gradle_task tool for AI agent #123

libs/plugin-api.jar on main predates IdeTerminalService. CI builds with --ref stage, but a local build-plugins.sh without --ref won't compile AI-Core until Update libs runs.

[Daniel-ADFA]

Reviewed at 454fc25. Findings were checked against this code and against the host API merged to CodeOnTheGo stage in #2113.

IMPORTANT

• RunShellCommandHandler.kt:88 - a command waiting for input is reported as succeeded

MINOR

• ApprovalTextFormatter.kt:72 - a line starting with an RTL letter is shown reordered
• RunShellCommandHandler.kt:117 - every NotStarted says retrying will not help
• StopTerminalCommandHandler.kt:17 - the stop approval shows only the command id
• ToolResultsPrompt.kt:84 - the shell output cap is keyed by the emitted tool name
• PR description is out of date (below)

Findings without a diff anchor

MINOR: The PR description no longer matches the code. It names read_terminal_session and stop_terminal_session, but the tools are read_terminal_command and stop_terminal_command. It says they work "without needing new user approvals", but stop_terminal_command asks every time. It mentions ApprovalKind, which this PR no longer has. QA working from the description will look for tools that do not exist.

Note: libs/plugin-api.jar on main predates IdeTerminalService. CI builds with --ref stage, which has it since #2113 merged today, but a local build-plugins.sh without --ref will not compile AI-Core until Update libs runs.

Previous rounds

All 13 earlier findings are fixed at head:

• non-zero exit reported as failure: resultFor succeeds for any exit code
• read tool missing from LIVE_READS: read_terminal_command is in it
• mutatesProject: true, with empty trackedPathArgs so a shell run invalidates every read
• cd/export not carrying over: stated in the tool description
• Read/Stop duplication: TerminalCommandHandler
• ai-core.html "no network access": now names network.access for fetch_url
• recap dropped after a thinking-only prose turn: showsAnswer
• identical live re-reads counted as repeats: reset when the answer changed
• control and invisible characters in the approval: revealHidden (the RTL case above is what remains)
• Run Now tooltip: TOOLTIP_TAG_APPROVAL_RUN_COMMAND
• toolsRejectedBy keyed by URL only: Set<ServerModel>
• ApprovalKind duplicating ApprovalPreview: removed
• TerminalToolCall duplicating the build handlers: HostServiceCall

addons has no written approve/request-changes rule, so the default applied.

[Daniel-ADFA]

Requesting changes for the IMPORTANT finding in the review above (RunShellCommandHandler.kt:88): a command still running after 30 s is reported to the model as succeeded, including one waiting on a prompt. Reword the still-running note so it says only that the command has not exited, and have the model check for a waiting prompt. The MINOR findings and the stale PR description are worth fixing too, but they do not block.

[jatezzz]

@Daniel-ADFA Updated the PR description: it now names read_terminal_command / stop_terminal_command, says stop asks every time, and drops ApprovalKind.
It also notes that main's libs/plugin-api.jar predates IdeTerminalService until Update libs runs.