UAT: `ToolRunner` `SPECIFIC` execution environment mode does not forward `target_resource` to container executor — specific container routing is non-functional #2134

New issue

Open

opened 2026-04-03 04:21:20 +00:00 by freemo · 1 comment

freemo commented

2026-04-03 04:21:20 +00:00

Owner

Metadata

Branch: fix/tool-runner-specific-mode-target-resource-forwarding
Commit Message: fix(tool): forward target_resource in ToolRunner SPECIFIC mode to resolver and container executor
Milestone: v3.7.0
Parent Epic: #398

Background and Context

The spec (§Tool Capability Metadata) defines a specific execution environment preference mode for tools:

capability:
  write_scope:
    environment:
      required: container
      preferred: container
      specific: <resource-name>  # A specific container required (optional)

The ExecutionEnvironmentPreference model supports mode=SPECIFIC with a target_resource field that names the specific container resource to use.

Current Behavior

In ToolRunner.execute(), when a tool has mode=SPECIFIC, the code sets effective_tool_env = "container" but does NOT forward pref.target_resource to the resolver or container executor. There is an explicit TODO comment in the code acknowledging this:

if pref.mode == EnvironmentPreferenceMode.SPECIFIC:
    # Route to container; the named target_resource identifies
    # which container to use.
    effective_tool_env = "container"
    # TODO: pass pref.target_resource to the resolver /
    # container executor so the specific named resource is
    # selected.  The current resolver and ContainerToolExecutor
    # APIs do not accept a target_resource parameter.
    logger.debug(
        "tool_env_preference.specific_override",
        tool=tool_name,
        target_resource=pref.target_resource,
    )

This means tools with mode=SPECIFIC are routed to ANY available container, not the specific named container resource. The target_resource name is logged but otherwise ignored.

Expected Behavior

Per the spec, when a tool has specific: <resource-name> in its execution environment capability, the tool runner should route execution to that specific named container resource. If that specific container is not available, the tool should fail with an error indicating the specific resource is unavailable.

Steps to Reproduce

Create a tool with ExecutionEnvironmentPreference(mode=SPECIFIC, target_resource="local/api-dev")
Execute the tool with a project that has a different container resource linked (e.g., local/other-container)
Observe: the tool routes to the generic container instead of local/api-dev

Code Location

/app/src/cleveragents/tool/runner.py — ToolRunner.execute(), lines handling EnvironmentPreferenceMode.SPECIFIC
/app/src/cleveragents/application/services/execution_environment_resolver.py — ExecutionEnvironmentResolver (does not accept target_resource)
/app/src/cleveragents/tool/container_executor.py — ContainerToolExecutor (does not accept target_resource)

Subtasks

Add target_resource: str | None parameter to ExecutionEnvironmentResolver.resolve() for specific container routing
Add target_resource: str | None parameter to ContainerToolExecutor.execute_tool() to select the specific named container
Update ToolRunner.execute() to forward pref.target_resource to the resolver and executor when mode=SPECIFIC
Implement error handling: when the specific target container is unavailable, raise a clear error naming the specific resource
Write Behave BDD unit tests verifying SPECIFIC mode routes to the correct named container
Write Behave BDD unit tests verifying the error path when the specific container is unavailable
Ensure all nox stages pass (lint, typecheck, unit_tests, coverage_report)

Definition of Done

ExecutionEnvironmentResolver accepts a target_resource parameter for specific container routing
ContainerToolExecutor.execute_tool() accepts a target_resource parameter to select the specific container
ToolRunner.execute() forwards pref.target_resource to the resolver and executor when mode=SPECIFIC
When the specific target container is unavailable, a clear error is returned naming the specific resource
Tests verify that SPECIFIC mode routes to the correct named container
All nox stages pass
Coverage >= 97%

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: ca-new-issue-creator

## Metadata - **Branch**: `fix/tool-runner-specific-mode-target-resource-forwarding` - **Commit Message**: `fix(tool): forward target_resource in ToolRunner SPECIFIC mode to resolver and container executor` - **Milestone**: v3.7.0 - **Parent Epic**: #398 ## Background and Context The spec (§Tool Capability Metadata) defines a `specific` execution environment preference mode for tools: ```yaml capability: write_scope: environment: required: container preferred: container specific: <resource-name> # A specific container required (optional) ``` The `ExecutionEnvironmentPreference` model supports `mode=SPECIFIC` with a `target_resource` field that names the specific container resource to use. ## Current Behavior In `ToolRunner.execute()`, when a tool has `mode=SPECIFIC`, the code sets `effective_tool_env = "container"` but does NOT forward `pref.target_resource` to the resolver or container executor. There is an explicit TODO comment in the code acknowledging this: ```python if pref.mode == EnvironmentPreferenceMode.SPECIFIC: # Route to container; the named target_resource identifies # which container to use. effective_tool_env = "container" # TODO: pass pref.target_resource to the resolver / # container executor so the specific named resource is # selected. The current resolver and ContainerToolExecutor # APIs do not accept a target_resource parameter. logger.debug( "tool_env_preference.specific_override", tool=tool_name, target_resource=pref.target_resource, ) ``` This means tools with `mode=SPECIFIC` are routed to ANY available container, not the specific named container resource. The `target_resource` name is logged but otherwise ignored. ## Expected Behavior Per the spec, when a tool has `specific: <resource-name>` in its execution environment capability, the tool runner should route execution to that specific named container resource. If that specific container is not available, the tool should fail with an error indicating the specific resource is unavailable. ## Steps to Reproduce 1. Create a tool with `ExecutionEnvironmentPreference(mode=SPECIFIC, target_resource="local/api-dev")` 2. Execute the tool with a project that has a different container resource linked (e.g., `local/other-container`) 3. Observe: the tool routes to the generic container instead of `local/api-dev` ## Code Location - `/app/src/cleveragents/tool/runner.py` — `ToolRunner.execute()`, lines handling `EnvironmentPreferenceMode.SPECIFIC` - `/app/src/cleveragents/application/services/execution_environment_resolver.py` — `ExecutionEnvironmentResolver` (does not accept `target_resource`) - `/app/src/cleveragents/tool/container_executor.py` — `ContainerToolExecutor` (does not accept `target_resource`) ## Subtasks - [ ] Add `target_resource: str | None` parameter to `ExecutionEnvironmentResolver.resolve()` for specific container routing - [ ] Add `target_resource: str | None` parameter to `ContainerToolExecutor.execute_tool()` to select the specific named container - [ ] Update `ToolRunner.execute()` to forward `pref.target_resource` to the resolver and executor when `mode=SPECIFIC` - [ ] Implement error handling: when the specific target container is unavailable, raise a clear error naming the specific resource - [ ] Write Behave BDD unit tests verifying `SPECIFIC` mode routes to the correct named container - [ ] Write Behave BDD unit tests verifying the error path when the specific container is unavailable - [ ] Ensure all nox stages pass (lint, typecheck, unit_tests, coverage_report) ## Definition of Done - [ ] `ExecutionEnvironmentResolver` accepts a `target_resource` parameter for specific container routing - [ ] `ContainerToolExecutor.execute_tool()` accepts a `target_resource` parameter to select the specific container - [ ] `ToolRunner.execute()` forwards `pref.target_resource` to the resolver and executor when `mode=SPECIFIC` - [ ] When the specific target container is unavailable, a clear error is returned naming the specific resource - [ ] Tests verify that `SPECIFIC` mode routes to the correct named container - [ ] All nox stages pass - [ ] Coverage >= 97% --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator

freemo added this to the v3.7.0 milestone

2026-04-03 04:21:24 +00:00

freemo referenced this issue

2026-04-03 04:21:38 +00:00

[UAT-SUPERVISOR] Progress Report — Cycle 721 — v3.7.0 #2138

freemo commented

2026-04-03 04:21:55 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
Priority: Medium (confirmed) — The SPECIFIC mode for tool execution environment is non-functional. The target_resource is logged but ignored, routing to any available container instead of the named one.
Milestone: v3.7.0 (confirmed — Tool Runtime Epic #398)
MoSCoW: Should Have — The SPECIFIC execution environment mode is a spec-defined feature for precise container routing. Without it, tools that need a specific container resource will silently route to the wrong container.
Parent Epic: #398 (confirmed correct)

Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: ca-project-owner

Issue triaged by project owner: - **State**: Verified - **Priority**: Medium (confirmed) — The `SPECIFIC` mode for tool execution environment is non-functional. The `target_resource` is logged but ignored, routing to any available container instead of the named one. - **Milestone**: v3.7.0 (confirmed — Tool Runtime Epic #398) - **MoSCoW**: Should Have — The `SPECIFIC` execution environment mode is a spec-defined feature for precise container routing. Without it, tools that need a specific container resource will silently route to the wrong container. - **Parent Epic**: #398 (confirmed correct) --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner

freemo added a new dependency

2026-04-03 04:22:01 +00:00

#398 Epic: Post-MVP Resources

freemo referenced this issue

2026-04-03 04:23:16 +00:00

[CA-AUTO] UAT Pool Supervisor — v3.7.0 — Session Tracker #2023

freemo referenced this issue

2026-04-03 04:31:47 +00:00

[UAT-SUPERVISOR] Progress Report — Cycle 731 — v3.7.0 #2157

freemo referenced this issue

2026-04-03 04:32:08 +00:00

[CA-AUTO] UAT Pool Supervisor — v3.7.0 — Session Tracker #2023