x_aeon_agents 2.8.1 → 2.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4c95fbf7ea4fb512819b0462de5b1fd7345421fb33f7e4d016d4cd6897b66415
-  data.tar.gz: 92d92a27cf1aaec21544b282c41b14b42deea2d5e0389685f3c2d9303a681c4b
+  metadata.gz: 65a34b357014c65f6925fabe32e192a1070f0e87840967910921aa0e6aa89bc9
+  data.tar.gz: 5966f1f1c4d5bf986c2287b5bc07783f8d58f95a6abf2163ba8fb933bc5e609c
 SHA512:
-  metadata.gz: f1957d9fa88264eb0db84d5f99e46e75275d49bbe91dbf386b1b7fecd020a75ad87faf376c361f9c8a96b090f0d9724dec85e18345ab5ada403cd8096fde2a3a
-  data.tar.gz: 7966f5edbc3a73ccda0986b2703f392c9eae7842292504c6c958c315e7026a7362631665bb599969ae59496493c280161ad933fc317e222e3aad88c1d76bef3a
+  metadata.gz: c83f42f410a60e3aa2b7ff70b2e951fa43a7609b776261fff6e607c36630d65a8d2f6dc3f88c304313f251c975e7135fa6f6d256b3fad8d6ea60b98d3449ae3f
+  data.tar.gz: b116642387232b0467145d20327be1650afe717d8e4c0b5e3f8c210dbf91fd1b1069e291d23f31e8708f706f4fba83885e52e85f1e28a0496b522aa8fe6861d1

data/CHANGELOG.md

@@ -1,3 +1,25 @@
+# [v2.9.0](https://github.com/Muriel-Salvan/x_aeon_agents/compare/v2.8.1...v2.9.0) (2026-11-13 11:26:58)
+
+## Global changes
+### Patches
+
+* [feat(cline): constrain agent prompts, filter unused tools and bound runs with default timeout/retries](https://github.com/Muriel-Salvan/x_aeon_agents/commit/cae5e014c5f8c00212b74aa68609a5f0e94aadd3)
+
+## Changes for agent_defaults
+### Features
+
+* [feat(cline): constrain agent prompts, filter unused tools and bound runs with default timeout/retries](https://github.com/Muriel-Salvan/x_aeon_agents/commit/cae5e014c5f8c00212b74aa68609a5f0e94aadd3)
+
+## Changes for agents
+### Features
+
+* [feat(cline): constrain agent prompts, filter unused tools and bound runs with default timeout/retries](https://github.com/Muriel-Salvan/x_aeon_agents/commit/cae5e014c5f8c00212b74aa68609a5f0e94aadd3)
+
+## Changes for cline
+### Features
+
+* [feat(cline): constrain agent prompts, filter unused tools and bound runs with default timeout/retries](https://github.com/Muriel-Salvan/x_aeon_agents/commit/cae5e014c5f8c00212b74aa68609a5f0e94aadd3)
+
 # [v2.8.1](https://github.com/Muriel-Salvan/x_aeon_agents/compare/v2.8.0...v2.8.1) (2026-11-12 17:54:34)
 
 ### Patches

data/README.md

@@ -327,8 +327,8 @@ Files are looked up in the following locations and evaluated from the lowest pri
 - **`configure_agent(agent_class_name) { |agent_config| ... }`** — define the default kwargs to be merged when initializing agents of a given class (e.g. `:CoderAgent`). The block is evaluated every time an agent of this class is instantiated: it is given the currently merged configuration (a Hash of kwargs, that can be modified in place), and returns a Hash of additional kwargs merged on top. It is re-entrant: it can be called several times for the same class, from the same file or from different ones (global, project, env-var designated), each call seeing the configuration accumulated by the previous ones. Typical kwargs keys (as used by the agent frameworks):
   - `skills` — Array of skill names the agent should follow
   - `model` — LLM model to use (e.g. `'deepseek/deepseek-v4-flash'`)
-  - `cli_options` — Hash of options merged into the Cline CLI invocation (e.g. `plan: true`)
-  - `configure_global` — Proc given the Cline global settings to tweak
+  - `cli_options` — Hash of options merged into the Cline CLI invocation (e.g. `plan: true`). Cline agents always get `timeout: 600` (10 minutes) and `retries: 5` by default; options given here supersede them option by option (`nil` disables one)
+  - `configure_global` — Proc given the Cline global settings to tweak. Whatever it configures, the Cline tools that X-Aeon agents don't use (agent spawning and team management tools) are always disabled, as is `ask_question` when `interactive` is off; lists are merged without duplicates
 
   ```ruby
   configure_agent(:PlanGeneratorAgent) do |agent_config|
@@ -461,7 +461,8 @@ Each capability is implemented by an `Agents::*Agent` class built on `composable
 Every agent is enriched by the [`AgentDefaults`](https://github.com/Muriel-Salvan/x_aeon_agents/blob/main/lib/x_aeon_agents/agent_defaults.rb) mixin, which:
 
 - injects `new_agent`, `task`, `step` and `step_agent` to build multi-step pipelines;
-- auto-configures the frameworks (`setup_composable_agents`, `setup_ai_agents`, `setup_cline`) and injects per-class defaults (overridable with the `configure_agent` config DSL);
+- auto-configures the frameworks (`setup_composable_agents`, `setup_ai_agents`, `setup_cline`) and injects per-class defaults (overridable with the `configure_agent` config DSL); for Cline agents, it also injects `timeout: 600` and `retries: 5` CLI options to bound every run (configured options supersede them);
+- disables the Cline tools that X-Aeon agents don't use (agent spawning, team management, and `ask_question` in non-interactive mode) in the Cline global settings, merging them without duplicates with the ones configured by `configure_global`;
 - enforces **input/output artifact contracts** and adds **resume** support (via the `ArtifactContract` + `Resumable` mixins);
 - gives each agent a per-session directory under `Config.data_dir/sessions/<id>`.
 

data/TODO.md

@@ -1,3 +1,4 @@
+* Fix the tokens metrics that seem to be wrong with Cline.
 * Consider remove the checklists from MarkdownHeavy (maybe having MarkdownFiles?).
 * Embed TaskStarter as an option to implement-issue CLI.
 * Add a --tdd option to implement-issue and use a TddAgent in place of DeveloperAgent.

data/lib/x_aeon_agents/agent_defaults.rb

@@ -63,6 +63,9 @@ module XAeonAgents
             AgentDefaults.root_agents << self if parent_agent.nil?
             # If we inherit from some frameworks initialize them now.
             Config.setup_composable_agents
+            # Possible transformation applied to the agent's kwargs once the framework defaults,
+            # the config DSL procs and the explicitly given kwargs are merged.
+            kwargs_processor = proc { |agent_kwarg_hash| agent_kwarg_hash }
             kwargs_from_agent_defaults =
               case self
               when ComposableAgents::AiAgents::Agent
@@ -72,9 +75,51 @@ module XAeonAgents
                 }
               when ComposableAgents::Cline::Agent
                 Config.setup_cline
+                # Default Cline CLI options bounding every agent run: no run can stall forever,
+                # and consecutive mistakes are limited. Configured options supersede them.
+                default_cline_cli_options = { timeout: 600, retries: 5 }
+                # Whatever Cline global settings are configured (through the config DSL or explicitly),
+                # always disable the Cline tools that are not used by X-Aeon agents: agents are
+                # orchestrated by ComposableAgents (letting an LLM spawn agents or manage teams would
+                # bypass this orchestration), and no human user answers questions in non-interactive mode.
+                # Merge these tools with the configured ones, without duplicates.
+                kwargs_processor = proc do |cline_agent_kwargs|
+                  configured_global_settings = cline_agent_kwargs[:configure_global]
+                  cline_agent_kwargs[:configure_global] = proc do |global_settings|
+                    configured_global_settings&.call(global_settings)
+                    disabled_tools = %w[
+                      spawn_agent
+                      team_attach_outcome_fragment
+                      team_await_runs
+                      team_broadcast
+                      team_cancel_run
+                      team_cleanup
+                      team_create_outcome
+                      team_finalize_outcome
+                      team_list_outcomes
+                      team_list_runs
+                      team_mission_log
+                      team_read_mailbox
+                      team_review_outcome_fragment
+                      team_run_task
+                      team_send_message
+                      team_shutdown_teammate
+                      team_spawn_teammate
+                      team_status
+                      team_task
+                      teams
+                    ]
+                    disabled_tools << 'ask_question' unless Config.interactive
+                    global_settings.disabled_tools = disabled_tools | Array(global_settings.disabled_tools)
+                  end
+                  # Always bound Cline runs, while letting the configured CLI options supersede the
+                  # defaults option by option (a nil value disables a default, as cline-rb skips nil options).
+                  cline_agent_kwargs[:cli_options] = default_cline_cli_options.merge(cline_agent_kwargs[:cli_options] || {})
+                  cline_agent_kwargs
+                end
                 {
                   api_key: Config.cline_api_key,
-                  cli_options: Config.default_cline_cli_args,
+                  cli_options: Config.default_cline_cli_args.merge(default_cline_cli_options),
                   strategy: ComposableAgents::PromptRenderingStrategy::MarkdownHeavyFiles
                 }
               else
@@ -87,7 +132,7 @@ module XAeonAgents
             @session_id = session_id || AgentDefaults.singleton_session_id
             @session_dir = "#{Config.data_dir}/sessions/#{@session_id}"
             run_id = "#{@session_id}-#{kwargs[:name] || self.class.name.split('::').last}"
-            agent_kwargs = kwargs_from_config.merge(kwargs)
+            agent_kwargs = kwargs_processor.call(kwargs_from_config.merge(kwargs))
             # TODO: Redesign how prompt rendering strategies are initialized with regard to the constructors and remove
             #   this code smell.
             # The prompt rendering strategy is included in the agent's singleton class by PromptDrivenAgent's

data/lib/x_aeon_agents/agents/coder_agent.rb

@@ -73,6 +73,7 @@ module XAeonAgents
             EO_CONSTRAINT
             '- Always verify the files you have edited or created at the end of the task to ensure they are completed and working as expected.',
             Helpers.repository_access_constraint(writable: true),
+            Helpers.cline_tools_constraint,
             Helpers.non_interactive_constraint,
             '',
             'REMEMBER, be helpful and proactive!',

data/lib/x_aeon_agents/agents/documenter_agent.rb

@@ -56,6 +56,7 @@ module XAeonAgents
             '- Documentation describes the CURRENT STATE only.',
             '- Documentation is NOT a changelog.',
             Helpers.repository_access_constraint(writable: true),
+            Helpers.cline_tools_constraint,
             Helpers.non_interactive_constraint
           ].compact.join("\n"),
           **agent_params

data/lib/x_aeon_agents/agents/feedback_analyst_agent.rb

@@ -66,6 +66,7 @@ module XAeonAgents
           '- Write the extracted requirements to the output artifact file given in this prompt.',
           '- If no implementation is required, write exactly `No requirements` in this file.',
           Helpers.repository_access_constraint,
+          Helpers.cline_tools_constraint,
           Helpers.artifacts_access_constraint(artifact_ref(:requirements)),
           Helpers.non_interactive_constraint
         ].compact.join("\n")

data/lib/x_aeon_agents/agents/plan_generator_agent.rb

@@ -53,6 +53,7 @@ module XAeonAgents
           '- You may only analyze and propose plans.',
           '- Do NOT execute the plan yourself.',
           Helpers.repository_access_constraint,
+          Helpers.cline_tools_constraint,
           Helpers.artifacts_access_constraint(artifact_ref(:plan)),
           Helpers.non_interactive_constraint
         ].compact.join("\n")

data/lib/x_aeon_agents/agents/readme/about_analyzer_agent.rb

@@ -57,6 +57,7 @@ module XAeonAgents
                 Do not try to document other parts.
             EO_CONSTRAINT
             Helpers.repository_access_constraint,
+            Helpers.cline_tools_constraint,
             Helpers.artifacts_access_constraint(artifact_ref(:about), artifact_ref(:name), artifact_ref(:description)),
             Helpers.non_interactive_constraint
           ].compact.join("\n")

data/lib/x_aeon_agents/agents/readme/contributing_agent.rb

@@ -49,6 +49,7 @@ module XAeonAgents
             '- Do not describe the technical setup or prequisites, as they are already covered by other sections.',
             '- Do not cover how to develop in this project: it is already covered in other sections.',
             Helpers.repository_access_constraint,
+            Helpers.cline_tools_constraint,
             Helpers.artifacts_access_constraint(artifact_ref(:contributing)),
             Helpers.non_interactive_constraint
           ].compact.join("\n")

data/lib/x_aeon_agents/agents/readme/development_agent.rb

@@ -56,6 +56,7 @@ module XAeonAgents
             '- Do not cover the end-user main requirements and prerequisites: they are already covered in other sections.',
             '- Do not cover the contribution workflow (pull requests, CI, issues...): this is already covered in other sections.',
             Helpers.repository_access_constraint,
+            Helpers.cline_tools_constraint,
             Helpers.artifacts_access_constraint(artifact_ref(:development)),
             Helpers.non_interactive_constraint
           ].compact.join("\n")

data/lib/x_aeon_agents/agents/readme/documentation_agent.rb

@@ -45,6 +45,7 @@ module XAeonAgents
                 Do not try to document other parts.
             EO_CONSTRAINT
             Helpers.repository_access_constraint,
+            Helpers.cline_tools_constraint,
             Helpers.artifacts_access_constraint(artifact_ref(:documentation)),
             Helpers.non_interactive_constraint
           ].compact.join("\n")

data/lib/x_aeon_agents/agents/readme/features_agent.rb

@@ -47,6 +47,7 @@ module XAeonAgents
                 Do not try to document other parts.
             EO_CONSTRAINT
             Helpers.repository_access_constraint,
+            Helpers.cline_tools_constraint,
             Helpers.artifacts_access_constraint(artifact_ref(:features)),
             Helpers.non_interactive_constraint
           ].compact.join("\n")

data/lib/x_aeon_agents/agents/readme/how_it_works_agent.rb

@@ -49,6 +49,7 @@ module XAeonAgents
             EO_CONSTRAINT
             '- Do not provide long paragraphs: focus on readability by splitting long paragraphs into several short ones.',
             Helpers.repository_access_constraint,
+            Helpers.cline_tools_constraint,
             Helpers.artifacts_access_constraint(artifact_ref(:how_it_works)),
             Helpers.non_interactive_constraint
           ].compact.join("\n")

data/lib/x_aeon_agents/agents/readme/license_agent.rb

@@ -45,6 +45,7 @@ module XAeonAgents
                 Do not try to document other parts.
             EO_CONSTRAINT
             Helpers.repository_access_constraint,
+            Helpers.cline_tools_constraint,
             Helpers.artifacts_access_constraint(artifact_ref(:license)),
             Helpers.non_interactive_constraint
           ].compact.join("\n")

data/lib/x_aeon_agents/agents/readme/public_api_agent.rb

@@ -46,6 +46,7 @@ module XAeonAgents
             EO_CONSTRAINT
             '- Only document public API entry points: executables and library public methods belonging to yarn `Public API` group.',
             Helpers.repository_access_constraint,
+            Helpers.cline_tools_constraint,
             Helpers.artifacts_access_constraint(artifact_ref(:public_api)),
             Helpers.non_interactive_constraint
           ].compact.join("\n")

data/lib/x_aeon_agents/agents/readme/quick_start_agent.rb

@@ -52,6 +52,7 @@ module XAeonAgents
             EO_CONSTRAINT
             "- This section is not meant for developers: don't describe how to develop, test, document, package or contribute to this project.",
             Helpers.repository_access_constraint,
+            Helpers.cline_tools_constraint,
             Helpers.artifacts_access_constraint(artifact_ref(:quick_start)),
             Helpers.non_interactive_constraint
           ].compact.join("\n")

data/lib/x_aeon_agents/agents/readme/requirements_agent.rb

@@ -45,6 +45,7 @@ module XAeonAgents
                 Do not try to document other parts.
             EO_CONSTRAINT
             Helpers.repository_access_constraint,
+            Helpers.cline_tools_constraint,
             Helpers.artifacts_access_constraint(artifact_ref(:requirements)),
             Helpers.non_interactive_constraint
           ].compact.join("\n")

data/lib/x_aeon_agents/agents/review_responder_agent.rb

@@ -73,6 +73,7 @@ module XAeonAgents
           '- You MUST NOT ask for user confirmation.',
           "- Write the reply text to the output artifact file `#{artifact_ref(:reply)}`.",
           Helpers.repository_access_constraint,
+          Helpers.cline_tools_constraint,
           Helpers.artifacts_access_constraint(artifact_ref(:reply)),
           Helpers.non_interactive_constraint
         ].compact.join("\n")

data/lib/x_aeon_agents/agents/tester_agent.rb

@@ -61,6 +61,7 @@ module XAeonAgents
         )
         self.constraints = [
           Helpers.repository_access_constraint(writable: true),
+          Helpers.cline_tools_constraint,
           Helpers.artifacts_access_constraint(artifact_ref(:plan_modifications)),
           Helpers.non_interactive_constraint
         ].compact.join("\n")

data/lib/x_aeon_agents/helpers.rb

@@ -197,6 +197,21 @@ module XAeonAgents
           'so proceed using your best judgment without asking'
       end
 
+      # Get the constraint explaining how to use the tools that are available to agents of the Cline kind.
+      # Constraints are rendered as Markdown bullet lists: the returned sentences include their own bullet prefixes.
+      #
+      # @return [String] The constraint about using the tools available to Cline agents
+      def cline_tools_constraint
+        <<~EO_CONSTRAINT.rstrip
+          - The `run_commands` tool takes ONE shell script as a plain string.
+            - NEVER wrap it in `[ ]` or JSON.
+            - One command per call; chain commands with `&&` only on one line.
+            - Never use multi-line heredocs.
+          - Always use the `editor` tool to write files.
+          - You are a single agent: there is no team. NEVER call `team_*` tools: they will fail and count as mistakes.
+        EO_CONSTRAINT
+      end
+
       # Allow user to review and edit content before using it
       #
       # When the interactive mode is disabled (Config.interactive), no review file

data/lib/x_aeon_agents/version.rb

@@ -2,5 +2,5 @@ module XAeonAgents
   # @!group Global API
 
   # Gem version
-  VERSION = '2.8.1'
+  VERSION = '2.9.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: x_aeon_agents
 version: !ruby/object:Gem::Version
-  version: 2.8.1
+  version: 2.9.0
 platform: ruby
 authors:
 - Muriel Salvan