cleveragents-core/docs/advanced-concepts/container-tools.md

Advanced Concepts: Container Tools, Scope Chain, Budgets & Safety (v3.6.0)

Milestone: v3.6.0 — M7: Advanced Concepts & Deferred Features Parent: Advanced Concepts Overview

---

Container Tool Execution

v3.6.0 adds first-class support for executing tools inside containers, building on the container resource types introduced in ADR-039.

Overview

Container tool execution allows actors to run tools in isolated container environments rather than directly on the host. This provides:

• Stronger isolation — tool side effects are contained within the container
• Reproducible environments — tools run in a known, versioned environment
• Language-agnostic tools — tools can be written in any language supported by the container
• Parallel execution — multiple containers can run simultaneously for independent tool calls

Container Tool Configuration

Tools declare their container requirements in their YAML definition:

name: my-org/python-linter
type: container-tool
image: "python:3.12-slim"
command: ["python", "-m", "pylint"]
mounts:
  - source: "{{resource.git_dir.path}}"
    target: "/workspace"
    readonly: true
environment:
  PYTHONPATH: "/workspace/src"
timeout: 60

Execution Model

Container tools follow the same ToolRuntime interface as host tools. The ContainerToolExecutor handles:

1. Image resolution — pulls the image if not cached locally
2. Mount binding — maps resource paths to container mount points
3. Execution — runs the container with the specified command and arguments
4. Output capture — streams stdout/stderr back to the ToolResult
5. Cleanup — removes the container after execution (configurable)

Devcontainer Integration

When a project has a .devcontainer/devcontainer.json, CleverAgents can use the devcontainer as the execution environment for all tools in that project. This is configured via the devcontainer-instance resource type (ADR-043):

resources:
  - name: dev_env
    type: devcontainer-instance
    devcontainer_path: ".devcontainer/devcontainer.json"
    use_for_tools: true

---

Pluggable Scope Chain Resolution Extensions

The scope chain resolution system determines which projects, plans, and resources are in scope for a given actor invocation. v3.6.0 makes this system extensible via a plugin interface.

Scope Chain Resolution Protocol

The ScopeChainResolver interface defines a single method:

class ScopeChainResolver(Protocol):
    def resolve(
        self,
        base_scope: Scope,
        context: ResolutionContext,
    ) -> Scope:
        """
        Extend or modify the base scope based on the resolution context.

        Args:
            base_scope: The scope as determined by the persona and explicit @ references.
            context: The current resolution context (session, plan, actor, prompt).

        Returns:
            The resolved scope, which may add, remove, or reorder items from base_scope.
        """
        ...

Built-in Resolvers

Resolver	Description
PersonaScopeResolver	Adds persona-scoped projects and plans (always active)
ReferenceResolver	Adds explicitly @-referenced resources (always active)
DependencyGraphResolver	Automatically includes resources that are dependencies of in-scope resources
RecentlyModifiedResolver	Adds recently modified files from in-scope projects
TestCoverageResolver	Adds test files that cover in-scope source files

Custom Resolver Registration

Custom resolvers are registered via the plugin system:

from cleveragents.scope import ScopeChainResolver, register_resolver

@register_resolver(name="my-org/git-blame-resolver", priority=50)
class GitBlameResolver:
    def resolve(self, base_scope, context):
        # Add files recently modified by the current git user
        ...

---

Cost and Session Budgets

v3.6.0 introduces comprehensive cost tracking and budget enforcement across sessions and plans.

Cost Tracking

Every LLM invocation is tracked with:

• Input tokens and output tokens (provider-reported)
• Cost in USD (computed from provider pricing tables, updated monthly)
• Model used (for multi-provider fallback chains)
• Session ID and plan ID for attribution

Cost data is stored in the SQLite database and queryable via:

agents session cost                    # Total cost for current session
agents session cost --all              # All sessions with costs
agents plan cost <plan-id>             # Cost breakdown for a specific plan
agents config get billing.total_spent  # Lifetime total

Budget Configuration

Budgets are configured at multiple levels (plan > action > project > global):

[billing]
max_cost_per_session = 5.00     # USD; hard limit per session
max_cost_per_plan = 2.00        # USD; hard limit per plan
max_total_cost = 100.00         # USD; lifetime hard limit
warn_at_percent = 80            # Warn when 80% of any budget is consumed

These settings correspond to the SafetyProfile fields defined in ADR-041:

Config Key	SafetyProfile Field
max_cost_per_plan	SafetyProfile.max_cost_per_plan
max_total_cost	SafetyProfile.max_total_cost

Budget Enforcement

When a budget limit is reached:

1. The current LLM invocation is not started (pre-flight check)
2. A BudgetExceededError is raised with the budget type, limit, and current spend
3. The plan transitions to PAUSED state with pause_reason = "budget_exceeded"
4. The user is notified via the CLI output or TUI notification system
5. The user can increase the budget via agents config set billing.max_cost_per_plan <new_limit> and resume the plan with agents plan resume <plan-id>

---

Safety Profiles

Safety profiles (ADR-041) provide fine-grained control over what actions an actor is permitted to take. v3.6.0 completes the safety profile implementation with full enforcement in the plan lifecycle.

SafetyProfile Fields

Field	Type	Default	Description
require_sandbox	bool	True	Require sandbox isolation for all file writes
require_checkpoints	bool	True	Require checkpoints before destructive operations
allow_unsafe_tools	bool	False	Allow tools marked as unsafe: true
require_human_approval	bool	False	Require human approval before each action step
allowed_skill_categories	list[str]	[] (all)	Restrict to specific skill categories
max_cost_per_plan	float or None	None	Maximum cost per plan in USD
max_total_cost	float or None	None	Maximum lifetime cost in USD
max_retries_per_step	int	3	Maximum retries per action step (0-100)

Built-in Safety Profiles

v3.6.0 ships with named safety profiles that can be referenced by name:

Profile	Description
strict	All safety flags enabled; no unsafe tools; human approval required
standard	Sandbox and checkpoints required; unsafe tools blocked; no human approval
permissive	Sandbox required; checkpoints optional; unsafe tools allowed
read-only	No file writes permitted; all tools restricted to read operations
cost-capped-1usd	Standard safety + $1.00 per-plan cost cap
cost-capped-5usd	Standard safety + $5.00 per-plan cost cap

Applying Safety Profiles

Safety profiles can be applied at multiple levels:

# Global default
agents config set safety.profile strict

# Per-project
agents project set-safety my-project --profile standard

# Per-plan (at creation time)
agents plan use my-action --safety-profile permissive

# action.yaml
name: my-action
safety_profile:
  require_sandbox: true
  allow_unsafe_tools: false
  max_cost_per_plan: 2.00

---

Related ADRs

ADR	Title	Relevance
ADR-039	Container Resource Types	Container tool execution
ADR-041	Safety Profile Extraction	Safety profiles and cost budgets
ADR-043	Devcontainer Integration	Devcontainer tool execution

---

Documentation for v3.6.0 — IN PROGRESS. Features described here reflect the planned scope as of 2026-04-15. Some features may be adjusted as implementation progresses.

Generated by [AUTO-DOCS-5] — CleverAgents Documentation Bot