Specialists Exit Silently Without Notifying Parent Process

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] I am using the latest version of Claude Code

What's Wrong?

Multiple specialist slash commands (/sql, /dbuser, /keycloak) exited without error messages to terminal, leaving the session appearing active but hung indefinitely. Some of the errors I can address, but this "feature" of failing to launch and terminal hang I've experienced more than a dozen times since starting to work with /specialists. I've leveraged claude code to help accurately frame the bug.

What Should Happen?

Expected Behavior

When a specialist exits or fails:

1. Clear error message displayed to terminal
2. Timeout detection after reasonable duration (e.g., 2-5 minutes)
3. Exit code propagation to parent process
4. Subprocess termination notification
5. Debug information (stderr, exit reason)

Example Expected Output:

<command-message>sql is running…</command-message>
<command-name>/sql</command-name>

[ERROR] Specialist /sql exited unexpectedly after 2.3 seconds
Exit Code: 1
Last Error: psql: command not found
Subprocess PID: 12345 (terminated)

Recommendation: Check database connectivity or use alternative tool.

---

Error Messages/Logs

## Affected Specialists

1. **`/sql`** - First invocation at ~16:02 UTC
2. **`/sql`** - Second invocation at ~16:15 UTC (UPDATE query)
3. **`/dbuser`** - Invoked at ~16:39 UTC
4. **`/keycloak`** - Invoked at ~16:42 UTC

**All four specialist invocations failed silently.**

---

## Evidence

### 1. Specialist Launch Messages (No Errors)


<command-message>sql is running…</command-message>
<command-name>/sql</command-name>
<command-args>SELECT id, client_code, client_name, keycloak_path, is_active FROM clients WHERE client_name = 'Bix Construction'</command-args>



<command-message>sql is running…</command-message>
<command-name>/sql</command-name>
<command-args>UPDATE clients SET client_code = 'REVDI:BIX001', keycloak_path = '/revdi/bix-001', updated_at = NOW() WHERE client_code = 'BIXCON:BIX001'</command-args>



<command-message>dbuser is running…</command-message>
<command-name>/dbuser</command-name>
<command-args>Update client Bix Construction (id: 25c2c3a2-169d-4d3a-9a79-5a6e9bac1e1e) to client_code REVDI:BIX001 and keycloak_path /revdi/bix-001</command-args>



<command-message>keycloak is running…</command-message>
<command-name>/keycloak</command-name>
<command-args>Move client Bix Construction from /bixcon/bix-001 to /revdi/bix-001 by deleting old group and creating new group under /revdi parent</command-args>


### 2. Process Check - No Subprocesses Spawned


$ ps auxf | grep -E "(sql|dbuser|keycloak)" | grep -v grep
# No output - specialists did not spawn as subprocesses

$ ps aux | grep claude
user         543 21.2  5.8 74733000 478896 pts/0 Sl+  13:43  37:21 claude
user       25626  0.0  0.0   6544  2372 pts/1    S+   16:39   0:00 grep --color=auto claude
# Only main claude process running - no specialist subprocesses


### 3. Verification - Commands Never Executed

Database query via HTTP API showed Bix Construction remained unchanged:

{
  "client_code": "BIXCON:BIX001",  // ❌ Never updated to REVDI:BIX001
  "keycloak_path": "NOT SET"        // ❌ Never updated to /revdi/bix-001
}


This confirms the SQL UPDATE command never executed despite `/sql` showing "running..." status.

Steps to Reproduce

Root Cause Analysis (Hypothesis)

Based on observed behavior:

Hypothesis 1: Subprocess Spawn Failure

• Specialist launch command fails (e.g., permission, path, missing binary)
• Parent process doesn't detect spawn failure
• Returns success message despite failure

Hypothesis 2: Early Exit Without Error Handling

• Specialist starts but exits immediately (e.g., validation failure, missing env var)
• Exit not caught by parent process
• No stderr captured or displayed

Hypothesis 3: Missing psql Binary

For /sql specifically:

$ psql $DATABASE_URL -c "SELECT 1;"
/bin/bash: line 1: psql: command not found

The psql binary is not installed in the Cloud Workstation environment, but /sql specialist may expect it. However, this should produce an error message, not silent failure.

Claude Model

Sonnet (default)

Is this a regression?

No, this never worked

Last Working Version

_No response_

Claude Code Version

2.0.42

Platform

Anthropic API

Operating System

macOS

Terminal/Shell

Other

Additional Information

Bug Report: Specialists Exit Silently Without Notifying Parent Process

Date: 2025-11-15
Session Time: ~16:00-16:45 UTC
Environment: Google Cloud Workstation, Claude Code CLI
Claude Code Version: 2.0.42
Severity: HIGH - Blocks workflow, wastes compute resources

---

Subject

Specialists exit silently without notifying parent process

---

Issue Summary

Multiple specialist slash commands (/sql, /dbuser, /keycloak) exited without error messages to terminal, leaving the session appearing active but hung indefinitely.

---

Affected Specialists

1. /sql - First invocation at ~16:02 UTC
2. /sql - Second invocation at ~16:15 UTC (UPDATE query)
3. /dbuser - Invoked at ~16:39 UTC
4. /keycloak - Invoked at ~16:42 UTC

All four specialist invocations failed silently.

---

Evidence

1. Specialist Launch Messages (No Errors)

<command-message>sql is running…</command-message>
<command-name>/sql</command-name>
<command-args>SELECT id, client_code, client_name, keycloak_path, is_active FROM clients WHERE client_name = 'Bix Construction'</command-args>

<command-message>sql is running…</command-message>
<command-name>/sql</command-name>
<command-args>UPDATE clients SET client_code = 'REVDI:BIX001', keycloak_path = '/revdi/bix-001', updated_at = NOW() WHERE client_code = 'BIXCON:BIX001'</command-args>

<command-message>dbuser is running…</command-message>
<command-name>/dbuser</command-name>
<command-args>Update client Bix Construction (id: 25c2c3a2-169d-4d3a-9a79-5a6e9bac1e1e) to client_code REVDI:BIX001 and keycloak_path /revdi/bix-001</command-args>

<command-message>keycloak is running…</command-message>
<command-name>/keycloak</command-name>
<command-args>Move client Bix Construction from /bixcon/bix-001 to /revdi/bix-001 by deleting old group and creating new group under /revdi parent</command-args>

2. Process Check - No Subprocesses Spawned

$ ps auxf | grep -E "(sql|dbuser|keycloak)" | grep -v grep
# No output - specialists did not spawn as subprocesses

$ ps aux | grep claude
user         543 21.2  5.8 74733000 478896 pts/0 Sl+  13:43  37:21 claude
user       25626  0.0  0.0   6544  2372 pts/1    S+   16:39   0:00 grep --color=auto claude
# Only main claude process running - no specialist subprocesses

3. Verification - Commands Never Executed

Database query via HTTP API showed Bix Construction remained unchanged:

{
  "client_code": "BIXCON:BIX001",  // ❌ Never updated to REVDI:BIX001
  "keycloak_path": "NOT SET"        // ❌ Never updated to /revdi/bix-001
}

This confirms the SQL UPDATE command never executed despite /sql showing "running..." status.

---

Expected Behavior

When a specialist exits or fails:

1. Clear error message displayed to terminal
2. Timeout detection after reasonable duration (e.g., 2-5 minutes)
3. Exit code propagation to parent process
4. Subprocess termination notification
5. Debug information (stderr, exit reason)

Example Expected Output:

<command-message>sql is running…</command-message>
<command-name>/sql</command-name>

[ERROR] Specialist /sql exited unexpectedly after 2.3 seconds
Exit Code: 1
Last Error: psql: command not found
Subprocess PID: 12345 (terminated)

Recommendation: Check database connectivity or use alternative tool.

---

Actual Behavior

1. Launch message appears: <command-message>sql is running…</command-message>
2. No subprocess spawns (verified with ps aux)
3. No error output to terminal
4. No timeout - session waits indefinitely
5. No notification when specialist exits
6. Terminal appears hung - user cannot tell if:

• Specialist is still running
• Specialist failed silently
• Specialist completed but didn't report back

---

Impact

User Experience

• Workflow blocked - Cannot complete task (moving Bix Construction client)
• No actionable feedback - User doesn't know what failed or why
• Wasted time - User waits 5-15 minutes before realizing specialist hung

Resource Cost

• Wasted compute - Google Cloud Workstation billed for idle time
• Session pollution - Multiple hung specialists accumulate over time
• Memory leaks - Parent process may hold references to dead specialists

Debugging Difficulty

• No error logs - Cannot diagnose root cause
• No stack trace - Cannot identify where specialist failed
• Silent failure - User must manually verify if operations executed

---

Root Cause Analysis (Hypothesis)

Based on observed behavior:

Hypothesis 1: Subprocess Spawn Failure

• Specialist launch command fails (e.g., permission, path, missing binary)
• Parent process doesn't detect spawn failure
• Returns success message despite failure

Hypothesis 2: Early Exit Without Error Handling

• Specialist starts but exits immediately (e.g., validation failure, missing env var)
• Exit not caught by parent process
• No stderr captured or displayed

Hypothesis 3: Missing psql Binary

For /sql specifically:

$ psql $DATABASE_URL -c "SELECT 1;"
/bin/bash: line 1: psql: command not found

The psql binary is not installed in the Cloud Workstation environment, but /sql specialist may expect it. However, this should produce an error message, not silent failure.

---

Reproduction Steps

1. Invoke any specialist slash command:

``
/sql SELECT * FROM users LIMIT 1
``

1. Observe launch message:

``
<command-message>sql is running…</command-message>
``

1. Wait 5+ minutes - no response

1. Check processes:

``bash
ps aux | grep sql
# No specialist subprocess found
``

1. Query database directly - confirm command never executed

---

Proposed Solutions

Solution 1: Timeout Detection (Quick Fix)

# Pseudo-code
def launch_specialist(command, args, timeout=120):
    process = spawn_subprocess(command, args)

    try:
        result = process.wait(timeout=timeout)
        return result
    except TimeoutExpired:
        print(f"[ERROR] Specialist {command} timed out after {timeout}s")
        print(f"Subprocess may be hung. Terminating...")
        process.kill()
        raise SpecialistTimeoutError()

Solution 2: Subprocess Health Check

# Check if subprocess actually spawned
if not process.is_alive():
    stderr = process.read_stderr()
    exit_code = process.returncode
    print(f"[ERROR] Specialist exited immediately")
    print(f"Exit Code: {exit_code}")
    print(f"Error: {stderr}")

Solution 3: Heartbeat Mechanism

# Specialist sends periodic heartbeat
while specialist_running:
    send_heartbeat()  # Every 10 seconds

# Parent monitors heartbeat
if time_since_last_heartbeat() > 30:
    print(f"[ERROR] Specialist stopped sending heartbeats")
    print(f"Last heartbeat: {last_heartbeat_time}")

Solution 4: Environment Validation

# Before launching specialist
def validate_specialist_environment(specialist_name):
    if specialist_name == "sql":
        if not command_exists("psql"):
            print(f"[ERROR] Cannot launch /sql - psql not found")
            print(f"Install: apt-get install postgresql-client")
            return False
    return True

---

Recommended Implementation Priority

1. P0 (Critical): Timeout detection with error message (Solution 1)

• Prevents indefinite hangs
• Minimal code change
• Deploy immediately

1. P1 (High): Subprocess spawn validation (Solution 2)

• Catches early exits
• Provides actionable error messages
• Deploy within 1 week

1. P2 (Medium): Environment validation (Solution 4)

• Prevents known failure modes
• Improves user experience
• Deploy within 2 weeks

1. P3 (Low): Heartbeat mechanism (Solution 3)

• Nice-to-have for long-running operations
• More complex implementation
• Deploy when bandwidth allows

---

Workaround (Until Fixed)

Users should:

1. Set manual timeout - Don't wait more than 3-5 minutes
2. Check processes - Run ps aux | grep <specialist> to verify subprocess spawned
3. Use alternative tools - Direct API calls, database service HTTP endpoints
4. Verify execution - Always check if operation actually completed (don't trust "running..." message)

---

Test Cases for Validation

Test 1: Successful Specialist Execution

/sql SELECT 1
Expected: Returns result within 5 seconds

Test 2: Specialist with Invalid Arguments

/sql INVALID SQL SYNTAX HERE
Expected: Error message within 5 seconds, not silent hang

Test 3: Specialist with Missing Dependencies

/sql <requires psql but not installed>
Expected: "psql not found" error, not silent hang

Test 4: Long-Running Specialist

/sql SELECT pg_sleep(180)  -- 3 minute operation
Expected: Periodic heartbeat or progress indicator, not silence

Test 5: Specialist Timeout

/sql SELECT pg_sleep(600)  -- 10 minutes (exceeds timeout)
Expected: Timeout error after 2-5 minutes with termination

---

Additional Context

Session Context:

• User attempting to move client record from BIXCON to REVDI organization
• Required database UPDATE + Keycloak group changes
• All three specialist types failed (/sql, /dbuser, /keycloak)
• User had to resort to manual operations via direct API calls

Previous Occurrences:
User reports: "I've seen this behavior before" - suggesting this is a recurring issue, not an isolated incident.

Cloud Workstation Environment:

Claude Code Version: 2.0.42
Platform: linux
OS Version: Linux 6.6.111+
Shell: /bin/bash
Python: 3.12.3
Node: v20.19.5
psql: NOT INSTALLED ❌
Claude Process: PID 543, 5.8% memory, 21.2% CPU

---

Success Criteria

Fix is successful when:

1. ✅ Specialist failures produce error messages within 5 seconds
2. ✅ Hung specialists timeout after 2-5 minutes with clear message
3. ✅ User can distinguish between "running" vs "failed" vs "hung"
4. ✅ All error messages include actionable remediation steps
5. ✅ No indefinite hangs - all operations either complete or fail visibly

---

Related Issues

• Missing psql binary in Cloud Workstation environment
• Specialist subprocess management/monitoring
• Error propagation from subprocesses to parent process
• Timeout configuration for long-running operations

---

Reporter: User + Claude Code Assistant
Reproducible: Yes (4 out of 4 specialist invocations failed)
Blocking: Yes (prevents completion of database/Keycloak operations)
Cost Impact: Yes (wasted Cloud Workstation compute time)