claude_hooks 1.0.2 → 1.2.0

data/docs/mitts/setup.md

@@ -0,0 +1,303 @@
+# Setting up Mitts in your repository
+
+This guide walks you through everything needed to get the Mitts coding bots running in a GitHub repository, from zero to a first successful run. It assumes **the Mitts files are already present in your repo** (workflows, the composite action, the `.github/mitts/` scripts, `.agents/skills/`, and `AGENTS.md`) — extracting/copying them into a fresh repo is covered separately.
+
+For *how the system works* (architecture, the hybrid context system, the
+security model), see [`mitts-bots.md`](./mitts-bots.md). This document is the
+operational checklist.
+
+> **Time:** ~10 minutes of clicking + CLI. Most of it is one-time GitHub config.
+> You need **admin** on the repo (some steps touch repo Settings and secrets).
+
+---
+
+## At a glance
+
+| Step | Where | One-time? | Required? |
+|---|---|---|---|
+| 1. Files present | repo | — | ✅ |
+| 2. LLM endpoint config (vars + secret) | Actions vars/secrets | ✅ | ✅ |
+| 3. Allow Actions to open PRs | Settings → Actions | ✅ | ✅ |
+| 4. Protect `main` (no bot merges) | Settings → Rules | ✅ | ✅ strongly |
+| 5. Gate the release secret behind `main` | Settings → Environments | ✅ | ✅ if you publish |
+| 6. Decide who can trigger the bots | collaborators / org | ongoing | ✅ |
+| 7. Land the workflows on `main` | git | ✅ | ✅ |
+| 8. First run | issue / PR comment | — | ✅ |
+| 9. Optional knobs | Actions vars | anytime | optional |
+
+---
+
+## 1. Confirm the files are in place
+
+You should have this tree in the repo (see `mitts-bots.md` → "The pieces" for
+what each does):
+
+```
+AGENTS.md
+.agents/skills/…                       # keyword-triggered skills
+.github/
+├── actions/run-mitts/action.yml       # shared setup + run (issue + PR bots)
+├── mitts/
+│   ├── agent_task.py                   # SDK agent runner
+│   ├── context_builder.py              # deterministic prompt builder
+│   ├── recall_tool.py                  # cross-run memory tool
+│   ├── instructions/{issues,prs}.md    # per-surface task templates
+│   └── hooks/block_dangerous.sh        # guardrail hook
+└── workflows/
+    ├── mitts-pr-review.yml
+    ├── mitts-issue.yml
+    └── mitts-pr-followup.yml
+```
+
+Nothing here needs editing to run — the scripts locate their siblings and the
+hook relative to their own path, and the workflows reference the composite
+action by path. If your default branch is not `main`, note it — a few steps
+below refer to "the default branch".
+
+---
+
+## 2. Configure your LLM endpoint
+
+Mitts talks to **your own OpenAI-compatible endpoint** via LiteLLM. Three values
+are needed. Two are non-secret (**Actions variables**) and one is secret (an
+**Actions secret**).
+
+The names below are the exact identifiers the workflows read — don't rename them
+unless you also change the workflows:
+
+| Name | Kind | Example | Read by |
+|---|---|---|---|
+| `OPENHANDS_LLM_MODEL` | variable | `openai/gpt-oss-120b` | `mitts-*.yml` → `llm-model` → `LLM_MODEL` |
+| `OPENHANDS_LLM_BASE_URL` | variable | `https://your-endpoint.example/v1` | → `llm-base-url` → `LLM_BASE_URL` |
+| `OPENHANDS_LLM_API_KEY` | **secret** | `sk-…` | → `llm-api-key` → `LLM_API_KEY` |
+
+> These keep the `OPENHANDS_` prefix on purpose: they configure the underlying
+> OpenHands SDK / LiteLLM layer, which Mitts wraps but does not rename. All three
+> Mitts workflows read the same three names.
+
+Set them with the `gh` CLI (from the repo directory):
+
+```bash
+gh variable set OPENHANDS_LLM_MODEL    --body "openai/<your-model-name>"
+gh variable set OPENHANDS_LLM_BASE_URL --body "https://<your-endpoint>/v1"
+gh secret   set OPENHANDS_LLM_API_KEY  --body "<your-api-key>"
+```
+
+Or in the UI: **Settings → Secrets and variables → Actions** → the **Variables**
+tab for the first two, the **Secrets** tab for the key.
+
+Two gotchas that cause almost every first-run failure:
+
+- **Use the `openai/` prefix on the model** so LiteLLM treats it as an
+  OpenAI-compatible backend (e.g. `openai/gpt-oss-120b`, `openai/llama-3.3-70b`).
+- **The base URL usually needs the `/v1` suffix.** Confirm with your provider —
+  some expose the OpenAI-compatible routes at the root, most at `/v1`.
+
+Do **not** create a `GITHUB_TOKEN` secret — GitHub Actions injects it
+automatically for every run. The bots authenticate to GitHub with it.
+
+---
+
+## 3. Allow Actions to open pull requests
+
+By default a workflow's `GITHUB_TOKEN` can push a branch but **cannot open a
+PR**. The issue → PR bot needs both.
+
+**Settings → Actions → General → Workflow permissions:**
+
+- Select **Read and write permissions**.
+- Check **Allow GitHub Actions to create and approve pull requests**.
+
+Without the checkbox, the issue bot pushes a `mitts/issue-<n>` branch but the
+`gh pr create` step fails.
+
+---
+
+## 4. Protect `main` so the bot can't merge (structural containment)
+
+This is the core of the Mitts security model: the agent runs with `contents:
+write` + `pull-requests: write`, and the guarantee that **it can never land code
+on `main` by itself** comes from branch protection, not from trusting the agent.
+
+**Settings → Rules → Rulesets** (or classic **Branch protection rules**), on the
+default branch:
+
+- **Require a pull request before merging**, with at least **one approving
+  review**.
+- **Restrict who can push / bypass** to admins only.
+
+The bot uses the built-in `GITHUB_TOKEN`, which is not an admin, so it can open
+PRs but cannot merge them or push to `main` directly. A human approval stays in
+the loop. See `mitts-bots.md` → "Structural containment" for the full reasoning
+(why the behavioral hook is defense-in-depth, not the boundary).
+
+> Skipping this is only acceptable on a throwaway/private repo you fully control.
+> Do **not** point the bots at a repo that publishes releases without it — see
+> the next step.
+
+---
+
+## 5. Gate the release secret behind `main` (if you publish)
+
+This repo's `ruby-gem.yml` publishes to RubyGems using
+`secrets.RUBYGEMS_AUTH_TOKEN`, and its publish job runs on `push` to
+`refs/heads/main`. To make that secret unreachable to a prompt-injected agent,
+move it behind a branch-scoped **Environment** so it's only readable from the
+default branch.
+
+**Settings → Environments → New environment** (e.g. `release`):
+
+1. Add `RUBYGEMS_AUTH_TOKEN` as an **environment secret** (remove it as a plain
+   repo secret so it's *only* available via the environment).
+2. Under **Deployment branches and tags**, choose **Selected branches and tags**
+   and allow only the default branch (add a tag pattern too if you tag releases).
+3. Reference it from the publish job:
+
+   ```yaml
+   jobs:
+     publish:
+       environment: release
+       # …
+   ```
+
+The chain this creates: no admin merge → nothing lands on `main` → no
+`push`-to-`main` event → no `release` environment access → `RUBYGEMS_AUTH_TOKEN`
+is never exposed. A compromised bot token pushing some *other* branch can't match
+the deployment-branch policy, so the publish job is rejected before the secret is
+readable.
+
+> **If you don't publish anything**, you can skip this step — but still do step 4.
+> **Caveat:** this guarantee holds for `push`/`pull_request` triggers. If you add
+> secret-bearing jobs on `workflow_dispatch`, `release`, or `schedule` (which can
+> fire without a merge), gate those with required reviewers on the environment
+> too.
+
+---
+
+## 6. Decide who can trigger the bots
+
+The write-capable paths — `mitts-issue`, `mitts-pr-followup`, and the on-demand
+`@mitts review` comment — only run when the commenter's `author_association` is
+`OWNER`, `MEMBER`, or `COLLABORATOR`. Everyone else (`CONTRIBUTOR`, `NONE`,
+`FIRST_TIMER`) is ignored.
+
+- **Nothing to configure to be safe** — the gate is already in the workflows.
+- **To let a specific person trigger the bots**, add them as a **repo
+  collaborator** (or org member) rather than loosening the gate. On a public
+  repo, loosening it would let any stranger drive a write-capable agent with
+  `@mitts implement <prompt injection>` and burn your LLM budget.
+
+The **automatic** PR review on `opened`/`reopened` is intentionally *ungated* —
+it's read-only (`contents: read`, only posts a review), which is the point of
+reviewing incoming contributions.
+
+---
+
+## 7. Land the workflows on the default branch
+
+GitHub only fires `issue_comment` triggers from workflow files that exist **on
+the default branch**. The bots go live only once these are merged to `main` —
+this is a GitHub rule, not a config choice.
+
+```bash
+git checkout -b add-mitts-bots
+git add AGENTS.md .agents/ \
+        .github/mitts .github/actions/run-mitts \
+        .github/workflows/mitts-*.yml docs/mitts/
+git commit -m "Add Mitts GitHub Actions bots (review, issue, PR follow-up)"
+git push -u origin add-mitts-bots
+gh pr create --fill
+```
+
+Merge that PR. Until it's on the default branch, commenting `@mitts …` does
+nothing (the auto PR-review on `pull_request` will run from a branch, but the
+comment-driven bots will not).
+
+---
+
+## 8. First run
+
+Trigger one and watch it:
+
+```bash
+# e.g. comment "@mitts review" on any open PR, then:
+gh run watch
+```
+
+Or open an issue and comment `@mitts what would it take to add X?` (a
+question — no code change) as a low-risk first test.
+
+**If the run fails**, the most likely cause is the model string or base URL:
+
+- Adjust `OPENHANDS_LLM_MODEL` (try with/without the `openai/` prefix).
+- Toggle the `/v1` suffix on `OPENHANDS_LLM_BASE_URL`.
+- Re-trigger with a new comment.
+
+Every run appends a cost/token summary (model, cost, prompt/completion tokens,
+skills loaded) to the **Actions step summary** — open the run in the Actions UI
+and click the summary tab. A run that ends `ERROR`/`STUCK` exits non-zero and the
+workflow posts a failure comment on the issue/PR.
+
+### What to expect on the first bot-opened PR
+
+The built-in `GITHUB_TOKEN` does **not** retrigger other workflows, so a PR the
+bot opens won't automatically run `test.yml` — its checks tab may look empty.
+That's expected, not a hang. If you want the bot's PRs to trigger CI, use a PAT
+or GitHub App token instead of the default token.
+
+---
+
+## 9. Optional environment knobs
+
+All optional. Set as **Actions variables** (`gh variable set NAME --body VALUE`)
+unless noted. Defaults are fine for most setups.
+
+| Variable | Default | What it does |
+|---|---|---|
+| `LLM_MAX_ITER` | `60` | Max agent iterations per run. Lower to cap cost/runtime; raise for harder tasks. |
+| `OPENHANDS_LOAD_PUBLIC_SKILLS` | off | `1`/`true` also loads skills from the `OpenHands/extensions` public registry (adds ~1–2 s for a git clone on first run). |
+| `EXTENSIONS_REF` | `main` | Branch/tag/SHA for the public extensions repo. Pin to a tag for reproducibility once you're happy. |
+| `OPENHANDS_KEEP_RUNS` | `5` | Prior-run subdirs retained per thread before each run. Older ones are pruned so the state artifact stays bounded. |
+
+Set automatically by the composite action — **you do not set these**, listed for
+reference:
+
+- `OPENHANDS_PERSIST_DIR` — root dir for cross-run event persistence (from
+  `runner.temp`).
+- `OPENHANDS_CONVERSATION_KEY` — per-thread key for the artifact (e.g. `pr-42`,
+  `issue-7`).
+
+The `mitts-pr-review.yml` review action also accepts an `extensions-version:`
+input (currently `main`) — pin it to a tag/SHA alongside `EXTENSIONS_REF` when
+you want reproducible reviews.
+
+---
+
+## Verifying the setup (quick checklist)
+
+- [ ] `gh variable list` shows `OPENHANDS_LLM_MODEL` and `OPENHANDS_LLM_BASE_URL`.
+- [ ] `gh secret list` shows `OPENHANDS_LLM_API_KEY`.
+- [ ] Settings → Actions → workflow permissions = **Read and write** + **create PRs** checked.
+- [ ] Default branch requires a PR + 1 approval; bypass restricted to admins.
+- [ ] (If publishing) `RUBYGEMS_AUTH_TOKEN` lives in a branch-scoped Environment, referenced via `environment:`.
+- [ ] `mitts-*.yml` are on the default branch.
+- [ ] A first `@mitts …` comment produced a run in the Actions tab.
+
+---
+
+## Usage reference
+
+Once set up, drive the bots from issue/PR comments:
+
+| You want to… | Where | Comment |
+|---|---|---|
+| Review a PR | PR | automatic on open/reopen, or `@mitts review` |
+| Turn an issue into a PR | issue | `@mitts implement <optional detail>` |
+| Ask about an issue | issue | `@mitts what would this involve?` (answers, no PR) |
+| Change code on a PR | PR | `@mitts add error handling for nil config` |
+| Ask about a PR | PR | `@mitts why did you use a mutex here?` (uses cross-run memory) |
+| Propose a plan (no code) | issue or PR | `@mitts plan <optional detail>` |
+
+Adding repo knowledge later: drop a new `.agents/skills/<name>/SKILL.md` (see the
+`run-tests` skill for the format) — it's picked up automatically on the next run,
+no config change needed.

data/docs/mitts/task.md

@@ -0,0 +1,44 @@
+
+## TODO:
+- [x] Add an AGENTS.md — done (repo root; loaded by all bots via `load_available_skills`)
+- [x] Idea: persistence but hybrid with a custom tool where it can fetch its own history if it needs to.
+  — done. Deterministic context injection (context_builder.py) + on-demand cross-run
+  memory via the recall_prior_reasoning custom tool (recall_tool.py) reading prior-run
+  event dirs bridged across runs as GitHub artifacts. No auto-replay (fresh
+  conversation_id each run). See docs/mitts/mitts-bots.md → "Hybrid context system".
+
+## Done (harness feature additions)
+- [x] Load AGENTS.md + project skills in agent_task.py via `load_available_skills`
+      (issue/PR bots now load AGENTS.md + .agents/skills/ on every run)
+- [x] AgentSkills: added `.agents/skills/run-tests/SKILL.md` as a progressive-disclosure example
+- [x] Sub-agent delegation: `enable_sub_agents=True` + `register_builtins_agents()` wired
+- [x] Guardrail hook: `.github/mitts/hooks/block_dangerous.sh` (force-push, CI, secrets)
+- [x] Cost/status reporting: metrics to $GITHUB_STEP_SUMMARY; ERROR/STUCK → exit 1
+- [x] Plan intent: `@mitts plan` branch in context_builder.py templates
+
+## Tools
+
+- Are there existing tools that we can use? 
+https://github.com/OpenHands/software-agent-sdk/tree/main/openhands-tools/openhands/tools
+
+- Do we need any custom tools? 
+https://docs.openhands.dev/sdk/guides/custom-tools
+  - [x] Yes — built `recall_prior_reasoning` (.github/mitts/recall_tool.py). Chosen over a skill.
+
+## Skills
+
+https://docs.openhands.dev/sdk/guides/skill
+  - [x] AGENTS.md loaded via load_available_skills → load_project_skills (all bots)
+  - [x] .agents/skills/ directory wired; run-tests SKILL.md added as example
+  - Optional public skills via OPENHANDS_LOAD_PUBLIC_SKILLS=1
+
+## Going further 
+
+https://docs.openhands.dev/sdk/guides/iterative-refinement
+
+### Subagents
+
+- [x] Built-in subagents registered via register_builtins_agents()
+- [x] TaskToolSet enabled (enable_sub_agents=True)
+- Source: https://github.com/OpenHands/software-agent-sdk/tree/main/openhands-tools/openhands/tools/preset/subagents
+

data/lib/claude_hooks/base.rb

@@ -9,7 +9,7 @@ module ClaudeHooks
   # Base class for Claude Code hook scripts
   class Base
     # Common input fields for all hook types
-    COMMON_INPUT_FIELDS = %w[session_id transcript_path cwd hook_event_name].freeze
+    COMMON_INPUT_FIELDS = %w[session_id transcript_path cwd hook_event_name permission_mode].freeze
 
     # Override in subclasses to specify hook type
     def self.hook_type
@@ -71,6 +71,27 @@ module ClaudeHooks
       @input_data['hook_event_name'] || @input_data['hookEventName'] || hook_type
     end
 
+    # Values: default|plan|acceptEdits|auto|dontAsk|bypassPermissions
+    def permission_mode
+      @input_data['permission_mode'] || @input_data['permissionMode'] || 'default'
+    end
+
+    def prompt_id
+      @input_data['prompt_id'] || @input_data['promptId']
+    end
+
+    def agent_id
+      @input_data['agent_id'] || @input_data['agentId']
+    end
+
+    def agent_type
+      @input_data['agent_type'] || @input_data['agentType']
+    end
+
+    def effort
+      @input_data.dig('effort', 'level')
+    end
+
     def read_transcript
       unless transcript_path && File.exist?(transcript_path)
         log "Transcript file not found at #{transcript_path}", level: :warn
@@ -111,6 +132,14 @@ module ClaudeHooks
       @output_data['hookSpecificOutput'] = nil
     end
 
+    def terminal_sequence!(seq)
+      @output_data['terminalSequence'] = seq
+    end
+
+    def terminal_sequence
+      @output_data['terminalSequence']
+    end
+
     # System message shown to the user (not to Claude)
     def system_message!(message)
       @output_data['systemMessage'] = message

data/lib/claude_hooks/config_change.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module ClaudeHooks
+  class ConfigChange < Base
+    def self.hook_type
+      'ConfigChange'
+    end
+
+    def self.input_fields
+      %w[source]
+    end
+
+    def source
+      @input_data['source']
+    end
+
+    def file_path
+      @input_data['file_path'] || @input_data['filePath']
+    end
+
+    def block!(reason = '')
+      @output_data['decision'] = 'block'
+      @output_data['reason'] = reason
+    end
+  end
+end

data/lib/claude_hooks/cwd_changed.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module ClaudeHooks
+  class CwdChanged < Base
+    def self.hook_type
+      'CwdChanged'
+    end
+
+    def self.input_fields
+      %w[old_cwd new_cwd]
+    end
+
+    def old_cwd
+      @input_data['old_cwd'] || @input_data['oldCwd']
+    end
+
+    def new_cwd
+      @input_data['new_cwd'] || @input_data['newCwd']
+    end
+
+    def watch_paths!(paths)
+      @output_data['hookSpecificOutput'] ||= { 'hookEventName' => hook_event_name }
+      @output_data['hookSpecificOutput']['watchPaths'] = Array(paths)
+    end
+  end
+end

data/lib/claude_hooks/elicitation.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module ClaudeHooks
+  class Elicitation < Base
+    def self.hook_type
+      'Elicitation'
+    end
+
+    def self.input_fields
+      %w[mcp_server_name message]
+    end
+
+    def mcp_server_name
+      @input_data['mcp_server_name'] || @input_data['mcpServerName']
+    end
+
+    def message
+      @input_data['message']
+    end
+
+    def mode
+      @input_data['mode']
+    end
+
+    def url
+      @input_data['url']
+    end
+
+    def elicitation_id
+      @input_data['elicitation_id'] || @input_data['elicitationId']
+    end
+
+    def requested_schema
+      @input_data['requested_schema'] || @input_data['requestedSchema']
+    end
+
+    def accept!(content = {})
+      @output_data['hookSpecificOutput'] = {
+        'hookEventName' => hook_event_name,
+        'action' => 'accept',
+        'content' => content
+      }
+    end
+
+    def decline!
+      @output_data['hookSpecificOutput'] = {
+        'hookEventName' => hook_event_name,
+        'action' => 'decline'
+      }
+    end
+
+    def cancel!
+      @output_data['hookSpecificOutput'] = {
+        'hookEventName' => hook_event_name,
+        'action' => 'cancel'
+      }
+    end
+  end
+end

data/lib/claude_hooks/elicitation_result.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module ClaudeHooks
+  class ElicitationResult < Base
+    def self.hook_type
+      'ElicitationResult'
+    end
+
+    def self.input_fields
+      %w[mcp_server_name action]
+    end
+
+    def mcp_server_name
+      @input_data['mcp_server_name'] || @input_data['mcpServerName']
+    end
+
+    def action
+      @input_data['action']
+    end
+
+    def mode
+      @input_data['mode']
+    end
+
+    def elicitation_id
+      @input_data['elicitation_id'] || @input_data['elicitationId']
+    end
+
+    def content
+      @input_data['content']
+    end
+
+    def accept!(content = {})
+      @output_data['hookSpecificOutput'] = {
+        'hookEventName' => hook_event_name,
+        'action' => 'accept',
+        'content' => content
+      }
+    end
+
+    def decline!
+      @output_data['hookSpecificOutput'] = {
+        'hookEventName' => hook_event_name,
+        'action' => 'decline'
+      }
+    end
+
+    def cancel!
+      @output_data['hookSpecificOutput'] = {
+        'hookEventName' => hook_event_name,
+        'action' => 'cancel'
+      }
+    end
+  end
+end

data/lib/claude_hooks/file_changed.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module ClaudeHooks
+  class FileChanged < Base
+    def self.hook_type
+      'FileChanged'
+    end
+
+    def self.input_fields
+      %w[file_path event]
+    end
+
+    def file_path
+      @input_data['file_path'] || @input_data['filePath']
+    end
+
+    # Values: change | add | unlink
+    def event
+      @input_data['event']
+    end
+
+    def created?
+      event == 'add'
+    end
+
+    def modified?
+      event == 'change'
+    end
+
+    def deleted?
+      event == 'unlink'
+    end
+
+    def watch_paths!(paths)
+      @output_data['hookSpecificOutput'] ||= { 'hookEventName' => hook_event_name }
+      @output_data['hookSpecificOutput']['watchPaths'] = Array(paths)
+    end
+  end
+end

data/lib/claude_hooks/instructions_loaded.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module ClaudeHooks
+  class InstructionsLoaded < Base
+    def self.hook_type
+      'InstructionsLoaded'
+    end
+
+    def self.input_fields
+      %w[file_path load_reason]
+    end
+
+    def file_path
+      @input_data['file_path'] || @input_data['filePath']
+    end
+
+    def load_reason
+      @input_data['load_reason'] || @input_data['loadReason']
+    end
+  end
+end