Explain why a previous SAGE command failed. Use after a non-zero command exit before editing code or retrying. Input is an optional SAGE run id; when omitted, the most recent failed run is analyzed. Returns a structured object with error_type, summary, root_cause, affected_files, and suggestions. Read-only: does not run commands, edit files, or contact external services.

Suggest safe next steps for a failed SAGE command. Use after sage_explain_error when you want possible fixes but do not want them executed automatically. Returns a list of fix suggestions with explanation, confidence, and candidate command when available. Read-only: it never applies patches and never runs the suggested command.

Run one focused local SAGE specialist for a bounded development task. Use only when a task clearly matches one specialization: code, test, debug, security, or performance. Returns agent_type, task, status, and a compact result. Side effects depend on the task: the specialist may inspect files, run local commands through SAGE, or propose edits. Do not use for open-ended chat, secrets, credentials, or tasks requiring external account access.

Run a named local workflow through SAGE, such as test, lint, build, or ci. Use when the project has a repeatable workflow and you want one structured result instead of several separate shell calls. The workflow must be local/project-defined. Returns success, per-step status, duration, and compact output. Side effects: runs the workflow's local commands and may change files if the workflow commands do. Do not use for deployment unless the user explicitly requested deployment.

List recent local SAGE command runs. Use to find a run_id for sage_show_raw, sage_explain_error, or sage_suggest_fix. Returns compact metadata such as run_id, command summary, exit_code, duration, timestamp, and compression ratio. Read-only: reads the local SAGE database only and does not execute commands.

Read a file with SAGE compression: small files exact, large files as outline + head with line references. Prefer this over cat/type/Get-Content to save context.

Search files with compressed, grouped results (exact paths and line numbers kept). Prefer this over rg/grep when output may be large.

Run one local shell command through SAGE with a purpose label. Use when you need command execution and want the result categorized as read, search, test, build, deploy, audit, or unknown. Returns exit_code, compact output, run_id, purpose, and agent metadata. Side effects are exactly the side effects of the command itself. Do not use for secrets, credential prompts, or deployment unless explicitly requested.

Recover the exact stored output of a previous run by ID (compression never destroys the original).

Create or update a file. Returns bytes/lines/sha256 confirmation instead of echoing the content back — saves the whole file's tokens. Existing files require overwrite=true (a snapshot is taken first so it is reversible).

Exact string replacement in a file. Returns a compact change preview instead of the whole file, and snapshots the pre-edit content for undo. old must match exactly and be unique unless replace_all=true.

Find files by pattern, newest first, junk directories ignored, capped output. Prefer over recursive directory listings.

Compact depth-limited directory overview instead of ls -R noise.

Run one local command with SAGE's failure-recovery loop. Use for development commands where automatic diagnosis and retry may help, such as tests or builds. Autonomy controls behavior: suggest reports fixes only, ask requires confirmation, auto may apply safe fixes and retry. Returns command result, recovery attempts, and verification status. Do not use for destructive commands, credential entry, production deploys, or external account changes.

Return the single best fix candidate for a failed SAGE command. Use when you need one actionable repair plan, not a list of alternatives. Input is an optional SAGE run id; when omitted, the most recent failed run is analyzed. Returns fix_command, strategy, confidence, and explanation, or null when no safe fix is known. Read-only: does not execute the fix and does not edit files.

Get the current agentic session state — failure streak, recent errors, intent chain. Useful for understanding context before deciding next action.