AI Delegation Flow

Relevant source files

The following files were used as context for generating this wiki page:

• .claude/skills/ccs-delegation/SKILL.md
• src/delegation/delegation-handler.ts
• src/delegation/session-manager.ts
• src/delegation/result-formatter.ts
• src/utils/delegation-validator.ts
• src/commands/help-command.ts

AI Delegation is a core architectural feature in CCS that allows a primary AI agent (typically Claude) to offload tasks to secondary AI profiles or compatible runtimes. This system provides a stable command surface for managing multiple providers such as Gemini, Codex, and local models via Ollama without requiring manual configuration changes for each switch.

The delegation flow handles profile validation, session persistence, execution, and the final formatting of results back to the user or the calling agent. It ensures that complex tasks can be routed to the most appropriate model based on cost, capability, or privacy requirements.

Sources: README.md, src/delegation/result-formatter.ts:18-20, src/commands/help-command.ts:251-255

Architecture and Components

The delegation system consists of several specialized modules that manage the lifecycle of a delegated task.

Core Modules

Component	Description
DelegationValidator	Validates that a target profile exists and has a correctly configured API key before execution begins.
SessionManager	Manages the persistence of delegated sessions, allowing for long-running tasks or continuations.
ResultFormatter	Processes raw execution output, extracts file changes, and generates a structured ASCII report.
DelegationHandler	Coordinates the flow between validation, execution, and result processing.

Sources: src/utils/delegation-validator.ts:20-25, src/delegation/result-formatter.ts:33-35, src/delegation/session-manager.ts

High-Level Flow

The following diagram illustrates the sequence of operations when a task is delegated:

The diagram shows the transition from the initial command through validation and execution to final result formatting.
Sources: src/delegation/result-formatter.ts:40-100, src/utils/delegation-validator.ts:32-60

Profile Validation

Before any delegation occurs, the DelegationValidator performs a multi-step check. It searches for candidate settings files (e.g., *.settings.json) within the CCS directory.

• Key Verification: It checks for ANTHROPIC_AUTH_TOKEN (proxy mode) or ANTHROPIC_API_KEY (native mode).
• Placeholder Detection: It rejects profiles still using default strings like YOUR_API_KEY_HERE or PLACEHOLDER.
• Ready Check: The isReady shorthand method provides a boolean check for other modules to determine if a profile can be safely launched.

Sources: src/utils/delegation-validator.ts:32-45, src/utils/delegation-validator.ts:77-90, src/utils/delegation-validator.ts:114-117

Result Processing and Formatting

The ResultFormatter class is responsible for transforming raw CLI output into a human-readable summary. It includes logic to handle successful completions, timeouts, and errors.

File Change Tracking

The system attempts to identify what the delegated agent changed in the local workspace. It uses two primary methods:

1. Regex Matching: Scans stdout for patterns like created:, modified:, or wrote:.
2. Filesystem Fallback: If regex yields no results, it uses a find command to locate files modified within the last 5 minutes, excluding infrastructure directories like .git, node_modules, or .claude.

Sources: src/delegation/result-formatter.ts:110-155, src/delegation/result-formatter.ts:168-175

Execution Result Structure

Results are encapsulated in an ExecutionResult object, which is then formatted into a stylized box output.

// Example of structured result data processed by ResultFormatter
interface ExecutionResult {
  profile: string;
  success: boolean;
  stdout: string;
  stderr: string;
  duration: number; // in milliseconds
  exitCode: number;
  totalCost?: number;
  numTurns?: number;
}

Sources: src/delegation/result-formatter.ts:24-30, src/delegation/result-formatter.ts:210-215

Error and Timeout Handling

The delegation flow includes specific handling for timeouts and common CLI errors. When a session exceeds its time limit, the formatTimeoutError method generates a specialized report including:

• The duration of the session before termination.
• Suggestions for recovery (e.g., using the :continue command or increasing the --timeout flag).
• Permission denials that may have contributed to the delay.

Sources: src/delegation/result-formatter.ts:52-58, src/delegation/result-formatter.ts:265-285

This sequence shows the interaction between the primary agent and the delegated runtime components.
Sources: src/delegation/result-formatter.ts:40-80, src/utils/delegation-validator.ts:32-35

Summary

The AI Delegation Flow provides a robust mechanism for multi-model workflows. By isolating validation, execution, and result formatting into discrete components, CCS ensures that users can switch between providers like ccs glm or ccs codex with consistent error handling and change tracking, regardless of the underlying model's native output format.

Sources: README.md, src/delegation/result-formatter.ts:98-105