pantheon-opencode 1.3.5-beta.60.efa533f → 1.3.6

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/permission-globs.ts

@@ -0,0 +1,86 @@
+/**
+ * O5 — Permission globs for delegation (permission.task model).
+ *
+ * Pure library. Glob patterns control which subagents an agent may invoke
+ * (routing.yml `permission.task`, e.g. `"*": "deny", "orchestrator-*":
+ * "allow"`). Last matching rule wins; a deny removes the agent from the
+ * delegate tool description entirely (not just blocks the call) — this
+ * prevents circular delegation at the permission layer.
+ *
+ * @module permission-globs
+ */
+
+// ─── Types ─────────────────────────────────────────────────────────────
+
+export type PermissionAction = 'allow' | 'deny'
+
+/** Glob pattern → action map (insertion order = rule order). */
+export type PermissionTaskConfig = Readonly<Record<string, PermissionAction>>
+
+// ─── Glob matching ─────────────────────────────────────────────────────
+
+/**
+ * Convert a glob pattern to an anchored RegExp. `*` matches any sequence
+ * (including empty), `?` matches exactly one character; everything else is
+ * literal. The pattern must match the WHOLE agent name.
+ */
+export function globToRegExp(pattern: string): RegExp {
+  const escaped = pattern
+    .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+    .replace(/\*/g, '.*')
+    .replace(/\?/g, '.')
+  return new RegExp(`^${escaped}$`)
+}
+
+/**
+ * Evaluate a permission.task config against an agent name. Iterates rules
+ * in insertion order and keeps the LAST match — last matching rule wins.
+ * Returns undefined when no rule matches.
+ */
+export function matchPermissionRule(
+  rules: PermissionTaskConfig,
+  agentName: string,
+): PermissionAction | undefined {
+  let matched: PermissionAction | undefined
+  for (const [pattern, action] of Object.entries(rules)) {
+    if (globToRegExp(pattern).test(agentName)) matched = action
+  }
+  return matched
+}
+
+/**
+ * Whether an agent may be invoked as a subagent. No rules (or empty) →
+ * allowed (the existing runtime matrix still applies). Otherwise the last
+ * matching rule decides; only an explicit 'allow' permits the agent.
+ */
+export function isAgentAllowed(
+  rules: PermissionTaskConfig | undefined,
+  agentName: string,
+): boolean {
+  if (rules === undefined || Object.keys(rules).length === 0) return true
+  return matchPermissionRule(rules, agentName) === 'allow'
+}
+
+/**
+ * The allowed subset of a candidate agent list — denied agents are removed
+ * entirely (they never appear in the delegate tool description).
+ */
+export function filterAllowedAgents(
+  rules: PermissionTaskConfig | undefined,
+  agentNames: readonly string[],
+): string[] {
+  return agentNames.filter((name) => isAgentAllowed(rules, name))
+}
+
+/**
+ * Render the delegate tool description's allowed-agent list. Denied agents
+ * are removed entirely (not just blocked at call time).
+ */
+export function buildAgentListDescription(
+  rules: PermissionTaskConfig | undefined,
+  agentNames: readonly string[],
+): string {
+  const allowed = filterAllowedAgents(rules, agentNames)
+  if (allowed.length === 0) return 'no subagents available (all denied by permission.task)'
+  return allowed.join(', ')
+}

package/src/pantheon/presets.d.mts

@@ -98,6 +98,47 @@ export declare function loadRoutingAgentModels(
   options?: RoutingAgentModelsOptions,
 ): Record<string, string>
 
+export interface RoutingRetryPolicyOptions {
+  routingPath?: string
+  logger?: { warn?: (msg: string) => void }
+}
+
+/**
+ * R1: per-error-type retry policy from routing.yml `retry_policy`
+ * (auth/rate_limit/timeout/other → max retries). Fail-open → null.
+ */
+export declare function loadRoutingRetryPolicy(
+  options?: RoutingRetryPolicyOptions,
+): Record<string, number> | null
+
+export interface RoutingCooldownResult {
+  allowed_fails: number
+  cooldown_time_seconds: number
+}
+
+/**
+ * R1: provider cooldown config from routing.yml `cooldown`. Fail-open → null.
+ */
+export declare function loadRoutingCooldown(
+  options?: RoutingRetryPolicyOptions,
+): RoutingCooldownResult | null
+
+/**
+ * R4: per-agent step caps from routing.yml `agents.<name>.max_steps`.
+ * Fail-open → {} (no agent capped).
+ */
+export declare function loadRoutingMaxSteps(
+  options?: RoutingRetryPolicyOptions,
+): Record<string, number>
+
+/**
+ * O5: permission.task glob rules from routing.yml `permission.task`
+ * (glob pattern → 'allow' | 'deny'). Fail-open → null.
+ */
+export declare function loadRoutingPermissionTask(
+  options?: RoutingRetryPolicyOptions,
+): Record<string, 'allow' | 'deny'> | null
+
 export declare function resolveActivePreset(options?: ResolveOptions): ResolvedPreset | null
 
 export declare function applyActivePresetToConfig<C extends object>(

package/src/pantheon/presets.mjs

@@ -210,6 +210,140 @@ export function loadPresetDefs(routingPath) {
   return (routing && typeof routing === 'object' && routing.presets) || {}
 }
 
+/**
+ * Load and parse the full routing.yml document (fail-open helper for the
+ * R1/R4/O5 config loaders below).
+ *
+ * @param {string} [routingPath] defaults to src/routing.yml
+ * @returns {object|null} parsed routing.yml, or null when unreadable
+ */
+function loadRoutingYaml(routingPath) {
+  const path = routingPath ?? fileURLToPath(new URL('../routing.yml', import.meta.url))
+  const raw = readFileSync(path, 'utf8')
+  const routing = yaml.load(raw)
+  return routing && typeof routing === 'object' ? routing : null
+}
+
+const RETRY_ERROR_TYPES = new Set(['auth', 'rate_limit', 'timeout', 'other'])
+
+/**
+ * Load the R1 per-error-type retry policy from routing.yml (`retry_policy:`).
+ * Fail-open: missing/unparseable config yields null (the caller falls back
+ * to DEFAULT_RETRY_POLICY) and warns via the optional logger.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.routingPath]
+ * @param {{warn?: Function}} [opts.logger]
+ * @returns {Record<string, number>|null} error-type → max retries
+ */
+export function loadRoutingRetryPolicy({ routingPath, logger = console } = {}) {
+  try {
+    const routing = loadRoutingYaml(routingPath)
+    const policy = routing?.retry_policy
+    if (!policy || typeof policy !== 'object' || Array.isArray(policy)) return null
+    const out = {}
+    for (const [type, max] of Object.entries(policy)) {
+      if (RETRY_ERROR_TYPES.has(type) && Number.isSafeInteger(max) && max >= 0) {
+        out[type] = max
+      }
+    }
+    return Object.keys(out).length > 0 ? out : null
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err)
+    logger.warn?.(`presets: routing.yml retry_policy unavailable (${reason})`)
+    return null
+  }
+}
+
+/**
+ * Load the R1 provider cooldown config from routing.yml (`cooldown:`).
+ * Fail-open: missing/unparseable config yields null (caller falls back to
+ * DEFAULT_COOLDOWN).
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.routingPath]
+ * @param {{warn?: Function}} [opts.logger]
+ * @returns {{allowed_fails: number, cooldown_time_seconds: number}|null}
+ */
+export function loadRoutingCooldown({ routingPath, logger = console } = {}) {
+  try {
+    const routing = loadRoutingYaml(routingPath)
+    const cooldown = routing?.cooldown
+    if (!cooldown || typeof cooldown !== 'object' || Array.isArray(cooldown)) return null
+    const allowedFails = cooldown.allowed_fails
+    const cooldownTimeSeconds = cooldown.cooldown_time_seconds
+    if (
+      !Number.isSafeInteger(allowedFails) ||
+      allowedFails < 1 ||
+      !Number.isSafeInteger(cooldownTimeSeconds) ||
+      cooldownTimeSeconds < 1
+    ) {
+      return null
+    }
+    return { allowed_fails: allowedFails, cooldown_time_seconds: cooldownTimeSeconds }
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err)
+    logger.warn?.(`presets: routing.yml cooldown unavailable (${reason})`)
+    return null
+  }
+}
+
+/**
+ * Load the R4 per-agent step caps from routing.yml
+ * (`agents.<name>.max_steps`). Fail-open: missing config yields {}.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.routingPath]
+ * @param {{warn?: Function}} [opts.logger]
+ * @returns {Record<string, number>} lowercase agent → max_steps
+ */
+export function loadRoutingMaxSteps({ routingPath, logger = console } = {}) {
+  try {
+    const routing = loadRoutingYaml(routingPath)
+    const agents = routing?.agents
+    if (!agents || typeof agents !== 'object') return {}
+    const out = {}
+    for (const [agent, spec] of Object.entries(agents)) {
+      const maxSteps = spec && typeof spec === 'object' ? spec.max_steps : undefined
+      if (Number.isSafeInteger(maxSteps) && maxSteps > 0) {
+        out[agent.toLowerCase()] = maxSteps
+      }
+    }
+    return out
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err)
+    logger.warn?.(`presets: routing.yml max_steps unavailable (${reason})`)
+    return {}
+  }
+}
+
+/**
+ * Load the O5 permission.task glob rules from routing.yml
+ * (`permission.task:`). Fail-open: missing config yields null (caller keeps
+ * the existing runtime matrix, everything allowed).
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.routingPath]
+ * @param {{warn?: Function}} [opts.logger]
+ * @returns {Record<string, 'allow'|'deny'>|null} glob pattern → action
+ */
+export function loadRoutingPermissionTask({ routingPath, logger = console } = {}) {
+  try {
+    const routing = loadRoutingYaml(routingPath)
+    const task = routing?.permission?.task
+    if (!task || typeof task !== 'object' || Array.isArray(task)) return null
+    const out = {}
+    for (const [pattern, action] of Object.entries(task)) {
+      if (action === 'allow' || action === 'deny') out[pattern] = action
+    }
+    return Object.keys(out).length > 0 ? out : null
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err)
+    logger.warn?.(`presets: routing.yml permission.task unavailable (${reason})`)
+    return null
+  }
+}
+
 /**
  * Load the DEFAULT agent → model mapping from routing.yml for the delegation
  * toolset (Fase 6 — wiring agentModels).
@@ -402,6 +536,7 @@ function providerDefKeyConfigured(provider, env) {
  * @returns {string|undefined} missing env var name, or undefined when usable
  */
 export function missingProviderKeyEnv(providerID, { env = process.env, routingPath } = {}) {
+  if (providerID === 'opencode-go') return undefined
   const defs = loadPresetDefs(routingPath)
   for (const def of Object.values(defs)) {
     const provider = def?.providers?.[providerID]