# AskUserQuestion for Matt Pocock's Grilling Skills Makes [Matt Pocock's grilling skills](https://github.com/mattpocock/skills) ask their questions with Claude Code's `AskUserQuestion` tool instead of plain text rounds. It is an add-on: the upstream skill files are never touched. ## Step by Step ### 1. Install Matt Pocock's skills (once) Skip this if you already have them. ```bash npx --yes skills@latest add mattpocock/skills --global --agent claude-code --skill '*' --yes ``` ### 2. Install this add-on ```bash bash -o pipefail -c 'curl -fsSL https://opengist.resetrix.work/weehong/9e381dc89dff4670b7232b910454f056/raw/HEAD/install-question-tools.sh | bash' ``` It prints each file it wrote (`Updated:`) and any backup it made (`Backup:`). If it prints `Installation failed`, nothing was changed; fix the reason it gives and run it again. ### 3. Start a fresh Claude Code session Hooks and `CLAUDE.md` are read when a session starts, so close any open session and start a new one. Type `/hooks` and check you see: - `PostToolUse` with matcher `Skill` - `UserPromptSubmit` Both run `grilling-question-hook.py`. ### 4. Start a grilling session Use any of these, the same way you would without the add-on: | You type | What it does | | --- | --- | | `/grill-me <your plan>` | Interview to sharpen a plan or design. | | `/grill-with-docs <your plan>` | Same, and writes ADRs and a glossary as you go. | | `/grilling <your plan>` | The core interview directly. | | `/loop-me` | Grill workflow specs for recurring tasks. | | "grill me on this" | Claude picks up the grilling skill by itself. | Skills that grill as part of their work (`wayfinder`, `triage`, `improve-codebase-architecture`) get the same behavior automatically. ### 5. Answer the question cards Instead of a wall of numbered text, each round arrives as `AskUserQuestion` cards: - Up to 4 questions per card. A bigger round comes as several cards in a row. - The first option is Claude's pick, marked **(Recommended)**, with the reason in its description. - Pick an option, or choose **Other** to type your own answer. - If you skip or dismiss a question, it stays open. Claude will not treat it as a yes. After each round Claude works out the next questions from your answers. The session ends when nothing is left open, and Claude asks you to confirm the shared understanding before acting on it. ### 6. If you still get plain text questions That is the expected fallback when `AskUserQuestion` cannot be used, for example in non-interactive `claude -p` runs, or for a question that is truly open ended. If it happens in a normal session: 1. Run `/hooks`. If the two hooks are missing, rerun step 2 and start a new session. 2. Check `python3 --version` works in the shell Claude Code uses. 3. Ask Claude "Did the grilling question policy load?" to see what it received. ### Update or remove - Update: run the step 2 command again. Nothing changes if you are already current. - Remove: see [Uninstall](#uninstall). ## Inspect Before Installing **Trust check:** this runs remote code and downloads a policy and a hook script from this gist. Read them first if you do not already trust the publisher and server. `pipefail` reports download failures; it is not a security sandbox. Files: [installer](https://opengist.resetrix.work/weehong/9e381dc89dff4670b7232b910454f056/raw/HEAD/install-question-tools.sh) | [policy](https://opengist.resetrix.work/weehong/9e381dc89dff4670b7232b910454f056/raw/HEAD/grilling-question-tools.md) | [hook](https://opengist.resetrix.work/weehong/9e381dc89dff4670b7232b910454f056/raw/HEAD/grilling-question-hook.py) To read everything first and then install from the same gist: ```bash base=https://opengist.resetrix.work/weehong/9e381dc89dff4670b7232b910454f056 for f in install-question-tools.sh grilling-question-tools.md grilling-question-hook.py; do curl -fsSL "$base/raw/HEAD/$f" -o "$f" done less install-question-tools.sh grilling-question-tools.md grilling-question-hook.py bash install-question-tools.sh ``` The installer downloads the policy and hook at `HEAD`, not your inspected copies. To pin them, take a full commit hash from the gist's [Revisions](https://opengist.resetrix.work/weehong/9e381dc89dff4670b7232b910454f056/revisions) and run `QUESTION_TOOLS_REVISION=<40-character-hash> bash install-question-tools.sh`. ## How It Works Four pieces, all under your Claude config directory (`~/.claude`, or `$CLAUDE_CONFIG_DIR` when set): | File | Purpose | | --- | --- | | `grilling-question-tools/grilling-question-tools.md` | The policy: how to turn a grilling round into `AskUserQuestion` calls. | | `grilling-question-tools/grilling-question-hook.py` | Hands the policy to Claude the moment a grilling flow starts. | | `settings.json` | Registers the hook for two events (below). | | `CLAUDE.md` | A short marked pointer to the policy, as a fallback. | The hook fires on: | Event | When | | --- | --- | | `PostToolUse`, matcher `Skill` | Claude loads `grilling`, `grill-me`, `grill-with-docs`, or `loop-me`. This covers `/grill-me`, `/grill-with-docs`, plugin names such as `mattpocock-skills:grilling`, and skills that call grilling (`wayfinder`, `triage`, `improve-codebase-architecture`). | | `UserPromptSubmit` | You type `/grilling` or `/loop-me` yourself, which skips the Skill tool. | Why a hook: the upstream `grilling` skill ships its own text format for each round, and it arrives later in the conversation than `CLAUDE.md`, so a `CLAUDE.md` note alone often loses. The hook adds the policy right after the skill loads. It only adds context: it never blocks or edits anything, and any error exits 0 silently so it cannot break a session. It reads the policy file each time, so policy updates need no settings change. The policy keeps the grilling flow intact: same rounds (split into calls of up to 4 questions), a recommended option first marked `(Recommended)`, the built-in Other answer for custom replies, skipped answers treated as unresolved, and the upstream text format as the fallback when `AskUserQuestion` is unavailable. It is guidance, not enforcement; Claude Code permissions and higher priority instructions still apply. ## Requirements - Linux, macOS, or WSL; Bash 3.2+, Python 3.8+, `curl`. `python3` must also be on the `PATH` Claude Code uses to run hooks. - Run as your normal user, without `sudo`. - Matt Pocock's skills installed separately (step 1). Use either the `npx` install or the Claude plugin, not both, or you may see duplicate skills. ## Updates and Safety Rerun the quick command to update. Identical reruns change nothing and make no backups. - Download errors or an invalid policy or hook abort before any file is changed. The checks (versioned markers, title, seven rules, hook header, and that the hook compiles) are sanity checks, not a signature. - Everything is checked before anything is written. Malformed or duplicate `CLAUDE.md` markers, a `settings.json` that is not a JSON object, or an unexpected `hooks` layout abort the run. - `CLAUDE.md` bytes outside the managed block are kept exactly. The markers are `<!-- BEGIN MATT-POCOCK-GRILLING-QUESTION-TOOLS -->` and `<!-- END MATT-POCOCK-GRILLING-QUESTION-TOOLS -->`; keep them intact. - In `settings.json`, only hook entries whose command runs `grilling-question-hook.py` are managed. Other settings and hooks are kept in order, but the file is rewritten as 2 space indented JSON when it changes. - Every changed file gets a sibling backup named `<filename>.question-tools-backup-<suffix>` (mode `0600`). Old backups are never replaced. - Symlinked files and directories (for example a dotfiles repo) are followed and kept as symlinks. Dangling symlinks and non-regular files are rejected. - Each file is replaced atomically, but not all files as one transaction. If a write fails midway, restore from the printed backups and rerun. Upgrading from the earlier multi-agent version moves the hook entry and the `CLAUDE.md` pointer to the new paths automatically. It leaves the old files in `~/.config/ai-agents/` and the pointer blocks in `~/.codex/AGENTS.md` and `~/.config/opencode/AGENTS.md`; remove those by hand if you no longer want them. ## Uninstall 1. `QUESTION_TOOLS_CLAUDE_HOOK=0 bash install-question-tools.sh` removes the managed hook entries from `settings.json`. 2. Delete the marked block from `CLAUDE.md`. 3. Delete the `grilling-question-tools` folder in your Claude config directory. ## Tests ```bash python3 -B -m unittest -v test_install_question_tools ``` They use temporary homes and a mocked `curl`: no network, no real install. The permission test is skipped when running as root.

#!/usr/bin/env python3 # MATT-POCOCK-GRILLING-QUESTION-HOOK v2 """Claude Code hook: attach the AskUserQuestion policy when grilling starts. Registered for two events by install-question-tools.sh: PostToolUse (matcher "Skill") fires when Claude loads a grilling skill, including grilling called by grill-me, grill-with-docs, wayfinder, triage, etc. UserPromptSubmit fires when the user types /grilling or /loop-me (typed slash commands do not go through the Skill tool). It never blocks or edits anything. It only adds context. Any error exits 0 silently so a broken hook can never interrupt a session. Usage: python3 grilling-question-hook.py /absolute/path/grilling-question-tools.md """ import json import re import sys SKILLS = ('grilling', 'grill-me', 'grill-with-docs', 'loop-me') # /grill-me and /grill-with-docs always call the Skill tool for "grilling", so # PostToolUse already covers them; matching them here would inject twice. TYPED = ('grilling', 'loop-me') SLASH = re.compile(r'^/(?:[\w.-]+:)?(%s)(?=\s|$)' % '|'.join(map(re.escape, TYPED))) MAX_POLICY = 32768 def skill_name(value): # Plugin installs namespace skills, e.g. "mattpocock-skills:grilling". return value.strip().rsplit(':', 1)[-1] if isinstance(value, str) else '' def triggered(event): name = event.get('hook_event_name') if name == 'PostToolUse' and event.get('tool_name') == 'Skill': tool_input = event.get('tool_input') if isinstance(tool_input, dict) and skill_name(tool_input.get('skill')) in SKILLS: return name if name == 'UserPromptSubmit': prompt = event.get('prompt') if isinstance(prompt, str) and SLASH.match(prompt.lstrip()): return name return None def main(): if len(sys.argv) != 2: return event = json.load(sys.stdin) if not isinstance(event, dict): return name = triggered(event) if not name: return with open(sys.argv[1], 'rb') as stream: policy = stream.read(MAX_POLICY + 1).decode('utf-8') if len(policy) > MAX_POLICY or 'MATT-POCOCK-GRILLING-QUESTION-POLICY' not in policy: print('Grilling question policy missing or invalid: %s' % sys.argv[1], file=sys.stderr) return context = ('A Matt Pocock grilling flow is active. Deliver its questions with ' 'AskUserQuestion as this policy describes; everything else in the ' 'flow is unchanged.\n\n' + policy.strip() + '\n') json.dump({'hookSpecificOutput': {'hookEventName': name, 'additionalContext': context}}, sys.stdout) if __name__ == '__main__': try: main() except Exception as error: # Never break the session. print('Grilling question hook skipped: %s' % error, file=sys.stderr) sys.exit(0)

<!-- BEGIN MATT-POCOCK-GRILLING-QUESTION-POLICY v2 --> # AskUserQuestion for Matt Pocock Grilling Flows Scope: apply only while running Matt Pocock's grilling flows (grilling, grill-me, grill-with-docs, loop-me, or a skill that calls grilling, such as wayfinder, triage, or improve-codebase-architecture). This changes how Claude Code delivers questions, not the flow's research, decision criteria, documentation, or completion requirements. Other conversations and skills keep their own behavior. 1. Research first. Look up what the codebase or tools can answer before asking the user. The main conversation owns the interview; subagents return findings and proposed questions to it and never prompt the user themselves. 2. Ask with AskUserQuestion when it is available and permitted in this session. Follow its actual schema and permission rules. Do not change modes or bypass a restriction to unlock it. 3. Keep the flow's rounds. A round is every question whose prerequisites are already settled. Each call takes 1 to 4 questions, so a larger round becomes several calls in a row; every question in the round stays independent of the others. Wait for answers before asking dependent follow ups. Never drop a question to fit the limits. 4. Make each question decidable: a header of at most 12 characters and 2 to 4 concrete options with their tradeoffs in the descriptions. Put your recommended option first, end its label with " (Recommended)", and give the reason in its description. Never invent a recommendation to fill the UI. When the fields would lose needed context, give it in a message just before the call. 5. Keep custom answers possible. AskUserQuestion adds an "Other" free text choice automatically, so do not add your own. Do not force an open ended question into false choices; ask it in plain text instead. Never read Other as agreement with a listed option. 6. Treat skipped, dismissed, empty, or ambiguous answers as unresolved, not as consent or acceptance of the recommendation. Clarify a blocking gap or defer it with the user's agreement. Keep unresolved decisions out of the confirmed decisions in any spec, ADR, or summary. 7. Fall back to the upstream text format. If AskUserQuestion is unavailable, disallowed, fails, or cannot express a question faithfully, use the grilling skill's own "Format a round like so" layout (numbered questions, each with a recommended answer), invite custom answers, and wait. Return to AskUserQuestion when it is usable. This is an instruction preference, not runtime enforcement. Higher priority instructions and Claude Code restrictions still apply. Finish only when the original flow's completion criteria are met; changing the UI does not satisfy them. <!-- END MATT-POCOCK-GRILLING-QUESTION-POLICY v2 -->

#!/usr/bin/env bash # Requires Bash 3.2+, Python 3.8+, and curl. No sudo; run one installer at a time. set -euo pipefail # Defining the complete function before calling it also avoids starting an # installation from a download truncated inside the embedded Python program. main() { command -v python3 >/dev/null || { printf '%s\n' 'Python 3.8+ is required.' >&2; return 1; } command -v curl >/dev/null || { printf '%s\n' 'curl is required.' >&2; return 1; } python3 - <<'PY' import json import os import re import shlex import stat import subprocess import sys import tempfile from pathlib import Path BEGIN = b'<!-- BEGIN MATT-POCOCK-GRILLING-QUESTION-TOOLS -->' END = b'<!-- END MATT-POCOCK-GRILLING-QUESTION-TOOLS -->' TOKEN = b'MATT-POCOCK-GRILLING-QUESTION-TOOLS' POLICY_BEGIN = '<!-- BEGIN MATT-POCOCK-GRILLING-QUESTION-POLICY v2 -->' POLICY_END = '<!-- END MATT-POCOCK-GRILLING-QUESTION-POLICY v2 -->' BASE = 'https://opengist.resetrix.work/weehong/9e381dc89dff4670b7232b910454f056' HOOK_NAME = 'grilling-question-hook.py' HOOK_HEADER = '#!/usr/bin/env python3\n# MATT-POCOCK-GRILLING-QUESTION-HOOK v2\n' HOOK_EVENTS = (('PostToolUse', 'Skill'), ('UserPromptSubmit', None)) def download(url): result = subprocess.run(['curl', '-fsSL', '--proto', '=https', '--proto-redir', '=https', '--connect-timeout', '15', '--max-time', '60', url], stdout=subprocess.PIPE, check=True) return result.stdout def is_managed_hook(hook): return (isinstance(hook, dict) and isinstance(hook.get('command'), str) and HOOK_NAME in hook['command']) def merge_settings(path, old, command): # Returns new settings bytes. Only hook entries running HOOK_NAME are managed; # every other key, event, and hook is kept in its original order. try: settings = json.loads(old.decode('utf-8')) if old.strip() else {} except (UnicodeDecodeError, ValueError) as error: raise ValueError('Claude settings are not valid JSON: %s (%s)' % (path, error)) if not isinstance(settings, dict): raise ValueError('Claude settings must be a JSON object: %s' % path) original = json.loads(json.dumps(settings)) hooks = settings.get('hooks', {}) if not isinstance(hooks, dict): raise ValueError('Claude settings "hooks" must be an object: %s' % path) for event in list(hooks): groups = hooks[event] if not isinstance(groups, list) or not all( isinstance(g, dict) and isinstance(g.get('hooks', []), list) for g in groups): raise ValueError('Unexpected Claude hooks layout for %s in %s. Fix it manually.' % (event, path)) kept, removed = [], False for group in groups: entries = group.get('hooks', []) others = [h for h in entries if not is_managed_hook(h)] if len(others) != len(entries): removed = True if not others: continue group = dict(group, hooks=others) kept.append(group) if removed and not kept: del hooks[event] else: hooks[event] = kept if command: for event, matcher in HOOK_EVENTS: group = {'matcher': matcher} if matcher else {} group['hooks'] = [{'type': 'command', 'command': command, 'timeout': 10}] hooks.setdefault(event, []).append(group) if hooks or 'hooks' in settings: settings['hooks'] = hooks if settings == original: return old return (json.dumps(settings, indent=2, ensure_ascii=False) + '\n').encode('utf-8') def resolve_target(path): # Resolve existing components strictly, but allow new files/directories. target = Path(path.anchor) for part in path.parts[1:]: target = target / part if target.is_symlink(): try: target = target.resolve(strict=True) except (OSError, RuntimeError) as error: raise ValueError('Dangling or unresolvable symlink: %s' % target) from error return target def check_path(path): for part in [path] + list(path.parents): if part.is_symlink(): raise ValueError('Path changed to a symlink during installation: %s' % part) if part.exists() and not (part.is_file() if part == path else part.is_dir()): raise ValueError('Not a regular file/directory: %s' % part) parent = path.parent while not parent.exists(): parent = parent.parent if not os.access(parent, os.W_OK | os.X_OK): raise ValueError('Directory is not writable/searchable: %s' % parent) if path.exists() and not os.access(path, os.R_OK | os.W_OK): raise ValueError('Instruction file is not readable/writable: %s' % path) def install(): if sys.version_info < (3, 8): raise ValueError('Python 3.8+ is required.') revision = os.environ.get('QUESTION_TOOLS_REVISION') or 'HEAD' if revision != 'HEAD' and not re.fullmatch(r'[0-9a-fA-F]{40}', revision): raise ValueError('QUESTION_TOOLS_REVISION must be HEAD or a full 40-character commit hash.') hook_setting = os.environ.get('QUESTION_TOOLS_CLAUDE_HOOK') or '1' if hook_setting not in ('0', '1'): raise ValueError('QUESTION_TOOLS_CLAUDE_HOOK must be 1 (install) or 0 (skip and remove).') url = BASE + '/raw/' + revision + '/grilling-question-tools.md' policy_bytes = download(url) policy = policy_bytes.decode('utf-8') lines = policy.splitlines() if (not lines or lines[0] != POLICY_BEGIN or lines[-1] != POLICY_END or policy.count(POLICY_BEGIN) != 1 or policy.count(POLICY_END) != 1 or len(policy) > 32768 or '\x00' in policy or TOKEN.decode() in policy or not policy.startswith(POLICY_BEGIN + '\n# AskUserQuestion for Matt Pocock Grilling Flows\n') or not all('\n%d. ' % i in policy for i in range(1, 8))): raise ValueError('Downloaded policy is incomplete or invalid; no instruction files changed.') hook_bytes = None if hook_setting == '1': hook_url = BASE + '/raw/' + revision + '/' + HOOK_NAME hook_bytes = download(hook_url) hook_source = hook_bytes.decode('utf-8') if (not hook_source.startswith(HOOK_HEADER) or len(hook_source) > 32768 or '\x00' in hook_source or TOKEN.decode() in hook_source or not hook_source.rstrip().endswith('sys.exit(0)')): raise ValueError('Downloaded Claude hook is incomplete or invalid; no instruction files changed.') try: compile(hook_source, HOOK_NAME, 'exec') except SyntaxError as error: raise ValueError('Downloaded Claude hook does not compile: %s' % error) home = os.environ.get('HOME') if not home or not os.path.isabs(home): raise ValueError('HOME must be an absolute path.') claude_dir = os.environ.get('CLAUDE_CONFIG_DIR') or home + '/.claude' if (not os.path.isabs(claude_dir) or '..' in Path(claude_dir).parts or any(c in claude_dir for c in '\r\n`')): raise ValueError('CLAUDE_CONFIG_DIR must be an absolute path without .. components.') policy_dir = Path(claude_dir) / 'grilling-question-tools' policy_path = resolve_target(policy_dir / 'grilling-question-tools.md') if any(c in str(policy_path) for c in '\r\n`'): raise ValueError('Policy path cannot contain newlines or backticks.') block = (BEGIN + b'\n' + ( 'Before running a Matt Pocock grilling flow (grilling, grill-me, grill-with-docs,\n' 'loop-me, or a skill that calls grilling), read `%s`.\n' 'Ask its questions with AskUserQuestion as that policy describes;\n' 'preserve all other workflow requirements.\n' % policy_path ).encode('utf-8') + END) paths = [resolve_target(Path(claude_dir) / 'CLAUDE.md')] hook_path = resolve_target(policy_dir / HOOK_NAME) settings_path = resolve_target(Path(claude_dir) / 'settings.json') # A hook command is run by a shell, so quote both paths. command = ('python3 %s %s' % (shlex.quote(str(hook_path)), shlex.quote(str(policy_path))) if hook_bytes is not None else None) managed = [policy_path, hook_path, settings_path] everything = managed + paths existing = [p for p in everything if p.exists()] if len(set(everything)) != len(everything) or any( os.path.samefile(a, b) for i, a in enumerate(existing) for b in existing[i + 1:]): raise ValueError('Policy, hook, settings, and CLAUDE.md must be separate files.') changes = [] # Preflight every destination before creating directories, backups, or files. for path in managed + paths: check_path(path) exists = path.exists() old = path.read_bytes() if exists else b'' if path == policy_path: new = policy_bytes elif path == hook_path: new = hook_bytes if hook_bytes is not None else old elif path == settings_path: new = merge_settings(path, old, command) elif TOKEN in old: if old.count(TOKEN) != 2 or old.count(BEGIN) != 1 or old.count(END) != 1: raise ValueError('Malformed/duplicate managed markers: %s. Repair them manually before rerunning.' % path) start, end = old.index(BEGIN), old.index(END) after = end + len(END) if (end < start or (start and old[start-1:start] != b'\n') or old[end-1:end] != b'\n' or (old[after:] and not old[after:].startswith((b'\n', b'\r\n'))) or not old[start+len(BEGIN):].startswith((b'\n', b'\r\n'))): raise ValueError('Malformed managed marker boundaries: %s' % path) new = old[:start] + block + old[after:] else: separator = (b'\n' if old.endswith(b'\n') else b'\n\n') if old else b'' new = old + separator + block + b'\n' if new != old: changes.append((path, exists, old, new)) elif exists: print('Unchanged: %s' % path) staged = [] try: for path, exists, old, new in changes: check_path(path) if path.exists() != exists or (exists and path.read_bytes() != old): raise ValueError('File changed during installation: %s. Retry with other writers stopped.' % path) path.parent.mkdir(parents=True, exist_ok=True) mode = stat.S_IMODE(path.stat().st_mode) if exists else 0o600 fd, temporary = tempfile.mkstemp(prefix='.' + path.name + '.question-tools-', dir=str(path.parent)) staged.append((path, temporary)) with os.fdopen(fd, 'wb') as stream: stream.write(new) stream.flush() os.fsync(stream.fileno()) os.fchmod(stream.fileno(), mode) if exists: fd, backup = tempfile.mkstemp(prefix=path.name + '.question-tools-backup-', dir=str(path.parent)) with os.fdopen(fd, 'wb') as stream: stream.write(old) stream.flush() os.fsync(stream.fileno()) print('Backup: %s' % backup) for path, temporary in staged: os.replace(temporary, path) print('Updated: %s' % path) finally: for _, temporary in staged: if os.path.exists(temporary): os.unlink(temporary) print('Policy source: %s' % url) if command: print('Claude Code hook: %s (PostToolUse on Skill, UserPromptSubmit)' % settings_path) else: print('Claude Code hook: skipped (QUESTION_TOOLS_CLAUDE_HOOK=0); managed entries removed if present.') print('Start a fresh Claude Code session; /hooks lists the registered hooks.') try: install() except (OSError, ValueError, subprocess.SubprocessError) as error: print('Installation failed: %s' % error, file=sys.stderr) sys.exit(1) PY } main "$@"

"""Sandbox-only installer tests; curl never accesses the network.""" import json import os from pathlib import Path import shlex import subprocess import tempfile import unittest ROOT = Path(__file__).resolve().parent INSTALLER = ROOT / 'install-question-tools.sh' HOOK_SCRIPT = ROOT / 'grilling-question-hook.py' POLICY = (ROOT / 'grilling-question-tools.md').read_bytes() HOOK = HOOK_SCRIPT.read_bytes() BEGIN = b'<!-- BEGIN MATT-POCOCK-GRILLING-QUESTION-TOOLS -->' END = b'<!-- END MATT-POCOCK-GRILLING-QUESTION-TOOLS -->' BASE = 'https://opengist.resetrix.work/weehong/9e381dc89dff4670b7232b910454f056' class InstallerTests(unittest.TestCase): def setUp(self): self.temp = tempfile.TemporaryDirectory(prefix='question-tools-test-') self.addCleanup(self.temp.cleanup) self.root = Path(self.temp.name) self.home = self.root / 'home' self.home.mkdir() self.bin = self.root / 'bin' self.bin.mkdir() self.fixture = self.root / 'policy.md' self.fixture.write_bytes(POLICY) self.hook_fixture = self.root / 'hook.py' self.hook_fixture.write_bytes(HOOK) curl = self.bin / 'curl' curl.write_text( '#!/usr/bin/env python3\n' 'import os, pathlib, sys\n' 'url = sys.argv[-1]\n' 'with open(os.environ["CURL_LOG"], "a") as log: log.write(url + "\\n")\n' 'if os.environ.get("CURL_FAIL") and url.endswith(os.environ["CURL_FAIL"]): sys.exit(22)\n' 'name = "HOOK_FIXTURE" if url.endswith(".py") else "POLICY_FIXTURE"\n' 'sys.stdout.buffer.write(pathlib.Path(os.environ[name]).read_bytes())\n' ) curl.chmod(0o700) self.env = {key: value for key, value in os.environ.items() if key not in ( 'HOME', 'CLAUDE_CONFIG_DIR', 'QUESTION_TOOLS_REVISION', 'QUESTION_TOOLS_CLAUDE_HOOK')} self.env.update(HOME=str(self.home), PATH=str(self.bin) + ':' + os.environ['PATH'], POLICY_FIXTURE=str(self.fixture), HOOK_FIXTURE=str(self.hook_fixture), CURL_LOG=str(self.root / 'curl.log')) self.use_claude_dir(self.home / '.claude') def use_claude_dir(self, claude): self.claude_md = claude / 'CLAUDE.md' self.settings = claude / 'settings.json' self.policy = claude / 'grilling-question-tools/grilling-question-tools.md' self.hook = claude / 'grilling-question-tools/grilling-question-hook.py' def run_install(self, success=True): result = subprocess.run(['bash', str(INSTALLER)], env=self.env, cwd=self.root, capture_output=True, text=True) self.assertEqual(result.returncode == 0, success, result.stdout + result.stderr) return result def write_claude_md(self, data=b'Unrelated\x80 instructions\r\n'): self.claude_md.parent.mkdir(parents=True, exist_ok=True) self.claude_md.write_bytes(data) def snapshot(self): return {str(p.relative_to(self.home)): ( ('link', os.readlink(p)) if p.is_symlink() else ('file', p.read_bytes(), p.stat().st_mode, p.stat().st_mtime_ns) if p.is_file() else ('directory',)) for p in self.home.rglob('*')} def curl_urls(self): return (self.root / 'curl.log').read_text().splitlines() def managed_commands(self, settings=None): data = settings if settings is not None else json.loads(self.settings.read_text()) found = {} for event, groups in data.get('hooks', {}).items(): for group in groups: for hook in group.get('hooks', []): if 'grilling-question-hook.py' in hook.get('command', ''): found.setdefault(event, []).append((group.get('matcher'), hook['command'])) return found def run_hook(self, event): result = subprocess.run(['python3', str(HOOK_SCRIPT), str(self.fixture)], input=json.dumps(event), capture_output=True, text=True) self.assertEqual(result.returncode, 0, result.stderr) return json.loads(result.stdout) if result.stdout.strip() else None # Installer def test_install_and_unchanged_rerun(self): original = b'Unrelated\x80 instructions\r\n' self.write_claude_md(original) self.claude_md.chmod(0o640) self.run_install() self.assertEqual(self.policy.read_bytes(), POLICY) self.assertEqual(self.hook.read_bytes(), HOOK) content = self.claude_md.read_bytes() self.assertTrue(content.startswith(original)) self.assertEqual(content.count(BEGIN), 1) self.assertIn(str(self.policy).encode(), content) self.assertNotIn(POLICY, content) backups = list(self.claude_md.parent.glob('CLAUDE.md.question-tools-backup-*')) self.assertEqual(len(backups), 1) self.assertEqual(backups[0].read_bytes(), original) self.assertEqual(backups[0].stat().st_mode & 0o777, 0o600) self.assertEqual(self.claude_md.stat().st_mode & 0o777, 0o640) self.assertEqual(self.curl_urls(), [BASE + '/raw/HEAD/grilling-question-tools.md', BASE + '/raw/HEAD/grilling-question-hook.py']) # Only Claude Code files are touched. self.assertEqual(sorted(p.name for p in self.home.iterdir()), ['.claude']) before = self.snapshot() self.run_install() self.assertEqual(self.snapshot(), before) def test_hook_merged_into_existing_settings(self): existing = {'model': 'opus', 'hooks': {'PostToolUse': [ {'matcher': 'Bash', 'hooks': [{'type': 'command', 'command': 'echo mine'}]}]}} self.settings.parent.mkdir(parents=True) self.settings.write_text(json.dumps(existing)) self.run_install() data = json.loads(self.settings.read_text()) self.assertEqual(data['model'], 'opus') self.assertEqual(data['hooks']['PostToolUse'][0], existing['hooks']['PostToolUse'][0]) commands = self.managed_commands(data) self.assertEqual([m for m, _ in commands['PostToolUse']], ['Skill']) self.assertEqual([m for m, _ in commands['UserPromptSubmit']], [None]) self.assertEqual(shlex.split(commands['PostToolUse'][0][1]), ['python3', str(self.hook), str(self.policy)]) backups = list(self.settings.parent.glob('settings.json.question-tools-backup-*')) self.assertEqual(len(backups), 1) self.assertEqual(json.loads(backups[0].read_text()), existing) before = self.snapshot() self.run_install() self.assertEqual(self.snapshot(), before) def test_migrates_older_install(self): # An older version embedded the policy in CLAUDE.md and pointed the hook # at ~/.config/ai-agents. Both are replaced, not duplicated. prefix, suffix = b'Existing\xff\r\n\n', b'\r\nAfter\x80' self.write_claude_md(prefix + BEGIN + b'\nold embedded policy\n' + END + suffix) old_command = "python3 '/old/ai-agents/grilling-question-hook.py' '/old/ai-agents/grilling-question-tools.md'" self.settings.write_text(json.dumps({'hooks': {'PostToolUse': [ {'matcher': 'Skill', 'hooks': [{'type': 'command', 'command': old_command, 'timeout': 10}]}]}})) self.run_install() content = self.claude_md.read_bytes() self.assertTrue(content.startswith(prefix + BEGIN)) self.assertTrue(content.endswith(END + suffix)) self.assertEqual(content.count(BEGIN), 1) self.assertNotIn(b'old embedded policy', content) commands = self.managed_commands() self.assertEqual({event: len(entries) for event, entries in commands.items()}, {'PostToolUse': 1, 'UserPromptSubmit': 1}) self.assertNotIn('/old/', json.dumps(commands)) def test_symlinked_claude_md_and_directory(self): dotfiles = self.home / 'dotfiles' (dotfiles / 'claude').mkdir(parents=True) (dotfiles / 'claude/CLAUDE.md').write_bytes(b'Mine\n') (self.home / '.claude').symlink_to(dotfiles / 'claude', target_is_directory=True) self.run_install() self.assertTrue((self.home / '.claude').is_symlink()) self.assertEqual((dotfiles / 'claude/CLAUDE.md').read_bytes().count(BEGIN), 1) self.assertEqual((dotfiles / 'claude/grilling-question-tools/grilling-question-tools.md').read_bytes(), POLICY) def test_claude_config_dir_with_space_and_revision(self): self.env['CLAUDE_CONFIG_DIR'] = str(self.home / 'claude config') self.env['QUESTION_TOOLS_REVISION'] = 'a' * 40 self.use_claude_dir(self.home / 'claude config') self.run_install() self.assertEqual(self.policy.read_bytes(), POLICY) self.assertIn(str(self.policy).encode(), self.claude_md.read_bytes()) self.assertEqual(shlex.split(self.managed_commands()['PostToolUse'][0][1]), ['python3', str(self.hook), str(self.policy)]) self.assertEqual(self.curl_urls(), [BASE + '/raw/' + 'a' * 40 + '/grilling-question-tools.md', BASE + '/raw/' + 'a' * 40 + '/grilling-question-hook.py']) self.assertFalse((self.home / '.claude').exists()) self.env['QUESTION_TOOLS_REVISION'] = 'HEAD~1' self.run_install(False) def test_hook_opt_out_removes_only_managed_entries(self): self.run_install() self.assertTrue(self.managed_commands()) self.env['QUESTION_TOOLS_CLAUDE_HOOK'] = '0' self.run_install() self.assertEqual(self.managed_commands(), {}) self.assertEqual(json.loads(self.settings.read_text()), {'hooks': {}}) self.assertEqual(self.curl_urls()[2:], [BASE + '/raw/HEAD/grilling-question-tools.md']) self.assertEqual(self.claude_md.read_bytes().count(BEGIN), 1) self.env['QUESTION_TOOLS_CLAUDE_HOOK'] = 'yes' self.run_install(False) def test_malformed_blocks_preflight_no_writes(self): for malformed in (BEGIN, END + b'\n' + BEGIN, BEGIN + b'\nx\n' + END + END, b'prefix' + BEGIN + b'\nx\n' + END, BEGIN + b'x\n' + END): with self.subTest(malformed=malformed): self.write_claude_md(malformed) before = self.snapshot() self.run_install(False) self.assertEqual(self.snapshot(), before) def test_invalid_settings_abort_before_writes(self): for bad in (b'{not json', b'[]', b'{"hooks": []}', b'{"hooks": {"Stop": {}}}'): with self.subTest(bad=bad): self.write_claude_md() self.settings.write_bytes(bad) before = self.snapshot() self.run_install(False) self.assertEqual(self.snapshot(), before) def test_download_failure_and_invalid_files_no_writes(self): self.write_claude_md() before = self.snapshot() for failing in ('.md', '.py'): with self.subTest(failing=failing): self.env['CURL_FAIL'] = failing self.run_install(False) self.assertEqual(self.snapshot(), before) del self.env['CURL_FAIL'] self.hook_fixture.write_bytes(HOOK[:len(HOOK) // 2]) self.run_install(False) self.assertEqual(self.snapshot(), before) self.hook_fixture.write_bytes(HOOK) self.fixture.write_bytes(b'incomplete') self.run_install(False) self.assertEqual(self.snapshot(), before) def test_dangling_file_and_directory_symlinks(self): for path in (self.claude_md, self.claude_md.parent): with self.subTest(path=path): path.parent.mkdir(parents=True, exist_ok=True) path.symlink_to(self.home / 'missing') before = self.snapshot() self.run_install(False) self.assertEqual(self.snapshot(), before) path.unlink() if path == self.claude_md: path.parent.rmdir() def test_nonregular_destination(self): self.claude_md.parent.mkdir(parents=True) os.mkfifo(self.claude_md) self.run_install(False) self.assertFalse(self.policy.exists()) self.assertEqual(list(self.home.rglob('*.question-tools-backup-*')), []) @unittest.skipIf(os.geteuid() == 0, 'root bypasses filesystem permissions') def test_permission_failure_preflight(self): self.write_claude_md() self.claude_md.chmod(0o400) before = self.snapshot() self.run_install(False) self.assertEqual(self.snapshot(), before) def test_policy_cannot_alias_claude_md(self): self.write_claude_md() self.policy.parent.mkdir(parents=True) self.policy.symlink_to(self.claude_md) before = self.snapshot() self.run_install(False) self.assertEqual(self.snapshot(), before) # Hook def test_hook_triggers_only_for_grilling(self): post = {'hook_event_name': 'PostToolUse', 'tool_name': 'Skill'} for skill in ('grilling', 'grill-me', 'mattpocock-skills:grilling', 'grill-with-docs', 'loop-me'): with self.subTest(skill=skill): out = self.run_hook(dict(post, tool_input={'skill': skill})) self.assertEqual(out['hookSpecificOutput']['hookEventName'], 'PostToolUse') context = out['hookSpecificOutput']['additionalContext'] self.assertIn('AskUserQuestion', context) self.assertIn(POLICY.decode().strip(), context) prompt = {'hook_event_name': 'UserPromptSubmit'} for text in ('/loop-me', ' /grilling my plan', '/mattpocock-skills:grilling x'): with self.subTest(text=text): out = self.run_hook(dict(prompt, prompt=text)) self.assertEqual(out['hookSpecificOutput']['hookEventName'], 'UserPromptSubmit') for event in (dict(post, tool_input={'skill': 'tdd'}), dict(post, tool_name='Bash', tool_input={'command': 'grilling'}), dict(prompt, prompt='please grill me'), dict(prompt, prompt='/grilling-extra'), dict(prompt, prompt='/tdd /grilling'), # Covered by the Skill call these make; avoids double injection. dict(prompt, prompt='/grill-me'), dict(prompt, prompt='/grill-with-docs')): with self.subTest(event=event): self.assertIsNone(self.run_hook(event)) def test_hook_never_fails_the_session(self): for stdin, policy in (('not json', self.fixture), ('[]', self.fixture), (json.dumps({'hook_event_name': 'UserPromptSubmit', 'prompt': '/grilling'}), self.root / 'missing.md')): with self.subTest(stdin=stdin, policy=policy): result = subprocess.run(['python3', str(HOOK_SCRIPT), str(policy)], input=stdin, capture_output=True, text=True) self.assertEqual((result.returncode, result.stdout), (0, '')) if __name__ == '__main__': unittest.main()