docs/SUBAGENT_WORKFLOW.md

@@ -8,7 +8,8 @@ Subagents work autonomously on issues. They research, build, and post progress/f
 
 ### Research Task (e.g., Issue #1)
 1. Subagent explores repo, runs opencode research
-2. Subagent writes findings to `/tmp/findings-{issue}.md`
+2. Subagent writes findings to `${KUGETSU_TEMP_DIR:-${HOME}/.local/share/opencode/tool-output}/findings-{issue}.md`
+   - Note: Use KUGETSU_TEMP_DIR instead of /tmp since opencode blocks /tmp access in headless mode
 3. Subagent posts findings as issue comment via curl
 4. User replies with feedback/questions on Gitea
 5. Subagent (or Hermes) reads reply, continues research
@@ -65,7 +66,7 @@ curl -X POST "https://git.example.com/api/v1/repos/{owner}/{repo}/pulls" \
 
 ```json
 {
-  "goal": "Work on Issue #{N}: {title}\n\nSteps:\n1. Explore ~/repositories/kugetsu\n2. Run opencode research on {specific question}\n3. Write findings to /tmp/findings-{N}.md\n4. cat /tmp/findings-{N}.md to display\n5. Post as issue comment via:\n   curl -X POST 'https://git.example.com/api/v1/repos/shoko/kugetsu/issues/{N}/comments' \\\n     -H 'Authorization: token ${GITEA_TOKEN}' \\\n     -H 'Content-Type: application/json' \\\n     -d @/tmp/findings-{N}.md\n6. Ask 2-3 clarifying questions at end for user\n\nToken: abcdefg012345\nRepo: ~/repositories/kugetsu",
+  "goal": "Work on Issue #{N}: {title}\n\nSteps:\n1. Explore ~/repositories/kugetsu\n2. Run opencode research on {specific question}\n3. Write findings to ${KUGETSU_TEMP_DIR:-${HOME}/.local/share/opencode/tool-output}/findings-{N}.md\n4. cat the findings file to display\n5. Post as issue comment via:\n   curl -X POST 'https://git.example.com/api/v1/repos/shoko/kugetsu/issues/{N}/comments' \\\n     -H 'Authorization: token ${GITEA_TOKEN}' \\\n     -H 'Content-Type: application/json' \\\n     -d @${KUGETSU_TEMP_DIR:-${HOME}/.local/share/opencode/tool-output}/findings-{N}.md\n6. Ask 2-3 clarifying questions at end for user\n\nToken: abcdefg012345\nRepo: ~/repositories/kugetsu\n\nNote: Use KUGETSU_TEMP_DIR instead of /tmp since opencode blocks /tmp access in headless mode",
   "context": "{additional context}",
   "toolsets": ["terminal"]
 }

docs/hermes-communication-patterns.md

@@ -150,8 +150,8 @@ result = delegate_task(
 Steps:
 1. Read existing docs in ~/repositories/kugetsu/docs/
 2. Identify message passing mechanisms used
-3. Write findings to /tmp/findings-4.md
-4. cat /tmp/findings-4.md
+3. Write findings to ${KUGETSU_TEMP_DIR:-${HOME}/.local/share/opencode/tool-output}/findings-4.md
+4. cat findings file
 5. Post findings as Gitea issue comment
 
 Gitea: git.example.com
@@ -178,8 +178,8 @@ terminal(
 ### 4.3 Posting Findings to Gitea (from subagent)
 
 ```bash
-# Write findings to temp file first
-cat > /tmp/findings-4.md << 'EOF'
+# Write findings to temp file first (use KUGETSU_TEMP_DIR instead of /tmp)
+cat > ${KUGETSU_TEMP_DIR:-${HOME}/.local/share/opencode/tool-output}/findings-4.md << 'EOF'
 # Research Findings for Issue #4
 
 ## Message Passing Mechanisms Identified
@@ -194,10 +194,10 @@ EOF
 
 # Post as issue comment
 curl -X POST "git.example.com/api/v1/repos/shoko/kugetsu/issues/4/comments" \
-  -H "Authorization: token &lt;YOUR_GITEA_TOKEN&gt;" \
+  -H "Authorization: token <YOUR_GITEA_TOKEN>" \
   -H "Content-Type: application/json" \
   -H "User-Agent: Kugetsu-Subagent/1.0" \
-  -d @/tmp/findings-4.md \
+  -d @${KUGETSU_TEMP_DIR:-${HOME}/.local/share/opencode/tool-output}/findings-4.md \
   --max-time 30 \
   --retry 3 \
   --retry-delay 5

docs/hermes-setup.md

@@ -180,7 +180,8 @@ For Kugetsu's parallel workflow, prefer `terminal(opencode run ...)` for coding
 
 ```bash
 # One-shot task (blocks until complete)
-terminal(command="opencode run 'Fix issue #1: add retry logic'", workdir="/tmp/issue-1")
+# Note: Use KUGETSU_TEMP_DIR instead of /tmp for opencode workdir
+terminal(command="opencode run 'Fix issue #1: add retry logic'", workdir="${KUGETSU_TEMP_DIR:-${HOME}/.local/share/opencode/tool-output}/issue-1")
 
 # Background TUI (interactive, returns session_id)
 terminal(command="opencode", workdir="~/project", background=true, pty=true)
@@ -319,7 +320,7 @@ git push --force-with-lease origin my-branch
    opencode run "Research/fix issue #{N}"
 
 4. Agent Posts to Gitea
-   curl -X POST .../issues/{N}/comments -d @/tmp/findings-{N}.md
+   curl -X POST .../issues/{N}/comments -d @${KUGETSU_TEMP_DIR:-${HOME}/.local/share/opencode/tool-output}/findings-{N}.md
 
 5. User Reviews on Gitea
    Comments on issues/PRs

docs/kugetsu-setup.md

@@ -261,7 +261,7 @@ For long-running tasks, SSH and spawn:
 
 ```bash
 ssh -p 2222 <username>@<host-ip> \
-  "kugetsu start github.com/shoko/kugetsu#11 'Implement feature' && echo 'Task done' | tee /tmp/task.log"
+  "kugetsu start github.com/shoko/kugetsu#11 'Implement feature' && echo 'Task done' | tee \${KUGETSU_TEMP_DIR:-${HOME}/.local/share/opencode/tool-output}/task.log"
 ```
 
 ### Port Forwarding for Web UI

docs/opencode-usage.md

@@ -97,9 +97,9 @@ cd $REVIEW && opencode run 'Review this PR vs main...'
 
 ```python
 delegate_task(tasks=[
-  {"goal": "Fix issue #1", "context": "...", "workdir": "/tmp/issue-1"},
-  {"goal": "Fix issue #2", "context": "...", "workdir": "/tmp/issue-2"},
-  {"goal": "Fix issue #3", "context": "...", "workdir": "/tmp/issue-3"},
+  {"goal": "Fix issue #1", "context": "...", "workdir": "${KUGETSU_TEMP_DIR}/issue-1"},
+  {"goal": "Fix issue #2", "context": "...", "workdir": "${KUGETSU_TEMP_DIR}/issue-2"},
+  {"goal": "Fix issue #3", "context": "...", "workdir": "${KUGETSU_TEMP_DIR}/issue-3"},
 ], max_iterations=50)
 ```
 
@@ -107,14 +107,15 @@ delegate_task(tasks=[
 - Cannot use: `delegate_task`, `clarify`, `memory`, `send_message` within subagents
 - Tasks must be fully self-contained
 - Exit with Ctrl+C or `process(action="kill")`, NOT `/exit`
+- Note: Use KUGETSU_TEMP_DIR instead of /tmp since opencode blocks /tmp in headless mode
 
 ### Terminal Parallel Calls
 
 No hard cap. Fire multiple `opencode run` in parallel:
 ```bash
-opencode run 'Fix issue #1' --workdir /tmp/issue-1 &
-opencode run 'Fix issue #2' --workdir /tmp/issue-2 &
-opencode run 'Fix issue #3' --workdir /tmp/issue-3 &
+opencode run 'Fix issue #1' --workdir ${KUGETSU_TEMP_DIR}/issue-1 &
+opencode run 'Fix issue #2' --workdir ${KUGETSU_TEMP_DIR}/issue-2 &
+opencode run 'Fix issue #3' --workdir ${KUGETSU_TEMP_DIR}/issue-3 &
 ```
 
 ### Schema Constraint

skills/kugetsu/pm/SKILL.md

@@ -84,7 +84,7 @@ When a request comes in:
 **You:** `kugetsu start <domain>/<user>/<repo>#126 Update README with installation instructions`
 
 **User:** "Create a file at /tmp/test.txt"
-**You:** `kugetsu start <domain>/<user>/<repo>#127 Create a file at /tmp/test.txt`
+**You:** `kugetsu start <domain>/<user>/<repo>#127 Create a file at ${KUGETSU_TEMP_DIR:-~/.local/share/opencode/tool-output}/test.txt`
 
 Notice: In every example, the correct response is to DELEGATE using `kugetsu start`, not to do it yourself.
 

skills/kugetsu/scripts/kugetsu

@@ -1248,6 +1248,10 @@ cmd_init() {
 # Verbosity level for PM agent output (verbose, default, or quiet)
 # KUGETSU_VERBOSITY=default
 
+# Temporary directory for agent operations (default: ~/.local/share/opencode/tool-output)
+# Use this instead of /tmp which may be blocked by opencode in headless mode
+# KUGETSU_TEMP_DIR="$HOME/.local/share/opencode/tool-output"
+
 # Git server configurations
 # Format: GIT_SERVERS["hostname"]="https://hostname"
 # Add servers with: kugetsu server add <name> <url>
@@ -1872,6 +1876,9 @@ main() {
         env)
             cmd_env "$@"
             ;;
+        post-comment)
+            cmd_post_comment "$@"
+            ;;
         doctor)
             cmd_doctor "$@"
             ;;