SDK Alignment & Security Improvements (Claude Agent SDK 0.1.x)

[shivanathd]

Overview

After reviewing the codebase against the official Claude Agent SDK documentation, I've identified several alignment issues and improvement opportunities. These range from critical SDK compatibility issues to security hardening suggestions.

---

🔴 Critical - SDK Compatibility

1. Loose Version Pinning

File: requirements.txt

claude-agent-sdk>=0.1.0  # Current latest is 0.1.18

Risk: The SDK has had breaking changes between minor versions (e.g., ClaudeCodeOptions → ClaudeAgentOptions, settings loading behavior).

Recommendation: Pin to claude-agent-sdk>=0.1.18,<0.2.0

---

2. Missing System Prompt Preset

File: client.py:187

system_prompt="You are an expert full-stack developer building a production-quality web application."

Issue: Custom system prompt loses Claude Code's built-in capabilities (tool awareness, multi-file editing patterns, error recovery).

Recommendation: Use the preset with append:

system_prompt={
    "type": "preset", 
    "preset": "claude_code",
    "append": "Focus on building production-quality web applications."
}

---

3. Incomplete Message Type Handling

File: agent.py:67-101

Currently only handles AssistantMessage and UserMessage. The SDK emits additional types:

• SystemMessage - System notifications
• ResultMessage - Final results
• ErrorMessage - Error states
• ProgressMessage - Progress updates

Recommendation: Add handlers for all message types to improve error visibility and debugging.

---

🟡 Medium - Best Practices

4. MCP Server Type Not Specified

File: client.py:163-181

The SDK now supports multiple MCP transport types (stdio, sse, http, sdk). Explicitly declaring type improves clarity:

"features": {
    "type": "stdio",  # Add this
    "command": sys.executable,
    ...
}

---

5. Security Hook Signature

File: security.py:314

async def bash_security_hook(input_data, tool_use_id=None, context=None):

The official SDK hook signature is:

async def hook(tool_input: dict, tool_use_id: str) -> dict:

The context parameter may not be passed in newer SDK versions.

---

6. Missing Hook Types

Currently only uses PreToolUse. Consider adding:

• PostToolUse - For logging/auditing successful operations
• SessionStart/SessionEnd - For resource cleanup
• PermissionRequest - For custom permission logic

---

7. No File Checkpointing

File: client.py

The SDK supports file checkpointing which enables query.rewindFiles() to undo agent file changes on error:

ClaudeAgentOptions(
    enable_file_checkpointing=True,  # Add this
    ...
)

---

🟢 Minor - Improvements

8. Hardcoded Configuration

File: client.py:197

max_turns=1000,

Consider making configurable via environment variable or config file.

---

9. MCP Server Health Checks

The feature MCP server (mcp_server/feature_mcp.py) lacks a readiness probe. If database initialization fails, the agent receives cryptic errors.

Suggestion: Add a health_check tool or startup validation that fails fast with clear error messages.

---

10. Security: rm Command in Allowlist

File: security.py:51

"rm",  # Use with caution

Risk: Agent could delete critical files outside intended scope.

Suggestions:

• Add validation to restrict rm to project directory only
• Block dangerous patterns like rm -rf /, rm -rf ~, rm -rf .
• Consider requiring --interactive flag

---

✅ Already Fixed (PR #1)

• start_ui.sh not auto-activating virtual environment

---

Environment

• Tested on: macOS 14.x, Python 3.12
• SDK Version analyzed: claude-agent-sdk 0.1.18
• Comparison source: Official Claude Agent SDK Docs

---

Happy to submit PRs for any of these items if helpful!

[dxcSithLord]

Comparison source link https://docs.anthropic.com/en/docs/claude-code/sdk not found (Ref Comparison source: Official Claude Agent SDK Docs ), please clarify.

[leonvanzyl]

Item 1 Addressed: SDK Version Pinning

The SDK version constraint has been updated in requirements.txt:

Before:

claude-agent-sdk>=0.1.0

After:

claude-agent-sdk>=0.1.0,<0.2.0

What this change does:

• Prevents automatic upgrades to potentially breaking 0.2.x versions
• Users still receive patch updates within the 0.1.x range (e.g., 0.1.18, 0.1.19, etc.)
• Addresses the concern about breaking changes between minor versions

Remaining items in this issue:

The following items from this issue are still open for future work:

Critical:

• 2. Missing System Prompt Preset
• 3. Incomplete Message Type Handling

Medium:

• 4. MCP Server Type Not Specified
• 5. Security Hook Signature
• 6. Missing Hook Types
• 7. No File Checkpointing

Minor:

• 8. Hardcoded Configuration
• 9. MCP Server Health Checks
• 10. Security: rm Command in Allowlist

This issue will remain open as other items are still pending.