aia 2.0.1 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9fa126ad31719e30c2d357d3573ba4b7832fe99ab082799c0e7b37c3b0d49314
-  data.tar.gz: 20706361c420669cb035fb03c996ef28895399ba850985715e44f6b9411ca47a
+  metadata.gz: 1d7d1dff13dc9c4e4558c4624bf6368cb32f42a4a4896238e1750e5beaa24d7b
+  data.tar.gz: e430f69d905314342a538d063b5123dd5fd454dabcd6bae08a2ad3d696d74d56
 SHA512:
-  metadata.gz: 6154106f03fa35cfbf562282eec6512dc210df4b40ae6c900eede45df5a5253f232fc6bbe7c9a0cf930a152558ffde96d45aa1894d8c338af5256f65a9ccbe82
-  data.tar.gz: 6ce2ca929686cd6e262f5f009581a087b710129f5d89a0d020d612dffd7bc5b555f794a41cfc38ca3f8a3b1941edfeff7cb08331f2c7ea036dfce2e4372c3ae0
+  metadata.gz: b136ae2840a452e8aa5dae4585588036ea10420abbd071c5fd3b45e0fea86a2f6c35005680757e8c2ebde9a63d8a6abf3538a164446c03cc1300aafd41a97728
+  data.tar.gz: 06c4e7081bdfe6c618bb4dc868d37daf232c491d04319bf8426232b85442a94eb279b04cba69e3e456d7580d51bdaede5d761367f9331f481387c15432506df4

data/CHANGELOG.md

@@ -1,6 +1,38 @@
 # Changelog
 
-## [2.0.1] 2026-11-02
+## [2.1.0] - 2026-11-07
+
+Coding-agent CLIs (Claude Code, Codex, GitHub Copilot) can be used as models, and a prompt file can ask for a special mode such as `debate` in its front matter. Batch runs now exit 1 when an LLM call fails. The unit test suite runs without API keys, a UTF-8 locale or a particular Ruby patch level, and every test file runs on its own.
+
+### Added
+
+- **Coding agents as models.** `--model claude_code/opus`, `codex/default` or `copilot/auto` sends prompts to the Claude Code, Codex or GitHub Copilot CLI in batch mode (stdin in, JSON out) through the `ruby_llm-providers-claude_code`, `-codex` and `-copilot` gems, which resume the agent's own session between turns. A bare provider name (`--model claude_code`) now means that provider's default model. Providers that answer `accepts_tools?` with `false` get no aia tools or MCP servers attached, with a one-line notice. An installed provider gem is found and loaded even when aia itself runs under Bundler (a `bin/aia` checkout, or an app that lists aia in its Gemfile) and the gem is not in that Gemfile, provided the bundle already satisfies the gem's dependencies.
+
+- **`mode:` front matter key.** A prompt file can ask for one of the special modes that the chat directives `/debate`, `/verify`, `/decompose`, `/delegate`, `/spawn`, `/orchestrate` and `/concurrent` request, by naming it in its front matter: `mode: debate`. Prompts run from the command line, in a pipeline or as executable prompts then get that mode, which until now ran only in chat; a `/debate` line inside a prompt file was sent to the model as text. As in chat, a debate needs several robots (`--model a,b,c`).
+
+### Fixed
+
+- **`--provider` outranks `AIA_MODEL` and the config file.** `--provider claude_code` replaced the provider only of models given without a `<provider>/` prefix, so with `AIA_MODEL=lms/qwen3.8` exported the flag did nothing and the prompt still went to LM Studio. A command-line `--provider` now applies to every model that came from the environment or a config file, prefix or not, keeping their model names; it sets the provider, never the model, so `--model claude_code` (a bare provider name) remains the way to ask for a provider's default model. Models named on the command line with `--model` keep an explicit prefix, since both values come from the same place. When a provider gem cannot be loaded because aia is running under Bundler, the warning now names the Gemfile to add the `ruby_llm-providers-<slug>` gem to.
+
+- **Batch runs exit 1 on LLM errors.** robot_lab shields a robot's exception into an `Error: ...` reply so one failing robot cannot crash a network, which left `aia prompt` printing a bad API key, rate limit or provider outage as the answer and exiting 0. A hook now records the real exception for each pipeline step: outside chat the step fails, the error goes to stderr and aia exits 1; in a chat session the error is shown and the session continues. Unshielded RubyLLM errors (image generation, provider setup) exit 1 with a one-line message instead of a backtrace.
+
+- **`--paint` works again, and `--image_quality` / `--image_style` reach the API.** Since 2.0.0 the image step handed `RubyLLM.paint` a `params:` keyword that ruby_llm 2.1 does not have, so every `--paint` run stopped with `ArgumentError: unknown keyword: :params` before any request was made. The options now go through `provider_options:`, which ruby_llm merges into the request, so `--image_quality hd --image_style vivid` take effect (#135).
+
+- **`DelegateHandler` and `DelegateToForemanTool` load what they use.** `delegate_handler.rb` now requires `TaskDecomposer` and `TaskExecutor`, and `delegate_to_foreman_tool.rb` requires `TaskBoardTool`. Each worked only because its one caller also required those files, so loading either on its own and calling it raised `uninitialized constant`.
+
+**Test suite**
+
+- **Failing test runs exit non-zero.** `test_helper.rb`'s `exit` override, which stops aia's exit calls from ending a test run early, also swallowed Minitest's exit status, so `rake test` and single test files exited 0 when tests failed. The override now stands down after the suite runs.
+
+- **Test suite loads on Ruby 4.1.** `ostruct` is a bundled gem since Ruby 4.0 and only reached the test bundle as a transitive dependency of `oj` 3.17.7; `oj` 3.17.8 dropped it, so `bundle update` left the suite unable to load `OpenStruct`. It is now a development dependency. The speech player test no longer stubs `ENV`, which Ruby 4.1 rejects as a shareable object.
+
+- **Unit suite passes without API keys or a UTF-8 locale.** The network-building tests create real RubyLLM chats, which ruby_llm 2.1 refuses without a provider API key, so 37 tests errored unless `OPENAI_API_KEY` was set. They now skip that credential check; they never call an API. The gemspec version test errored under a non-UTF-8 locale; it now loads the gemspec and compares its version with `AIA::VERSION`. `test_helper.rb` requires `ostruct`, so test files that use `OpenStruct` also run on their own.
+
+- **Every unit test file runs on its own.** Six files raised `uninitialized constant` when run alone, because aia loads a class each one uses lazily: `TaskDecomposer`, `TaskExecutor`, `TaskBoardTool` (one file each) and `ToolFilter::TFIDF` (three files). Each file now requires that class.
+
+- **`ConfigTest` ignores the shell's `AIA_PLUGINS_DIR`.** The test that checks `paths.plugins_dir` defaults to `nil` read whatever the developer's shell had exported and failed, and the two tests that set the variable deleted it afterwards. All three now set the variable for their own run and restore it.
+
+## [2.0.1] - 2026-11-02
 
 ### Fixed
 
@@ -11,7 +43,7 @@
 - `logger.mcp.file` defaults to `~/.config/aia/logs/mcp.log` (was `STDOUT`), so MCP connection warnings no longer print over the spinner. Failed servers are still listed in the startup banner. A config file that sets `file: STDOUT` keeps the old behavior.
 - Log directories are created when they don't exist.
 
-## [2.0.0] 2026-11-02
+## [2.0.0] - 2026-11-02
 
 AIA 2.0 rebuilds the CLI on [robot_lab](https://github.com/MadBomber/robot_lab): every session is a crew of robots, MCP servers come from ruby_llm 2.1's built-in client, and any provider RubyLLM registers can be used. This entry summarizes everything since 1.1.1, the last 1.x release, including the `2.0.0.pre.alpha` and `2.0.0.pre.beta2` pre-releases.
 
@@ -436,7 +468,7 @@ If you used a 2.0 pre-release: the KBS rule engine, `/rules`, user-defined rule
   - Added `handle_tool_crash` method that logs errors with 5-line traceback
   - Tool crashes no longer crash AIA - conversation continues gracefully
 
-## [0.9.24] 2025-12-17
+## [0.9.24] - 2025-12-17
 ### Fixes
 - Ran into a problem with the `shared_tools` gem and the --require parameter of AIA which required changes to both gems.
 
@@ -461,7 +493,7 @@ If you used a 2.0 pre-release: the KBS rule engine, `/rules`, user-defined rule
   - Added `handle_tool_crash` method for graceful error handling
   - Removed debug statements
 
-## [0.9.23] 2025-12-06
+## [0.9.23] - 2025-12-06
 
 ### New Features
 - **MCP Server Configuration**: Added native support for defining MCP (Model Context Protocol) servers in the config file
@@ -494,7 +526,7 @@ If you used a 2.0 pre-release: the KBS rule engine, `/rules`, user-defined rule
       MY_VAR: "value"
 ```
 
-## [0.9.22] 2025-11-12
+## [0.9.22] - 2025-11-12
 
 ### Bug Fixes
 - **TEST SUITE**: Fixed all Mocha test isolation issues causing stub contamination between tests
@@ -510,14 +542,14 @@ If you used a 2.0 pre-release: the KBS rule engine, `/rules`, user-defined rule
 - Standardized stub usage pattern across test suite for consistency
 - Eliminated stub leakage that caused "unexpected invocation" and "AIA was instantiated in one test but receiving invocations in another" errors
 
-## [0.9.21] 2025-10-08
+## [0.9.21] - 2025-10-08
 ### Bug Fixes
 - **Checkpoint Directive Output**: Fixed `//checkpoint` directive to return empty string instead of status message (lib/aia/directives/configuration.rb:155)
   - Prevents checkpoint creation messages from entering AI context
   - Outputs confirmation to STDOUT instead for user feedback
   - Prevents potential AI manipulation of checkpoint system
 
-## [0.9.20] 2025-10-06
+## [0.9.20] - 2025-10-06
 ### Added
 - **Enhanced Multi-Model Role System (ADR-005)**: Implemented per-model role assignment with inline syntax
   - New inline syntax: `--model MODEL[=ROLE][,MODEL[=ROLE]]...`
@@ -581,7 +613,7 @@ If you used a 2.0 pre-release: the KBS rule engine, `/rules`, user-defined rule
 - Enhanced `apply_file_config_to_struct` to detect and process model arrays with role hashes
 - Enhanced `envar_options` to parse inline syntax for `:model` key (lib/aia/config/base.rb:212-217)
 
-## [0.9.19] 2025-10-06
+## [0.9.19] - 2025-10-06
 
 ### Bug Fixes
 - **CRITICAL BUG FIX**: Fixed multi-model cross-talk issue (#118) where models could see each other's conversation history
@@ -644,7 +676,7 @@ bin/aia --chat --model lms/openai/gpt-oss-20b,ollama/gpt-oss:20b --tokens
 # (Previously: LMS would say "5 times", Ollama "6 times" due to cross-talk)
 ```
 
-## [0.9.18] 2025-10-05
+## [0.9.18] - 2025-10-05
 
 ### Bug Fixes
 - **BUG FIX**: Fixed RubyLLM provider error parsing to handle both OpenAI and LM Studio error formats
@@ -663,7 +695,7 @@ bin/aia --chat --model lms/openai/gpt-oss-20b,ollama/gpt-oss:20b --tokens
 - Cleaned up debug puts statements from RubyLLMAdapter and provider_fix
 - Added robust JSON parsing with fallback error handling
 
-## [0.9.17] 2025-10-04
+## [0.9.17] - 2025-10-04
 
 ### New Features
 - **NEW FEATURE**: Enhanced local model support with comprehensive validation and error handling
@@ -713,7 +745,7 @@ aia --model ollama/llama3.2 --chat
 > //models
 ```
 
-## [0.9.16] 2025-09-26
+## [0.9.16] - 2025-09-26
 
 ### New Features
 - **NEW FEATURE**: Added support for Ollama AI provider
@@ -724,7 +756,7 @@ aia --model ollama/llama3.2 --chat
 - **ENHANCEMENT**: Expanded AI provider ecosystem with three new local/self-hosted model options
 - **ENHANCEMENT**: Improved flexibility for users preferring local LLM deployments
 
-## [0.9.15] 2025-09-21
+## [0.9.15] - 2025-09-21
 
 ### New Features
 - **NEW FEATURE**: Added `//paste` directive to insert clipboard contents into prompts
@@ -734,7 +766,7 @@ aia --model ollama/llama3.2 --chat
 - Enhanced DirectiveProcessor with clipboard integration using the clipboard gem
 - Added comprehensive test coverage for paste directive functionality
 
-## [0.9.14] 2025-09-19
+## [0.9.14] - 2025-09-19
 
 ### New Features
 - **NEW FEATURE**: Added `//checkpoint` directive to create named snapshots of conversation context
@@ -760,7 +792,7 @@ aia --model ollama/llama3.2 --chat
 - Refactored help directive to collect directives from all registered modules
 - Added comprehensive test coverage for checkpoint and restore functionality
 
-## [0.9.13] 2025-09-02
+## [0.9.13] - 2025-09-02
 ### New Features
 - **NEW FEATURE**: Added `--tokens` flag to show token counts for each model
 - **NEW FEATURE**: Added `--cost` flag to enable cost estimation for each model
@@ -778,7 +810,7 @@ aia --model ollama/llama3.2 --chat
 - Enhanced test suite with improved assertions and coverage
 - Updated various gem dependencies to latest stable versions
 
-## [0.9.12] 2025-08-28
+## [0.9.12] - 2025-08-28
 
 ### New Features
 - **MAJOR NEW FEATURE**: Multi-model support - specify multiple AI models simultaneously with comma-separated syntax
@@ -845,15 +877,15 @@ aia --chat -m gpt-4o-mini,gpt-3.5-turbo
 - TODO: focus on log file consistency using Logger
 
 
-## [0.9.11] 2025-07-31
+## [0.9.11] - 2025-07-31
 - added a cost per 1 million input tokens to available_models query output
 - updated ruby_llm to version 1.4.0
 - updated all other gem dependencies to their latest versions
 
-## [0.9.10] 2025-07-18
+## [0.9.10] - 2025-07-18
 - updated ruby_llm-mcp to version 0.6.1 which solves problems with MCP tools not being installed
 
-## [0.9.9] 2025-07-10
+## [0.9.9] - 2025-07-10
 - refactored the Session and Config classes into more testable method_missing
 - updated the test suire for both the Session and Config classes
 - added support for MCP servers coming into AIA via the shared_tools gem
@@ -864,13 +896,13 @@ aia --chat -m gpt-4o-mini,gpt-3.5-turbo
 - //available_models now has context window size and capabilities for each model returned
 
 
-## [0.9.8] 2025-06-25
+## [0.9.8] - 2025-06-25
 - fixing an issue with pipelined prompts
 - now showing the complete modality of the model on the processing line.
 - changed -p option from prompts_dir to pipeline
 - found problem with simple cov and deep cov w/r/t their reported test coverage; they have problems with heredoc and complex conditionals.
 
-## [0.9.7] 2025-06-20
+## [0.9.7] - 2025-06-20
 
 - **NEW FEATURE**: Added `--available_models` CLI option to list all available AI models
 - **NEW FEATURE**: Added `//tools` to show a list of available tools and their description
@@ -881,7 +913,7 @@ aia --chat -m gpt-4o-mini,gpt-3.5-turbo
 - **DOCUMENTATION**: Updated README for better clarity and structure
 - **DEPENDENCY**: Updated Gemfile.lock with latest dependency versions
 
-## [0.9.6] 2025-06-13
+## [0.9.6] - 2025-06-13
 - fixed issue 84 with the //llms directive
 - changed the monkey patch to the RubyLLM::Model::Modalities class at the suggestions of the RubyLLM author in prep for a PR against that gem.
 - added the shared_tools gem - need to add examples on how to use it with the --tools option
@@ -889,11 +921,11 @@ aia --chat -m gpt-4o-mini,gpt-3.5-turbo
 - added images/aia.png to README.md
 - let claude code rewrite the README.md file.  Some details were dropped but overall in reads better.  Need to add the details to a wiki or other documentation site.
 
-## [0.9.5] 2025-06-04
+## [0.9.5] - 2025-06-04
 - changed the RubyLLM::Modalities class to use method_missing for mode query
 - hunting for why the //llms query directive is not finding image_to_image LLMs.
 
-## [0.9.4] 2025-06-03
+## [0.9.4] - 2025-06-03
 - using RubyLLM v1.3.0
 - setting up a docs infrastructure to behave like the ruby_llm gem's guides side
 - fixed bug in the text-to-image workflow
@@ -901,7 +933,7 @@ aia --chat -m gpt-4o-mini,gpt-3.5-turbo
 - need to pay attention to the test suite
 - also need to ensure the non text2text modes are working
 
-## [0.9.3rc1] 2025-05-24
+## [0.9.3rc1] - 2025-05-24
 - using ruby_llm v1.3.0rc1
 - added a models database refresh based on integer days interval with the --refresh option
 - config file now has a "last_refresh" String in format YYYY-MM-DD
@@ -910,41 +942,41 @@ aia --chat -m gpt-4o-mini,gpt-3.5-turbo
 - fixed a bug in the prompt_manager gem which is now at v0.5.5
 
 
-## [0.9.2] 2025-05-18
+## [0.9.2] - 2025-05-18
 - removing the MCP experiment
 - adding support for RubyLLM::Tool usage in place of the MCP stuff
 - updated prompt_manager to v0.5.4 which fixed shell integration problem
 
-## [0.9.1] 2025-05-16
+## [0.9.1] - 2025-05-16
 - rethink MCP approach in favor of just RubyLLM::Tool
 - fixed problem with //clear
 - fixed a problem with a priming prompt in a chat loop
 
-## [0.9.0] 2025-05-13
+## [0.9.0] - 2025-05-13
 - Adding experimental MCP Client support
 - removed the CLI options --erb and --shell but kept them in the config file with a default of true for both
 
-## [0.8.6] 2025-04-23
+## [0.8.6] - 2025-04-23
 - Added a client adapter for the ruby_llm gem
 - Added the adapter config item and the --adapter option to select at runtime which client to use ai_client or ruby_llm
 
-## [0.8.5] 2025-04-19
+## [0.8.5] - 2025-04-19
 - documentation updates
 - integrated the https://pure.md web service for inserting web pages into the context window
    - //include http?://example.com/stuff
    - //webpage http?://example.com/stuff
 
-## [0.8.2] 2025-04-18
+## [0.8.2] - 2025-04-18
 - fixed problems with pre-loaded context and chat repl
 - piped content into `aia --chat` is now a part of the context/instructions
 - content via "aia --chat < some_file" is added to the context/instructions
 - `aia --chat context_file.txt context_file2.txt` now works
 - `aia --chat prompt_id context)file.txt` also works
 
-## [0.8.1] 2025-04-17
+## [0.8.1] - 2025-04-17
 - bumped version to 0.8.1 after correcting merge conflicts
 
-## [0.8.0] WIP - 2025-04-15
+## [0.8.0] - 2025-04-15
 - Updated PromptManager to v0.5.1 which has some of the functionality that was originally developed in the AIA.
 - Enhanced README.md to include a comprehensive table of configuration options with defaults and associated environment variables.
 - Added a note in README.md about the expandability of configuration options from a config file for dynamic prompt generation.
@@ -952,7 +984,7 @@ aia --chat -m gpt-4o-mini,gpt-3.5-turbo
 - Ensured version consistency across `.version`, `aia.gemspec`, and `lib/aia/version.rb`.
 - Verified and updated documentation to ensure readiness for release on RubyGems.org.
 
-## [0.7.1] WIP - 2025-03-22
+## [0.7.1] - 2025-03-22
 - Added `UIPresenter` class for handling user interface presentation.
 - Added `DirectiveProcessor` class for processing chat-based directives.
 - Added `HistoryManager` class for managing conversation and variable history.
@@ -966,7 +998,7 @@ aia --chat -m gpt-4o-mini,gpt-3.5-turbo
 - Improved error handling and user feedback for directive processing.
 - Enhanced logging and output options for chat sessions.
 
-## [0.7.0] WIP - 2025-03-17
+## [0.7.0] - 2025-03-17
 - Major code refactoring for better organization and maintainability:
   - Extracted `DirectiveProcessor` class to handle chat-based directives
   - Extracted `HistoryManager` class for conversation and variable history management
@@ -977,13 +1009,13 @@ aia --chat -m gpt-4o-mini,gpt-3.5-turbo
 - Improved output handling to suppress STDOUT when chat mode is off and output file is specified
 - Updated spinner format in the process_prompt method for better user experience
 
-## [0.6.?] WIP
+## [0.6.?] - WIP
 - Implemented Tony Stark's Clean Slate Protocol on the develop branch
 
-## [0.5.17] 2024-05-17
+## [0.5.17] - 2024-05-17
 - removed replaced `semver` with `versionaire`
 
-## [0.5.16] 2024-04-02
+## [0.5.16] - 2024-04-02
 - fixed prompt pipelines
 - added //next and //pipeline directives as shortcuts to //config [next,pipeline]
 - Added new backend "client" as an internal OpenAI client
@@ -992,82 +1024,82 @@ aia --chat -m gpt-4o-mini,gpt-3.5-turbo
 - Added --voice default: alloy (if "siri" and Mac? then uses cli tool "say")
 - Added --image_size and --image_quality (--is --iq)
 
-## [0.5.15] 2024-03-30
+## [0.5.15] - 2024-03-30
 - Added the ability to accept piped in text to be appended to the end of the prompt text: curl $URL | aia ad_hoc
 - Fixed bugs with entering directives as follow-up prompts during a chat session
 
-## [0.5.14] 2024-03-09
+## [0.5.14] - 2024-03-09
 - Directly access OpenAI to do text to speech when using the `--speak` option
 - Added --voice to specify which voice to use
 - Added --speech_model to specify which TTS model to use
 
-## [0.5.13] 2024-03-03
+## [0.5.13] - 2024-03-03
 - Added CLI-utility `llm` as a backend processor
 
-## [0.5.12] 2024-02-24
+## [0.5.12] - 2024-02-24
 - Happy Birthday Ruby!
 - Added --next CLI option
 - Added --pipeline CLI option
 
-## [0.5.11] 2024-02-18
+## [0.5.11] - 2024-02-18
 - allow directives to return information that is inserted into the prompt text
 - added //shell command directive
 - added //ruby ruby_code directive
 - added //include path_to_file directive
 
-## [0.5.10] 2024-02-03
+## [0.5.10] - 2024-02-03
 - Added --roles_dir to isolate roles from other prompts if desired
 - Changed --prompts to --prompts_dir to be consistent
 - Refactored common fzf usage into its own tool class
 
-## [0.5.9] 2024-02-01
+## [0.5.9] - 2024-02-01
 - Added a "I'm working" spinner thing when "--verbose" is used as an indication that the backend is in the process of composing its response to the prompt.
 
-## [0.5.8] 2024-01-17
+## [0.5.8] - 2024-01-17
 - Changed the behavior of the --dump option.  It must now be followed by path/to/file.ext where ext is a supported config file format: yml, yaml, toml
 
-## [0.5.7] 2024-01-15
+## [0.5.7] - 2024-01-15
 - Added ERB processing to the config_file
 
-## [0.5.6] 2024-01-15
+## [0.5.6] - 2024-01-15
 - Adding processing for directives, shell integration and erb to the follow up prompt in a chat session
 - some code refactoring.
 
-## [0.5.3] 2024-01-14
+## [0.5.3] - 2024-01-14
 - adding ability to render markdown to the terminal using the "glow" CLI utility
 
-## [0.5.2] 2024-01-13
+## [0.5.2] - 2024-01-13
 - wrap response when its going to the terminal
 
-## [0.5.1] 2024-01-12
+## [0.5.1] - 2024-01-12
 - removed a wicked puts "loaded" statement
 - fixed missed code when the options were changed to --out_file and --log_file
 - fixed completion functions by updating $PROMPT_DIR to $AIA_PROMPTS_DIR to match the documentation.
 
-## [0.5.0] 2024-01-05
+## [0.5.0] - 2024-01-05
 - breaking changes:
     - changed `--config` to `--config_file`
     - changed `--env` to `--shell`
     - changed `--output` to `--out_file`
         - changed default `out_file` to `STDOUT`
 
-## [0.4.3] 2023-12-31
+## [0.4.3] - 2023-12-31
 - added --env to process embedded system environment variables and shell commands within a prompt.
 - added --erb to process Embedded RuBy within a prompt because have embedded shell commands will only get you in a trouble.  Having ERB will really get you into trouble.  Remember the simple prompt is usually the best prompt.
 
-## [0.4.2] 2023-12-31
+## [0.4.2] - 2023-12-31
 - added the --role CLI option to pre-pend a "role" prompt to the front of a primary prompt.
 
-## [0.4.1] 2023-12-31
+## [0.4.1] - 2023-12-31
 - added a chat mode
 - prompt directives now supported
 - version bumped to match the `prompt_manager` gem
 
-## [0.3.20] 2023-12-28
+## [0.3.20] - 2023-12-28
 - added work around to issue with multiple context files going to the `mods` backend
 - added shellwords gem to sanitize prompt text on the command line
 
-## [0.3.19] 2023-12-26
+## [0.3.19] - 2023-12-26
 - major code refactoring.
 - supports config files \*.yml, \*.yaml and \*.toml
 - usage implemented as a man page. --help will display the man page/
@@ -1080,7 +1112,7 @@ aia --chat -m gpt-4o-mini,gpt-3.5-turbo
     3. envar values             over-rides ...
     4. default values
 
-## [0.3.0] = 2023-11-23
+## [0.3.0] - 2023-11-23
 
 - Matching version to [prompt_manager](https://github.com/prompt_manager) This version allows for the user of history in the entry of values to prompt keywords.  KW_HISTORY_MAX is set at 5.  Changed CLI interaction to use historical selection and editing of prior keyword values.
 

data/README.md

@@ -6,7 +6,7 @@
 
   <img src="docs/assets/images/aia.png" alt="Robots waiter ready to take your order."><br />
   **The Prompt is the Code**<br />
-  <p>Check out the new <a href="https://madbomber.github.io/aia/extending/multi-model/#giving-each-model-a-role">Inline Role Syntax</a> when working with multiple concurrent models.</p>
+  <p>New in 2.1: <a href="#coding-agents-as-models-claude-code-codex-copilot">coding agents as models</a>. Point <code>--model</code> at <code>claude_code/</code>, <code>codex/</code> or <code>copilot/</code> and the Claude Code, Codex or GitHub Copilot CLI answers your prompt, alone or as a member of a crew.</p>
 </div>
 
 ---
@@ -33,6 +33,7 @@ For more information on AIA visit these locations:
 | Prompt management | File-based system with history, variables, and fuzzy search | Limited or none |
 | Workflow pipelines | Native `--next` / `--pipeline` chaining | Manual chaining required |
 | Local model support | Ollama and LM Studio out of the box | Varies |
+| Coding agents as models | Claude Code, Codex and Copilot CLIs used like any other model, alone or in a crew | Not available |
 | Tool integration | RubyLLM tools + MCP server ecosystem | Limited |
 | Shell & ERB integration | Native — prompts are live Ruby/shell programs | External only |
 | Agent orchestration | Debate, spawn, verify, decompose, delegate directives | Not available |
@@ -74,15 +75,15 @@ For more information on AIA visit these locations:
 
 ```plain
 
-       ,      ,        AIA v2.0.0 is Online
+       ,      ,        AIA v2.1.0 is Online
        (\____/)
-        (_oo_)         Models: gpt-4o-mini
-         (O)               DB: refreshed 2026-03-19 at 10:56
-       __|||__    \)     Libs: ruby_llm v2.1.1, robot_lab v0.5.0, simple_flow v0.4.0,
-     [/ Tobor \]  /            trak_flow v0.2.0, typed_bus v0.0.1
-    / \_______/ \/      Tools: none loaded
-   /    /___\             MCP: (none configured)
-  (\   /_____\           Crew: @tobor
+        (_oo_)         Models: claude-sonnet-4-6
+         (O)               DB: refreshed 2026-11-01 at 22:28
+       __|||__    \)     Libs: ruby_llm v2.1.1, robot_lab v0.6.0, simple_flow v0.4.0, trak_flow v0.2.0, typed_bus v0.0.1
+     [/ Tobor \]  /     Tools: none loaded
+    / \_______/ \/        MCP: (none configured)
+   /    /___\            Crew: @tobor
+  (\   /_____\
      :::     :::
      :::     :::
 
@@ -175,6 +176,7 @@ Implement a schema registry with event-driven synchronization...
       - [Ollama Integration](#ollama-integration)
       - [LM Studio Integration](#lm-studio-integration)
       - [Listing Local Models](#listing-local-models)
+    - [Coding Agents as Models (Claude Code, Codex, Copilot)](#coding-agents-as-models-claude-code-codex-copilot)
     - [Shell Integration](#shell-integration)
     - [Embedded Ruby (ERB)](#embedded-ruby-erb)
     - [Prompt Sequences](#prompt-sequences)
@@ -296,7 +298,8 @@ aia --fuzzy
 | Option | Description | Example |
 |--------|-------------|---------|
 | `--chat` | Start interactive chat session | `aia --chat` |
-| `--model MODEL` | Specify AI model(s) to use. Supports `MODEL[=ROLE]` syntax | `aia --model gpt-4o-mini,gpt-3.5-turbo` or `aia --model gpt-4o=architect,claude=security` |
+| `--model MODEL` | Specify AI model(s) to use. Supports `MODEL[=ROLE]` syntax. A bare provider name (`claude_code`) means that provider's default model | `aia --model gpt-4o-mini,gpt-3.5-turbo` or `aia --model gpt-4o=architect,claude=security` |
+| `--provider SLUG` | Provider for models named without a `provider/` prefix. Also re-points models from `AIA_MODEL` or the config file at this provider, keeping their names. Scopes `--list-models` | `aia --provider ollama -m llama3.2` |
 | `--consensus` | Enable consensus mode for multi-model | `aia --consensus` |
 | `--no-consensus` | Force individual responses | `aia --no-consensus` |
 | `--role ROLE` | Use a role/system prompt (default for all models) | `aia --role expert` |
@@ -348,6 +351,8 @@ AIA determines configuration settings using this order (highest to lowest priori
 
 **Note:** When `-c` / `--config-file` is used, it replaces the user config and environment variables. Configuration resets to bundled defaults, then the specified file is applied, then CLI arguments take precedence.
 
+**`--provider` sets the provider, not the model.** Models named with `--model` and no `provider/` prefix get it. Models that came from `AIA_MODEL` or a config file get it too, replacing their own prefix but keeping their names, because the command line outranks both. So `--provider claude_code` with `AIA_MODEL=lms/qwen3.8` exported asks Claude Code for a model named `qwen3.8`. To use a provider's default model, name the provider as the model: `--model claude_code` means `claude_code/default`.
+
 ### Configuration Methods
 
 **Environment Variables:**
@@ -964,6 +969,46 @@ The `/available_models` directive (alias: `/models`) lists all models known to t
 - 📡 **Offline**: Works without internet connection
 - 🔧 **Control**: Full control over model and parameters
 
+### Coding Agents as Models (Claude Code, Codex, Copilot)
+
+An agent CLI can stand in for a model. With the matching
+`ruby_llm-providers-*` gem installed, the provider prefix sends the prompt to
+the agent's batch mode on stdin and reads its answer back from stdout. The
+agent keeps its own tools, settings and MCP servers and works in the current
+directory, so any aia prompt, pipeline or multi-model run can be driven by an
+agent that reads and edits files.
+
+| Prefix | Gem | CLI |
+|---|---|---|
+| `claude_code/` | `ruby_llm-providers-claude_code` | `claude -p` |
+| `codex/` | `ruby_llm-providers-codex` | `codex exec` |
+| `copilot/` | `ruby_llm-providers-copilot` | `copilot` (non-interactive) |
+
+```bash
+gem install ruby_llm-providers-claude_code
+
+# The part after the slash is the agent's --model; a bare prefix means its default
+aia --model claude_code/opus refactor_prompt
+aia --model claude_code my_prompt
+
+# --provider alone keeps the model name from AIA_MODEL or the config file and
+# hands it to the agent; for the agent's default model use --model as above
+aia --provider claude_code --model sonnet my_prompt
+
+# Chat keeps the agent's session alive between turns (--resume)
+aia --chat --model claude_code/sonnet
+
+# Cross-vendor review: one agent implements, another reviews
+aia --model claude_code/sonnet=implementer,codex/default=reviewer --consensus review_prompt
+
+aia --list-models --provider claude_code
+```
+
+Because the agent brings its own tools, aia's `--tools` and MCP servers are
+not attached to these robots (a one-line notice says so). Permissions, the
+working directory, timeouts and extra CLI flags are set through the gem's
+`RubyLLM.config.<provider>_*` options; see each gem's README.
+
 ### Shell Integration
 
 AIA automatically processes shell patterns in prompts:
@@ -1393,18 +1438,18 @@ mcp_servers:
 
 #### Verifying MCP Server Configuration
 
-When MCP servers are configured, AIA displays them in the startup robot:
+When MCP servers are configured, AIA lists them in the startup robot with each server's tool count in parentheses. Servers that failed to connect are named after `FAILED:`:
 
 ```
-       ,      ,        AIA v2.0.0 is Online
+       ,      ,        AIA v2.1.0 is Online
        (\____/)
-        (_oo_)         Models: gpt-4o-mini
-         (O)               DB: refreshed 2026-03-19 at 10:56
-       __|||__    \)     Libs: ruby_llm v2.1.1, robot_lab v0.5.0, simple_flow v0.4.0,
-     [/ Tobor \]  /            trak_flow v0.2.0, typed_bus v0.0.1
-    / \_______/ \/      Tools: 24 tools loaded
-   /    /___\             MCP: github, htm
-  (\   /_____\           Crew: @tobor
+        (_oo_)         Models: claude-sonnet-4-6
+         (O)               DB: refreshed 2026-11-01 at 22:28
+       __|||__    \)     Libs: ruby_llm v2.1.1, robot_lab v0.6.0, simple_flow v0.4.0, trak_flow v0.2.0, typed_bus v0.0.1
+     [/ Tobor \]  /     Tools: 109 tools loaded
+    / \_______/ \/        MCP: github(42), brew(14), redis(53) | FAILED: htm
+   /    /___\            Crew: @tobor
+  (\   /_____\
      :::     :::
      :::     :::
 

data/lib/aia/config/cli_parser.rb

@@ -99,8 +99,9 @@ module AIA
         end
 
         opts.on('--provider SLUG',
-                'Default provider for models given without a provider/ prefix; ' \
-                'also scopes --list-models (any RubyLLM-registered provider)') do |slug|
+                'Provider for models given without a provider/ prefix; also re-points ' \
+                'models from AIA_MODEL or the config file at it, keeping their names. ' \
+                'Scopes --list-models (any RubyLLM-registered provider)') do |slug|
           options[:provider] = slug
         end
 

data/lib/aia/config/model_spec.rb

@@ -13,6 +13,10 @@
 
 module AIA
   class ModelSpec
+    # The model id used when a bare provider name is given (e.g. `claude_code`):
+    # the provider's own default model.
+    DEFAULT_MODEL = 'default'
+
     attr_accessor :name, :role, :instance, :internal_id, :provider
 
     def initialize(hash = {})
@@ -76,18 +80,23 @@ module AIA
 
     private
 
-    # Extract a provider prefix from the model name. The prefix is a provider
-    # exactly when RubyLLM knows it (registered already, or loadable as a
+    # Extract a provider from the model name. "<provider>/<model-id>" splits
+    # on the slash; a bare "<provider>" with no slash names that provider's
+    # DEFAULT_MODEL, which is how agent-CLI providers such as claude_code,
+    # codex and copilot are usually given. The prefix is a provider exactly
+    # when RubyLLM knows it (registered already, or loadable as a
     # conventional ruby_llm-providers-<prefix> gem) — no provider names are
     # hardcoded here. Names whose first segment is not a provider (registry
-    # ids like "meta-llama/llama-4-maverick") pass through untouched.
+    # ids like "meta-llama/llama-4-maverick", plain ids like "gpt-4o") pass
+    # through untouched.
     def extract_provider_from_name!
-      return unless @name&.include?('/')
+      return if @name.nil?
 
       prefix, rest = @name.split('/', 2)
       return unless ProviderRegistry.available?(prefix)
+
       @provider = prefix
-      @name = rest
+      @name = rest || DEFAULT_MODEL
     end
   end
 end

data/lib/aia/config.rb

@@ -227,7 +227,7 @@ module AIA
       apply_models_env_var unless overrides[:models]
       apply_plugins_dir_env_var unless overrides[:plugins_dir]
       apply_overrides(overrides) if overrides && !overrides.empty?
-      apply_default_provider
+      apply_cli_provider(overrides.key?(:models) ? :fill : :replace)
       expand_paths
       process_mcp_files(overrides[:mcp_files]) if overrides[:mcp_files]
     end
@@ -382,13 +382,22 @@ module AIA
       end
     end
 
-    # `--provider SLUG` gives prefixless models a default provider. A model
-    # named with an explicit "<provider>/" prefix keeps its own.
-    def apply_default_provider
+    # `--provider SLUG` on the command line. Given together with --model
+    # (+mode+ :fill), it is the provider for the models named there without
+    # a "<provider>/" prefix; an explicit prefix keeps its own provider,
+    # since both values come from the command line. Given without --model
+    # (+mode+ :replace), the models from AIA_MODEL or the config file keep
+    # their names but take this provider, prefix or not, because a
+    # command-line flag outranks both.
+    #
+    # @param mode [Symbol] :fill or :replace
+    def apply_cli_provider(mode)
       return if provider.nil? || provider.to_s.empty?
 
       Array(models).each do |spec|
-        spec.provider ||= provider if spec.respond_to?(:provider)
+        next unless spec.respond_to?(:provider)
+
+        spec.provider = provider if mode == :replace || spec.provider.nil?
       end
     end
 

data/lib/aia/delegate_handler.rb

@@ -9,6 +9,9 @@
 # Decomposition is delegated to TaskDecomposer.
 # Step execution is delegated to TaskExecutor.
 
+require_relative 'task_decomposer'
+require_relative 'task_executor'
+
 module AIA
   class DelegateHandler
     include ContentExtractor

data/lib/aia/errors.rb

@@ -36,4 +36,8 @@ module AIA
 
   # Raised when all sub-tasks fail in SpecialModeHandler decompose mode
   class DecomposeError < Error; end
+
+  # Raised when a robot's LLM call fails during a batch (non-chat) pipeline
+  # step; robot_lab shields the exception into reply text, this surfaces it
+  class LLMError < Error; end
 end

data/lib/aia/llm_error_collector.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+# lib/aia/llm_error_collector.rb
+#
+# A robot_lab hook that remembers the exceptions robots raise while a
+# pipeline step runs. robot_lab's Network shields a robot's exception into
+# an "Error: ..." reply so one failing robot cannot crash the network, which
+# also hides the failure from aia: a batch run would print the error as the
+# answer and exit 0. The on_error hook fires before the shield, so the
+# PipelineOrchestrator can ask afterwards whether the step really failed.
+
+module AIA
+  class LLMErrorCollector < RobotLab::Hook
+    Entry = Data.define(:robot_name, :error) do
+      def to_s
+        prefix = robot_name.empty? ? '' : "#{robot_name}: "
+        "#{prefix}#{error.class}: #{error.message}"
+      end
+    end
+
+    @errors = []
+    @mutex  = Mutex.new
+
+    class << self
+      # Register the collector on +registry+ once. robot_lab's global
+      # registry (the default) is consulted by every Robot#run, including
+      # the robots a Network runs in parallel threads.
+      #
+      # @param registry [RobotLab::HookRegistry]
+      def install!(registry = RobotLab.hooks)
+        return if registry.registrations.any? { |reg| reg.handler_class == self }
+
+        registry.on(self)
+      end
+
+      # robot_lab hook: a robot run raised +ctx.error+.
+      #
+      # @param ctx [RobotLab::RunHookContext]
+      def on_error(ctx)
+        robot_name = ctx.respond_to?(:robot) ? ctx.robot&.name.to_s : ''
+        @mutex.synchronize { @errors << Entry.new(robot_name: robot_name, error: ctx.error) }
+      end
+
+      # Forget the errors of the previous step.
+      def reset!
+        @mutex.synchronize { @errors.clear }
+      end
+
+      # @return [Array<Entry>] the errors recorded since the last reset!
+      def errors
+        @mutex.synchronize { @errors.dup }
+      end
+
+      def errors?
+        !errors.empty?
+      end
+
+      # One line naming the prompt and every distinct error it hit.
+      #
+      # @param prompt_id [String]
+      # @return [String]
+      def message(prompt_id)
+        "LLM error in prompt '#{prompt_id}': #{errors.map(&:to_s).uniq.join('; ')}"
+      end
+    end
+  end
+end

data/lib/aia/pipeline_orchestrator.rb

@@ -38,6 +38,8 @@ module AIA
       bridge = config.flags.track_pipeline ? TrakFlowBridge.new : nil
       bridge&.create_plan_from_pipeline(config.pipeline)
 
+      LLMErrorCollector.install!
+
       until config.pipeline.empty?
         prompt_id = config.pipeline.shift
         next if prompt_id.nil? || prompt_id.empty?
@@ -69,7 +71,15 @@ module AIA
       # Front matter may have changed the model or its settings
       @robot = @robot_sync.call(@robot) if @robot_sync
 
+      LLMErrorCollector.reset!
+      if special_mode_handled?(prompt_text)
+        bridge&.update_step_status(prompt_id, :completed) unless llm_errors_handled?(prompt_id, bridge)
+        return
+      end
+
       result, content = compute_result(prompt_text, config)
+      return if llm_errors_handled?(prompt_id, bridge)
+
       bridge&.update_step_status(prompt_id, :completed)
 
       @tracker.record_turn(model: config.models.first.name, input: prompt_text, result: result)
@@ -79,6 +89,46 @@ module AIA
       raise
     end
 
+    # robot_lab shields a robot's exception into an "Error: ..." reply, so a
+    # failed LLM call comes back looking like an answer. The collector hook
+    # saw the real exception. Outside chat the step fails and aia exits 1
+    # (see AIA.run); in a chat session the error is shown and the session
+    # carries on. True when the step failed.
+    def llm_errors_handled?(prompt_id, bridge)
+      return false unless LLMErrorCollector.errors?
+
+      message = LLMErrorCollector.message(prompt_id)
+      raise AIA::LLMError, message unless AIA.chat?
+
+      @ui.display_info(message)
+      @ui.display_separator
+      bridge&.update_step_status(prompt_id, :failed, reason: message)
+      true
+    end
+
+    # A directive in the prompt (/debate, /verify, /decompose, /delegate,
+    # /spawn, /orchestrate) asked for a special mode: hand the turn to the
+    # SpecialModeHandler, as ChatLoop does. True when it ran the turn, which
+    # includes displaying, saving and recording it. Concurrent MCP is left
+    # to execute_prompt, which honors it alongside config.concurrency.auto.
+    # A --paint step has no robot turn to hand over.
+    def special_mode_handled?(prompt_text)
+      return false if AIA.paint? || !special_mode_requested?
+
+      special_mode_handler.robot = @robot
+      special_mode_handler.handle(prompt_text)
+    end
+
+    # True when the turn state holds a mode for SpecialModeHandler to run.
+    def special_mode_requested?
+      mode = AIA.turn_state.active_mode
+      !mode.nil? && mode != :concurrent_mcp
+    end
+
+    def special_mode_handler
+      @special_mode_handler ||= SpecialModeHandler.new(robot: @robot, ui_presenter: @ui, tracker: @tracker)
+    end
+
     # Show a step's response, then save and speak it. A --paint step saved
     # an image next to the output file, so there is no text to keep or speak.
     def present_result(content, result, config)
@@ -108,16 +158,16 @@ module AIA
       img_cfg = config.image
       quality = img_cfg.quality
       style   = img_cfg.style
-      params  = {}
-      params[:quality] = quality if quality && !quality.to_s.strip.empty?
-      params[:style]   = style   if style   && !style.to_s.strip.empty?
+      provider_options = {}
+      provider_options[:quality] = quality if quality && !quality.to_s.strip.empty?
+      provider_options[:style]   = style   if style   && !style.to_s.strip.empty?
 
       image = @ui.with_spinner("Generating image") do
         RubyLLM.paint(
           prompt_text,
-          model:  img_cfg.model || 'gpt-image-1',
-          size:   img_cfg.size  || '1024x1024',
-          params: params
+          model: img_cfg.model || 'gpt-image-1',
+          size:  img_cfg.size  || '1024x1024',
+          provider_options:
         )
       end
 

data/lib/aia/prompt_handler.rb

@@ -22,6 +22,9 @@ module AIA
       'erb'         => [%w[config erb], %w[config flags erb]]
     }.freeze
 
+    # Front matter `mode:` names that differ from their TurnState mode.
+    MODE_SHORTHANDS = { 'concurrent' => :concurrent_mcp }.freeze
+
     def initialize
       @prompts_dir = AIA.config.prompts.dir
 
@@ -36,6 +39,22 @@ module AIA
       register_pm_directives
     end
 
+    # The TurnState mode a front matter `mode:` +value+ names: a chat
+    # directive's name without the slash (debate, verify, decompose,
+    # delegate, spawn, orchestrate, concurrent).
+    #
+    # @param value [String, Symbol]
+    # @return [Symbol] one of TurnState::EXCLUSIVE_MODES
+    # @raise [ConfigurationError] for a name that is not a mode
+    def self.mode_for(value)
+      name = value.to_s.strip.downcase
+      mode = MODE_SHORTHANDS.fetch(name, name.to_sym)
+      return mode if TurnState::EXCLUSIVE_MODES.include?(mode)
+
+      names = (TurnState::EXCLUSIVE_MODES - MODE_SHORTHANDS.values).map(&:to_s) + MODE_SHORTHANDS.keys
+      raise ConfigurationError, "Unknown mode: #{value.inspect} (one of #{names.sort.join(', ')})"
+    end
+
     # A shell/erb flag is on unless it is explicitly false.
     #
     # @param flags [#shell, #erb, nil]
@@ -212,6 +231,11 @@ module AIA
 
       erb_val = shorthand(meta_hash, :erb)
       cfg.flags.erb = erb_val unless erb_val.nil?
+
+      # mode → the special mode for this prompt's turn, as the chat
+      # directive of that name (/debate, /verify, ...) would request it
+      mode_val = shorthand(meta_hash, :mode)
+      AIA.turn_state.request(self.class.mode_for(mode_val)) if mode_val
     end
 
     # Fetch a front-matter shorthand value by string or symbol key.

data/lib/aia/provider_registry.rb

@@ -37,7 +37,9 @@ module AIA
     # Attempt to require the conventional gem path for a provider slug.
     # Returns true when the provider ends up registered. Failed lookups are
     # cached so repeated non-provider prefixes (model ids also use "/")
-    # don't pay the require cost every time.
+    # don't pay the require cost every time. When the plain require fails
+    # because aia runs under Bundler and the gem is installed but not in the
+    # Gemfile, the gem is sideloaded from the RubyGems search path.
     def load(slug)
       slug = slug.to_s
       return false unless slug.match?(/\A[a-z0-9_]+\z/)
@@ -50,22 +52,71 @@ module AIA
           require "ruby_llm/providers/#{slug}"
           registered?(slug)
         rescue LoadError
-          false
+          sideload(slug)
         end
     end
 
+    # Load an installed `ruby_llm-providers-<slug>` gem that the active
+    # bundle hides. Under Bundler only the Gemfile's gems can be required,
+    # so a provider gem added with `gem install` is invisible to a plain
+    # require even though it sits on disk. This finds its gemspec on the
+    # RubyGems search path and, when every runtime dependency it declares is
+    # already satisfied by the bundle, adds its lib directory to the load
+    # path and requires it. The bundle itself is not changed. Returns true
+    # when the provider ends up registered.
+    def sideload(slug)
+      spec = installed_spec(slug)
+      return false unless spec
+
+      unmet = spec.runtime_dependencies.reject { |dep| dependency_met?(dep) }
+      unless unmet.empty?
+        AIA.debug_warn("#{spec.full_name} is installed but needs #{unmet.join(', ')}, which this bundle does not provide")
+        return false
+      end
+
+      spec.full_require_paths.each { |dir| $LOAD_PATH.unshift(dir) unless $LOAD_PATH.include?(dir) }
+      require "ruby_llm/providers/#{slug}"
+      registered?(slug)
+    rescue LoadError
+      false
+    end
+
+    # The newest installed gemspec for `ruby_llm-providers-<slug>`, read from
+    # the specifications directories on the RubyGems search path, or nil.
+    # Reads the files directly, so it sees gems the bundle does not.
+    def installed_spec(slug)
+      name = "ruby_llm-providers-#{slug}"
+      Gem.path
+         .flat_map { |dir| Dir[File.join(dir, 'specifications', "#{name}-*.gemspec")] }
+         .filter_map { |file| Gem::Specification.load(file) }
+         .select { |spec| spec.name == name }
+         .max_by(&:version)
+    end
+
+    # Whether a gem dependency is satisfied by a gem already active in this
+    # process (under Bundler, that is the bundle).
+    def dependency_met?(dep)
+      active = Gem.loaded_specs[dep.name]
+      !active.nil? && dep.requirement.satisfied_by?(active.version)
+    end
+
     # A provider instance ready for API calls (model listing etc.).
     # Raises RubyLLM's own errors for unknown or unconfigured providers.
     def instantiate(slug)
       RubyLLM::Provider.resolve!(slug.to_sym).new(RubyLLM.config)
     end
 
-    # Slugs of conventionally named provider gems visible to the bundle
-    # (ruby_llm-providers-<slug>), whether or not they are loaded yet.
+    # Slugs of conventionally named provider gems (ruby_llm-providers-<slug>)
+    # that are installed, whether in the bundle or only on the RubyGems
+    # search path, and whether or not they are loaded yet.
     def installed_gem_slugs
-      Gem::Specification.filter_map do |spec|
-        spec.name.delete_prefix('ruby_llm-providers-') if spec.name.start_with?('ruby_llm-providers-')
-      end.uniq
+      prefix = 'ruby_llm-providers-'
+      bundled = Gem::Specification.map(&:name)
+      on_disk = Gem.path.flat_map { |dir| Dir[File.join(dir, 'specifications', "#{prefix}*.gemspec")] }
+                   .map { |file| File.basename(file, '.gemspec').sub(/-[^-]+\z/, '') }
+      (bundled + on_disk).select { |name| name.start_with?(prefix) }
+                         .map { |name| name.delete_prefix(prefix) }
+                         .uniq
     end
 
     # Register every installed conventional provider gem, so a full listing

data/lib/aia/robot_factory.rb

@@ -243,9 +243,49 @@ module AIA
       # @return [RobotLab::Robot]
       def build_robot(spec, **opts)
         opts[:provider] = resolve_provider(spec) if spec.provider
+        opts = without_tools(spec, opts) unless provider_accepts_tools?(spec.provider)
         RobotLab.build(model: spec.name, **opts)
       end
 
+      # Whether a provider can take RubyLLM tools. Agent-CLI providers
+      # (claude_code, codex, copilot) run their own tools and say so with a
+      # class-level `accepts_tools?` returning false; every other provider
+      # accepts tools. Nothing is hardcoded here — the provider class decides.
+      #
+      # @param provider [String, nil] a RubyLLM provider slug
+      # @return [Boolean]
+      def provider_accepts_tools?(provider)
+        klass = provider && ProviderRegistry.providers[provider.to_s]
+        return true unless klass.respond_to?(:accepts_tools?)
+
+        klass.accepts_tools?
+      end
+
+      # Strip the tools and MCP servers from a robot's build options for a
+      # provider that brings its own, telling the user once per provider what
+      # was left out so a `--tools` or `--mcp-use` that silently did nothing
+      # is not a mystery.
+      #
+      # @param spec [AIA::ModelSpec]
+      # @param opts [Hash] RobotLab.build options
+      # @return [Hash] opts with empty local_tools: and mcp:
+      def without_tools(spec, opts)
+        dropped = []
+        dropped << 'tools' if opts[:local_tools]&.any?
+        dropped << 'MCP servers' if opts[:mcp]&.any?
+        notice_tools_dropped(spec.provider, dropped) unless dropped.empty?
+        opts.merge(local_tools: [], mcp: [])
+      end
+
+      # One notice per provider per process.
+      def notice_tools_dropped(provider, dropped)
+        @tools_dropped_notices ||= {}
+        return if @tools_dropped_notices[provider]
+
+        @tools_dropped_notices[provider] = true
+        AIA.debug_warn("#{provider} runs its own tools; aia #{dropped.join(' and ')} are not attached to it")
+      end
+
       # Resolve a spec's provider to a RubyLLM provider slug. Slugs pass
       # through unchanged — RubyLLM's registry is the single source of truth —
       # but the method stays as the seam where optional provider gems get
@@ -265,10 +305,23 @@ module AIA
 
         AIA.debug_warn(
           "provider '#{provider}' is not registered with RubyLLM and no " \
-          "ruby_llm/providers/#{provider} library could be loaded"
+          "ruby_llm/providers/#{provider} library could be loaded#{bundler_hint(provider)}"
         )
       end
 
+      # Under Bundler only the gems in the Gemfile can be required, so a
+      # provider gem installed with `gem install` stays invisible. Name the
+      # Gemfile to add it to; outside Bundler there is nothing to add.
+      #
+      # @param provider [String] a provider slug
+      # @param gemfile [String, nil] the active Gemfile; nil when not under Bundler
+      # @return [String] text to append to the warning, "" outside Bundler
+      def bundler_hint(provider, gemfile = ENV.fetch('BUNDLE_GEMFILE', nil))
+        return '' if gemfile.nil? || gemfile.empty?
+
+        "; aia is running under Bundler, so add gem 'ruby_llm-providers-#{provider}' to #{gemfile}"
+      end
+
       private
 
       # Configure RobotLab providers from AIA config

data/lib/aia/special_mode_handler.rb

@@ -253,8 +253,6 @@ module AIA
     def delegate_handler
       @delegate_handler ||= begin
         require_relative 'delegate_handler'
-        require_relative 'task_decomposer'
-        require_relative 'task_executor'
         DelegateHandler.new(
           robot: @robot, ui_presenter: @ui_presenter,
           tracker: @tracker, task_coordinator: AIA.task_coordinator

data/lib/aia/tools/delegate_to_foreman_tool.rb

@@ -7,6 +7,8 @@
 # with full TaskBoardTool access. Foreman is built on first use
 # and cached for the session.
 
+require_relative 'task_board_tool'
+
 module AIA
   class DelegateToForemanTool < RubyLLM::Tool
     description "Delegate a task management request to Foreman, the task board manager. " \

data/lib/aia/version.rb

@@ -1,5 +1,5 @@
 # lib/aia/version.rb
 
 module AIA
-  VERSION = '2.0.1'.freeze
+  VERSION = '2.1.0'.freeze
 end

data/lib/aia.rb

@@ -73,6 +73,7 @@ require_relative 'aia/mention_router'
 require_relative 'aia/special_mode_handler'
 require_relative 'aia/mcp_connection_manager'
 require_relative 'aia/startup_coordinator'
+require_relative 'aia/llm_error_collector'
 require_relative 'aia/pipeline_orchestrator'
 require_relative 'aia/chat_loop'
 require_relative 'aia/session'
@@ -185,16 +186,23 @@ module AIA
       RobotFactory.setup(@config)
       load_fzf_integration
       start_session
-    rescue AIA::ConfigurationError => e
-      $stderr.puts e.message
-      exit 1
     rescue AIA::Error => e
-      $stderr.puts e.message
-      exit 1
+      fail_run(e.message)
+    rescue RubyLLM::Error, RubyLLM::ConfigurationError => e
+      # An LLM failure that nothing shielded (image generation, provider setup)
+      fail_run("LLM error: #{e.class}: #{e.message}")
     end
 
     private
 
+    # Print a one-line fatal error to stderr and exit 1.
+    #
+    # @param message [String]
+    def fail_run(message)
+      $stderr.puts message
+      exit 1
+    end
+
     # Record startup in all three log files. Only aia.log gets the full
     # configuration dump; llm.log and mcp.log just note that AIA started,
     # since their configuration is already covered by the aia.log entry.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: aia
 version: !ruby/object:Gem::Version
-  version: 2.0.1
+  version: 2.1.0
 platform: ruby
 authors:
 - Dewayne VanHoozer
@@ -331,6 +331,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: ostruct
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -401,16 +415,17 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: 'AIA is a powerful CLI console application that brings multi-model AI
-  capabilities to your command line, supporting 20+ providers including OpenAI, Anthropic,
-  and Google. Built on robot_lab for robust robot orchestration, AIA v2 provides a
-  thin CLI shell over a rich execution engine. Run multiple AI models simultaneously
-  for comparison, get consensus responses from collaborative AI teams, or compare
-  individual outputs side-by-side. With dynamic prompt management, embedded directives,
-  shell and Ruby integration, interactive chats, and comprehensive history tracking,
-  AIA transforms how you interact with AI.
+description: |
+  AIA runs large language models from the terminal. Prompts are Markdown files with YAML front matter: parameters
+  that AIA asks for, directives such as /include and /shell, ERB and shell expansion, and keys that pick the model,
+  temperature or a special mode. Run a prompt once, chain prompts into a pipeline, make a prompt file executable,
+  or open an interactive chat with history, checkpoints and skills.
 
-  '
+  Every session is a crew of robots built on robot_lab. Name several models to compare them side by side, ask for a
+  consensus or a debate, have two independent answers reconciled with /verify, or decompose and delegate work to
+  specialists. Robots use RubyLLM tools and MCP servers through ruby_llm 2.1's built-in client, with per-tool
+  approval and automatic tool filtering. Any provider RubyLLM registers can be used, local or remote, plus optional
+  ruby_llm-providers-* gems that run Claude Code, Codex or GitHub Copilot as models. Requires Ruby 4.0.9 or newer.
 email:
 - dvanhoozer@gmail.com
 executables:
@@ -456,6 +471,7 @@ files:
 - lib/aia/history_transfer.rb
 - lib/aia/input_collector.rb
 - lib/aia/layered_orchestrator.rb
+- lib/aia/llm_error_collector.rb
 - lib/aia/logger.rb
 - lib/aia/mcp_config_normalizer.rb
 - lib/aia/mcp_connection_manager.rb
@@ -533,12 +549,14 @@ metadata:
 post_install_message: |2+
 
   ╔══════════════════════════════════════════════════════════════╗
-  ║               AIA — AI Assistant v2.0                        ║
+  ║                  AIA — AI Assistant v2.1.0                   ║
   ║                                                              ║
-  ║  v2 is powered by robot_lab for robust orchestration         ║
+  ║  Prompts as Markdown, crews of robots, MCP servers, and      ║
+  ║  any RubyLLM provider, including coding-agent CLIs.          ║
   ╚══════════════════════════════════════════════════════════════╝
 
   Get started:  aia --help
+  What is new:  https://github.com/MadBomber/aia/blob/main/CHANGELOG.md
   Full docs:    https://madbomber.github.io/aia
 
 rdoc_options: []
@@ -557,7 +575,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.23
 specification_version: 4
-summary: Multi-model AI CLI with dynamic prompts, consensus responses, shell & Ruby
-  integration, and seamless chat workflows.
+summary: 'Command-line AI assistant: Markdown prompts with directives, ERB and shell,
+  chat with crews of robots, MCP servers, and any RubyLLM provider including coding-agent
+  CLIs.'
 test_files: []
 ...