@heart-of-gold/toolkit 0.1.14 → 0.1.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heart-of-gold/toolkit",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "type": "module",
   "description": "Cross-platform installer for Heart of Gold skills — works with Codex, OpenCode, Pi, Claude Code, and more",
   "bin": {

package/plugins/guide/skills/claude-code/SKILL.md

@@ -9,6 +9,8 @@ Use this skill to hand a bounded task to Claude Code from the current harness, c
 
 This skill is task-based, not review-only. Use `plan` for safe read-only analysis, but use other permission modes when the task requires command execution or edits.
 
+The canonical execution path is direct `claude` CLI usage, mirroring the `codex` skill's direct `codex exec` pattern. The bundled wrapper is optional and must not replace the direct path unless the user explicitly asks for it or you are debugging Claude Code invocation behavior itself.
+
 ## Available Models
 
 | Model | Best for |
@@ -37,11 +39,15 @@ Choose the permission mode based on what Claude Code needs to do:
 `plan` is not the general default for this skill. It is only the safe default for bounded read-only tasks.
 
 ## Running a Task
-1. Ask the user which model alias to use (default: `sonnet`) and which permission mode to use when that choice materially affects behavior.
-2. Decide whether Claude should receive the artifact directly or discover it itself:
+1. Always ask the user which model alias to use (default: `sonnet`) before running Claude Code, unless the user already specified the model.
+2. Ask for permission mode in the same prompt when the user did not specify it. Default to:
+   - `plan` for bounded read-only analysis
+   - `acceptEdits` for implementation or refactoring work
+   - `default` when Claude needs broader repo exploration without auto-edit authority
+3. Decide whether Claude should receive the artifact directly or discover it itself:
    - Pass diffs, logs, or file contents via stdin for safe read-only review
    - Let Claude inspect the working tree when the task requires tool use
-3. Assemble the command with the appropriate options:
+4. Assemble the command with the appropriate options:
    - `-p, --print` for non-interactive output
    - `--output-format <text|json|stream-json>`
    - `--model <MODEL>`
@@ -52,17 +58,19 @@ Choose the permission mode based on what Claude Code needs to do:
    - `--add-dir <DIR>` when Claude must read outside the current working directory
    - `--name <NAME>` when you want a stable, human-readable session
    - `"your prompt here"` as the final positional argument
-4. Prefer `--output-format text` for human-readable summaries and `--output-format json` for automation or machine parsing.
-5. In headless automation, prefer explicit permissions:
+5. Prefer `--output-format text` for human-readable summaries and `--output-format json` for automation or machine parsing.
+6. In headless automation, prefer explicit permissions:
    - `plan` for provided artifacts
    - `acceptEdits` for edit-capable runs
    - `default` only when prompts are acceptable or when permissions are constrained with `--allowedTools`
-6. Run the command, capture stdout/stderr, and summarize the outcome for the user.
+7. Run the command, capture stdout/stderr, and summarize the outcome for the user.
+8. If Claude Code does not actually return output, stop and report that failure. Do not substitute your own review or analysis and present it as if it came from Claude Code.
 
 ## Codex Execution
 
 When this skill is used from Codex, the skill cannot bypass Codex sandbox policy on its own. Instead, instruct Codex to choose the correct execution path:
 
+- Prefer the direct `claude` command patterns in this skill. Do not silently substitute the bundled wrapper for the normal path just because it exists.
 - Run inside the sandbox first when the task is clearly local and read-only.
 - If Claude Code needs network access, auth refresh, access outside the writable sandbox, or the in-sandbox run fails or hangs for likely sandbox reasons, rerun via `exec_command` with `sandbox_permissions: "require_escalated"`.
 - Use a concise justification that tells the reviewer why Claude Code needs elevation, for example:
@@ -164,8 +172,15 @@ Use it as a thin helper around the documented CLI patterns above. It supports:
 - `--name`
 - `--no-session-persistence`
 - `--verbose`
+- `--timeout-seconds`
+
+Do not treat the wrapper as the default execution path for this skill. Use it only when:
+
+- the user explicitly asks to use the wrapper
+- you are debugging Claude Code hangs or invocation edge cases
+- you need its optional timeout helper for diagnosis
 
-Prefer the direct `claude` commands in this document when debugging or when you need to reason about permissions precisely.
+Otherwise, use the direct `claude` commands in this document.
 
 ## Following Up
 
@@ -199,8 +214,9 @@ claude -r latest -p \
 ## Error Handling
 
 - Stop and report failures whenever `claude --version` or a `claude -p` command exits non-zero.
+- If Claude Code hangs or times out, report that Claude did not complete in this environment. Do not continue with a self-authored substitute while implying it came from Claude.
 - If Claude Code reports permission issues, choose the correct permission mode or constrain tools explicitly.
 - If a headless run gets stuck on permissions, either switch to `plan`, use `acceptEdits`, or provide `--allowedTools` / a permission prompt tool.
 - In Codex, if the likely cause is sandboxing or network denial, rerun with reviewer-approved `require_escalated` execution instead of repeatedly retrying the same sandboxed command.
 - Do not use `bypassPermissions` unless the user explicitly approves it.
-- If debugging a failing wrapper invocation, fall back to the direct `claude` command first.
+- If the direct `claude` path fails, report that failure directly. Do not route around it by pretending a wrapper run or a self-authored review is equivalent to Claude output.

package/plugins/guide/skills/claude-code/scripts/run-claude-code.sh

@@ -25,6 +25,7 @@ Options:
   --permission-prompt-tool CMD  External permission handler for headless runs
   --no-session-persistence      Do not persist the session on disk
   --verbose                     Enable verbose Claude Code output
+  --timeout-seconds N           Kill Claude Code if it does not finish within N seconds
   --help                        Show this help text
 EOF
 }
@@ -43,6 +44,7 @@ name=""
 verbose=0
 no_session_persistence=0
 permission_prompt_tool=""
+timeout_seconds=""
 declare -a add_dirs=()
 declare -a allowed_tools=()
 declare -a disallowed_tools=()
@@ -130,6 +132,11 @@ while [[ $# -gt 0 ]]; do
       verbose=1
       shift
       ;;
+    --timeout-seconds)
+      [[ $# -ge 2 ]] || { echo "Missing value for --timeout-seconds" >&2; exit 2; }
+      timeout_seconds="$2"
+      shift 2
+      ;;
     --help|-h)
       usage
       exit 0
@@ -218,4 +225,24 @@ if [[ -n "$cwd" ]]; then
   cd "$cwd"
 fi
 
-exec "${cmd[@]}"
+if [[ -n "$timeout_seconds" ]]; then
+  python3 -c '
+import os, signal, subprocess, sys
+timeout = float(sys.argv[1])
+cmd = sys.argv[2:]
+proc = subprocess.Popen(cmd)
+try:
+    rc = proc.wait(timeout=timeout)
+    sys.exit(rc)
+except subprocess.TimeoutExpired:
+    proc.kill()
+    try:
+        proc.wait(timeout=5)
+    except subprocess.TimeoutExpired:
+        pass
+    print(f"Claude Code timed out after {timeout:g} seconds", file=sys.stderr)
+    sys.exit(124)
+' "$timeout_seconds" "${cmd[@]}"
+else
+  exec "${cmd[@]}"
+fi

package/src/index.ts

@@ -7,7 +7,7 @@ import { targetsCommand } from "./commands/targets";
 const main = defineCommand({
   meta: {
     name: "heart-of-gold",
-    version: "0.1.14",
+    version: "0.1.16",
     description:
       "Cross-platform installer for Heart of Gold skills — Codex, OpenCode, Pi, Claude Code, and more",
   },