all-hands-cli 0.1.0

package/.allhands/harness/src/hooks/enforcement.ts

@@ -0,0 +1,170 @@
+/**
+ * Enforcement Hooks
+ *
+ * PreToolUse hooks that enforce usage patterns:
+ * - Block GitHub URLs in WebFetch/Bash (suggest gh CLI)
+ * - Block WebFetch (suggest research tools)
+ * - Block WebSearch (suggest research delegation)
+ */
+
+import type { Command } from 'commander';
+import {
+  HookInput,
+  HookCategory,
+  RegisterFn,
+  allowTool,
+  denyTool,
+  registerCategory,
+  registerCategoryForDaemon,
+} from './shared.js';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Constants
+// ─────────────────────────────────────────────────────────────────────────────
+
+const GITHUB_DOMAINS = ['github.com', 'raw.githubusercontent.com', 'gist.github.com'];
+
+// ─────────────────────────────────────────────────────────────────────────────
+// GitHub URL Enforcement
+// ─────────────────────────────────────────────────────────────────────────────
+
+const HOOK_GITHUB_URL = 'enforcement github-url';
+
+/**
+ * Block GitHub URLs in WebFetch and Bash fetch commands.
+ * Suggests using the gh CLI instead.
+ *
+ * Triggered by: PreToolUse matcher "(WebFetch|Bash)"
+ */
+export function enforceGitHubUrl(input: HookInput): void {
+  const toolName = input.tool_name || '';
+  const toolInput = input.tool_input || {};
+
+  // Check WebFetch URLs
+  if (toolName === 'WebFetch') {
+    const url = (toolInput.url as string) || '';
+    for (const domain of GITHUB_DOMAINS) {
+      if (url.includes(domain)) {
+        denyTool("GitHub URL detected. Use 'gh' CLI: gh api repos/OWNER/REPO/contents/PATH", HOOK_GITHUB_URL);
+      }
+    }
+    allowTool(HOOK_GITHUB_URL);
+  }
+
+  // Check Bash commands for curl, wget, tavily extract
+  if (toolName === 'Bash') {
+    const command = (toolInput.command as string) || '';
+
+    // Check for fetch-like commands
+    const isFetchCmd = ['curl', 'wget', 'tavily extract'].some((cmd) => command.includes(cmd));
+    if (!isFetchCmd) {
+      allowTool(HOOK_GITHUB_URL);
+    }
+
+    // Check for GitHub URLs
+    for (const domain of GITHUB_DOMAINS) {
+      if (command.includes(domain)) {
+        denyTool("GitHub URL detected. Use 'gh' CLI: gh api repos/OWNER/REPO/contents/PATH", HOOK_GITHUB_URL);
+      }
+    }
+  }
+
+  allowTool(HOOK_GITHUB_URL);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Research Fetch Enforcement
+// ─────────────────────────────────────────────────────────────────────────────
+
+const HOOK_RESEARCH_FETCH = 'enforcement research-fetch';
+
+/**
+ * Block WebFetch and suggest research tools.
+ *
+ * Triggered by: PreToolUse matcher "WebFetch"
+ */
+export function enforceResearchFetch(input: HookInput): void {
+  const url = (input.tool_input?.url as string) || '';
+
+  if (!url) {
+    allowTool(HOOK_RESEARCH_FETCH);
+  }
+
+  denyTool(
+    'WebFetch blocked. Use `ah tavily extract "<url>"` instead.',
+    HOOK_RESEARCH_FETCH
+  );
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Research Search Enforcement
+// ─────────────────────────────────────────────────────────────────────────────
+
+const HOOK_RESEARCH_SEARCH = 'enforcement research-search';
+
+/**
+ * Block WebSearch and suggest research delegation.
+ *
+ * Triggered by: PreToolUse matcher "WebSearch"
+ */
+export function enforceResearchSearch(_input: HookInput): void {
+  denyTool(
+    'WebSearch blocked. Use `ah perplexity research "<query>"` instead.',
+    HOOK_RESEARCH_SEARCH
+  );
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Hook Category Definition
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Enforcement hooks category */
+export const category: HookCategory = {
+  name: 'enforcement',
+  description: 'Enforcement hooks (PreToolUse)',
+  hooks: [
+    {
+      name: 'github-url',
+      description: 'Block GitHub URLs in fetch commands',
+      handler: enforceGitHubUrl,
+      errorFallback: { type: 'allowTool' },
+      logPayload: (input) => ({ tool: input.tool_name }),
+    },
+    {
+      name: 'research-fetch',
+      description: 'Block WebFetch and suggest `ah tavily extract "<url>"` instead',
+      handler: enforceResearchFetch,
+      errorFallback: { type: 'allowTool' },
+      logPayload: (input) => ({ tool: input.tool_name }),
+    },
+    {
+      name: 'research-search',
+      description: 'Block WebSearch and suggest `ah perplexity research "<query>"` instead',
+      handler: enforceResearchSearch,
+      errorFallback: { type: 'allowTool' },
+      logPayload: (input) => ({ tool: input.tool_name }),
+    },
+  ],
+};
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Command Registration
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Register enforcement hook subcommands.
+ */
+export function register(parent: Command): void {
+  registerCategory(parent, category);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Daemon Handler Registration
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Register handlers for daemon mode.
+ */
+export function registerDaemonHandlers(register: RegisterFn): void {
+  registerCategoryForDaemon(category, register);
+}

package/.allhands/harness/src/hooks/index.ts

@@ -0,0 +1,54 @@
+/**
+ * Hook Registry - Auto-discovers hook modules.
+ *
+ * Each hook file should export a `register` function that takes
+ * a Commander Command (the parent 'hooks' command) and registers its subcommands.
+ *
+ * Skips: index.ts, shared.ts, transcript-parser.ts (utilities)
+ */
+
+import { readdirSync, statSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+import type { Command } from 'commander';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// Files to skip (utilities, not hook commands)
+const SKIP_FILES = ['index.ts', 'shared.ts', 'transcript-parser.ts'];
+
+export interface HookModule {
+  register: (parent: Command) => void;
+}
+
+/**
+ * Auto-discover and register all hook modules.
+ *
+ * @param parent - The parent 'hooks' command to register subcommands on
+ */
+export async function discoverAndRegisterHooks(parent: Command): Promise<void> {
+  const entries = readdirSync(__dirname);
+
+  for (const entry of entries) {
+    const entryPath = join(__dirname, entry);
+    const stat = statSync(entryPath);
+
+    // Skip directories and non-ts files
+    if (stat.isDirectory()) continue;
+    if (!entry.endsWith('.ts')) continue;
+    if (SKIP_FILES.includes(entry)) continue;
+
+    const moduleName = entry.replace('.ts', '');
+    const importPath = `./${moduleName}.js`;
+
+    try {
+      const module = (await import(importPath)) as HookModule;
+      if (typeof module.register === 'function') {
+        module.register(parent);
+      }
+    } catch (e) {
+      // Skip modules with errors - log for debugging
+      console.error(`Warning: Could not load hook module ${moduleName}: ${e}`);
+    }
+  }
+}

package/.allhands/harness/src/hooks/lifecycle.ts

@@ -0,0 +1,229 @@
+/**
+ * Lifecycle Hooks
+ *
+ * Hooks for agent lifecycle events:
+ * - Stop: Send notification and kill tmux window
+ * - PreCompact: Summarize progress, append to prompt file, kill tmux window
+ */
+
+import { existsSync } from 'fs';
+import type { Command } from 'commander';
+import {
+  HookInput,
+  HookCategory,
+  RegisterFn,
+  outputStopHook,
+  outputPreCompact,
+  registerCategory,
+  registerCategoryForDaemon,
+} from './shared.js';
+import { logHookSuccess } from '../lib/trace-store.js';
+import { sendNotification } from '../lib/notification.js';
+import { killWindow, SESSION_NAME, windowExists, getCurrentSession } from '../lib/tmux.js';
+import { getPromptByNumber } from '../lib/prompts.js';
+import { getCurrentBranch, sanitizeBranchForDir } from '../lib/planning.js';
+import { runCompaction } from '../lib/compaction.js';
+
+const HOOK_AGENT_STOP = 'lifecycle agent-stop';
+const HOOK_AGENT_COMPACT = 'lifecycle agent-compact';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Agent Stop
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Handle agent stop lifecycle event.
+ *
+ * - Sends desktop notification
+ * - Kills the tmux window (for prompt-scoped agents that may not close naturally)
+ * - Approves the stop
+ *
+ * Triggered by: Stop matcher "*"
+ */
+export function handleAgentStop(_input: HookInput): void {
+  const agentId = process.env.AGENT_ID;
+  const agentType = process.env.AGENT_TYPE || 'Agent';
+  const isPromptScoped = process.env.PROMPT_SCOPED === 'true';
+
+  // Send notification
+  const title = agentId ? `${agentType} Stopped` : 'Agent Stopped';
+  const message = agentId ? `Agent ${agentId} has stopped` : 'The agent session has stopped';
+
+  sendNotification({
+    title,
+    message,
+    type: 'banner',
+  });
+
+  // Kill the tmux window for prompt-scoped agents AND the emergent planner.
+  // Non-prompt-scoped agents (except emergent) should remain running (their window stays open).
+  // Prompt-scoped agents may not close naturally even with exec, so we
+  // explicitly kill them here. The emergent planner is prompt_scoped, but
+  // this condition also covers it by agent type for clarity.
+  if (isPromptScoped || agentType === 'emergent') {
+    const sessionName = getCurrentSession() || SESSION_NAME;
+    if (agentId && windowExists(sessionName, agentId)) {
+      killWindow(sessionName, agentId);
+    }
+  }
+
+  // Approve stop
+  outputStopHook('approve', undefined, HOOK_AGENT_STOP);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Pre-Compact
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Handle pre-compaction lifecycle event.
+ *
+ * When context gets too long and compaction is triggered for a prompt-scoped agent:
+ * 1. Run full compaction analysis via oracle:
+ *    - Analyze conversation for progress, learnings, blockers
+ *    - Recommend action: continue (keep code) or scratch (discard)
+ *    - Increment attempts counter in prompt frontmatter
+ *    - Append detailed progress update to prompt file
+ *    - Execute recommendation (commit or discard changes)
+ * 2. Kill the tmux window (terminate the Claude instance)
+ * 3. Event loop can then re-run the prompt with learnings
+ *
+ * Criteria to run full compaction:
+ * - PROMPT_SCOPED=true (agent is prompt-scoped)
+ * - PROMPT_NUMBER is set (we know which prompt file to update)
+ * - transcript_path exists (we have conversation logs to analyze)
+ *
+ * Triggered by: PreCompact matcher "*"
+ */
+export async function handleAgentCompact(input: HookInput): Promise<void> {
+  const agentId = process.env.AGENT_ID;
+  const promptNumber = process.env.PROMPT_NUMBER;
+  const isPromptScoped = process.env.PROMPT_SCOPED === 'true';
+  const transcriptPath = input.transcript_path;
+
+  const agentType = process.env.AGENT_TYPE;
+
+  // Only process compaction for prompt executor agents (prompt-scoped with PROMPT_NUMBER).
+  // The emergent planner is prompt_scoped (for window naming) but must NOT run compaction —
+  // it plans hypotheses, not implementation. Non-prompt-scoped agents pass through too.
+  if (!isPromptScoped || !promptNumber || agentType === 'emergent') {
+    logHookSuccess(HOOK_AGENT_COMPACT, {
+      action: 'skip',
+      reason: !isPromptScoped ? 'not_prompt_scoped' : agentType === 'emergent' ? 'emergent_planner' : 'no_prompt_number',
+    });
+    return outputPreCompact(undefined);
+  }
+
+  // Use current session (not hardcoded SESSION_NAME) since agents may be
+  // spawned in whatever session is active, not necessarily 'ah-hub'
+  const sessionName = getCurrentSession() || SESSION_NAME;
+
+  // Get the planning key (sanitized branch name) for directory lookups.
+  // The planning directory is .planning/<sanitized-branch>/ (e.g., "feature-core-taskflow-crud").
+  const branch = getCurrentBranch();
+  const planningKey = sanitizeBranchForDir(branch);
+
+  // Get the prompt file
+  const promptNum = parseInt(promptNumber, 10);
+  const prompt = getPromptByNumber(promptNum, planningKey);
+
+  if (!prompt) {
+    // Prompt file not found, kill window and exit
+    logHookSuccess(HOOK_AGENT_COMPACT, { action: 'skip', reason: 'no_prompt', promptNum, planningKey });
+    if (agentId && windowExists(sessionName, agentId)) {
+      killWindow(sessionName, agentId);
+    }
+    return outputPreCompact(undefined);
+  }
+
+  // Need transcript to run compaction analysis
+  if (!transcriptPath || !existsSync(transcriptPath)) {
+    sendNotification({
+      title: 'Compaction Skipped',
+      message: `No transcript available for prompt ${promptNumber}`,
+      type: 'banner',
+    });
+    if (agentId && windowExists(sessionName, agentId)) {
+      killWindow(sessionName, agentId);
+    }
+    return outputPreCompact(undefined, HOOK_AGENT_COMPACT);
+  }
+
+  // Notify that compaction is starting
+  sendNotification({
+    title: 'Compaction Starting',
+    message: `Analyzing prompt ${promptNumber}...`,
+    type: 'banner',
+  });
+
+  try {
+    // Run full compaction analysis (result written to prompt file)
+    await runCompaction({
+      conversationLogs: transcriptPath,
+      promptFile: prompt.path,
+    });
+  } catch {
+    // Compaction failed - error logged to trace store
+  }
+
+  // Kill the tmux window after compaction completes.
+  // PreCompact hook does NOT stop the Claude session - we must explicitly kill it.
+  if (agentId && windowExists(sessionName, agentId)) {
+    killWindow(sessionName, agentId);
+  }
+
+  outputPreCompact(undefined, HOOK_AGENT_COMPACT);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Hook Category Definition
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Lifecycle hooks category */
+export const category: HookCategory = {
+  name: 'lifecycle',
+  description: 'Lifecycle hooks (Stop, PreCompact)',
+  hooks: [
+    {
+      name: 'agent-stop',
+      description: 'Handle agent stop event',
+      handler: handleAgentStop,
+      errorFallback: { type: 'outputStopHook', decision: 'approve' },
+      logPayload: () => ({ agentId: process.env.AGENT_ID }),
+    },
+    {
+      name: 'agent-compact',
+      description: 'Handle pre-compaction event',
+      handler: handleAgentCompact,
+      errorFallback: { type: 'continue' },
+      logPayload: () => ({
+        agentId: process.env.AGENT_ID,
+        promptNumber: process.env.PROMPT_NUMBER,
+        promptScoped: process.env.PROMPT_SCOPED,
+        specName: process.env.SPEC_NAME,
+      }),
+    },
+  ],
+};
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Command Registration
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Register lifecycle hook subcommands.
+ */
+export function register(parent: Command): void {
+  registerCategory(parent, category);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Daemon Handler Registration
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Register handlers for daemon mode.
+ */
+export function registerDaemonHandlers(register: RegisterFn): void {
+  registerCategoryForDaemon(category, register);
+}

package/.allhands/harness/src/hooks/notification.ts

@@ -0,0 +1,104 @@
+/**
+ * Notification Hooks
+ *
+ * Hooks that send desktop notifications for various Claude Code events:
+ * - stop: Agent has stopped working (Stop:*)
+ * - compact: Context is being compacted (PreCompact:*)
+ *
+ * Uses jamf/Notifier for macOS notifications.
+ */
+
+import type { Command } from 'commander';
+import { HookInput, readHookInput } from './shared.js';
+import { sendGateNotification } from '../lib/notification.js';
+import { logHookStart, logHookSuccess } from '../lib/trace-store.js';
+
+const HOOK_STOP = 'notification stop';
+const HOOK_COMPACT = 'notification compact';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Stop: Agent stopped
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Handle stop notification.
+ *
+ * Sends a notification when the agent has stopped working.
+ *
+ * Triggered by: Stop matcher "*"
+ */
+function handleStopNotification(_input: HookInput): void {
+  sendGateNotification('Stopped', 'Agent has finished');
+
+  // Output approval to allow stop
+  logHookSuccess(HOOK_STOP, { action: 'approve' });
+  console.log(JSON.stringify({ decision: 'approve' }));
+  process.exit(0);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// PreCompact: Context compaction
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Handle pre-compact notification.
+ *
+ * Sends a notification when the agent is about to compact context.
+ *
+ * Triggered by: PreCompact matcher "*"
+ */
+function handleCompactNotification(_input: HookInput): void {
+  sendGateNotification('Compacting', 'Context is being summarized');
+
+  // Output to allow compaction to proceed
+  logHookSuccess(HOOK_COMPACT, { action: 'continue' });
+  console.log(JSON.stringify({ continue: true }));
+  process.exit(0);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Command Registration
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Register notification hook subcommands.
+ */
+export function register(parent: Command): void {
+  const notification = parent
+    .command('notification')
+    .description('Notification hooks (desktop alerts for events)');
+
+  // ah hooks notification stop
+  notification
+    .command('stop')
+    .description('Handle stop notification (Stop:*)')
+    .action(async () => {
+      try {
+        const input = await readHookInput();
+        logHookStart(HOOK_STOP, {});
+        handleStopNotification(input);
+      } catch {
+        // On error, approve stop
+        logHookSuccess(HOOK_STOP, { action: 'approve', error: true });
+        console.log(JSON.stringify({ decision: 'approve' }));
+        process.exit(0);
+      }
+    });
+
+  // ah hooks notification compact
+  notification
+    .command('compact')
+    .description('Handle compact notification (PreCompact:*)')
+    .action(async () => {
+      try {
+        const input = await readHookInput();
+        logHookStart(HOOK_COMPACT, {});
+        handleCompactNotification(input);
+      } catch {
+        // On error, allow compaction
+        logHookSuccess(HOOK_COMPACT, { action: 'continue', error: true });
+        console.log(JSON.stringify({ continue: true }));
+        process.exit(0);
+      }
+    });
+}