Migration from V2

This guide covers upgrading from Sugar V2 (subprocess-based) to V3 (Claude Agent SDK integration).

What's Changed

Sugar 3.0 introduces a fundamentally new execution model while maintaining backwards compatibility:

Quick Migration

For most users, migration is automatic:

# 1. Update Sugar
pip install --upgrade sugarai

# 2. Verify installation
sugar --version  # Should show 3.x.x

# 3. Test with dry run
sugar run --dry-run --once

V3 defaults to the new SDK executor while maintaining full compatibility with V2 configurations.

Configuration Changes

Executor Selection

V3 introduces the executor option to choose between execution backends:

sugar:
  claude:
    # V3 default - Native SDK
    executor: sdk

    # Fall back to V2 behavior
    # executor: legacy

New Agent Configuration

V3 adds the agent section for SDK-specific settings:

sugar:
  agent:
    model: claude-sonnet-4-20250514
    max_tokens: 8192
    permission_mode: acceptEdits
    timeout: 300

    # New in V3: Quality gates
    quality_gates:
      enabled: true
      protected_files:
        - ".env"
        - "*.pem"
      blocked_commands:
        - "sudo"
        - "rm -rf /"

Retry Configuration

V3 adds configurable retry behavior:

sugar:
  agent:
    max_retries: 3
    retry_base_delay: 1.0
    retry_max_delay: 30.0

Code Changes

If You Extended Sugar

If you wrote custom code using Sugar internals, note these changes:

V2 Code Example

# V2 approach
from sugar.executor.claude_wrapper import ClaudeWrapper

wrapper = ClaudeWrapper(config)
result = wrapper.execute("Fix the bug", task_id="123")
if result.success:
    print(result.output)

V3 Code Example

# V3 approach
from sugar.agent.base import SugarAgent, SugarAgentConfig

async def main():
    config = SugarAgentConfig(
        model="claude-sonnet-4-20250514",
        permission_mode="acceptEdits",
    )
    agent = SugarAgent(config)

    async with agent:
        response = await agent.execute("Fix the bug", task_context="Bug fix")
        if response.success:
            print(response.content)
            print(f"Files modified: {response.files_modified}")

Using Legacy Mode

If you need to stay on V2 behavior temporarily:

sugar:
  claude:
    executor: legacy
    command: "claude"
    timeout: 1800

This runs Sugar 3.0 with the V2 subprocess wrapper.

Note: Legacy mode is deprecated and will be removed in a future release. We recommend migrating to the SDK executor.

New Features in V3

Quality Gates

Pre and post-execution hooks for security:

sugar:
  agent:
    quality_gates:
      enabled: true
      protected_files: [".env", "*.key", "secrets/*"]
      blocked_commands: ["sudo", "rm -rf"]

Full Tool Tracking

Every tool invocation is logged:

# View execution audit
sugar status --verbose

# Response includes:
# - tool_uses: List of all tool invocations
# - files_modified: All file changes
# - quality_gate_results: Security audit

MCP Server Support

Extend agent capabilities with MCP servers:

sugar:
  agent:
    mcp_servers:
      filesystem:
        command: npx
        args: ["-y", "@anthropic/mcp-server-filesystem"]

Troubleshooting Migration

Import Errors

# If you get import errors, ensure clean install
pip uninstall sugarai
pip install sugarai

Config Validation Errors

V3 is stricter about config validation. Check for:

• Invalid YAML syntax
• Unknown configuration keys
• Type mismatches (string vs list)

Permission Issues

If tasks fail with permission errors:

1. Check permission_mode setting
2. Review protected_files patterns
3. Disable quality gates temporarily to isolate the issue

Getting Help

• Agent SDK Reference - Full SDK documentation
• Configuration - All config options
• Troubleshooting - Common issues
• GitHub Issues - Report problems