teleportation-cli 1.0.1 → 1.0.2

package/.claude/hooks/stop.mjs

@@ -29,6 +29,9 @@ const isValidSessionId = (id) => {
 // Max length for assistant response preview (characters)
 const ASSISTANT_RESPONSE_MAX_LENGTH = 2000;
 
+// Max size for full transcript (bytes) - 500KB
+const MAX_TRANSCRIPT_SIZE = 500 * 1024;
+
 // Retry configuration
 const MAX_RETRIES = 3;
 const RETRY_DELAY_MS = 1000;
@@ -150,6 +153,178 @@ const extractLastAssistantMessage = async (transcriptPath, log) => {
   }
 };
 
+/**
+ * Extract the full conversation transcript from the transcript file
+ * Returns all user and assistant messages with turn_index
+ * @returns {Object|null} - { messages: [{ role, content, turn_index }], total_turns: number, truncated: boolean, original_size: number } or null
+ */
+const extractFullTranscript = async (transcriptPath, log) => {
+  try {
+    if (!transcriptPath) {
+      log('No transcript_path provided for full extraction');
+      return null;
+    }
+
+    // Read file directly
+    let content;
+    try {
+      content = await readFile(transcriptPath, 'utf8');
+    } catch (e) {
+      if (e.code === 'ENOENT') {
+        log(`Transcript file not found: ${transcriptPath}`);
+        return null;
+      }
+      if (e.code === 'EACCES' || e.code === 'EPERM') {
+        log(`Permission denied reading transcript: ${transcriptPath}`);
+        return null;
+      }
+      log(`Error reading transcript for full extraction: ${e.code || e.message}`);
+      return null;
+    }
+
+    let transcript;
+
+    // Try parsing as JSON array first
+    try {
+      transcript = JSON.parse(content);
+      log('Parsed transcript as JSON array for full extraction');
+    } catch (e) {
+      // Try parsing as JSONL (newline-delimited JSON)
+      log('JSON parse failed for full extraction, trying JSONL format');
+      const lines = content.trim().split('\n').filter(l => l.trim());
+      transcript = lines.map(line => {
+        try {
+          return JSON.parse(line);
+        } catch {
+          return null;
+        }
+      }).filter(Boolean);
+      log(`Parsed transcript as JSONL (${transcript.length} messages) for full extraction`);
+    }
+
+    if (!Array.isArray(transcript)) {
+      log(`Transcript is not an array for full extraction: ${typeof transcript}`);
+      return null;
+    }
+
+    log(`Full transcript has ${transcript.length} raw messages`);
+
+    // Extract all user and assistant messages
+    const messages = [];
+    let turnIndex = 0;
+
+    for (const msg of transcript) {
+      const role = msg.role || msg.type || '';
+      const isAssistant = role === 'assistant' || role === 'model' || msg.isAssistant;
+      const isUser = role === 'user' || role === 'human' || msg.isUser;
+
+      if (!isAssistant && !isUser) continue;
+
+      // Extract content
+      let text = '';
+      if (typeof msg.content === 'string') {
+        text = msg.content;
+      } else if (Array.isArray(msg.content)) {
+        // Content blocks format: [{ type: 'text', text: '...' }, ...]
+        text = msg.content
+          .filter(block => block.type === 'text' && block.text)
+          .map(block => block.text)
+          .join('\n\n');
+      } else if (msg.text) {
+        text = msg.text;
+      } else if (msg.message && typeof msg.message === 'string') {
+        text = msg.message;
+      }
+
+      if (text && text.trim()) {
+        messages.push({
+          role: isAssistant ? 'assistant' : 'user',
+          content: text.trim(),
+          turn_index: turnIndex
+        });
+        turnIndex++;
+      }
+    }
+
+    log(`Extracted ${messages.length} messages from transcript`);
+
+    if (messages.length === 0) {
+      log('No valid messages found in transcript');
+      return null;
+    }
+
+    // Check size and truncate if needed (reliability requirement: 500KB limit)
+    let result = {
+      messages,
+      total_turns: messages.length,
+      truncated: false,
+      original_size: 0
+    };
+
+    const jsonSize = JSON.stringify(result).length;
+    result.original_size = jsonSize;
+
+    if (jsonSize > MAX_TRANSCRIPT_SIZE) {
+      log(`Transcript size ${jsonSize} exceeds limit ${MAX_TRANSCRIPT_SIZE}, truncating...`);
+
+      // Use size estimation to avoid O(n²) repeated JSON.stringify calls
+      // Estimate average message size and calculate how many to keep
+      const metadataOverhead = 100; // Approximate overhead for result wrapper
+      const avgMsgSize = (jsonSize - metadataOverhead) / messages.length;
+      const targetCount = Math.max(1, Math.floor((MAX_TRANSCRIPT_SIZE - metadataOverhead) / avgMsgSize));
+
+      // Keep the most recent messages (slice from end)
+      let truncatedMessages = messages.slice(-targetCount);
+
+      // Verify size with a single stringify check
+      let testResult = {
+        messages: truncatedMessages,
+        total_turns: messages.length,
+        truncated: true,
+        original_size: jsonSize
+      };
+
+      // If still too large (estimation was off), remove a few more messages
+      while (truncatedMessages.length > 1 && JSON.stringify(testResult).length > MAX_TRANSCRIPT_SIZE) {
+        truncatedMessages = truncatedMessages.slice(1); // Remove oldest of remaining
+        testResult = {
+          messages: truncatedMessages,
+          total_turns: messages.length,
+          truncated: true,
+          original_size: jsonSize
+        };
+      }
+
+      result = testResult;
+
+      // If still too large with just one message, truncate the message content
+      if (truncatedMessages.length === 0) {
+        log('All messages truncated - transcript too large for any message');
+        return null;
+      }
+
+      if (JSON.stringify(result).length > MAX_TRANSCRIPT_SIZE) {
+        const lastMsg = { ...truncatedMessages[truncatedMessages.length - 1] }; // Clone to avoid mutation
+        const maxContentLen = Math.floor(MAX_TRANSCRIPT_SIZE * 0.8); // Leave room for metadata
+        lastMsg.content = lastMsg.content.substring(0, maxContentLen) + '... [truncated]';
+        result = {
+          messages: [lastMsg],
+          total_turns: messages.length,
+          truncated: true,
+          original_size: jsonSize
+        };
+      }
+
+      log(`Truncated transcript to ${result.messages.length} messages`);
+    }
+
+    return result;
+  } catch (e) {
+    log(`Error extracting full transcript: ${e.message}`);
+    return null;
+  }
+};
+
 (async () => {
   const hookLogFile = env.TELEPORTATION_HOOK_LOG || '/tmp/teleportation-hook.log';
   const log = (msg) => {
@@ -242,7 +417,36 @@ const extractLastAssistantMessage = async (transcriptPath, log) => {
     log('Skipping assistant response log (stop_hook_active=true)');
   }
 
-  // 2. Check for pending messages from mobile app (existing functionality)
+  // 2. Store full transcript for session (new feature: PRD-0011 Phase 2)
+  // Only store if not in a recursive stop hook call
+  if (!stop_hook_active) {
+    try {
+      const transcriptData = await extractFullTranscript(transcript_path, log);
+
+      if (transcriptData && transcriptData.messages && transcriptData.messages.length > 0) {
+        await fetchJsonWithRetry(`${RELAY_API_URL}/api/sessions/${session_id}/transcript`, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            'Authorization': `Bearer ${RELAY_API_KEY}`
+          },
+          body: JSON.stringify({
+            messages: transcriptData.messages,
+            total_turns: transcriptData.total_turns,
+            truncated: transcriptData.truncated,
+            original_size: transcriptData.original_size,
+            stored_at: Date.now()
+          })
+        }, log);
+        log(`Stored full transcript (${transcriptData.messages.length} messages, ${transcriptData.total_turns} total turns, truncated: ${transcriptData.truncated})`);
+      }
+    } catch (e) {
+      // Reliability: Log but don't fail hook if transcript storage fails
+      log(`Failed to store full transcript: ${e.message}`);
+    }
+  }
+
+  // 3. Check for pending messages from mobile app (existing functionality)
   try {
     const res = await fetch(`${RELAY_API_URL}/api/messages/pending?session_id=${encodeURIComponent(session_id)}`, {
       headers: { 'Authorization': `Bearer ${RELAY_API_KEY}` }

package/.claude/hooks/user_prompt_submit.mjs

@@ -139,6 +139,63 @@ const fetchJson = async (url, opts) => {
     }
   }
 
+  // Log user message to timeline (skip special commands that are already logged differently)
+  if (session_id && prompt && typeof prompt === 'string') {
+    const trimmed = prompt.trim();
+    const lowered = trimmed.toLowerCase();
+
+    // Skip special commands - they are handled above or have their own logging
+    const isSpecialCommand =
+      lowered === '/away' || lowered === 'teleportation away' ||
+      lowered === '/back' || lowered === 'teleportation back' ||
+      lowered === '/model' || lowered.startsWith('/model ');
+
+    if (!isSpecialCommand && trimmed.length > 0) {
+      try {
+        const { loadConfig } = await import('./config-loader.mjs');
+        const config = await loadConfig();
+        const RELAY_API_URL = env.RELAY_API_URL || config.relayApiUrl || '';
+        const RELAY_API_KEY = env.RELAY_API_KEY || config.relayApiKey || '';
+
+        if (RELAY_API_URL && RELAY_API_KEY) {
+          // Truncate prompt to 2000 chars for storage efficiency
+          const MAX_PROMPT_LENGTH = 2000;
+          const truncatedPrompt = trimmed.length > MAX_PROMPT_LENGTH
+            ? trimmed.substring(0, MAX_PROMPT_LENGTH)
+            : trimmed;
+
+          await fetch(`${RELAY_API_URL}/api/timeline`, {
+            method: 'POST',
+            headers: {
+              'Content-Type': 'application/json',
+              'Authorization': `Bearer ${RELAY_API_KEY}`
+            },
+            body: JSON.stringify({
+              session_id,
+              type: 'user_message',
+              data: {
+                prompt: truncatedPrompt,
+                full_length: trimmed.length,
+                truncated: trimmed.length > MAX_PROMPT_LENGTH,
+                timestamp: Date.now()
+              }
+            })
+          });
+
+          if (env.DEBUG) {
+            log(`Logged user_message to timeline for session ${session_id}`);
+          }
+        }
+      } catch (e) {
+        // Non-critical - log error but don't block prompt submission
+        log(`Failed to log user message to timeline: ${e.message}`);
+        if (env.DEBUG) {
+          console.error(`[UserPromptSubmit] Failed to log user message: ${e.message}`);
+        }
+      }
+    }
+  }
+
   // Always suppress output from this hook
   try { stdout.write(JSON.stringify({ suppressOutput: true })); } catch {}
   return exit(0);

package/lib/daemon/teleportation-daemon.js

@@ -4,26 +4,33 @@
  * Teleportation Daemon
  *
  * Persistent background service that:
- * - Polls relay API for approved tool requests
- * - Spawns child Claude Code processes via `claude --resume <session_id> -p "<prompt>"`
+ * - Polls relay API for approved tool requests and inbox messages
+ * - Routes all remote messages to Claude Code via the machine coder interface
  * - Executes approved tools asynchronously when user is away
  * - Maintains session registry and approval queue
  * - Provides HTTP server for hook communication
  *
  * SECURITY ARCHITECTURE:
  * ----------------------
- * This daemon executes shell commands via spawn('sh', ['-c', command]) which bypasses
- * Claude CLI's built-in security controls. This is an intentional architectural decision
- * to enable remote approval/execution, but requires defense-in-depth measures:
+ * Remote message execution is delegated to Claude Code's security model:
  *
- * 1. COMMAND WHITELIST: Only pre-approved command prefixes are allowed (see ALLOWED_COMMAND_PREFIXES)
- * 2. SHELL INJECTION BLOCKING: Commands containing metacharacters (;|&`$() etc.) are rejected
- * 3. APPROVAL FLOW: All commands must be explicitly approved via the relay API
- * 4. DEVELOPMENT BYPASS: ALLOW_ALL_COMMANDS requires TELEPORTATION_DANGER_ZONE confirmation
+ * 1. CLAUDE CODE PERMISSIONS: All tool calls go through Claude Code's permission system
+ *    - When hooks are active, tool approvals are routed via Teleportation Relay
+ *    - When using --dangerously-skip-permissions, Claude auto-approves tool calls
+ * 2. SESSION VALIDATION: Each execution validates the session is still active via Relay API
+ * 3. APPROVAL CONTEXT: All executions require an approvalContext (inbox_message, approval_queue)
+ *    for audit trail
+ * 4. MACHINE CODER INTERFACE: Unified interface supports Claude Code, Gemini CLI, and future backends
  *
- * For production deployments requiring Claude CLI integration, consider:
- * - Using the CLAUDE_CLI_PATH environment variable to specify a custom Claude CLI wrapper
- * - Implementing additional command validation in a proxy layer
+ * LEGACY SHELL EXECUTION:
+ * The daemon also supports direct shell command execution via executeCommand() for specific
+ * use cases like approval queue processing. This path uses:
+ * - COMMAND WHITELIST: Only pre-approved command prefixes (see ALLOWED_COMMAND_PREFIXES)
+ * - SHELL INJECTION BLOCKING: Commands with metacharacters (;|&`$() etc.) are rejected
+ *
+ * For production deployments, consider:
+ * - Using --dangerously-skip-permissions only in sandboxed environments
+ * - Implementing rate limiting on the relay API
  * - Enabling audit logging by setting DEBUG=1
  */
 
@@ -54,6 +61,11 @@ const CLAUDE_CLI = process.env.CLAUDE_CLI_PATH || 'claude'; // Configurable Clau
 const ALLOW_ALL_COMMANDS = process.env.TELEPORTATION_DAEMON_ALLOW_ALL_COMMANDS === 'true';
 const HEARTBEAT_INTERVAL_MS = parseInt(process.env.DAEMON_HEARTBEAT_INTERVAL_MS || '30000', 10); // 30 sec default
 
+// Message routing configuration
+// REQUIRE_COMMAND_WHITELIST: If true, use legacy shell execution with command whitelist
+// Default: false (all messages route to Claude Code)
+const REQUIRE_COMMAND_WHITELIST = process.env.TELEPORTATION_REQUIRE_COMMAND_WHITELIST === 'true';
+
 // Machine coder configuration
 // PREFERRED_CODER: 'claude-code' | 'gemini-cli' | 'auto' (default: auto)
 // 'auto' will use Claude Code if available, otherwise Gemini CLI
@@ -68,6 +80,10 @@ const ROUTER_ENABLED = process.env.TELEPORTATION_ROUTER_ENABLED !== 'false' && !
 const ROUTER_VERBOSE = process.env.TELEPORTATION_ROUTER_VERBOSE === 'true';
 const ROUTER_MAX_ESCALATIONS = parseInt(process.env.TELEPORTATION_ROUTER_MAX_ESCALATIONS || '2', 10);
 
+// Test helper: allows mocking executeWithMachineCoder in tests
+// In production, this just holds null and the real function is called
+const _executeWithMachineCoderRef = { fn: null };
+
 // Lazy-initialized router instance
 let _router = null;
 function getRouter() {
@@ -184,8 +200,17 @@ const MAX_EXECUTIONS = 1000; // Maximum executions to keep in memory (LRU cache)
 // Maximum output size to prevent memory issues
 const MAX_OUTPUT_SIZE = 100_000; // 100KB
 
-// Command whitelist for inbox execution (security: prevents arbitrary command execution)
-// Only commands starting with these prefixes are allowed
+// LEGACY SHELL EXECUTION:
+// These constants and functions are kept for:
+// 1. Whitelist fallback mode (TELEPORTATION_REQUIRE_COMMAND_WHITELIST=true)
+// 2. Direct shell execution via approval queue processing
+// 3. Backward compatibility with existing tests
+//
+// For inbox messages, all prompts are now routed to Claude Code by default.
+// See handleInboxMessage() for the current flow.
+
+// Command whitelist for legacy shell execution (security: prevents arbitrary command execution)
+// Only commands starting with these prefixes are allowed when TELEPORTATION_REQUIRE_COMMAND_WHITELIST=true
 const ALLOWED_COMMAND_PREFIXES = [
   'git ',        // Git operations
   'npm ',        // NPM package management
@@ -253,7 +278,15 @@ function sanitizeCommand(command) {
 }
 
 /**
- * Check if a command is allowed based on the whitelist
+ * LEGACY: Check if a command is allowed based on the whitelist
+ *
+ * This function is kept for:
+ * - Whitelist fallback mode (TELEPORTATION_REQUIRE_COMMAND_WHITELIST=true)
+ * - executeCommand() which is used by approval queue processing
+ * - Backward compatibility with existing tests
+ *
+ * For inbox messages, all prompts are now routed to Claude Code by default.
+ *
  * @param {string} command - The command to validate
  * @returns {{ allowed: boolean, reason?: string }}
  */
@@ -685,9 +718,17 @@ async function checkIdleTimeout() {
 }
 
 /**
- * Execute a shell command in the session's working directory
+ * LEGACY: Execute a shell command in the session's working directory
  * Returns { success, stdout, stderr, exit_code, error }
  *
+ * This function is kept for:
+ * - Approval queue processing (executing approved tool calls)
+ * - Whitelist fallback mode (TELEPORTATION_REQUIRE_COMMAND_WHITELIST=true)
+ * - Backward compatibility with existing tests
+ *
+ * For inbox messages, all prompts are now routed to Claude Code by default.
+ * See handleInboxMessage() and executeWithMachineCoder() for the current flow.
+ *
  * Security: Commands must be in the ALLOWED_COMMAND_PREFIXES whitelist
  */
 async function executeCommand(session_id, command) {
@@ -755,7 +796,18 @@ async function handleInboxMessage(session_id, message) {
     // For command messages, execute the command and post result back to the main agent inbox
     if (meta.type === 'command') {
       const replyAgentId = meta.reply_agent_id || 'main';
-      const commandText = message.text || '';
+      const commandText = (message.text || '').trim();
+
+      // Validate non-empty message before processing
+      if (!commandText) {
+        console.warn(`[daemon] Received empty message ${message.id}, skipping execution`);
+        // Still acknowledge the message to prevent re-delivery
+        await fetch(`${RELAY_API_URL}/api/messages/${encodeURIComponent(message.id)}/ack`, {
+          method: 'POST',
+          headers: { 'Authorization': `Bearer ${RELAY_API_KEY}` }
+        });
+        return;
+      }
 
       // Invalidate pending approvals BEFORE executing new command
       // This prevents race conditions where stale approvals could be acted upon
@@ -783,39 +835,57 @@ async function handleInboxMessage(session_id, message) {
         // Continue with execution - this is not critical
       }
 
-      // Hybrid Execution Logic:
-      // 1. Check if it's a valid whitelisted shell command
-      const validation = isCommandAllowed(commandText);
+      // Route message to Claude Code (default) or use legacy shell execution (with feature flag)
       let executionResult;
-      let executionType = 'shell';
-
-      if (validation.allowed) {
-        // Fast path: Execute shell command directly
-        console.log(`[daemon] Executing direct shell command: ${commandText}`);
-        executionResult = await executeCommand(session_id, commandText);
+      let executionType;
+
+      // Feature flag: TELEPORTATION_REQUIRE_COMMAND_WHITELIST enables legacy whitelist-based execution
+      if (REQUIRE_COMMAND_WHITELIST) {
+        // Legacy mode: check if command is in whitelist, execute via shell if allowed
+        const validation = isCommandAllowed(commandText);
+        if (validation.allowed) {
+          executionType = 'shell';
+          console.log(`[daemon] Legacy shell execution: ${commandText.substring(0, 100)}`);
+          executionResult = await executeCommand(session_id, commandText);
+        } else {
+          // Command not in whitelist - reject in legacy mode
+          console.log(`[daemon] Command rejected by whitelist: ${commandText.substring(0, 100)}`);
+          executionResult = {
+            success: false,
+            exit_code: -1,
+            stdout: '',
+            stderr: '',
+            error: validation.reason
+          };
+          executionType = 'rejected';
+        }
       } else {
-        // Fallback: Natural language prompt via machine coder (Claude/Gemini/etc.)
-        console.log(`[daemon] Command not in whitelist, handing off to machine coder: ${commandText}`);
+        // Default mode: route all messages to Claude Code
         executionType = 'agent';
-        
-        // Stream output callback for inbox message execution
+        console.log(`[daemon] Routing message to Claude Code: ${commandText.substring(0, 100)}`);
+
+        // Stream output callback for message execution
         const onOutput = createStreamingCallback(session_id, message.id, {
           message_id: message.id
         });
-        
+
         // Use the unified machine coder interface
         // This supports Claude Code, Gemini CLI, and future backends
+        // Note: _executeWithMachineCoderRef.fn is used for test mocking
         try {
-          executionResult = await executeWithMachineCoder(session_id, commandText, {
+          const executeFn = _executeWithMachineCoderRef.fn || executeWithMachineCoder;
+          executionResult = await executeFn(session_id, commandText, {
             onOutput,
             approvalContext: { type: 'inbox_message', id: message.id },
           });
-          
+
           // Track which coder was used
           if (executionResult.coder_used) {
             console.log(`[daemon] Executed via ${executionResult.coder_used}`);
           }
         } catch (error) {
+          const preview = commandText.substring(0, 50);
+          console.error(`[daemon] Machine coder execution failed for "${preview}...":`, error.message);
           executionResult = {
             success: false,
             exit_code: -1,
@@ -838,13 +908,17 @@ async function handleInboxMessage(session_id, message) {
       );
 
       // Build result message with execution details
+      // Note: executeWithMachineCoder returns 'output', legacy executeCommand returns 'stdout'
+      // Using ?? to handle empty string correctly (|| would skip empty string)
       let resultText = '';
       if (executionResult.success) {
-        const header = executionType === 'agent' ? 'Claude executed your request:\n\n' : 'Command executed successfully:\n\n';
-        resultText = `${header}${executionResult.stdout}`;
+        const resultOutput = executionResult.output ?? executionResult.stdout ?? '';
+        resultText = `Claude completed your request:\n\n${resultOutput}`;
       } else {
-        const header = executionType === 'agent' ? 'Claude failed to execute request:\n\n' : `Command failed with exit code ${executionResult.exit_code}:\n\n`;
-        resultText = `${header}Error: ${executionResult.error}\n\nStderr:\n${executionResult.stderr}`;
+        resultText = `Claude failed to complete request:\n\nError: ${executionResult.error}`;
+        if (executionResult.stderr) {
+          resultText += `\n\nDetails:\n${executionResult.stderr}`;
+        }
       }
 
       try {
@@ -1525,11 +1599,19 @@ async function executeWithMachineCoder(session_id, prompt, options = {}) {
   
   // Execute via the coder
   const startedAt = Date.now();
-  
+
   try {
-    // For Claude Code with resume support, use resume if we have a claude_session_id
+    // Always use execute() for remote inbox messages since our claude_session_id
+    // is actually the teleportation UUID, not a real Claude Code session ID.
+    // Passing UUID to claude --resume causes it to fail.
+    // Use UUID v4 regex pattern for robust detection instead of fragile hyphen check.
+    const UUID_V4_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
     let result;
-    if (coder.name === 'claude-code' && session.claude_session_id) {
+    const isValidClaudeSession = session.claude_session_id &&
+      session.claude_session_id !== session.session_id &&
+      !UUID_V4_PATTERN.test(session.claude_session_id);
+
+    if (coder.name === 'claude-code' && isValidClaudeSession) {
       result = await coder.resume(session.claude_session_id, prompt, execOptions);
     } else {
       result = await coder.execute(execOptions);
@@ -1975,7 +2057,14 @@ const __test = {
   _setLastSessionActivityAt: (value) => {
     lastSessionActivityAt = value;
   },
-  _getSessionsMap: () => sessions
+  _getSessionsMap: () => sessions,
+  // Test helper: inject mock for executeWithMachineCoder
+  _setExecuteWithMachineCoder: (mockFn) => {
+    _executeWithMachineCoderRef.fn = mockFn;
+  },
+  _resetExecuteWithMachineCoder: () => {
+    _executeWithMachineCoderRef.fn = null;
+  }
 };
 
 export {
@@ -2000,6 +2089,7 @@ export {
   sendStreamingMessage,
   MAX_EXECUTIONS,
   PREFERRED_CODER, // New: machine coder preference
+  REQUIRE_COMMAND_WHITELIST, // Feature flag for legacy whitelist mode
   // Router integration for cost-aware LLM calls
   routedCompletion,
   classifyTaskTier,

package/lib/machine-coders/claude-code-adapter.js

@@ -16,6 +16,51 @@ import { MachineCoder, CODER_NAMES } from './interface.js';
 
 const execAsync = promisify(exec);
 
+// Grace period before killing process after receiving result (allows hooks to finish)
+// Configurable via environment variable for production tuning
+const PROCESS_KILL_GRACE_MS = parseInt(process.env.TELEPORTATION_PROCESS_GRACE_MS || '50', 10);
+
+// Environment variables to pass to Claude Code process (allowlist for security)
+// Only pass essential env vars instead of spreading all of process.env
+const ALLOWED_ENV_VARS = [
+  'HOME',
+  'PATH',
+  'SHELL',
+  'USER',
+  'TERM',
+  'LANG',
+  'LC_ALL',
+  'TMPDIR',
+  'XDG_CONFIG_HOME',
+  'XDG_DATA_HOME',
+  'XDG_CACHE_HOME',
+  // Claude Code specific
+  'ANTHROPIC_API_KEY',
+  'CLAUDE_CODE_USE_BEDROCK',
+  'CLAUDE_CODE_USE_VERTEX',
+  // Node.js
+  'NODE_ENV',
+  'NODE_OPTIONS',
+];
+
+/**
+ * Build a filtered environment object for spawning Claude Code
+ * Uses allowlist approach for security - only passes essential env vars
+ * @param {string} sessionId - Teleportation session ID to pass
+ * @returns {Object} Environment object
+ */
+function buildSecureEnv(sessionId) {
+  const env = {};
+  for (const key of ALLOWED_ENV_VARS) {
+    if (process.env[key] !== undefined) {
+      env[key] = process.env[key];
+    }
+  }
+  // Always pass session ID to hooks
+  env.TELEPORTATION_SESSION_ID = sessionId;
+  return env;
+}
+
 /**
  * Check if a command exists on the system
  * @param {string} command
@@ -36,9 +81,25 @@ async function commandExists(command) {
 export class ClaudeCodeAdapter extends MachineCoder {
   name = CODER_NAMES.CLAUDE_CODE;
   displayName = 'Claude Code';
-  
+
   // Track running processes for stop()
   #runningProcesses = new Map();
+
+  /**
+   * Close stdin immediately to prevent Claude Code from hanging
+   * Claude Code waits for stdin to close when spawned - without this,
+   * the process hangs indefinitely waiting for possible input.
+   * @param {ChildProcess} proc - The spawned process
+   * @private
+   */
+  #closeStdinSafely(proc) {
+    try {
+      proc.stdin.end();
+    } catch (err) {
+      // Log but don't throw - stdin might already be closed or in error state
+      console.warn('[claude-adapter] Failed to close stdin:', err.message);
+    }
+  }
   
   /**
    * Check if Claude Code CLI is available
@@ -102,40 +163,39 @@ export class ClaudeCodeAdapter extends MachineCoder {
     
     // Output format for parsing
     args.push('--output-format', 'json');
-    
+
     return new Promise((resolve, reject) => {
       const startTime = Date.now();
       let stdout = '';
       let stderr = '';
       const toolCalls = [];
-      
+      let resolved = false; // Prevent double-resolution race condition
+      let killTimeout = null; // Track kill timeout for cleanup
+
       const proc = spawn('claude', args, {
         cwd: projectPath,
-        env: {
-          ...process.env,
-          // Pass session ID to hooks
-          TELEPORTATION_SESSION_ID: sessionId,
-        },
+        env: buildSecureEnv(sessionId),
       });
-      
+
       this.#runningProcesses.set(executionId, proc);
-      
+      this.#closeStdinSafely(proc);
+
       // Timeout handling
       const timeout = setTimeout(() => {
         proc.kill('SIGTERM');
         reject(new Error(`Execution timed out after ${timeoutMs}ms`));
       }, timeoutMs);
-      
+
       proc.stdout.on('data', (data) => {
         const chunk = data.toString();
         stdout += chunk;
-        
+
         // Try to parse JSON events for progress
         try {
           const lines = chunk.split('\n').filter(l => l.trim());
           for (const line of lines) {
             const event = JSON.parse(line);
-            
+
             // Track tool calls
             if (event.type === 'tool_use') {
               toolCalls.push({
@@ -145,12 +205,49 @@ export class ClaudeCodeAdapter extends MachineCoder {
                 timestamp: Date.now(),
               });
             }
-            
+
             onProgress?.({
               type: event.type,
               timestamp: Date.now(),
               data: event,
             });
+
+            // When we receive a final result, resolve early and kill the process
+            // This handles cases where hooks keep the process alive after completion
+            if (event.type === 'result') {
+              if (resolved) return; // Prevent double-resolution
+              resolved = true;
+
+              clearTimeout(timeout);
+              this.#runningProcesses.delete(executionId);
+
+              const durationMs = Date.now() - startTime;
+              const output = event.result || event.response || event.output || '';
+              const stats = { durationMs };
+
+              if (event.usage) {
+                stats.tokensUsed = event.usage.total_tokens;
+              }
+              if (event.cost || event.total_cost_usd) {
+                stats.cost = event.cost || event.total_cost_usd;
+              }
+              if (event.model) {
+                stats.model = event.model;
+              }
+
+              // Kill the process since we have the result (small delay for hooks to finish)
+              killTimeout = setTimeout(() => proc.kill('SIGTERM'), PROCESS_KILL_GRACE_MS);
+
+              resolve({
+                success: !event.is_error,
+                output,
+                error: event.is_error ? (event.error || 'Unknown error') : undefined,
+                toolCalls,
+                stats,
+                executionId,
+              });
+              return;
+            }
           }
         } catch {
           // Not JSON, just raw output
@@ -172,15 +269,19 @@ export class ClaudeCodeAdapter extends MachineCoder {
       });
       
       proc.on('close', (code) => {
+        if (resolved) return; // Prevent double-resolution
+        resolved = true;
+
         clearTimeout(timeout);
+        if (killTimeout) clearTimeout(killTimeout); // Clean up kill timeout if process exits naturally
         this.#runningProcesses.delete(executionId);
-        
+
         const durationMs = Date.now() - startTime;
-        
+
         // Try to parse final JSON output
         let output = stdout;
         let stats = { durationMs };
-        
+
         try {
           const result = JSON.parse(stdout);
           output = result.result || result.response || result.output || stdout;
@@ -196,7 +297,7 @@ export class ClaudeCodeAdapter extends MachineCoder {
         } catch {
           // Not JSON, use raw output
         }
-        
+
         resolve({
           success: code === 0,
           output,
@@ -238,45 +339,98 @@ export class ClaudeCodeAdapter extends MachineCoder {
     }
     
     args.push('--output-format', 'json');
-    
+
     return new Promise((resolve, reject) => {
       const startTime = Date.now();
       let stdout = '';
       let stderr = '';
       const toolCalls = [];
-      
+      let resolved = false; // Prevent double-resolution race condition
+      let killTimeout = null; // Track kill timeout for cleanup
+
       const proc = spawn('claude', args, {
         cwd: projectPath,
-        env: {
-          ...process.env,
-          TELEPORTATION_SESSION_ID: sessionId,
-        },
+        env: buildSecureEnv(sessionId),
       });
-      
+
       this.#runningProcesses.set(executionId, proc);
-      
+      this.#closeStdinSafely(proc);
+
       const timeout = setTimeout(() => {
         proc.kill('SIGTERM');
         reject(new Error(`Resume timed out after ${timeoutMs}ms`));
       }, timeoutMs);
-      
+
       proc.stdout.on('data', (data) => {
-        stdout += data.toString();
-        onProgress?.({
-          type: 'output',
-          timestamp: Date.now(),
-          data: { text: data.toString() },
-        });
+        const chunk = data.toString();
+        stdout += chunk;
+
+        // Try to parse JSON result
+        try {
+          const lines = chunk.split('\n').filter(l => l.trim());
+          for (const line of lines) {
+            const event = JSON.parse(line);
+
+            onProgress?.({
+              type: event.type || 'output',
+              timestamp: Date.now(),
+              data: event,
+            });
+
+            // When we receive a final result, resolve early and kill the process
+            if (event.type === 'result') {
+              if (resolved) return; // Prevent double-resolution
+              resolved = true;
+
+              clearTimeout(timeout);
+              this.#runningProcesses.delete(executionId);
+
+              const output = event.result || event.response || event.output || '';
+              const stats = { durationMs: Date.now() - startTime };
+
+              if (event.usage) {
+                stats.tokensUsed = event.usage.total_tokens;
+              }
+              if (event.cost || event.total_cost_usd) {
+                stats.cost = event.cost || event.total_cost_usd;
+              }
+
+              // Kill the process since we have the result (small delay for hooks to finish)
+              killTimeout = setTimeout(() => proc.kill('SIGTERM'), PROCESS_KILL_GRACE_MS);
+
+              resolve({
+                success: !event.is_error,
+                output,
+                error: event.is_error ? (event.error || 'Unknown error') : undefined,
+                toolCalls,
+                stats,
+                executionId,
+              });
+              return;
+            }
+          }
+        } catch {
+          // Not JSON, just raw output
+          onProgress?.({
+            type: 'output',
+            timestamp: Date.now(),
+            data: { text: chunk },
+          });
+        }
       });
-      
+
       proc.stderr.on('data', (data) => {
         stderr += data.toString();
       });
-      
+
       proc.on('close', (code) => {
+        if (resolved) return; // Prevent double-resolution
+        resolved = true;
+
         clearTimeout(timeout);
+        if (killTimeout) clearTimeout(killTimeout); // Clean up kill timeout if process exits naturally
         this.#runningProcesses.delete(executionId);
-        
+
         resolve({
           success: code === 0,
           output: stdout,
@@ -286,7 +440,7 @@ export class ClaudeCodeAdapter extends MachineCoder {
           executionId,
         });
       });
-      
+
       proc.on('error', (err) => {
         clearTimeout(timeout);
         this.#runningProcesses.delete(executionId);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "teleportation-cli",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Remote approval system for Claude Code - approve AI coding changes from your phone",
   "type": "module",
   "main": "teleportation-cli.cjs",