@heart-of-gold/toolkit 0.1.11 → 0.1.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heart-of-gold/toolkit",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "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

@@ -1,91 +1,165 @@
 ---
 name: claude-code
-description: Use when the user asks to run Claude Code CLI (`claude`, `claude resume`) or asks for a second opinion, review, analysis, refactor, or follow-up specifically from Claude Code.
+description: Use when the user asks to run Claude Code CLI (`claude`, `claude resume`) for review, analysis, implementation, refactoring, debugging, or follow-up specifically through Claude Code.
 ---
 
 # Claude Code CLI Skill Guide
 
+Use this skill to hand a bounded task to Claude Code from the current harness, capture the result, and summarize it back to the user.
+
+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.
+
 ## Available Models
 
 | Model | Best for |
 | --- | --- |
+| `default` | Anthropic's recommended default for the current account and environment |
 | `sonnet` | Default recommendation for most coding, review, and analysis tasks |
-| `opus` | Stronger reasoning for ambiguous or high-stakes reviews |
-| `haiku` | Faster and cheaper for lightweight follow-ups |
+| `opus` | Stronger reasoning for ambiguous, high-stakes, or architecture-heavy work |
+| `haiku` | Fast, lightweight follow-ups and narrow questions |
+| `opusplan` | Hybrid mode that uses `opus` for planning and `sonnet` for execution |
+
+Prefer aliases over hardcoded snapshot names in this skill, because Anthropic documents aliases as the stable Claude Code interface and moves them forward as newer snapshots ship.
+
+Default recommendation: `sonnet` for most tasks, `opus` when depth matters more than speed, and `opusplan` when the task naturally alternates between planning and execution.
+
+## Permission Modes
+
+Choose the permission mode based on what Claude Code needs to do:
+
+| Mode | Use when | Notes |
+| --- | --- | --- |
+| `plan` | The task is read-only and Claude does not need to execute commands or edit files | Safest option for reviewing provided diffs, logs, file contents, or design docs |
+| `default` | Claude may need to inspect the repo more freely and you can tolerate permission prompts | Good interactive default; less reliable in headless automation unless permissions are pre-arranged |
+| `acceptEdits` | Claude should be able to make local code changes | Strong default for implementation, refactors, and fixes |
+| `bypassPermissions` | Full automation is required in a trusted sandbox and the user explicitly approves it | High risk; do not default to this |
 
-Default recommendation: `sonnet` for most tasks, `opus` when depth matters more than speed.
+`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 to use (default: `sonnet`) AND which permission mode to use (`plan`, `acceptEdits`, `default`, `auto`, or `bypassPermissions`) in a single prompt when both matter.
-2. Default to `--permission-mode plan` for reviews, read-only analysis, and second opinions.
+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:
+   - 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:
    - `-p, --print` for non-interactive output
    - `--output-format <text|json|stream-json>`
    - `--model <MODEL>`
    - `--permission-mode <MODE>`
    - `--effort <low|medium|high|max>`
-   - `--add-dir <DIR>` when Claude Code must read outside the current working directory
+   - `--max-turns <N>` to bound cost and runtime
+   - `--allowedTools` / `--disallowedTools` to constrain tool access
+   - `--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` unless the caller explicitly needs JSON.
-5. Run the command, capture stdout/stderr, and summarize the outcome for the user.
-6. After Claude Code completes, tell the user they can resume by asking for `claude resume` or another Claude Code follow-up.
+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:
+   - `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.
 
-### Quick Reference
-| Use case | Permission mode | Key flags |
-| --- | --- | --- |
-| Read-only review or analysis | `plan` | `-p --output-format text --permission-mode plan` |
-| Apply local edits | `acceptEdits` | `-p --output-format text --permission-mode acceptEdits` |
-| Stronger review pass | `plan` | `--model opus --effort high` |
-| Resume recent session | Inherited | `-r latest -p "new prompt" --output-format text` |
+## Best Practices
+
+- Use `--max-turns` for automation. It keeps review and implementation runs bounded.
+- Use `--output-format json` when another agent or script needs structured output.
+- Use `--allowedTools` to make headless runs more reliable and safer.
+- Pipe diffs or logs into Claude for read-only analysis instead of asking Claude to execute shell commands just to fetch them.
+- Use `acceptEdits` for real implementation work; do not force read-only `plan` mode onto edit tasks.
+- Use `bypassPermissions` only in a trusted sandbox and only with explicit user approval.
+- Use `-r latest -p` for follow-up instead of re-explaining the entire task.
 
-## Recommended Commands
+## Recommended Patterns
 
-### Review the current diff
+### 1. Review a provided diff safely
+
+Pass the diff via stdin and keep Claude in `plan` mode:
 
 ```bash
-claude -p \
+git diff --staged | claude -p \
   --output-format text \
   --model sonnet \
   --permission-mode plan \
-  --effort medium \
-  "Review the current git diff. Return findings ordered by severity with file paths and concise explanations."
+  --max-turns 1 \
+  "Review this diff. Return findings ordered by severity with file paths and concise explanations."
 ```
 
-### Review a specific file
+### 2. Ask Claude to inspect the repo and analyze
+
+Use `default` or a constrained tool set when Claude needs to discover context itself:
 
 ```bash
 claude -p \
   --output-format text \
   --model sonnet \
-  --permission-mode plan \
+  --permission-mode default \
+  --max-turns 4 \
+  --allowedTools "Read,Grep,Glob,Bash(git diff:*),Bash(git status:*)" \
+  "Analyze the current changes and explain the main design risks."
+```
+
+### 3. Ask Claude to implement or refactor
+
+Use `acceptEdits` when Claude should change files:
+
+```bash
+claude -p \
+  --output-format text \
+  --model sonnet \
+  --permission-mode acceptEdits \
   --effort high \
-  "Review src/server.ts for correctness, regressions, and missing tests. Keep the response concise."
+  --max-turns 8 \
+  "Implement the requested change in the current repo, keep the diff minimal, and summarize what changed."
 ```
 
-### Continue the latest Claude Code session
+### 4. Resume the latest Claude Code session
 
 ```bash
 claude -r latest -p \
   --output-format text \
-  "Focus only on the migration risk you mentioned. What is the safest rollout plan?"
+  "Focus only on the migration risk you mentioned earlier. What is the safest rollout plan?"
 ```
 
-## Optional Wrapper
+### 5. Request structured output for automation
 
-This skill also ships a convenience wrapper at `scripts/run-claude-code.sh`.
+```bash
+claude -p \
+  --output-format json \
+  --model sonnet \
+  --permission-mode plan \
+  --max-turns 1 \
+  "Summarize the provided diff as JSON with keys: verdict, findings, risks."
+```
 
-Use it only as a thin helper around the direct `claude` commands above:
+## Optional Wrapper
 
-- `scripts/run-claude-code.sh --check` verifies that Claude Code is installed
-- `scripts/run-claude-code.sh --prompt "..." --permission-mode plan` mirrors the direct CLI usage
+This skill also ships a convenience wrapper at `scripts/run-claude-code.sh`.
 
-Prefer the direct `claude` commands in this document when debugging, because they are easier to inspect and adapt.
+Use it as a thin helper around the documented CLI patterns above. It supports:
+
+- `--check`
+- `--prompt`
+- `--model`
+- `--permission-mode`
+- `--effort`
+- `--max-turns`
+- `--output-format`
+- `--allowed-tools`
+- `--disallowed-tools`
+- `--add-dir`
+- `--resume`
+- `--continue`
+- `--name`
+- `--no-session-persistence`
+- `--verbose`
+
+Prefer the direct `claude` commands in this document when debugging or when you need to reason about permissions precisely.
 
 ## Following Up
 
 - After every Claude Code command, confirm whether the user wants a follow-up, a resume, or a different model / permission mode.
-- When resuming, keep the new prompt narrow instead of restating the whole task.
 - Restate the chosen model, effort, and permission mode when proposing a retry.
+- Keep resume prompts narrow. Avoid restating the whole task unless context was lost.
 
 ## Critical Evaluation of Claude Code Output
 
@@ -95,7 +169,7 @@ Claude Code is a colleague, not an authority.
 - Trust your own knowledge when confident.
 - Push back if Claude Code makes a claim that conflicts with the code or docs in front of you.
 - Research disagreements before accepting them for high-impact decisions.
-- Do not defer blindly on models, tool flags, or fast-moving best practices.
+- Do not defer blindly on models, permissions, or fast-moving best practices.
 
 ### When Claude Code Seems Wrong
 1. State the disagreement clearly to the user.
@@ -113,6 +187,7 @@ claude -r latest -p \
 ## Error Handling
 
 - Stop and report failures whenever `claude --version` or a `claude -p` command exits non-zero.
-- If Claude Code reports permission issues, retry only after choosing the correct `--permission-mode`.
+- 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.
 - Do not use `bypassPermissions` unless the user explicitly approves it.
 - If debugging a failing wrapper invocation, fall back to the direct `claude` command first.

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

@@ -13,11 +13,18 @@ Options:
   --model MODEL                 Claude model or alias (default: sonnet)
   --permission-mode MODE        plan, acceptEdits, default, auto, dontAsk, bypassPermissions
   --effort LEVEL                low, medium, high, max
+  --max-turns N                 Bound the number of Claude turns
   --output-format FORMAT        text, json, stream-json (default: text)
   --resume VALUE                Resume a session, for example: latest
   --continue                    Continue the most recent session in the current directory
   --add-dir PATH                Additional directory to allow tool access to; repeatable
+  --allowed-tools SPEC          Allowed tools spec; repeatable
+  --disallowed-tools SPEC       Disallowed tools spec; repeatable
   --cwd PATH                    Working directory to run Claude Code from
+  --name NAME                   Human-readable session name
+  --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
   --help                        Show this help text
 EOF
 }
@@ -27,11 +34,18 @@ prompt=""
 model="sonnet"
 permission_mode=""
 effort=""
+max_turns=""
 output_format="text"
 resume_value=""
 continue_mode=0
 cwd=""
+name=""
+verbose=0
+no_session_persistence=0
+permission_prompt_tool=""
 declare -a add_dirs=()
+declare -a allowed_tools=()
+declare -a disallowed_tools=()
 
 while [[ $# -gt 0 ]]; do
   case "$1" in
@@ -59,6 +73,11 @@ while [[ $# -gt 0 ]]; do
       effort="$2"
       shift 2
       ;;
+    --max-turns)
+      [[ $# -ge 2 ]] || { echo "Missing value for --max-turns" >&2; exit 2; }
+      max_turns="$2"
+      shift 2
+      ;;
     --output-format)
       [[ $# -ge 2 ]] || { echo "Missing value for --output-format" >&2; exit 2; }
       output_format="$2"
@@ -78,11 +97,39 @@ while [[ $# -gt 0 ]]; do
       add_dirs+=("$2")
       shift 2
       ;;
+    --allowed-tools|--allowedTools)
+      [[ $# -ge 2 ]] || { echo "Missing value for --allowed-tools" >&2; exit 2; }
+      allowed_tools+=("$2")
+      shift 2
+      ;;
+    --disallowed-tools|--disallowedTools)
+      [[ $# -ge 2 ]] || { echo "Missing value for --disallowed-tools" >&2; exit 2; }
+      disallowed_tools+=("$2")
+      shift 2
+      ;;
     --cwd)
       [[ $# -ge 2 ]] || { echo "Missing value for --cwd" >&2; exit 2; }
       cwd="$2"
       shift 2
       ;;
+    --name)
+      [[ $# -ge 2 ]] || { echo "Missing value for --name" >&2; exit 2; }
+      name="$2"
+      shift 2
+      ;;
+    --permission-prompt-tool)
+      [[ $# -ge 2 ]] || { echo "Missing value for --permission-prompt-tool" >&2; exit 2; }
+      permission_prompt_tool="$2"
+      shift 2
+      ;;
+    --no-session-persistence)
+      no_session_persistence=1
+      shift
+      ;;
+    --verbose)
+      verbose=1
+      shift
+      ;;
     --help|-h)
       usage
       exit 0
@@ -127,12 +174,44 @@ if [[ -n "$effort" ]]; then
   cmd+=(--effort "$effort")
 fi
 
+if [[ -n "$max_turns" ]]; then
+  cmd+=(--max-turns "$max_turns")
+fi
+
+if [[ -n "$name" ]]; then
+  cmd+=(--name "$name")
+fi
+
+if [[ -n "$permission_prompt_tool" ]]; then
+  cmd+=(--permission-prompt-tool "$permission_prompt_tool")
+fi
+
+if [[ "$no_session_persistence" -eq 1 ]]; then
+  cmd+=(--no-session-persistence)
+fi
+
+if [[ "$verbose" -eq 1 ]]; then
+  cmd+=(--verbose)
+fi
+
 if ((${#add_dirs[@]} > 0)); then
   for dir in "${add_dirs[@]}"; do
     cmd+=(--add-dir "$dir")
   done
 fi
 
+if ((${#allowed_tools[@]} > 0)); then
+  for tool in "${allowed_tools[@]}"; do
+    cmd+=(--allowedTools "$tool")
+  done
+fi
+
+if ((${#disallowed_tools[@]} > 0)); then
+  for tool in "${disallowed_tools[@]}"; do
+    cmd+=(--disallowedTools "$tool")
+  done
+fi
+
 cmd+=("$prompt")
 
 if [[ -n "$cwd" ]]; then

package/src/index.ts

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