impulso 0.19.1

package/commands/plannotator-last.md

@@ -0,0 +1,45 @@
+---
+description:
+  'Open Plannotator on the latest rendered assistant message and use the
+  returned annotations to revise that message or continue.'
+---
+
+# Plannotator Last
+
+Use when user wants latest assistant response annotated in Plannotator.
+
+No commentary before launch — preamble becomes the thing annotated.
+
+## Protocol
+
+1. Launch plannotator immediately (no preamble):
+
+   ```bash
+   impulso-hub plannotator launch last
+   ```
+
+   Returns JSON with `url`, `remoteUrl`, `port`, `pid`. Non-blocking.
+
+2. **IMMEDIATELY relay URL:** "Open Plannotator at `<URL>` (remote: `<Remote>`).
+   Annotate the last message, then tell me when done." WAIT for user.
+
+3. After user confirms:
+
+   ```bash
+   impulso-hub plannotator wait
+   ```
+
+   Returns `{"decision":"approved"|"dismissed"|"annotated","feedback":"..."}`.
+
+4. Apply the decision:
+   - `approved` → acknowledge, proceed.
+   - `dismissed` → session closed, say so, continue.
+   - `annotated` → address the feedback text.
+
+5. Launch timeout (exit 2): check stderr, ask whether to retry.
+
+Run commands yourself. Never ask user to paste shell commands into chat.
+
+---
+
+**User arguments:** $ARGUMENTS

package/commands/plannotator-review.md

@@ -0,0 +1,46 @@
+---
+description:
+  "Open Plannotator's browser-based code review UI for the current worktree or a
+  pull request URL, then act on the feedback that comes back."
+---
+
+# Plannotator Review
+
+Use when user wants code changes reviewed in Plannotator.
+
+## Protocol
+
+1. Determine the review target. User gave PR URL → set `TARGET` to the PR URL.
+   Worktree review → leave `TARGET` empty.
+
+2. Launch plannotator and get the URL:
+
+   ```bash
+   impulso-hub plannotator launch review [TARGET]
+   ```
+
+   Returns JSON with `url`, `remoteUrl`, `port`, `pid`. Non-blocking.
+
+3. **IMMEDIATELY relay URL:** "Open Plannotator at `<URL>` (remote: `<Remote>`).
+   Review the changes, then tell me when done." WAIT for user to confirm.
+
+4. After user confirms, wait for plannotator to finish:
+
+   ```bash
+   impulso-hub plannotator wait
+   ```
+
+   Returns `{"decision":"approved"|"dismissed"|"annotated","feedback":"..."}`.
+
+5. Apply the decision:
+   - `approved` → acknowledge, proceed.
+   - `dismissed` → session closed, say so, continue.
+   - `annotated` → address the feedback text.
+
+6. Launch timeout (exit 2): check stderr, ask whether to retry.
+
+Run commands yourself. Never ask user to paste shell commands into chat.
+
+---
+
+**User arguments:** $ARGUMENTS

package/harnesses/claude/README.md

@@ -0,0 +1,109 @@
+# Impulso — Claude Code Harness
+
+Glue for running Impulso on Claude Code.
+
+## Install
+
+```bash
+./harnesses/claude/install.sh
+```
+
+Idempotent. Hard-requires `rtk` and `tokensave` on PATH (aborts otherwise).
+Creates an isolated profile at `~/.config/impulso-profile/claude/`:
+
+- Symlinks `skills/` and `commands/` → repo dirs. If the target already has a
+  real dir (shared profiles), bundled entries are linked individually inside it
+  — foreign entries untouched
+- Copies the ruleset as `IMPULSO-AGENTS.md` (never clobbers a user `AGENTS.md`)
+  and ensures `CLAUDE.md` imports it — created if missing, appended otherwise
+  (Claude Code reads `CLAUDE.md`, not `AGENTS.md`)
+- `settings.json`: generated from the self-boot `claude/settings.json` (single
+  source, hooks pinned to this repo) and **merged** into any existing settings
+  via `merge-settings.cjs` — foreign hooks and keys survive, stale impulso
+  entries are replaced
+- Registers the `tokensave` MCP server (user scope)
+
+Uninstall reverses exactly that — targeted removals only, never touches foreign
+content, never `rm -rf`'s `~/.claude`:
+
+```bash
+./harnesses/claude/uninstall.sh
+```
+
+Health check for the whole harness (binaries, symlinks, configs, MCP):
+
+```bash
+./doctor.sh
+```
+
+Launch with the isolated profile:
+
+```bash
+CLAUDE_CONFIG_DIR=~/.config/impulso-profile/claude claude
+```
+
+To install into `~/.claude/` directly (shared with your normal Claude Code
+config):
+
+```bash
+IMPULSO_CLAUDE_PROFILE="$HOME/.claude" ./harnesses/claude/install.sh
+```
+
+## Plannotator
+
+Plannotator slash commands work directly after install (vendored in `skills/`).
+Requires the `plannotator` binary:
+
+```bash
+curl -fsSL https://plannotator.ai/install.sh | bash
+```
+
+## RTK (token savings)
+
+`install.sh` hard-requires the `rtk` binary:
+
+```bash
+brew install rtk
+```
+
+PreToolUse hook rewrites Bash commands through `rtk rewrite` (only when rtk
+exits 0). Enforcement is runtime, not just install time:
+
+- `preflight.cjs` (UserPromptSubmit) blocks every prompt while `rtk` or
+  `tokensave` is missing from PATH, with install hints.
+- `rtk.cjs` (PreToolUse) blocks Bash calls when `rtk` is missing.
+- A failed rewrite with rtk present passes the command through unchanged.
+
+## DirectSpeech
+
+Always active — enforced by the harness, no toggle, no flag files.
+
+- Ruleset: Impulso mode block in `shared/AGENTS.md`, loaded via `CLAUDE.md` →
+  `@AGENTS.md`.
+- Per-turn reinforcement: `directspeech-context.cjs` (UserPromptSubmit) injects
+  one line unconditionally. The line lives in `shared/directspeech-config.cjs`,
+  shared with the opencode harness.
+- Escape hatches are model-level: Auto-Clarity for security warnings and
+  irreversible actions; code/commits/PRs always written normal.
+
+## Tests
+
+```bash
+node harnesses/claude/tests.cjs   # hook contracts + config assertions
+node shared/tests.cjs             # reinforcement line unit tests
+```
+
+## Structure
+
+```
+impulso/harnesses/claude/
+├── README.md
+├── install.sh
+├── uninstall.sh
+├── merge-settings.cjs
+├── tests.cjs
+└── hooks/
+    ├── preflight.cjs
+    ├── rtk.cjs
+    └── directspeech-context.cjs
+```

package/harnesses/claude/hooks/bash-state-guard.cjs

@@ -0,0 +1,84 @@
+// impulso bash-state-guard hook — Claude Code
+//
+// PreToolUse handler (matcher: Bash).
+// Blocks any Bash command that touches gate-owned state paths:
+//   .impulso/work/<slug>/state.json   or   .impulso/active
+// Gate invocations (impulso-hub / scripts/impulso-hub.cjs) are always allowed.
+//
+// Exit codes:
+//   0 — allow
+//   2 — blocked (canary phrase on stderr)
+//
+// Reads like `cat state.json` are blocked too (fail-closed). Stderr includes
+// guidance for status queries.
+//
+// Hook: PreToolUse (matcher: Bash)
+//
+// Exported for use by pretooluse-bash.cjs dispatcher:
+//   check(input) -> { block: boolean, stderr?: string }
+
+'use strict';
+
+const path = require('node:path');
+const { isStateGuardHit, isGateInvocation } = require(
+  path.join(__dirname, '..', '..', '..', 'shared', 'state-guard.cjs'),
+);
+
+// Pure function: check whether a hook input payload should be blocked.
+// Returns { block: true, stderr: '...' } when blocked, { block: false } otherwise.
+function check(input) {
+  const toolName = (input.tool_name || '').toLowerCase();
+  if (toolName !== 'bash') return { block: false };
+  const command = (input.tool_input && input.tool_input.command) || '';
+  if (!command) return { block: false };
+  if (isGateInvocation(command)) return { block: false };
+  if (isStateGuardHit(command)) {
+    return {
+      block: true,
+      stderr:
+        'state file is gate-owned; use impulso-hub\nread state via: impulso-hub status --json\n',
+    };
+  }
+  return { block: false };
+}
+
+module.exports = { check };
+
+function main() {
+  let done = false;
+  const chunks = [];
+
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('readable', () => {
+    let c;
+    while ((c = process.stdin.read()) !== null) chunks.push(c);
+  });
+
+  function finish(raw) {
+    if (done) return;
+    done = true;
+    clearTimeout(timer); // safe: timer defined below before finish can fire
+
+    let input;
+    try {
+      input = JSON.parse(raw || '{}');
+    } catch (_e) {
+      process.exit(0);
+      return;
+    }
+
+    const result = check(input);
+    if (result.block) {
+      if (result.stderr) process.stderr.write(result.stderr);
+      process.exit(2);
+      return;
+    }
+
+    process.exit(0);
+  }
+
+  process.stdin.on('end', () => finish(chunks.join('')));
+  const timer = setTimeout(() => finish(chunks.join('')), 1000);
+}
+
+if (require.main === module) main();

package/harnesses/claude/hooks/directspeech-context.cjs

@@ -0,0 +1,29 @@
+// impulso-directspeech context hook — Claude Code
+//
+// UserPromptSubmit handler. DirectSpeech is always on — inject the
+// reinforcement line as additionalContext every turn, unconditionally.
+// No flags, no toggles, no modes.
+//
+// Hook: UserPromptSubmit
+//
+// Exported for use by userpromptsubmit.cjs dispatcher:
+//   contextObject() -> { hookSpecificOutput: { hookEventName, additionalContext } }
+
+const path = require('node:path');
+const config = require(path.join(__dirname, '../../../shared/directspeech-config.cjs'));
+
+// Pure function: build the hook output object.
+function contextObject() {
+  return {
+    hookSpecificOutput: {
+      hookEventName: 'UserPromptSubmit',
+      additionalContext: config.reinforcementLine(),
+    },
+  };
+}
+
+module.exports = { contextObject };
+
+if (require.main === module) {
+  process.stdout.write(JSON.stringify(contextObject()) + '\n');
+}

package/harnesses/claude/hooks/path-guard.cjs

@@ -0,0 +1,106 @@
+// impulso path-guard hook — Claude Code
+//
+// PreToolUse handler (matcher: Edit|Write). Enforces two deny rules:
+//
+// Deny 1 — gate-owned state files (fail-CLOSED; never depends on role):
+//   Normalized file_path matches /(^|\/)\.impulso\/(work\/[^/]+\/state\.json|active)$/
+//   → exit 2 "state file is gate-owned; use impulso-hub"
+//
+// Deny 2 — read-only agent writing to source tree:
+//   Role file for session_id exists AND role ∈ {scout, scout-writer, planner, reviewer}
+//   AND normalized path does NOT contain '/.impulso/'
+//   → exit 2 "read-only agent (<role>): source tree writes denied; workspace (.impulso/) only"
+//
+// Everything else → exit 0 (allow). Missing or unparseable role file → treat
+// as no role (exit 0), EXCEPT Deny 1 which is unconditional.
+//
+// Sessions dir: IMPULSO_SESSIONS_DIR env (default: os.tmpdir()/impulso-sessions).
+//
+// Hook: PreToolUse (matcher: Edit|Write)
+
+const os = require('node:os');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const READ_ONLY_ROLES = new Set(['scout', 'scout-writer', 'planner', 'reviewer']);
+
+// Matches gate-owned state paths:
+//   .impulso/work/<slug>/state.json   or   .impulso/active
+// at any position in the path (absolute or relative).
+const STATE_FILE_RE = /(^|\/)\.impulso\/(work\/[^/]+\/state\.json|active)$/;
+
+function sessionsDir() {
+  return process.env.IMPULSO_SESSIONS_DIR || path.join(os.tmpdir(), 'impulso-sessions');
+}
+
+function getRole(sessionId) {
+  if (!sessionId) return null;
+  try {
+    const p = path.join(sessionsDir(), sessionId + '.json');
+    const data = JSON.parse(fs.readFileSync(p, 'utf8'));
+    return data.role || null;
+  } catch (_e) {
+    return null; // Missing or unparseable → no role
+  }
+}
+
+function main() {
+  let done = false;
+  const chunks = [];
+
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('readable', () => {
+    let c;
+    while ((c = process.stdin.read()) !== null) chunks.push(c);
+  });
+
+  function finish(raw) {
+    if (done) return;
+    done = true;
+    clearTimeout(timer); // safe: finish() is only called after const timer = ... executes
+
+    let input;
+    try {
+      input = JSON.parse(raw || '{}');
+    } catch (_e) {
+      process.exit(0); // Fail-open on parse error
+      return;
+    }
+
+    const filePath = (input.tool_input && input.tool_input.file_path) || '';
+    // Normalize: replace backslashes first, then resolve dot/dot-dot segments.
+    const normalized = path.posix.normalize(filePath.replace(/\\/g, '/'));
+    // Lowercase copy for case-insensitive checks (macOS FS is case-insensitive).
+    // Never alter `normalized` — it is used in stderr messages.
+    const normalizedLower = normalized.toLowerCase();
+
+    // Deny 1: gate-owned state files — unconditional, no role check needed
+    if (STATE_FILE_RE.test(normalizedLower)) {
+      process.stderr.write('state file is gate-owned; use impulso-hub\n');
+      process.exit(2);
+      return;
+    }
+
+    // Deny 2: read-only role writing to source tree
+    const sessionId = input.session_id || null;
+    const role = getRole(sessionId);
+
+    // Workspace = path contains /.impulso/ (absolute) OR starts with .impulso/ (relative).
+    const isWorkspace =
+      normalizedLower.includes('/.impulso/') || normalizedLower.startsWith('.impulso/');
+    if (role && READ_ONLY_ROLES.has(role) && !isWorkspace) {
+      process.stderr.write(
+        `read-only agent (${role}): source tree writes denied; workspace (.impulso/) only\n`,
+      );
+      process.exit(2);
+      return;
+    }
+
+    process.exit(0);
+  }
+
+  process.stdin.on('end', () => finish(chunks.join('')));
+  const timer = setTimeout(() => finish(chunks.join('')), 1000);
+}
+
+main();

package/harnesses/claude/hooks/preflight.cjs

@@ -0,0 +1,39 @@
+// impulso preflight hook — Claude Code
+//
+// UserPromptSubmit handler. Enforces the hard-required binaries (rtk,
+// tokensave): if either is missing from PATH, exit 2 blocks the prompt and
+// surfaces install instructions. Impulso is opinionated — no degraded mode.
+//
+// Hook: UserPromptSubmit
+//
+// Exported for use by userpromptsubmit.cjs dispatcher:
+//   missingBinaries() -> [{bin, hint}]
+
+const { spawnSync } = require('node:child_process');
+
+const REQUIRED = [
+  { bin: 'rtk', hint: 'brew install rtk-ai/tap/rtk' },
+  { bin: 'tokensave', hint: 'brew install aovestdipaperino/tap/tokensave' },
+  { bin: 'plannotator', hint: 'npm i -g plannotator' },
+];
+
+// Pure function: returns required binaries missing from PATH.
+function missingBinaries() {
+  return REQUIRED.filter(({ bin }) => {
+    const r = spawnSync('which', [bin], { stdio: ['ignore', 'pipe', 'ignore'] });
+    return r.error || r.status !== 0;
+  });
+}
+
+module.exports = { missingBinaries };
+
+if (require.main === module) {
+  const missing = missingBinaries();
+  if (missing.length > 0) {
+    const lines = missing.map(({ bin, hint }) => `  ${bin} — install: ${hint}`);
+    process.stderr.write(
+      'impulso: hard-required binaries missing from PATH:\n' + lines.join('\n') + '\n',
+    );
+    process.exit(2);
+  }
+}

package/harnesses/claude/hooks/pretooluse-bash.cjs

@@ -0,0 +1,69 @@
+// impulso pretooluse-bash dispatcher — Claude Code
+//
+// PreToolUse(Bash) dispatcher. Reads stdin once, runs rtk rewrite then
+// bash-state-guard. rtk's exit-2 (missing binary) short-circuits before the
+// guard runs.
+//
+// Hook: PreToolUse (matcher: Bash)
+
+'use strict';
+
+const path = require('node:path');
+const rtk = require(path.join(__dirname, 'rtk.cjs'));
+const bashStateGuard = require(path.join(__dirname, 'bash-state-guard.cjs'));
+
+const chunks = [];
+let done = false;
+process.stdin.setEncoding('utf8');
+process.stdin.on('readable', () => {
+  let c;
+  while ((c = process.stdin.read()) !== null) chunks.push(c);
+});
+
+function finish(raw) {
+  if (done) return;
+  done = true;
+  clearTimeout(timer); // safe: timer defined below before finish can fire
+
+  let input;
+  try {
+    input = JSON.parse(raw);
+  } catch (_e) {
+    process.exit(0);
+    return;
+  }
+
+  // Stage 1: rtk rewrite (may process.exit(2) if rtk missing)
+  const rtkResult = rtk.rewriteResult(input);
+
+  // Stage 2: bash-state-guard on the effective (possibly rewritten) input
+  const effectiveInput = rtkResult
+    ? { ...input, tool_input: { ...input.tool_input, command: rtkResult.updatedInput.command } }
+    : input;
+
+  const guard = bashStateGuard.check(effectiveInput);
+  if (guard.block) {
+    if (guard.stderr) process.stderr.write(guard.stderr);
+    process.exit(2);
+    return;
+  }
+
+  // Emit rewrite result if rtk changed the command
+  if (rtkResult) {
+    process.stdout.write(
+      JSON.stringify({
+        hookSpecificOutput: {
+          hookEventName: 'PreToolUse',
+          updatedInput: rtkResult.updatedInput,
+        },
+      }) + '\n',
+    );
+  }
+
+  process.exit(0);
+}
+
+process.stdin.on('end', () => finish(chunks.join('')));
+// 1-second fallback: if Claude Code's hook runner delays closing stdin,
+// finish on whatever data arrived. Mirrors bash-state-guard.cjs defensive design.
+const timer = setTimeout(() => finish(chunks.join('')), 1000);

package/harnesses/claude/hooks/rtk.cjs

@@ -0,0 +1,87 @@
+// impulso rtk hook — Claude Code
+//
+// PreToolUse Bash handler. Rewrites bash commands through `rtk rewrite`
+// for token savings. Mirrors the opencode rtk.ts plugin behavior.
+//
+// Hook: PreToolUse (matcher: Bash)
+//
+// Exported for use by pretooluse-bash.cjs dispatcher:
+//   rewriteResult(input) -> { updatedInput: {command} } | null
+//     Returns null when tool is not Bash, command is empty, or rtk exits
+//     non-zero. May process.exit(2) if rtk is missing from PATH.
+
+const { spawnSync } = require('node:child_process');
+
+// Returns the rewritten command, or null to pass through unchanged.
+//
+// rtk is hard-required: missing from PATH (spawn ENOENT) blocks the Bash
+// call — exit 2 makes Claude Code reject the tool use and feeds stderr back
+// to the model. Do not fall back to raw commands; fix the install.
+//
+// A non-zero exit with rtk PRESENT means this particular rewrite failed —
+// pass through unchanged (rtk's partial stdout must not be trusted).
+function rewrite(command) {
+  const r = spawnSync('rtk', ['rewrite', command], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    timeout: 5000,
+  });
+  if (r.error && r.error.code === 'ENOENT') {
+    process.stderr.write(
+      'impulso: rtk is hard-required but missing from PATH. ' +
+        'Install: brew install rtk-ai/tap/rtk\n',
+    );
+    process.exit(2);
+  }
+  if (r.error || r.status !== 0) return null;
+  return r.stdout.trim();
+}
+
+// Pure function: evaluate rtk rewrite for a hook input payload.
+// Returns { updatedInput: { command } } when rtk rewrites the command,
+// null otherwise. May process.exit(2) if rtk is missing from PATH.
+function rewriteResult(input) {
+  const toolName = (input.tool_name || '').toLowerCase();
+  if (toolName !== 'bash' && toolName !== 'shell') return null;
+  const command = input.tool_input && input.tool_input.command;
+  if (typeof command !== 'string' || !command) return null;
+  const rewritten = rewrite(command);
+  if (rewritten && rewritten !== command) {
+    return { updatedInput: { command: rewritten } };
+  }
+  return null;
+}
+
+module.exports = { rewriteResult };
+
+function main() {
+  const chunks = [];
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('readable', () => {
+    let chunk;
+    while ((chunk = process.stdin.read()) !== null) {
+      chunks.push(chunk);
+    }
+  });
+
+  process.stdin.on('end', () => {
+    try {
+      const input = JSON.parse(chunks.join(''));
+      const result = rewriteResult(input);
+      if (result) {
+        process.stdout.write(
+          JSON.stringify({
+            hookSpecificOutput: {
+              hookEventName: 'PreToolUse',
+              updatedInput: result.updatedInput,
+            },
+          }) + '\n',
+        );
+      }
+    } catch (e) {
+      // Parse / filesystem errors — pass through unchanged
+    }
+  });
+}
+
+if (require.main === module) main();