Refactor: Remove SDK duplication in src/claude/ (~68% line reduction)

[RichardAtCT]

Summary

A deep review of src/claude/ (2,774 lines across 8 files) against claude-agent-sdk v0.1.31 reveals that ~68% (~1,880 lines) duplicates or over-complicates native SDK functionality.

Full analysis: docs/SDK_DUPLICATION_REVIEW.md

Key Findings

#	Finding	Impact	Lines Affected
1	Using query() instead of ClaudeSDKClient — we built a 340-line SessionManager with temp IDs and swap logic for what the SDK handles natively	HIGH	~330
2	ToolMonitor validates tools reactively during streaming; SDK's can_use_tool blocks before execution	HIGH	~425
3	Maintaining two complete backends (SDK 513 lines + CLI subprocess 594 lines + parser 338 lines) with identical dataclasses and extraction logic	HIGH	~1,012
4	Not using max_budget_usd — cost tracked in 4 places but never enforced	MEDIUM	~10
5	Manual disallowed_tools checking — SDK has native option	MEDIUM	~15
6	Bash substring blocklist (>, `	, &, ;) blocks legitimate shell usage; should use can_use_tool` + sandbox	MEDIUM

Proposed Phases

Phase	What	Risk
1	Low-risk cleanup: dead state, ResultMessage.result, pass disallowed_tools to SDK options	None
2	Remove CLI subprocess backend (integration.py, parser.py, fallback logic)	Medium — upgrade SDK first
3	Replace ToolMonitor with can_use_tool callback	Medium — write tests first
4	Switch query() to ClaudeSDKClient for multi-turn conversations	High — prototype first
5	Final cleanup: CLI discovery, consolidate dataclasses	Low

Prerequisites

• Upgrade claude-agent-sdk to latest (currently on 0.1.31)
• Ensure test coverage on existing security validation rules
• Prototype ClaudeSDKClient lifecycle management (one client per user? per directory?)

Target State

File	Before	After
integration.py	594	deleted
parser.py	338	deleted
session.py	340	~90
monitor.py	333	~50
facade.py	568	~270
sdk_integration.py	513	~410
Total	2,774	~900

[RichardAtCT]

Progress update — 4 of 5 phases complete

Line count: 2,774 → 1,359 (51% reduction so far)

File	Before	Current	Target	Status
integration.py	594	deleted	deleted	✅ PR #59
parser.py	338	deleted	deleted	✅ PR #59
session.py	340	336	~90	Refactored for ClaudeSDKClient (PR #56), still has full session management
monitor.py	333	124	~50	✅ Slimmed to just check_bash_directory_boundary() (PR #62)
facade.py	568	275	~270	✅ Simplified after backend removal
sdk_integration.py	513	559	~410	Grew slightly — absorbed ClaudeSDKClient lifecycle + can_use_tool callback
exceptions.py	—	29	—	Retained (small, useful)
__init__.py	88	36	—	Cleaned up
Total	2,774	1,359	~900

Phases

Phase	Description	Status	PR
1	Low-risk cleanup: dead state, pass disallowed_tools to SDK	✅ Done	#59
2	Remove CLI subprocess backend (integration.py, parser.py, fallback logic)	✅ Done	#59
3	Replace ToolMonitor with can_use_tool callback	✅ Done (in review)	#62
4	Switch query() to ClaudeSDKClient for multi-turn	✅ Done	#56
5	Final cleanup: CLI discovery, consolidate dataclasses	⬜ Not started	—

Findings

#	Finding	Status
1	Using query() instead of ClaudeSDKClient	✅ Fixed — PR #56
2	ToolMonitor reactive validation → SDK can_use_tool	✅ Fixed — PR #62 (in review)
3	Dual backends (SDK + CLI subprocess)	✅ Fixed — PR #59 removed CLI backend
4	Not using max_budget_usd	⬜ Open
5	Manual disallowed_tools checking	✅ Fixed — PR #59 passes to SDK options
6	Bash substring blocklist too aggressive	✅ Fixed — PR #62 replaced with check_bash_directory_boundary()

Prerequisites

• Upgrade claude-agent-sdk to latest — PR chore: upgrade claude-agent-sdk from ^0.1.30 to ^0.1.38 #52
• Ensure test coverage on security validation — PR Replace ToolMonitor with SDK can_use_tool callback #62 adds can_use_tool tests
• Prototype ClaudeSDKClient lifecycle management — PR Replace query() with ClaudeSDKClient for native session management #56

Remaining work

• Phase 5 (final cleanup): Consolidate dataclasses between sdk_integration.py and session.py, slim down session.py toward the ~90 line target, review CLI discovery logic
• Finding 4 (max_budget_usd): Low priority, could be a quick win
• Gap between current (1,359) and target (~900) is mostly in session.py and sdk_integration.py

[RichardAtCT]

Progress update — Phase 3 merged, 4 of 5 phases complete

Line count: 2,774 → 1,527 (45% reduction)

PR #62 is now merged (rebased and conflict-resolved against PRs #69, #83, #89, #94 that landed first).

File	Before	Current	Target	Status
integration.py	594	deleted	deleted	✅ PR #59
parser.py	338	deleted	deleted	✅ PR #59
session.py	340	376	~90	Refactored for ClaudeSDKClient (PR #56)
monitor.py	333	200	~50	✅ ToolMonitor deleted, only check_bash_directory_boundary() + _is_claude_internal_path() remain (PR #62)
facade.py	568	275	~270	✅ Simplified — dead tool error methods removed (PR #62)
sdk_integration.py	513	611	~410	Grew — absorbed can_use_tool callback + stderr capture (PRs #62, #94)
exceptions.py	—	29	—	Retained, ClaudeToolValidationError removed
__init__.py	88	36	—	Cleaned up
Total	2,774	1,527	~900

Phases

Phase	Description	Status	PR
1	Low-risk cleanup: dead state, pass disallowed_tools to SDK	✅ Done	#59
2	Remove CLI subprocess backend	✅ Done	#59
3	Replace ToolMonitor with can_use_tool callback	✅ Merged	#62
4	Switch query() to ClaudeSDKClient for multi-turn	✅ Done	#56
5	Final cleanup: consolidate dataclasses, slim session.py	⬜ Not started	—

Remaining work (Phase 5)

Gap between current (1,527) and target (~900) is mostly in:

• session.py (376 → ~90): Full session management could be simplified significantly
• sdk_integration.py (611 → ~410): Consolidate dataclasses, review CLI discovery logic
• monitor.py (200 → ~50): Could further slim by inlining helper functions

Also open: Finding 4 (max_budget_usd) — low priority quick win.