aws-cli-agent 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -4,8 +4,206 @@ All notable changes to this project are documented here.
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
 versioning follows [SemVer](https://semver.org/).
 
-## [0.4.0] - 2026-05-17
+## [0.5.0] - 2026-05-19
 
 ### Added
 
-- Initial official release. Agentic AI assistant that turns natural-language requests into AWS CLI commands and runs them locally.
+- **Graceful error handling for AWS CLI failures.** AWS CLI exit codes
+  252–255 (parse error, missing credentials, client error, server error)
+  are now classified as fatal and abort the agent loop immediately rather
+  than being fed back to the model for retry. The user sees the AWS
+  stderr printed verbatim in red; the process exits 1. Other non-zero
+  exits remain soft failures — the model can decide whether to retry,
+  bounded by `maxSteps` as before.
+- **Ctrl-C handling.** Pressing Ctrl-C at any agent-driven prompt
+  (approval prompts, agent-asked questions, the bash script's
+  execute/save/cancel dialog) now exits cleanly with a "cancelled by
+  user" message on stderr and exit code 130 (SIGINT convention). No
+  stack trace, no red error, no "ran N commands" footer.
+- **SSM-session Ctrl-C silenced.** When you Ctrl-C to end an interactive
+  AWS CLI session (SSM Session Manager shells, port-forwards, etc.),
+  exit code 130 is treated as a clean termination instead of an error.
+  The audit log still records the real exit code for accuracy.
+- **`endReason` field on `RunResult`.** Internal API used by cli.ts to
+  pick the right exit code: `completed` (0), `cancelled` (130), or
+  `fatal` (1).
+
+### Changed
+
+- **The "ran N commands" footer is now verbose-only.** Previously printed
+  on every multi-command run; now requires `--verbose` / `-v` to surface.
+  With verbose off, nothing aca generates reaches the terminal — only
+  the AWS CLI's verbatim output does, matching the README's promise.
+
+## [0.4.0] - 2026-05-18
+
+### Changed
+
+- **Dependency upgrades.** Vercel AI SDK v4 → v6, zod v3 → v4, TypeScript
+  v5 → v6, ESLint v9 → v10, `@types/node` v22 → v25, and all `@ai-sdk/*`
+  provider packages to their v6-compatible majors (`@ai-sdk/anthropic`@3,
+  `@ai-sdk/openai`@3, `@ai-sdk/google`@3, `@ai-sdk/amazon-bedrock`@4).
+  Required code changes:
+  - `generateText({ maxSteps })` → `generateText({ stopWhen: stepCountIs(n) })`
+  - Tool definition field `parameters:` → `inputSchema:`
+  - Tool call payload `args` → `input`
+  - Usage fields `promptTokens` / `completionTokens` →
+    `inputTokens` / `outputTokens` (the data we write to `usage.log` keeps
+    the legacy names — they're a stable public interface, just remapped at
+    extraction time).
+  - `createOpenAI({ compatibility: 'strict' })` removed; the option no longer
+    exists.
+  - Zod v4 `.default({})` on object schemas now requires the fully-typed
+    default value; updated `LoggingSchema` and `autoApprove` defaults.
+  - Step events from `onStepFinish` dropped the `stepType` field; the debug
+    log now only mentions `finishReason`.
+
+### Fixed
+
+- **Interactive AWS CLI commands now work.** Previously, commands like
+  `aws ssm start-session` (interactive shells), port-forwarding sessions, and
+  log tails with `--follow` appeared to hang — the child process's stdout was
+  being captured into a string for the agent's context, and the child's stdin
+  was never connected to the user's terminal. Now the host detects common
+  interactive patterns and uses `stdio: 'inherit'` for those commands, so the
+  user's terminal connects directly to the AWS CLI subprocess.
+- **General log no longer echoes to the console.** Previously, the operational
+  `Logger` wrote both to `general.log` *and* to stderr at every level above
+  the threshold — meaning `--log-level debug` would spam debug lines into the
+  user's terminal. Now `Logger` is strictly file-only; the only things that
+  reach the console are (a) the AWS CLI's verbatim stdout, (b) approval
+  prompts, (c) error summaries, and (d) reasoning steps when `verbose` is
+  on. To watch operational logs live: `tail -f
+  ~/.local/state/aws-cli-agent/general.log`.
+
+### Added
+
+- **`--interactive` / `-i` CLI flag** to force every AWS CLI command in a run
+  to inherit the user's terminal. Useful as an escape hatch for commands not
+  in the auto-detect list (`ssm start-session`, `ssm start-session` with
+  port-forward documents, `ecs execute-command`, `logs tail --follow`).
+- **`interactive` parameter on `execute_aws_command` tool.** Lets the agent
+  explicitly mark a command as interactive when it knows the command needs
+  a TTY. For interactive runs, the agent receives a "do not summarize"
+  signal instead of stdout.
+- **Auto-approve never applies to interactive commands.** Handing your
+  terminal to a subprocess is a meaningful event; it always prompts.
+
+- **Prompt caching** for Anthropic and Bedrock providers (`caching: true` by
+  default). Marks the system prompt + tool definitions as cacheable; cache
+  reads cost ~10% of normal input tokens on these providers. OpenAI
+  auto-caches without our involvement; Google Gemini isn't supported yet.
+  Cache hit/miss tokens are recorded in `usage.log` as `cacheReadTokens` and
+  `cacheWriteTokens`. Typical cost reduction: ~60% off the input bill for
+  frequent users.
+- **Usage log** — `usage.log` (JSONL) records token totals per `aca`
+  invocation: timestamp, provider, model, steps, prompt/completion/total
+  tokens. Enable/disable via `logging.usageLog` (default `true`). Sum the
+  day's tokens with `cat usage.log | jq -s 'map(.totalTokens) | add'`.
+- **Interactive prompting** during the reasoning process. The `prompt_user`
+  tool now supports four question kinds: `text` (free-form), `choice` (pick
+  one from a finite list), `confirm` (yes/no), and `secret` (hidden input
+  for short secrets like MFA codes). New `prompt_user_multi` tool batches
+  several related questions into a single round so the agent doesn't need
+  multiple model round-trips to gather setup data.
+- **Sharpened system prompt** with explicit anti-guessing rules and worked
+  examples of when to ask vs. when to discover. The agent is much more
+  likely to stop and ask when it isn't certain rather than picking a
+  plausible answer and acting on it.
+
+## [0.3.0] - 2026-05-15
+
+### Changed
+
+- **Renamed** package from `ai-aws` to `aws-cli-agent`. Short CLI name is `aca`;
+  the long name `aws-cli-agent` works too. Install with
+  `npm install -g aws-cli-agent`.
+- **Restructured logging config.** Replaced top-level `logLevel`, `audit.enabled`,
+  and `reasoning.enabled` with a nested `logging` object:
+  ```json
+  "logging": { "level": "error", "auditLog": true, "reasoningLog": false }
+  ```
+  Defaults are now: level `error` (was `info`), audit on (unchanged), reasoning
+  log **off** (was on).
+- **Renamed general log file** from `ai-aws.log` to `general.log`.
+- **`--verbose` is now reasoning-only.** Previously also bumped log level to
+  debug; now controls only whether reasoning is echoed to the console. Use
+  `--log-level debug` separately if you want a noisier general log.
+- **Restructured Bedrock config** into a nested `bedrock` object:
+  ```json
+  "bedrock": { "region": "us-east-1", "profile": "shared-services" }
+  ```
+  Replaces the old top-level `bedrockRegion` / `bedrockProfile`.
+
+### Added
+
+- **`defaultRegion`** config and `--region` CLI flag. The configured region
+  is auto-appended as `--region` to every AWS CLI call the agent makes —
+  unless the agent itself specified a region, in which case its choice wins.
+- **Bash script "save to disk" option.** When the agent generates a script,
+  the user now sees a three-way prompt: Execute / Save to disk / Cancel.
+  The save path is shown inline so you know exactly where the file lands.
+  Folder is configurable via `scriptFolder`; default is
+  `$XDG_DATA_HOME/aws-cli-agent/scripts`.
+- **Two npm-installable binary names**: `aws-cli-agent` and `aca` (same binary).
+- **GitHub Actions CI** (lint, typecheck, build, smoke test on Node 20 & 22).
+- **GitHub Actions Release** workflow (publishes to npm on tag push or release
+  publication, with provenance attestation).
+- **Dependabot** config for npm and GitHub Actions.
+- **Smoke test** script (`npm test`) that exercises the basic CLI surface
+  without needing cloud credentials.
+
+### Removed
+
+- **`--quiet` / `-q` flag.** Use `--log-level error` (or `silent`) instead.
+- **Top-level config keys** `logLevel`, `audit`, `reasoning`, `bedrockRegion`,
+  `bedrockProfile`. See "Changed" above.
+- **`autoApprove` no longer applies to bash scripts.** Scripts always prompt
+  (Execute / Save / Cancel). The flag still skips approval for individual
+  AWS CLI calls.
+
+### Migration notes
+
+The old `ai-aws` config at `~/.config/ai-aws/config.json` is not read or
+migrated. Run `aca config` to write a fresh default at the new path. Translate
+old → new keys:
+
+| Old | New |
+|---|---|
+| `logLevel` | `logging.level` |
+| `audit.enabled` | `logging.auditLog` |
+| `reasoning.enabled` | `logging.reasoningLog` |
+| `bedrockRegion` | `bedrock.region` |
+| `bedrockProfile` | `bedrock.profile` |
+
+History at the old `~/.local/state/ai-aws/` location won't be picked up.
+If you want to keep it: `mv ~/.local/state/ai-aws ~/.local/state/aws-cli-agent`.
+
+## [0.2.0] - 2026-05-14
+
+### Added
+
+- Amazon Bedrock as a provider option via `@ai-sdk/amazon-bedrock`. Uses the
+  standard AWS credential chain; no API key required. Configurable via
+  optional `bedrockRegion` and `bedrockProfile` (since superseded by nested
+  `bedrock` in 0.3.0).
+- Audit log: append-only JSONL of every executed command/script with full
+  stdout/stderr/exit code. Bash scripts also log full source.
+- Reasoning log: text record of agent reasoning steps and tool calls.
+- ESLint 9 with flat config (`npm run lint`, `npm run lint:fix`).
+
+### Changed
+
+- Output policy: stdout is reserved for the verbatim AWS CLI output. The agent
+  cannot rewrite or summarize results. Pipe to `jq`, `wc`, etc. like you would
+  with the AWS CLI directly.
+- Moved `history.jsonl` from `$XDG_DATA_HOME` to `$XDG_STATE_HOME` alongside
+  the logs.
+
+## [0.1.0] - 2026-05-14
+
+### Added
+
+- Initial release. Agentic AWS CLI assistant with multi-step tool calling
+  (Vercel AI SDK), local-only state, XDG-compliant paths, configurable
+  providers (Anthropic / OpenAI / Google), per-command approval prompts.

package/README.md

@@ -33,6 +33,12 @@ The first example is interactive — the agent runs a read-only `describe-instan
 - **Audit log is your friend.** Every executed command — including its stdout, stderr, and exit code — lands in `audit.log` (JSONL). If you ever need to reconstruct what happened, it's all there. Don't disable `logging.auditLog` unless you have a specific reason.
 - **No warranty.** **You use this agent at your own risk.** The authors are not responsible for unintended AWS API calls, deleted resources, exceeded budgets, or any other damage caused by using this tool. If you wouldn't run `aws` commands blindly from a script you found in someone's gist, don't run `aca` blindly either.
 
+## Trademark & affiliation
+
+`aws-cli-agent` (`aca`) is an independent project, not affiliated with or
+endorsed by Amazon Web Services. "AWS" and "Amazon Web Services" are
+trademarks of Amazon.com, Inc.
+
 ## Installation
 
 ```bash
@@ -370,4 +376,4 @@ Without this rule, the approval prompts and reasoning lines would land in the ne
 
 ## License
 
-MIT
+MIT

package/dist/agent.d.ts

@@ -28,6 +28,18 @@ export type RunResult = {
     finalError: string | null;
     /** Did the last execute_* call run successfully? */
     ranCommand: boolean;
+    /**
+     * How the run ended. cli.ts uses this to pick the exit code and decide
+     * whether to print the AWS stderr as a red error:
+     *   - 'completed'  — normal end, model stopped on its own (exit 0)
+     *   - 'cancelled'  — Ctrl-C at a prompt; cli.ts prints "cancelled by
+     *                    user" on stderr and exits 130 (the canonical SIGINT
+     *                    exit code)
+     *   - 'fatal'      — AWS CLI returned an unrecoverable exit code
+     *                    (252-255); finalError carries the stderr, cli.ts
+     *                    prints it in red and exits 1
+     */
+    endReason: 'completed' | 'cancelled' | 'fatal';
 };
 export declare function runAgent(opts: {
     input: string;

package/dist/agent.js

@@ -1,6 +1,7 @@
 import { streamText, stepCountIs } from 'ai';
 import { createModel } from './providers.js';
 import { createTools } from './tools/index.js';
+import { FatalAwsCliError, UserCancelledError } from './errors.js';
 const SYSTEM_PROMPT = `You are aws-cli-agent (aca), an agentic assistant that translates natural-language requests into AWS CLI commands and executes them locally on the user's machine.
 
 Capabilities (via tools):
@@ -37,7 +38,8 @@ Operating rules:
 8. Interactive commands: some AWS CLI commands require a real terminal — SSM Session Manager shells (\`ssm start-session\`), port-forwarding sessions (the same command with --document-name AWS-StartPortForwardingSession*), ECS Exec (\`ecs execute-command\`), log tails with --follow. For these, set \`interactive: true\` on the execute_aws_command call. The host will connect the user's terminal directly to the command and you will receive no stdout — DO NOT try to summarize or describe the output afterwards, since you can't see it. Common patterns auto-detect, but setting the flag explicitly is safer.
 9. The final action of a successful run MUST be either execute_aws_command (the user-requested action) or execute_bash_script. If the user cancels via prompt_user, stop gracefully and explain in one sentence.
 10. NEVER include credentials, API keys, secrets, or session tokens in commands or scripts. AWS credentials come from the user's existing profile.
-11. Keep your reasoning concise — one or two sentences per step. DO NOT summarize, restate, reformat, or describe the output of the AWS CLI. The CLI's stdout is shown to the user directly by the host program. Your only post-execution job is to stop. If anything went wrong, say so briefly; if it succeeded, you may stop without further commentary.`;
+11. Handling AWS CLI errors: if execute_aws_command returns a result with \`ok: false\` (and a non-zero exitCode), you may retry ONCE with a different approach if it's clearly worth trying — wrong region, wrong profile, missing flag, fixable typo. Don't loop trying minor variations. The host caps total run length via maxSteps; respect it. Note: unrecoverable errors (auth failure, missing credentials, permission denied, malformed request, AWS service errors) terminate the run before you'd see them, so you don't need to handle those cases — they're handled for you.
+12. Keep your reasoning concise — one or two sentences per step. DO NOT summarize, restate, reformat, or describe the output of the AWS CLI. The CLI's stdout is shown to the user directly by the host program. Your only post-execution job is to stop. If anything went wrong, say so briefly; if it succeeded, you may stop without further commentary.`;
 export async function runAgent(opts) {
     const { input, config, logger, history, audit, reasoning, usage } = opts;
     const executions = [];
@@ -144,61 +146,159 @@ export async function runAgent(opts) {
     // Two execution sites collaborate to print one step:
     //   1. text-end (here) → reasoning text line
     //   2. onToolCallStart (callback above) → tool: line, then execute()
-    for await (const part of result.fullStream) {
-        switch (part.type) {
-            case 'start-step': {
-                stepCounter += 1;
-                toolCallStepNumber = stepCounter; // visible to onToolCallStart
-                currentReasoning = '';
-                currentToolCalls = [];
-                reasoningEchoed = false;
-                break;
-            }
-            case 'text-delta': {
-                currentReasoning += part.text;
-                break;
-            }
-            case 'text-end': {
-                if (!reasoningEchoed) {
-                    reasoning.echoReasoning(stepCounter, currentReasoning);
-                    reasoningEchoed = true;
+    // Terminal state for the run. The for-await loop transitions us out of
+    // 'completed' (the default) into 'cancelled' on Ctrl-C, or 'fatal' on
+    // an unrecoverable AWS CLI failure. cli.ts uses endReason to pick the
+    // exit code and the user-facing message.
+    let endReason = 'completed';
+    try {
+        for await (const part of result.fullStream) {
+            switch (part.type) {
+                case 'start-step': {
+                    stepCounter += 1;
+                    toolCallStepNumber = stepCounter; // visible to onToolCallStart
+                    currentReasoning = '';
+                    currentToolCalls = [];
+                    reasoningEchoed = false;
+                    break;
                 }
-                break;
-            }
-            case 'tool-call': {
-                // Backup echo path: if text-end didn't fire (provider variant or
-                // text-less step), echo whatever reasoning we have when we see
-                // tool-call. The tool-call LINE itself is NOT printed here — it's
-                // printed by experimental_onToolCallStart, which fires
-                // synchronously before execute() and guarantees ordering above
-                // any approval prompt.
-                if (!reasoningEchoed) {
-                    reasoning.echoReasoning(stepCounter, currentReasoning);
-                    reasoningEchoed = true;
+                case 'text-delta': {
+                    currentReasoning += part.text;
+                    break;
+                }
+                case 'text-end': {
+                    if (!reasoningEchoed) {
+                        reasoning.echoReasoning(stepCounter, currentReasoning);
+                        reasoningEchoed = true;
+                    }
+                    break;
                 }
-                break;
+                case 'tool-call': {
+                    // Backup echo path: if text-end didn't fire (provider variant or
+                    // text-less step), echo whatever reasoning we have when we see
+                    // tool-call. The tool-call LINE itself is NOT printed here — it's
+                    // printed by experimental_onToolCallStart, which fires
+                    // synchronously before execute() and guarantees ordering above
+                    // any approval prompt.
+                    if (!reasoningEchoed) {
+                        reasoning.echoReasoning(stepCounter, currentReasoning);
+                        reasoningEchoed = true;
+                    }
+                    break;
+                }
+                case 'tool-error': {
+                    // The SDK catches errors thrown from tool.execute() and emits
+                    // them as tool-error events instead of rejecting the stream. So
+                    // we inspect every tool-error for our sentinels:
+                    //
+                    //   - UserCancelledError → throw out of the loop so the outer
+                    //     catch propagates it to cli.ts for "cancelled by user" + exit 130.
+                    //   - FatalAwsCliError → set endReason='fatal' and stop iterating.
+                    //     The failed call has already been recorded in executions[]
+                    //     by the tool (audit + record fire before the throw), so
+                    //     finalError further down will pick up the stderr naturally.
+                    //   - Anything else: ignore. Soft failures shouldn't be thrown
+                    //     (tools return them as results), and any other thrown error
+                    //     is treated as a tool-level failure the model can decide
+                    //     how to handle.
+                    if (part.error instanceof UserCancelledError) {
+                        throw part.error;
+                    }
+                    if (part.error instanceof FatalAwsCliError) {
+                        endReason = 'fatal';
+                        logger.warn(`Run ended on fatal AWS CLI error (exit ${part.error.exitCode}).`);
+                        // Flush this step's reasoning to the file log; the tool-call
+                        // event for this step already fired, so currentToolCalls is
+                        // populated. We need to break out cleanly without waiting
+                        // for finish-step (the SDK may still emit it, may not).
+                        reasoning.logStepToFile({
+                            step: stepCounter,
+                            reasoning: currentReasoning,
+                            toolCalls: currentToolCalls,
+                            finishReason: 'fatal-error',
+                        });
+                        // Stop processing the stream. We don't break out of the
+                        // for-await directly because we want to drain remaining events
+                        // for the SDK's internal cleanup; but we set a flag so we
+                        // don't process them.
+                        // Simplest: just let the loop continue. finish-step / finish
+                        // events will pass through harmlessly.
+                    }
+                    break;
+                }
+                case 'finish-step': {
+                    // After a fatal tool-error, finish-step still arrives for the
+                    // same step. The reasoning was already flushed in the tool-error
+                    // handler — don't double-flush. For normal steps, this is the
+                    // path that flushes.
+                    if (endReason !== 'fatal') {
+                        reasoning.logStepToFile({
+                            step: stepCounter,
+                            reasoning: currentReasoning,
+                            toolCalls: currentToolCalls,
+                            finishReason: part.finishReason,
+                        });
+                    }
+                    logger.debug(`Step ${stepCounter} finished (finishReason=${part.finishReason})`);
+                    break;
+                }
+                // Other event types (reasoning-delta for thinking-models,
+                // tool-input-delta, source, file, raw, etc.) are ignored —
+                // fullStream is forward-compatible.
             }
-            case 'finish-step': {
+        }
+    }
+    catch (err) {
+        // The for-await loop throws when we re-throw UserCancelledError above.
+        // It can also throw on genuine SDK / provider failures. We distinguish:
+        if (err instanceof UserCancelledError) {
+            // No endReason='cancelled' assignment here: we throw immediately
+            // and the post-stream code in this function never runs. cli.ts is
+            // the one that recognizes UserCancelledError and exits 130 — it
+            // doesn't need RunResult.endReason for that.
+            if (currentReasoning.trim().length > 0 || currentToolCalls.length > 0) {
                 reasoning.logStepToFile({
                     step: stepCounter,
                     reasoning: currentReasoning,
                     toolCalls: currentToolCalls,
-                    finishReason: part.finishReason,
+                    finishReason: 'cancelled',
                 });
-                logger.debug(`Step ${stepCounter} finished (finishReason=${part.finishReason})`);
-                break;
             }
-            // Other event types (reasoning-delta for thinking-models,
-            // tool-input-delta, source, file, raw, etc.) are ignored —
-            // fullStream is forward-compatible.
+            logger.info('Run cancelled by user.');
+            throw err;
         }
+        // Genuine bug or provider failure. Let it bubble.
+        throw err;
+    }
+    // After the stream completes (normally OR via FatalAwsCliError), pull
+    // the post-stream promises. Most runs reach here with all three already
+    // resolved (the stream completion is the signal). But when we caught a
+    // FatalAwsCliError mid-stream, the SDK may have left these in a rejected
+    // state — the stream didn't naturally complete. Defensive try/await
+    // around each so we degrade gracefully: a partial RunResult with
+    // whatever usage we got from steps that did complete is better than
+    // crashing on a downstream `await` and losing the failure context.
+    let finalText = '';
+    let finalSteps = [];
+    let totalUsage;
+    try {
+        finalText = await result.text;
+    }
+    catch (err) {
+        logger.debug('result.text rejected (expected after fatal/cancel)', err);
+    }
+    try {
+        finalSteps = await result.steps;
+    }
+    catch (err) {
+        logger.debug('result.steps rejected (expected after fatal/cancel)', err);
+    }
+    try {
+        totalUsage = await result.totalUsage;
+    }
+    catch (err) {
+        logger.debug('result.totalUsage rejected (expected after fatal/cancel)', err);
     }
-    // Wait for all the post-stream promises to resolve. They're already
-    // ready by the time fullStream finishes (the stream completion is the
-    // signal), so these awaits are effectively synchronous.
-    const finalText = await result.text;
-    const finalSteps = await result.steps;
-    const totalUsage = await result.totalUsage;
     logger.info(`Agent finished after ${finalSteps.length} step(s)`);
     logger.debug('Final text', finalText);
     // Token usage for this invocation.
@@ -278,6 +378,7 @@ export async function runAgent(opts) {
         finalOutput,
         finalError,
         ranCommand,
+        endReason,
     };
 }
 /**

package/dist/cli.js

@@ -8,7 +8,8 @@ import { UsageLogger } from './usage.js';
 import { History } from './history.js';
 import { runAgent } from './agent.js';
 import { FILES, PATHS, DEFAULT_SCRIPT_FOLDER } from './paths.js';
-const VERSION = '0.4.0';
+import { UserCancelledError } from './errors.js';
+const VERSION = '0.5.0';
 /**
  * Apply CLI flags on top of the loaded config. Flags only override; they
  * never widen or compose with each other implicitly.
@@ -154,7 +155,13 @@ export async function main(argv) {
             // Footer counts only commands that actually executed. Declined or
             // cancelled commands appear in `result.commands` for the history
             // log but don't count as "ran" since no subprocess was started.
-            if (result.executedCommandCount > 0) {
+            //
+            // Gated on `cfg.verbose`: the footer is supplementary information
+            // ("here's what happened during the run") that's useful while you're
+            // watching the agent work, but noisy for scripted/pipeline use. With
+            // verbose off, nothing aca generates reaches the terminal — only the
+            // AWS CLI's verbatim output does.
+            if (cfg.verbose && result.executedCommandCount > 0) {
                 const tag = result.profile ? `[${result.profile}]` : '';
                 const cmds = result.executedCommandCount === 1
                     ? '1 command'
@@ -163,10 +170,19 @@ export async function main(argv) {
             }
         }
         catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            logger.error('Agent failed', msg);
-            process.stderr.write(chalk.red('Error: ') + msg + '\n');
-            process.exitCode = 1;
+            // User cancelled (Ctrl-C at a prompt). Print a calm message,
+            // exit 130 (SIGINT convention), no red error, no "ran N" footer,
+            // no stack trace.
+            if (err instanceof UserCancelledError) {
+                process.stderr.write(chalk.dim('cancelled by user\n'));
+                process.exitCode = 130;
+            }
+            else {
+                const msg = err instanceof Error ? err.message : String(err);
+                logger.error('Agent failed', msg);
+                process.stderr.write(chalk.red('Error: ') + msg + '\n');
+                process.exitCode = 1;
+            }
         }
         finally {
             logger.close();

package/dist/errors.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Sentinel error: the user pressed Ctrl-C during a prompt. Thrown from
+ * inside tool `execute()` functions when Inquirer throws ExitPromptError,
+ * propagated up through the agent loop, caught at the cli.ts boundary
+ * where it triggers a clean exit with status 130.
+ *
+ * Using a custom class (not a string match) gives us reliable
+ * `instanceof UserCancelledError` checks across all the places that need
+ * to handle the cancellation differently from real errors.
+ */
+export declare class UserCancelledError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Sentinel error: the AWS CLI returned an exit code in FATAL_AWS_EXIT_CODES
+ * (252-255). These indicate an unrecoverable condition — auth failure,
+ * missing credentials, malformed request, AWS service failure — and
+ * retrying won't help. The tool throws this instead of returning a result,
+ * so the model never gets a chance to retry. The agent loop catches it,
+ * propagates the stderr to the user, and exits 1.
+ *
+ * Carries the original cmd, exitCode, and stderr so cli.ts can surface
+ * them to the user.
+ */
+export declare class FatalAwsCliError extends Error {
+    readonly cmd: string;
+    readonly exitCode: number;
+    readonly stderr: string;
+    constructor(cmd: string, exitCode: number, stderr: string);
+}
+/**
+ * AWS CLI exit codes that indicate an unrecoverable condition:
+ *   252 — Command-line parsing errors (typically a bug in our agent or
+ *         the CLI itself; retrying won't help)
+ *   253 — Profile/credentials not found in the credential chain
+ *   254 — Client-side error (4xx from the service — auth, permission,
+ *         malformed request)
+ *   255 — Server-side error (5xx from the service — internal AWS issues)
+ *
+ * Anything else non-zero is a soft error (resource not found, etc.) and
+ * gets returned to the model normally — it may try a different approach.
+ * The model is bounded by `maxSteps` for runaway loops; we deliberately
+ * don't impose a separate soft-failure cap.
+ *
+ * Exit code 130 (SIGINT) in interactive mode is treated as a clean user
+ * cancellation, not an error — see aws-cli.ts's `effectivelyOk` rule.
+ */
+export declare const FATAL_AWS_EXIT_CODES: Set<number>;
+/**
+ * Wrap an Inquirer prompt promise so that Ctrl-C (which Inquirer reports
+ * as `ExitPromptError`) becomes our `UserCancelledError` sentinel. The
+ * Inquirer error class isn't easily importable, so we detect by `.name`.
+ * Re-throws any other error unchanged.
+ *
+ *   const answer = await wrapPrompt(confirm({ message: '...' }));
+ */
+export declare function wrapPrompt<T>(p: Promise<T>): Promise<T>;

package/dist/errors.js

@@ -0,0 +1,76 @@
+/**
+ * Sentinel error: the user pressed Ctrl-C during a prompt. Thrown from
+ * inside tool `execute()` functions when Inquirer throws ExitPromptError,
+ * propagated up through the agent loop, caught at the cli.ts boundary
+ * where it triggers a clean exit with status 130.
+ *
+ * Using a custom class (not a string match) gives us reliable
+ * `instanceof UserCancelledError` checks across all the places that need
+ * to handle the cancellation differently from real errors.
+ */
+export class UserCancelledError extends Error {
+    constructor(message = 'User cancelled the operation.') {
+        super(message);
+        this.name = 'UserCancelledError';
+    }
+}
+/**
+ * Sentinel error: the AWS CLI returned an exit code in FATAL_AWS_EXIT_CODES
+ * (252-255). These indicate an unrecoverable condition — auth failure,
+ * missing credentials, malformed request, AWS service failure — and
+ * retrying won't help. The tool throws this instead of returning a result,
+ * so the model never gets a chance to retry. The agent loop catches it,
+ * propagates the stderr to the user, and exits 1.
+ *
+ * Carries the original cmd, exitCode, and stderr so cli.ts can surface
+ * them to the user.
+ */
+export class FatalAwsCliError extends Error {
+    cmd;
+    exitCode;
+    stderr;
+    constructor(cmd, exitCode, stderr) {
+        super(`AWS CLI exited with code ${exitCode} (unrecoverable): ${stderr.trim() || '<no stderr>'}`);
+        this.cmd = cmd;
+        this.exitCode = exitCode;
+        this.stderr = stderr;
+        this.name = 'FatalAwsCliError';
+    }
+}
+/**
+ * AWS CLI exit codes that indicate an unrecoverable condition:
+ *   252 — Command-line parsing errors (typically a bug in our agent or
+ *         the CLI itself; retrying won't help)
+ *   253 — Profile/credentials not found in the credential chain
+ *   254 — Client-side error (4xx from the service — auth, permission,
+ *         malformed request)
+ *   255 — Server-side error (5xx from the service — internal AWS issues)
+ *
+ * Anything else non-zero is a soft error (resource not found, etc.) and
+ * gets returned to the model normally — it may try a different approach.
+ * The model is bounded by `maxSteps` for runaway loops; we deliberately
+ * don't impose a separate soft-failure cap.
+ *
+ * Exit code 130 (SIGINT) in interactive mode is treated as a clean user
+ * cancellation, not an error — see aws-cli.ts's `effectivelyOk` rule.
+ */
+export const FATAL_AWS_EXIT_CODES = new Set([252, 253, 254, 255]);
+/**
+ * Wrap an Inquirer prompt promise so that Ctrl-C (which Inquirer reports
+ * as `ExitPromptError`) becomes our `UserCancelledError` sentinel. The
+ * Inquirer error class isn't easily importable, so we detect by `.name`.
+ * Re-throws any other error unchanged.
+ *
+ *   const answer = await wrapPrompt(confirm({ message: '...' }));
+ */
+export async function wrapPrompt(p) {
+    try {
+        return await p;
+    }
+    catch (err) {
+        if (err instanceof Error && err.name === 'ExitPromptError') {
+            throw new UserCancelledError();
+        }
+        throw err;
+    }
+}

package/dist/tools/aws-cli.js

@@ -3,6 +3,7 @@ import { tool } from 'ai';
 import { z } from 'zod';
 import { confirm } from '@inquirer/prompts';
 import chalk from 'chalk';
+import { FATAL_AWS_EXIT_CODES, FatalAwsCliError, UserCancelledError, wrapPrompt } from '../errors.js';
 const READ_ONLY_VERBS = [
     /^describe-/,
     /^list-/,
@@ -164,7 +165,7 @@ export function awsCliTool(opts) {
                 if (useInteractive) {
                     process.stderr.write(`${chalk.bold('  Mode:    ')}${chalk.yellow('interactive')} (your terminal will be connected to the command)\n`);
                 }
-                const ok = await confirm({ message: 'Execute this command?', default: true });
+                const ok = await wrapPrompt(confirm({ message: 'Execute this command?', default: true }));
                 if (!ok) {
                     opts.logger.warn('User declined command');
                     // Record the declined call so the agent's end-of-run logic sees
@@ -208,9 +209,18 @@ export function awsCliTool(opts) {
                         opts.logger.trace('stderr', stderr);
                     }
                 }
-                else if (code !== 0) {
+                else if (code !== 0 && code !== 130) {
+                    // Exit 130 in interactive mode = user pressed Ctrl-C to end their
+                    // SSM session, shell, port-forward, etc. That's expected, not a
+                    // failure. Anything else is genuine — log it.
                     opts.logger.warn(`Interactive AWS CLI exited non-zero (${code})`);
                 }
+                // SSM sessions and other interactive AWS CLI commands return 130
+                // when the user Ctrl-Cs to end the session. That's the normal way
+                // to leave a shell — treat it as success for ok/exit purposes so we
+                // don't surface it as an error in cli.ts. The real exit code is
+                // still recorded in the audit log for accuracy.
+                const effectivelyOk = code === 0 || (useInteractive && code === 130);
                 // Audit captures whatever we have. For interactive runs stdout/stderr
                 // are empty — that's accurate, the bytes went to the terminal — and
                 // the audit entry serves as a record that "an interactive session
@@ -219,7 +229,7 @@ export function awsCliTool(opts) {
                     cmd: display,
                     profile,
                     exitCode: code,
-                    ok: code === 0,
+                    ok: effectivelyOk,
                     stdout: useInteractive ? '[interactive session — output not captured]' : stdout,
                     stderr: useInteractive ? '' : stderr,
                 });
@@ -234,18 +244,33 @@ export function awsCliTool(opts) {
                         : stdout,
                     stderr: useInteractive ? '' : stderr,
                     exitCode: code,
-                    ok: code === 0,
+                    ok: effectivelyOk,
                 });
                 // For the agent's context, return a clear signal that interactive
                 // mode ran so it doesn't try to parse fictional stdout.
                 if (useInteractive) {
                     return {
-                        ok: code === 0,
+                        ok: effectivelyOk,
                         exitCode: code,
                         interactive: true,
                         note: 'Interactive session ran. Output went directly to the user\'s terminal and was not captured. Do not summarize or describe its contents.',
                     };
                 }
+                // Classify failures. Fatal exit codes (252-255) indicate the call
+                // won't succeed without external intervention — bad credentials,
+                // missing resource, malformed request, AWS service failure. We
+                // throw FatalAwsCliError (after recording the audit trail above)
+                // rather than returning a result to the model: the throw unwinds
+                // the agent loop entirely, the user sees the AWS stderr in red,
+                // and we exit 1. The model never gets a chance to retry, because
+                // these classes of error don't get better with retries.
+                //
+                // Soft failures (other non-zero exits) ARE returned to the model
+                // as ordinary results. The model may retry with a different
+                // approach. maxSteps bounds the worst case if that goes nowhere.
+                if (code !== 0 && FATAL_AWS_EXIT_CODES.has(code)) {
+                    throw new FatalAwsCliError(display, code, stderr);
+                }
                 return {
                     ok: code === 0,
                     exitCode: code,
@@ -254,6 +279,11 @@ export function awsCliTool(opts) {
                 };
             }
             catch (err) {
+                // FatalAwsCliError is our own signal — propagate it cleanly.
+                // UserCancelledError must propagate too (Ctrl-C at the approval
+                // prompt) or it'd get swallowed into a spawn-failure log entry.
+                if (err instanceof FatalAwsCliError || err instanceof UserCancelledError)
+                    throw err;
                 const msg = err instanceof Error ? err.message : String(err);
                 opts.logger.error('Failed to spawn aws CLI', msg);
                 opts.audit.logCommand({

package/dist/tools/bash.js

@@ -7,6 +7,7 @@ import { z } from 'zod';
 import { select } from '@inquirer/prompts';
 import chalk from 'chalk';
 import { DEFAULT_SCRIPT_FOLDER } from '../paths.js';
+import { wrapPrompt } from '../errors.js';
 function runProcess(cmd, args) {
     return new Promise((resolve, reject) => {
         const proc = spawn(cmd, args, { env: process.env });
@@ -74,7 +75,7 @@ export function bashScriptTool(opts) {
             // — auto-approving them would defeat a primary safety boundary. The
             // autoApprove flag remains in effect for individual aws CLI commands
             // (where read-only is a meaningful and enforceable category).
-            const action = await select({
+            const action = await wrapPrompt(select({
                 message: 'What would you like to do with this script?',
                 choices: [
                     { value: 'execute', name: 'Execute now' },
@@ -82,7 +83,7 @@ export function bashScriptTool(opts) {
                     { value: 'cancel', name: 'Cancel' },
                 ],
                 default: 'execute',
-            });
+            }));
             if (action === 'cancel') {
                 opts.logger.warn('User cancelled script');
                 // Record the cancelled call so the agent's end-of-run logic sees

package/dist/tools/prompt.js

@@ -2,6 +2,7 @@ import { tool } from 'ai';
 import { z } from 'zod';
 import { confirm, input, password, select } from '@inquirer/prompts';
 import chalk from 'chalk';
+import { wrapPrompt } from '../errors.js';
 /**
  * Schema for a single question. Used both by `prompt_user` directly (single
  * question per call) and `prompt_user_multi` (batch of questions in one call).
@@ -44,28 +45,28 @@ async function askOne(q, logger) {
             if (!q.choices || q.choices.length === 0) {
                 throw new Error('kind="choice" requires non-empty `choices`.');
             }
-            const answer = await select({
+            const answer = await wrapPrompt(select({
                 message: q.message,
                 choices: q.choices.map((c) => ({ value: c, name: c })),
                 default: q.defaultValue,
-            });
+            }));
             return answer;
         }
         case 'confirm': {
             const def = (q.defaultValue ?? 'yes').toLowerCase().startsWith('y');
-            const answer = await confirm({ message: q.message, default: def });
+            const answer = await wrapPrompt(confirm({ message: q.message, default: def }));
             return answer ? 'yes' : 'no';
         }
         case 'secret': {
             // Inquirer's password prompt masks input. Used for short secrets like
             // MFA codes; long-lived AWS credentials should always come from the
             // user's profile, not be typed here.
-            const answer = await password({ message: q.message, mask: '*' });
+            const answer = await wrapPrompt(password({ message: q.message, mask: '*' }));
             return answer;
         }
         case 'text':
         default: {
-            const answer = await input({ message: q.message, default: q.defaultValue });
+            const answer = await wrapPrompt(input({ message: q.message, default: q.defaultValue }));
             return answer;
         }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aws-cli-agent",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Agentic AI assistant that turns natural-language requests into AWS CLI commands and runs them locally.",
   "type": "module",
   "bin": {
@@ -56,7 +56,7 @@
     "@ai-sdk/google": "^3.0.74",
     "@ai-sdk/openai": "^3.0.64",
     "@aws-sdk/credential-providers": "^3.1046.0",
-    "@inquirer/prompts": "^7.3.0",
+    "@inquirer/prompts": "^8.4.3",
     "ai": "^6.0.183",
     "chalk": "^5.4.0",
     "commander": "^13.0.0",