pantheon-opencode 1.4.3 → 1.5.0-beta.2

package/src/pantheon/goal-loop.ts

@@ -17,11 +17,11 @@
 import { z } from 'zod'
 
 import type { BackgroundJobBoard } from './background-job-board.ts'
+import type { ToolContextLike } from './delegation.ts'
 import { GoalStore } from './goal-store.ts'
 import { createPantheonLogger } from './logger.ts'
 import { safeSessionPath } from './session-guard.ts'
 import type { TodoEnforcerMessage } from './todo-enforcer.ts'
-import type { ToolContextLike } from './tool-context.ts'
 
 // Silence-by-default TUI policy (pantheon-hooks L42-58): warn → hooks.log,
 // console echo opt-in via PANTHEON_HOOKS_LOG=1. `deps.logger` stays for tests.
@@ -103,7 +103,7 @@ const goalUpdateArgs = {
 
 const goalGetArgs = {} satisfies z.ZodRawShape
 
-/** One structural goal tool: description + zod args shape + execute. */
+/** One structural goal tool: description + zod args shape + execute (delegation.ts shape). */
 export type GoalTool<Args extends z.ZodRawShape> = {
   description: string
   args: Args

package/src/pantheon/goal-store.ts

@@ -15,7 +15,7 @@
 import { mkdir, readFile, rename, writeFile } from 'node:fs/promises'
 import { join } from 'node:path'
 
-import { assertSafeParentSessionID } from './tool-context.ts'
+import { assertSafeParentSessionID } from './delegation-finalize.ts'
 
 export type GoalStatus = 'pending' | 'in_progress' | 'done'
 

package/src/pantheon/hashline/tool.ts

@@ -2,8 +2,8 @@
  * Hashline edit tool (Wave 2, PR #46) — structural `hashline_edit` tool that
  * anchors edits to stable sha256 content tags instead of fragile line numbers.
  *
- * Tool shape follows the plugin tool convention (`{description, args, execute}`,
- * zod-validated) used across the Pantheon toolset.
+ * Tool shape matches the delegation tools (`{description, args, execute}`,
+ * zod-validated — same import pattern as delegation.ts).
  *
  * Safety model (council-approved):
  *   1. ALL refs are validated against the ORIGINAL file snapshot BEFORE any

package/src/pantheon/model-command.ts

@@ -23,6 +23,8 @@ import { lstat, mkdir, open, rename, unlink } from 'node:fs/promises'
 import { homedir } from 'node:os'
 import { basename, dirname, join, resolve } from 'node:path'
 import { z } from 'zod'
+
+import type { ToolContextLike } from './delegation.ts'
 import {
   capabilityEntry,
   hasVision,
@@ -30,7 +32,6 @@ import {
   normalizeCapability,
   resolveActivePreset,
 } from './presets.mjs'
-import type { ToolContextLike } from './tool-context.ts'
 
 export type ModelScope = 'project' | 'global'
 export type ModelAction = 'status' | 'show' | 'set' | 'reset'

package/src/pantheon/permission-eval.ts

@@ -0,0 +1,284 @@
+/**
+ * S1 — Deny-first permission evaluation + PreToolUse-style hooks.
+ *
+ * Deny rules checked BEFORE allow rules. User-level denies cannot be
+ * overridden by project config. Hook exit-code semantics:
+ *   exit 0 → allow, exit 2 → hard deny, missing/throw → fail-open.
+ *
+ * @module permission-eval
+ */
+
+// ─── Types ─────────────────────────────────────────────────────────────
+
+/** Result of a permission evaluation. */
+export interface PermissionResult {
+  allowed: boolean
+  reason: 'allow' | 'deny' | 'hook_deny' | 'no_match'
+  message?: string
+}
+
+/** Hook script result (mirrors hook-runner.ts HookResult). */
+export interface HookResult {
+  code: number
+  stdout: string
+  stderr: string
+  /** When true, the hook script was not found — treat as fail-open. */
+  missing?: boolean
+}
+
+/**
+ * PreToolUse hook function signature.
+ * exit 0 → allow, exit 2 → hard deny, exit 1 → soft deny.
+ * Throw = fail-open.
+ */
+export type PreToolUseHook = (tool: string, args: unknown) => Promise<HookResult> | HookResult
+
+/** Permission configuration. */
+export interface PermissionConfig {
+  /** Deny rules — evaluated first. User-level denies override project allows. */
+  deny: readonly string[]
+  /** Allow rules — evaluated after deny. */
+  allow: readonly string[]
+  /** Optional hooks configuration. */
+  hooks?: {
+    /** PreToolUse hook function (in-process, not script path). */
+    preToolUse?: PreToolUseHook
+  }
+}
+
+// ─── Pattern matching ──────────────────────────────────────────────────
+
+/**
+ * Parse a permission rule pattern into { tool, argPattern }.
+ *
+ * Supported formats:
+ *   - "tool"             → tool="tool", argPattern="*"
+ *   - "tool:*"           → tool="tool", argPattern="*"
+ *   - "tool:subcommand"  → tool="tool", argPattern="subcommand"
+ *   - "tool(pattern)"    → tool="tool", argPattern="pattern" (full match)
+ *   - "*:*"              → tool="*", argPattern="*"
+ *   - "git push:*"       → tool="git push", argPattern="*" (subcommand prefix)
+ */
+function parsePattern(pattern: string): { tool: string; argPattern: string } {
+  // Handle "tool(pattern)" format — the content inside parens is the full
+  // arg pattern. Colons inside parens are literal, not separators.
+  const parenMatch = /^([^(]+)\(([^)]+)\)$/.exec(pattern)
+  if (parenMatch) {
+    const tool = parenMatch[1] ?? ''
+    const argPattern = parenMatch[2] ?? ''
+    return { tool, argPattern }
+  }
+
+  // Handle "tool:argPattern" or just "tool"
+  const colonIdx = pattern.indexOf(':')
+  if (colonIdx === -1) {
+    return { tool: pattern, argPattern: '*' }
+  }
+  const argPattern = pattern.slice(colonIdx + 1)
+  return {
+    tool: pattern.slice(0, colonIdx),
+    // Empty argPattern after colon = wildcard (e.g. "*:" matches any args)
+    argPattern: argPattern === '' ? '*' : argPattern,
+  }
+}
+
+/**
+ * Convert a glob-like pattern to a regex. `*` matches any sequence.
+ * Anchored to full match.
+ */
+function globToRegex(pattern: string): RegExp {
+  const escaped = pattern
+    .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+    .replace(/\*/g, '.*')
+    .replace(/\?/g, '.')
+  return new RegExp(`^${escaped}$`)
+}
+
+/** Extract a string representation from tool args for pattern matching. */
+function argsToString(args: unknown): string {
+  if (args === null || args === undefined) return ''
+  if (typeof args === 'string') return args
+  if (typeof args === 'object') {
+    const record = args as Record<string, unknown>
+    // Try common field names
+    for (const key of ['command', 'cmd', 'query', 'pattern', 'filePath', 'path', 'url']) {
+      if (typeof record[key] === 'string') return record[key]
+    }
+    return JSON.stringify(args)
+  }
+  return String(args)
+}
+
+/**
+ * Build a combined string for matching: "toolName argString".
+ * This allows patterns like "git push:*" to match tool="git" with args
+ * containing "push".
+ */
+function combinedString(tool: string, args: unknown): string {
+  const argsStr = argsToString(args)
+  return argsStr !== '' ? `${tool} ${argsStr}` : tool
+}
+
+/**
+ * Check if a tool+args matches a permission rule pattern.
+ * Returns true when the pattern matches.
+ *
+ * Matching strategy:
+ *   1. Wildcard tool ("*") → match any tool with argPattern
+ *   2. Direct tool match → check argPattern against args
+ *   3. Combined match (for "git push:*" style patterns) → prefix match
+ */
+function matchesRule(pattern: string, tool: string, args: unknown): boolean {
+  const { tool: patternTool, argPattern } = parsePattern(pattern)
+
+  // Wildcard tool: match any tool
+  if (patternTool === '*') {
+    if (argPattern === '*') return true
+    const argsStr = argsToString(args)
+    return globToRegex(argPattern).test(argsStr)
+  }
+
+  // Check direct tool match
+  if (globToRegex(patternTool).test(tool)) {
+    if (argPattern === '*') return true
+    const argsStr = argsToString(args)
+    return globToRegex(argPattern).test(argsStr)
+  }
+
+  // Combined match for patterns with spaces (e.g. "git push:*")
+  // The pattern tool includes a subcommand that appears in args.
+  // Use prefix matching: "git push" matches "git push origin main"
+  if (patternTool.includes(' ')) {
+    const combined = combinedString(tool, args)
+    // Prefix match: combined starts with pattern tool
+    if (combined.startsWith(patternTool)) {
+      return true
+    }
+  }
+
+  return false
+}
+
+// ─── Evaluation ────────────────────────────────────────────────────────
+
+/**
+ * Evaluate a permission config against a tool+args invocation.
+ *
+ * Evaluation order:
+ *   1. Check deny rules (user-level first, then project-level)
+ *   2. If no deny matched, run the PreToolUse hook
+ *   3. If hook exits 0 (or missing), check allow rules
+ *   4. If no allow matched → deny (implicit deny)
+ *
+ * User-level denies override project-level allows: a deny in the user config
+ * cannot be cancelled by an allow in the project config.
+ */
+export function evaluatePermission(
+  config: PermissionConfig,
+  invocation: { tool: string; args?: unknown },
+): PermissionResult {
+  const { tool, args } = invocation
+
+  // ── Step 1: Deny-first check ────────────────────────────────────────
+  for (const pattern of config.deny) {
+    if (matchesRule(pattern, tool, args)) {
+      return { allowed: false, reason: 'deny', message: `denied by rule: ${pattern}` }
+    }
+  }
+
+  // ── Step 2: PreToolUse hook ─────────────────────────────────────────
+  if (config.hooks?.preToolUse !== undefined) {
+    try {
+      const hookResult = config.hooks.preToolUse(tool, args)
+      // Support both sync and async hooks
+      // For sync hooks (non-Promise), check immediately
+      if (!(hookResult instanceof Promise)) {
+        // missing flag: hook script not found → fail-open
+        if (hookResult.missing === true) {
+          // Fall through to config evaluation (fail-open)
+        } else if (hookResult.code === 2) {
+          return {
+            allowed: false,
+            reason: 'hook_deny',
+            message: `hook hard deny (exit 2): ${hookResult.stderr}`,
+          }
+        } else if (hookResult.code !== 0) {
+          return {
+            allowed: false,
+            reason: 'hook_deny',
+            message: `hook deny (exit ${hookResult.code}): ${hookResult.stderr}`,
+          }
+        }
+        // Hook exited 0 (or missing) → fall through to allow check
+      }
+      // For async hooks, we cannot await in a sync function.
+      // Use evaluatePermissionAsync for async hooks.
+    } catch {
+      // Hook throw → fail-open: fall through to config evaluation
+    }
+  }
+
+  // ── Step 3: Allow check ─────────────────────────────────────────────
+  for (const pattern of config.allow) {
+    if (matchesRule(pattern, tool, args)) {
+      return { allowed: true, reason: 'allow', message: `allowed by rule: ${pattern}` }
+    }
+  }
+
+  // ── Step 4: No match → implicit deny ────────────────────────────────
+  return { allowed: false, reason: 'no_match', message: 'no matching allow rule' }
+}
+
+/**
+ * Async version of evaluatePermission that properly awaits hooks.
+ * Use this when hooks may be async (e.g., shell scripts).
+ */
+export async function evaluatePermissionAsync(
+  config: PermissionConfig,
+  invocation: { tool: string; args?: unknown },
+): Promise<PermissionResult> {
+  const { tool, args } = invocation
+
+  // ── Step 1: Deny-first check ────────────────────────────────────────
+  for (const pattern of config.deny) {
+    if (matchesRule(pattern, tool, args)) {
+      return { allowed: false, reason: 'deny', message: `denied by rule: ${pattern}` }
+    }
+  }
+
+  // ── Step 2: PreToolUse hook ─────────────────────────────────────────
+  if (config.hooks?.preToolUse !== undefined) {
+    try {
+      const hookResult = await config.hooks.preToolUse(tool, args)
+      // missing flag: hook script not found → fail-open
+      if (hookResult.missing === true) {
+        // Fall through to config evaluation (fail-open)
+      } else if (hookResult.code === 2) {
+        return {
+          allowed: false,
+          reason: 'hook_deny',
+          message: `hook hard deny (exit 2): ${hookResult.stderr}`,
+        }
+      } else if (hookResult.code !== 0) {
+        return {
+          allowed: false,
+          reason: 'hook_deny',
+          message: `hook deny (exit ${hookResult.code}): ${hookResult.stderr}`,
+        }
+      }
+      // Hook exited 0 (or missing) → fall through to allow check
+    } catch {
+      // Hook throw → fail-open: fall through to config evaluation
+    }
+  }
+
+  // ── Step 3: Allow check ─────────────────────────────────────────────
+  for (const pattern of config.allow) {
+    if (matchesRule(pattern, tool, args)) {
+      return { allowed: true, reason: 'allow', message: `allowed by rule: ${pattern}` }
+    }
+  }
+
+  // ── Step 4: No match → implicit deny ────────────────────────────────
+  return { allowed: false, reason: 'no_match', message: 'no matching allow rule' }
+}

package/src/pantheon/step-cap.ts

@@ -0,0 +1,110 @@
+/**
+ * R4 — Per-agent step caps (max_steps).
+ *
+ * Pure library. routing.yml `agents.<name>.max_steps` gives each agent a
+ * step budget (e.g. explore: 25, reviewer: 25, oracle: 15). When an agent's
+ * step count reaches max_steps it is forced to summarize-and-stop: the
+ * delegation is either skipped with a capped summary (already at cap) or
+ * the prompt is appended with a stop instruction (cap hit mid-dispatch).
+ *
+ * The tracker is PERMANENT-PER-PROCESS: counters accumulate for the process
+ * lifetime and are intentionally NOT reset on successful delegations or
+ * session end — a per-session reset would let an agent exceed its process
+ * budget over a long session. `reset()` exists as a tested utility for
+ * tests and future explicit reset points; no production caller wires it.
+ *
+ * @module step-cap
+ */
+
+// ─── Types ─────────────────────────────────────────────────────────────
+
+/** Default step budget when routing.yml omits max_steps for an agent. */
+export const DEFAULT_MAX_STEPS = 25
+
+// ─── Stop instruction ──────────────────────────────────────────────────
+
+/**
+ * The forced summarize-and-stop instruction injected into a prompt when an
+ * agent's step count reaches max_steps.
+ */
+export function buildStopInstruction(agent: string, maxSteps: number): string {
+  return (
+    `\n\n[STEP CAP REACHED — ${agent} at ${maxSteps} steps] ` +
+    `You have reached the maximum step budget for this delegation. ` +
+    `STOP working immediately and summarize what was accomplished (and ` +
+    `what remains, if any) as your final message. Do not start new work.`
+  )
+}
+
+/**
+ * The text returned when a delegation is skipped because the agent is
+ * already at its step cap — marks the delegation as capped and asks for a
+ * summary of prior results instead of starting new work.
+ */
+export function cappedSummary(agent: string, maxSteps: number): string {
+  return (
+    `[STEP CAP REACHED] ${agent} has reached its max_steps budget (${maxSteps}). ` +
+    `Delegation skipped — no new work was started. ` +
+    `Summarize prior results and stop.`
+  )
+}
+
+// ─── Tracker ───────────────────────────────────────────────────────────
+
+/**
+ * Per-agent step counters with a max_steps budget. Keyed by lowercase agent
+ * name (matching is case-insensitive). Agents without a configured budget
+ * are never capped.
+ */
+export class StepCapTracker {
+  private readonly steps = new Map<string, number>()
+  readonly maxStepsByAgent: Readonly<Record<string, number>>
+
+  constructor(maxStepsByAgent: Readonly<Record<string, number>> = {}) {
+    this.maxStepsByAgent = maxStepsByAgent
+  }
+
+  /** The configured budget for an agent, or undefined when uncapped. */
+  maxStepsFor(agent: string): number | undefined {
+    return this.maxStepsByAgent[agent.toLowerCase()]
+  }
+
+  /** Current step count for an agent. */
+  stepCount(agent: string): number {
+    return this.steps.get(agent.toLowerCase()) ?? 0
+  }
+
+  /** Whether the agent has reached (or exceeded) its max_steps budget. */
+  isCapped(agent: string): boolean {
+    const max = this.maxStepsFor(agent)
+    if (max === undefined) return false
+    return this.stepCount(agent) >= max
+  }
+
+  /**
+   * Record one step for an agent. Returns the new count and whether this
+   * step hit the cap (capped === true exactly when steps >= maxSteps).
+   */
+  recordStep(agent: string): {
+    steps: number
+    capped: boolean
+    maxSteps: number | undefined
+  } {
+    const key = agent.toLowerCase()
+    const max = this.maxStepsFor(agent)
+    const steps = (this.steps.get(key) ?? 0) + 1
+    this.steps.set(key, steps)
+    return { steps, capped: max !== undefined && steps >= max, maxSteps: max }
+  }
+
+  /**
+   * Reset an agent's step count.
+   *
+   * Intentionally NOT wired in production: the tracker is permanent-per-
+   * process (see module docstring) so agents cannot exceed their process
+   * budget via resets. Exists for tests and future explicit reset points.
+   */
+  reset(agent: string): void {
+    this.steps.delete(agent.toLowerCase())
+  }
+}