pantheon-opencode 1.4.1 → 1.4.3

package/src/pantheon/permission-eval.ts

@@ -1,284 +0,0 @@
-/**
- * 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

@@ -1,110 +0,0 @@
-/**
- * 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())
-  }
-}