feat: refactor Claude Code Agent directory architecture (v0.0.3) (#166)

## Summary

This PR refactors the Claude Code Agent MCP Server's directory
architecture to properly separate working directories from state
storage, addressing a fundamental design issue.

### Key Changes

- **BREAKING:** `init_agent` tool now requires `working_directory`
parameter (absolute path)
- **BREAKING:** `init_agent` tool now accepts optional `agent_id`
parameter for state directory naming
- **BREAKING:** Removed transcript resource (state resource now contains
transcript path reference)
- Implemented directory separation: working directory vs state directory
- Fixed transcript path to point to Claude Code's native transcript
files
- Enhanced path transformation logic to match Claude Code's naming
convention

### Architecture Improvements

**Before:** `/tmp/claude-agents` was used for both agent operations and
state storage (confusing)

**After:** Clean separation:
- **Working Directory**: Where Claude Code agent operates
(user-specified via `working_directory`)
- **State Directory**: Where state.json is stored
(`${CLAUDE_AGENT_BASE_DIR}/${agent_id}/`)
- **Transcript Path**: Points to Claude Code's native files
(`~/.claude/projects/{project-dir}/{session-id}.jsonl`)

### Testing

- ✅ All manual tests pass (3/3)
- ✅ Verified working directory separation with both mock and real Claude
Code CLI
- ✅ Validated native Claude Code transcript path detection
- ✅ Confirmed required parameter validation works correctly

### Breaking Changes

Users upgrading from previous versions must update their `init_agent`
calls to include the `working_directory` parameter.

**Before:**
```json
{
  "system_prompt": "You are a helpful assistant"
}
```

**After:**
```json
{
  "system_prompt": "You are a helpful assistant",
  "working_directory": "/path/to/project"
}
```

🤖 Generated with [Claude Code](https://claude.ai/code)

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: tadasant

experimental/claude-code-agent/CHANGELOG.md

@@ -4,6 +4,33 @@ All notable changes to the Claude Code Agent MCP Server will be documented in th
 
 ## [Unreleased]
 
+## [0.0.3] - 2025-10-10
+
+**BREAKING CHANGES:**
+
+- **BREAKING:** `init_agent` tool now requires `working_directory` parameter (absolute path)
+- **BREAKING:** `init_agent` tool now accepts optional `agent_id` parameter for state directory naming
+- **BREAKING:** Removed transcript resource (state resource now contains transcript path reference)
+
+**Improvements:**
+
+- Implemented directory separation: working directory (where agent operates) vs state directory (where state is stored)
+- Fixed transcript path to point to Claude Code's native transcript files (`~/.claude/projects/{project-dir}/{session-id}.jsonl`)
+- Enhanced path transformation logic to match Claude Code's naming convention for project directories
+- Updated all tests to use new parameter structure and verify directory separation
+- State storage now uses `CLAUDE_AGENT_BASE_DIR` exclusively with agent_id-based folder naming
+- Improved security validation to allow both working and state directories
+
+**Technical Details:**
+
+This release addresses the fundamental directory structure issue where `/tmp/claude-agents` was being used for both agent operations and state storage. The new architecture cleanly separates:
+
+- **Working Directory**: Where the Claude Code agent operates (user-specified via `working_directory` parameter)
+- **State Directory**: Where state.json and other metadata are stored (`${CLAUDE_AGENT_BASE_DIR}/${agent_id}/`)
+- **Transcript Path**: Points to Claude Code's native transcript files for seamless integration
+
+Users upgrading from previous versions must update their `init_agent` calls to include the `working_directory` parameter.
+
 ## [0.0.2] - 2025-10-08
 
 **CRITICAL FIX:**

experimental/claude-code-agent/MANUAL_TESTING.md

@@ -6,10 +6,10 @@ Manual tests for the Claude Code Agent MCP Server verify the integration with th
 
 ## Latest Test Results
 
-**Commit:** af8c3e4
-**Date:** 2025-10-08
+**Commit:** a35b31b
+**Date:** 2025-10-10
 **Overall:** 100% passing (3/3 test suites)
-**Note:** Manual tests from commit 390aabe still valid - this commit only adds prepare-publish.js for npm packaging
+**Note:** Verified new working_directory parameter and directory separation functionality
 
 ### Test Suite Results
 
@@ -110,20 +110,20 @@ Tests fail if:
 
 ## Manual Test Results
 
-**Last tested**: 2025-10-08
-**Commit**: af8c3e4
+**Last tested**: 2025-10-10
+**Commit**: a35b31b
 **Result**: SUCCESS (100% pass rate)
-**Note**: Tests from 390aabe still valid - af8c3e4 only adds packaging scripts
+**Note**: Verified new required working_directory parameter and directory separation functionality
 
 ### Test Execution Details
 
 - [x] Mock workflow test - PASSED
 - [x] Tool workflow test (real Claude Code CLI) - PASSED
 - [x] Error handling test - PASSED
 - [x] All 7 tools verified and working
-- [x] Resources properly managed
-- [x] State persistence fixed - single client instance maintained
-- [x] Session continuation working with --resume flag
+- [x] Required working_directory parameter validated
+- [x] Directory separation working (state vs working dirs)
+- [x] Native Claude Code transcript path detection verified
 - [x] Real Claude Code CLI integration verified
 
 ### Test Statistics
@@ -134,9 +134,10 @@ Tests fail if:
 
 ### Notes
 
-- Mock tests validate all tool functionality
+- Mock tests validate all tool functionality including new required parameters
 - Real Claude CLI integration fully tested and verified
-- Tool workflow test now passes with real Claude Code CLI
-- Session continuation properly uses --resume with session ID
-- Non-interactive mode working correctly with -p flag
+- Working directory separation correctly implemented (state vs working dirs)
+- Native Claude Code transcript path detection working (/Users/admin/.claude/projects/)
+- Required working_directory parameter validation working properly
+- Directory separation architecture verified with both mock and real implementations
 - All tests run without skips - complete coverage achieved

experimental/claude-code-agent/local/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-agent-mcp-server",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "Local implementation of claude-code-agent MCP server",
   "mcpName": "claude-code-agent",
   "main": "build/index.js",

experimental/claude-code-agent/local/prepare-publish.js

@@ -3,6 +3,7 @@ import { AgentState } from '../types.js';
 
 export class MockClaudeCodeClient implements IClaudeCodeClient {
   private mockState: AgentState | null = null;
+  private mockStateDirectory: string | null = null;
 
   private mockTranscript: Array<{
     role: string;
@@ -20,16 +21,20 @@ export class MockClaudeCodeClient implements IClaudeCodeClient {
     };
   }
 
-  async initAgent(systemPrompt: string) {
+  async initAgent(systemPrompt: string, workingDirectory: string, agentId?: string) {
+    const stateId = agentId || Math.random().toString(36).substr(2, 9);
+    const sessionId = 'mock-session-' + Math.random().toString(36).substr(2, 9);
+    this.mockStateDirectory = `/tmp/mock-state/${stateId}`;
     this.mockState = {
-      sessionId: 'mock-session-' + Math.random().toString(36).substr(2, 9),
+      sessionId,
       status: 'idle',
       systemPrompt,
       installedServers: [],
       createdAt: new Date().toISOString(),
       lastActiveAt: new Date().toISOString(),
-      workingDirectory: '/tmp/mock-agent',
+      workingDirectory: workingDirectory,
       claudeProjectPath: '/tmp/mock-claude-projects/integration-test',
+      transcriptPath: `/tmp/mock-claude-projects/integration-test/${sessionId}.jsonl`,
     };
 
     // Clear transcript on new agent init
@@ -38,7 +43,7 @@ export class MockClaudeCodeClient implements IClaudeCodeClient {
     return {
       sessionId: this.mockState.sessionId,
       status: 'idle' as const,
-      stateUri: 'file:///tmp/mock-agent/state.json',
+      stateUri: `file://${this.mockStateDirectory}/state.json`,
     };
   }
 
@@ -171,4 +176,8 @@ export class MockClaudeCodeClient implements IClaudeCodeClient {
   async getAgentState() {
     return this.mockState;
   }
+
+  async getStateDirectory() {
+    return this.mockStateDirectory;
+  }
 }