ssh_cmd_check_status
Wait a set duration, then check the status of a command started by ssh_cmd_run. Poll repeatedly until it returns a terminal state like completed or killed.
Instructions
Wait for the specified duration, then check the status of a command started with ssh_cmd_run. Call this repeatedly - it's designed to be polled - after ssh_cmd_run returns status='io_timeout' or 'wait_timeout' (the remote command is still genuinely running in both cases - background monitoring keeps collecting its output/exit code), until you get a TERMINAL status below. Do not rerun the original command while polling.
Terminal status values (nothing left to wait for, stop polling):
'completed': confirmed finished, exit_code is populated - including for commands that survived an io_timeout/wait_timeout, since background monitoring keeps watching for the real exit code.
'killed': the remote process was confirmed terminated (e.g. runtime_timeout killed it, or a prior ssh_cmd_kill call found it already gone) - exit_code is not known.
'completed_exit_code_unknown': rare fallback - monitoring stopped without a confirmed exit code (should only really happen from before background monitoring existed, or after an unexpected error) and a live check now confirms the remote process is no longer running. Only its output (via ssh_cmd_output) is available, not its exit code.
Non-terminal status values (keep polling):
'running': still being actively monitored, not yet finished.
'unknown_still_running': rare fallback (same caveat as 'completed_exit_code_unknown') where a live check confirms the remote command is still actually running. Not a failure - call this tool again to keep checking.
Other:
'not_found': the handle_id doesn't exist (may be from a previous connection - handles don't survive reconnects, but background task PIDs from ssh_task_launch do).
'unknown': the handle exists but its metadata is missing from history (rare, internal inconsistency) - treat like 'not_found'.
Fallback behavior: if handle_id doesn't match any ssh_cmd_run handle, this tool
also tries treating it as a raw background-task PID (same as ssh_task_status) and,
if that succeeds, returns {'pid', 'status': 'running'/'exited'/'invalid'/'error', 'is_background_task': True, ...} instead - a DIFFERENT status vocabulary than the
one above. Prefer ssh_task_status directly for PIDs to avoid ambiguity.
Returns:
{'handle_id', 'waited_seconds', 'status', 'exit_code', 'pid', 'output_available', 'output_lines', 'timestamp'}, plus 'next_step' (guidance
text) when status is non-terminal.
For an OPERATION handle (the handle_id of an 'in_progress' response from a
long-running tool such as ssh_archive_extract or ssh_file_transfer): returns
`{'handle_id', 'status', 'tool', 'operation', 'started', 'ended', ...}` with status
'running', 'completed' (plus 'result': the tool's full normal result) or 'failed'
(plus 'error'). The wait ends early as soon as the operation finishes. While
running it also returns 'elapsed_seconds' and 'progress': the current 'stage'
(e.g. 'uploading archive', 'extracting on host'), 'bytes_done'/'bytes_total'/
'percent' for transfers, counts such as 'files_searched', and 'last_update' /
'seconds_since_update' - if those stop advancing for a long time, the operation
may be stuck rather than just slow.Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| handle_id | Yes | Command handle ID to check status for - the 'id' returned by ssh_cmd_run, including in its io_timeout/wait_timeout response | |
| wait_seconds | No | Seconds to wait before checking. Clamped to the server's per-call wait cap (default 50s, since most MCP clients abort tool calls at ~60s) - the response's waited_seconds shows the wait actually applied. Short waits (1-10s) with repeated polling work best. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||