Unstick Session

Detect what's blocking a session and suggest or apply a resolution.

Arguments

$ARGUMENTS format: <session-name> [auto]

Instructions

1. •

   Parse arguments:

   • •Extract session name (required)
   • •Check for auto flag
2. •

   Capture session output:

   bash

   "$PLUGIN_DIR/bin/capture-session" "<session_name>" 40
   

3. •

   Analyze the output and determine:

   • •Is it actively working? (Look for ✢, ⏺, Thinking…)
   • •Is it stuck? What type?

   Stuck types:

   Type	Signs	Fix
   yes_no	(y/n), [Y/n], Continue?	Send y or n
   multi_choice	❯ 1., numbered options	Send number
   text_input	Enter:, Type:, waiting for input	Send text or Escape
   permission	Bash command, Allow, permission dialog	Send y or n
   interactive_editor	: alone (vim), (END), --More--	:q! or q
   hanging_command	No output, no prompt	Ctrl-C
   worker_idle	❯ prompt, no task	Needs new task

4. •

   Report findings:

   code

   ## Session: <name>
   
   **Status:** <working/stuck>
   **Stuck Type:** <type or N/A>
   **Details:** <what you see>
   
   **Suggested Fix:** <what to do>
   

5. •

   If auto mode and stuck:

   Execute the fix using tmux send-keys:

   bash

   # For yes_no:
   tmux send-keys -t "<session>" "y" && tmux send-keys -t "<session>" Enter
   
   # For multi_choice:
   tmux send-keys -t "<session>" "1" && tmux send-keys -t "<session>" Enter
   
   # For text_input (cancel):
   tmux send-keys -t "<session>" Escape
   
   # For permission:
   tmux send-keys -t "<session>" "y" && tmux send-keys -t "<session>" Enter
   
   # For interactive_editor (vim):
   tmux send-keys -t "<session>" Escape && tmux send-keys -l -t "<session>" ":q!" && tmux send-keys -t "<session>" Enter
   
   # For interactive_editor (pager):
   tmux send-keys -t "<session>" "q"
   
   # For hanging_command:
   tmux send-keys -t "<session>" C-c
   

   Then re-capture and verify the fix worked.

Example

/session-tools:unstick-session ai-worker-001

## Session: ai-worker-001

**Status:** stuck
**Stuck Type:** permission
**Details:** Waiting for approval: "Bash command: npm install"

**Suggested Fix:** Send 'y' Enter to approve, or 'n' Enter to deny