feat: Update to Claude Agent SDK 0.2.31

[arcaputo3]

Summary

• Upgrade Scalagent ScalaJS mirror from SDK 0.2.22 to 0.2.31
• Add new features and types introduced in SDK versions 0.2.23-0.2.31
• Bump version to 0.2.4-SNAPSHOT

Changes

AgentOptions

• debug: Boolean - Enable debug mode for verbose logging
• debugFile: Option[String] - Write debug logs to a file
• strictMcpConfig: Boolean - Enforce strict MCP server validation

SandboxSettings (Complete Rewrite)

• autoAllowBashIfSandboxed - Auto-allow Bash when sandboxed
• allowUnsandboxedCommands - Allow unsandboxed commands
• network: Option[SandboxNetworkConfig] - Network proxy configuration
• ignoreViolations - Violation ignore patterns
• enableWeakerNestedSandbox - Enable weaker nested sandbox
• excludedCommands - Commands excluded from sandbox
• ripgrep: Option[RipgrepConfig] - Custom ripgrep configuration

AgentDefinition

• skills: List[String] - Skill names to preload into agent context

HookEvent

• Setup - New hook event for initialization/maintenance triggers

SystemEvent

• FilesPersisted - Track persisted/failed files with PersistedFile and FailedFile types

QueryStream

• initializationResult: Task[InitializationResult] - Get full SDK control response

McpServerConfig

• ClaudeAIProxy - New server type for claude.ai proxy

Test plan

• All 151 existing tests pass
• Compilation verified with ./mill agent.compile
• Manual integration testing with new SDK features

Resolves TJC-726

🤖 Generated with Claude Code

[claude]

Pull Request Review: SDK Upgrade to 0.2.31

I've reviewed this pull request upgrading from SDK 0.2.22 to 0.2.31. Overall, this is a well-executed upgrade with comprehensive type mappings. Here's my detailed feedback:

✅ Strengths

1. Comprehensive Coverage - All new SDK features are properly mapped to Scala types with appropriate facades
2. Consistent API Design - Extension methods follow established patterns (e.g., withSkills, withDebug, withStrictMcpConfig)
3. Type Safety - Proper use of enums, sealed traits, and case classes maintains type safety
4. JSON Codec Support - All new types include proper JSON encoders/decoders for serialization
5. Documentation - Good inline documentation explaining new features and their SDK versions

🔍 Code Quality Observations

AgentOptions.scala:621-646

Good: The withDebug method signature is clean and flexible:

def withDebug(enabled: Boolean = true, file: Option[String] = None)

This allows both simple withDebug() and more complex withDebug(file = Some(...)) usage patterns.

SandboxSettings.scala (Complete Rewrite)

Concern: The complete rewrite of SandboxSettings is a breaking change. Old fields like networkAccess, allowedHosts, writableDirectories, and readOnlyDirectories have been removed and replaced with a completely different structure.

Impact: This will break existing code using the old sandbox API. Consider:

• Adding migration notes in the PR description
• Bumping major version (0.3.0 instead of 0.2.4) since this breaks backward compatibility
• Providing a deprecation path if supporting old code is important

Documentation Note: The comment at SandboxSettings.scala:6-11 is helpful in clarifying that permissions are separate from sandbox settings, but users migrating from the old API may be confused.

AgentDefinition.scala:247-256

Suggestion: The withSkills method could benefit from varargs consistency:

def withSkills(skillNames: String*): AgentDefinition =
  agent.copy(skills = skillNames.toList)

This matches the pattern used in other "with" methods and allows withSkills("skill1", "skill2") syntax.

HookEvent.scala

Good: The new Setup hook event is properly integrated with all the pattern matching in the toRaw and fromString methods.

🐛 Potential Issues

1. Missing Test Coverage ⚠️

   • No tests found for new SDK 0.2.31 features:
     • skills field in AgentDefinition
     • debug, debugFile, strictMcpConfig in AgentOptions
     • Setup hook event
     • FilesPersisted system event
     • ClaudeAIProxy MCP server type
     • initializationResult in QueryStream
     • New SandboxSettings structure and related types

   Recommendation: Add tests to AgentDefinitionSpec.scala and AgentOptionsSpec.scala covering the new features:

   // Example tests needed:
   test("withSkills adds skills to agent definition")
   test("withDebug enables debug mode")
   test("JSON round-trip preserves skills field")
   test("Setup hook event converts to/from raw correctly")

2. MessageConverter.scala:117

   • New case added for files_persisted event, looks correct
   • Proper camelCase conversion from snake_case (file_id → fileId)

3. QueryStream.scala:242

   • initializationResult method added correctly
   • Returns proper Task[InitializationResult]
   • Missing types: Need to verify SlashCommand, ModelInfo, AccountInfo exist (they're referenced in InitializationResult.fromRaw)

🔒 Security Considerations

1. Sandbox Settings Changes - The new sandbox configuration provides more granular control:

   • allowUnixSockets and allowAllUnixSockets could be security-sensitive
   • allowUnsandboxedCommands bypasses sandboxing entirely
   • Recommendation: Ensure users understand the security implications of these settings

2. Debug File Writing - debugFile option writes logs to arbitrary paths:

   • Could potentially be used to overwrite files
   • Recommendation: Consider path validation or documentation about security implications

3. ClaudeAIProxy - New MCP server type:

   • Proxies to claude.ai services
   • Question: What authentication/authorization is required? This should be documented.

⚡ Performance Considerations

• No obvious performance concerns
• The new features are opt-in and shouldn't impact existing code performance
• initializationResult method returns a Promise - users should be aware this is an async operation

📝 Documentation Suggestions

1. Migration Guide - Add a section to the PR description or CHANGELOG about migrating from old SandboxSettings API
2. Breaking Changes - Clearly mark the sandbox settings rewrite as a breaking change
3. Examples - Consider adding example code for new features:
   • Using the new skills field
   • Configuring sandbox network settings
   • Using the Setup hook event
   • Handling FilesPersisted events

📊 Test Coverage Gap

The PR description mentions:

• ✅ All 151 existing tests pass
• ✅ Compilation verified
• ⚠️ Manual integration testing with new SDK features - NOT DONE

Recommendation: Before merging, add:

1. Unit tests for all new API surface area
2. Integration tests demonstrating new features work correctly
3. Update test count expectation (should be more than 151 if new tests are added)

🎯 Recommendations Summary

Before Merging:

1. ⚠️ IMPORTANT: Add comprehensive test coverage for new SDK 0.2.31 features
2. ⚠️ BREAKING CHANGE: Consider bumping to 0.3.0 instead of 0.2.4-SNAPSHOT due to SandboxSettings rewrite
3. Add migration notes for SandboxSettings API changes
4. Document security implications of new sandbox and debug features
5. Verify all referenced types in InitializationResult.fromRaw exist

Nice to Have:
6. Add example code demonstrating new features
7. Update CHANGELOG with breaking changes section
8. Consider adding deprecation warnings if supporting old sandbox API

✨ Overall Assessment

This is a solid SDK upgrade with good type safety and API design. The main concerns are:

• Lack of test coverage for new features
• Breaking changes to SandboxSettings not reflected in version bump

Once tests are added and versioning is addressed, this will be ready to merge.

Rating: 7/10 (would be 9/10 with proper test coverage and version bump)

---

Review generated with Claude Code

[claude]

Code Review: Claude Agent SDK 0.2.31 Upgrade

I've completed a thorough review of this PR upgrading the SDK from 0.2.22 to 0.2.31. Overall, this is a well-structured upgrade that correctly mirrors the new SDK features. Here's my detailed feedback:

✅ Strengths

1. Comprehensive Feature Coverage

All new SDK features are properly mirrored:

• AgentDefinition skills support
• AgentOptions debug controls (debug, debugFile, strictMcpConfig)
• Complete SandboxSettings rewrite with network config
• ClaudeAIProxy MCP server type
• Setup hook event
• FilesPersisted system event
• QueryStream initializationResult

2. Excellent Code Quality

• Consistent naming conventions following Scala style
• Proper use of Option types for nullable fields
• Clean builder pattern with extension methods
• Well-documented with ScalaDoc comments

3. Strong Type Safety

• All JS interop properly handled with js.Dynamic and type casts
• Proper use of js.UndefOr for optional JS fields
• Safe conversions with toOption and getOrElse

4. Good Backward Compatibility

• Default values maintain backward compatibility
• Optional parameters for all new features
• No breaking changes to existing APIs

🔍 Areas for Improvement

1. Missing Test Coverage ⚠️

The PR mentions "All 151 existing tests pass" but none of the new features have test coverage:

• AgentDefinition.skills: No tests for withSkills() method or JSON serialization
• AgentOptions debug flags: No tests for withDebug() or withStrictMcpConfig
• SandboxSettings rewrite: Complete rewrite but no tests for the new structure
• ClaudeAIProxy: No tests for the new MCP server type
• HookEvent.Setup: Not tested in HookConfigSpec.scala
• SystemEvent.FilesPersisted: Not tested in AgentMessageSpec.scala
• InitializationResult: No tests for parsing or the new initializationResult method

Recommendation: Add test cases following the existing test patterns:

// Example for AgentDefinition.scala
test("withSkills adds skills to agent"):
  val agent = AgentDefinition("Test", "Prompt")
    .withSkills("code-review", "testing")
  assertEquals(agent.skills, List("code-review", "testing"))

test("toRaw includes skills when specified"):
  val agent = AgentDefinition("Test", "Prompt", skills = List("skill1"))
  val raw = agent.toRaw.asInstanceOf[js.Dynamic]
  val skills = raw.skills.asInstanceOf[js.Array[String]]
  assert(skills.contains("skill1"))

2. SandboxSettings Breaking Change ⚠️

The complete rewrite of SandboxSettings removes fields that users may be relying on:

• networkAccess: Option[Boolean] → removed
• allowedHosts: List[String] → moved to SandboxNetworkConfig.allowedDomains
• writableDirectories: List[String] → removed
• readOnlyDirectories: List[String] → removed

Impact: This could break existing code that uses these fields.

Recommendation:

• If this is intentional (matching SDK changes), document it clearly in the PR description
• Consider deprecation warnings if possible
• Update any examples that use the old fields

3. Documentation Clarity

SandboxSettings.scala:9-15 has a potentially confusing note:

"Filesystem and network restrictions are configured via permission rules, not via these sandbox settings."

This might confuse users about what sandbox settings actually control vs permissions.

Recommendation: Add examples showing how sandbox settings and permissions work together.

4. Minor Issues

a) RipgrepConfig.scala:180

The apply method creates a new instance unnecessarily:

def apply(command: String): RipgrepConfig = new RipgrepConfig(command)

Since RipgrepConfig is a case class, this is redundant. Consider removing the companion object apply (case class provides it automatically).

b) MessageConverter.scala:375-389

The parseFilesPersistedEvent uses file_id (snake_case) from JS:

fileId = f.file_id.asInstanceOf[String]

This is correct for JS interop, but ensure the SDK actually uses file_id and not fileId.

c) SandboxSettings.scala:55

Uses mapValues which is deprecated in Scala 2.13+:

ignoreViolations.view.mapValues(_.toJSArray).toSeq*

Recommendation: Use .view.mapValues() (which you're already doing) or .map { case (k, v) => k -> v.toJSArray } to be more explicit.

🔒 Security Considerations

All security aspects look good:

• Sandbox settings provide proper isolation controls
• Permission mode handling is correct
• No exposure of sensitive data
• Proper validation in builder methods (e.g., rejecting non-positive maxTurns)

🚀 Performance Considerations

No performance concerns:

• Lazy evaluation where appropriate
• No unnecessary allocations
• Efficient JS conversions

📋 Additional Recommendations

1. Add integration tests showing the new features work end-to-end with the actual SDK
2. Update examples if any use the old SandboxSettings API
3. Add migration guide if the SandboxSettings changes are breaking
4. Consider adding builder pattern tests to ensure method chaining works correctly for new methods

Summary

This is a well-implemented upgrade with solid type safety and good code organization. The main concern is missing test coverage for all new features. I recommend:

1. ✅ Approve after adding tests for the new features
2. ✅ Clarify breaking changes in SandboxSettings if any
3. ✅ Consider the minor improvements mentioned above

The code quality is excellent and follows the project's conventions well. Great work on maintaining consistency throughout!

---

Review Score: 8/10 - High quality implementation, needs test coverage to reach 10/10.