Skip to content

Soul-driven AI agent with permission-hardened tools, token budgets, and multi-channel access. Runs 24/7 from CLI, Telegram or More.

62.3 KB
Raw Blame
import { commandTouchesMercuryCredentials, isMercuryCredentialPath } from '../security/protected-paths.js';
import { ownerApprovedThisCall } from '../security/call-approval.js';
import { existsSync, readFileSync, writeFileSync, mkdirSync, realpathSync, lstatSync } from 'node:fs';
import { join, resolve, sep, dirname, basename } from 'node:path';
import { homedir } from 'node:os';
import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
import { getMercuryHome } from '../utils/config.js';
import { isReadOnlySegment, shellPaths, stripHeredocs } from './shell-paths.js';
import { logger } from '../utils/logger.js';
import { redactSecrets } from '../utils/redact.js';
import { BLOCKED_COMMANDS } from './shell/blocklist.js';
import {
  evaluateArgvPolicy,
  pinnedBinary,
  IN_PROCESS_BUILTINS,
  type BinaryResolver,
} from './shell/argv-lane.js';
import {
  makeContext,
  withChanges,
  permissionContextStore,
  newTurnOverlay,
  TURN_OWNED_FIELDS,
  type PermissionContext,
  type ContextScope,
  type TurnOverlay,
} from './permission-context.js';

/** `ctx` with an internal turn's allow-all grant applied (origin `turn` unless the owner already allowed all). */
function applyTurnGrant(ctx: PermissionContext, grant: { scopes: ContextScope[] } | null): PermissionContext {
  if (!grant) return ctx;
  return withChanges(ctx, {
    autoApprove: true,
    autoApproveOrigin: ctx.autoApprove ? ctx.autoApproveOrigin : 'turn',
    scopes: [...ctx.scopes, ...grant.scopes],
  });
}

import type { McpGateRequest, McpGateResult, McpResourceGateRequest } from './mcp/types.js';
import { MCP_LIST_RESOURCES_TOOL, MCP_READ_RESOURCE_TOOL } from './mcp/naming.js';

export type { PermissionContext } from './permission-context.js';

/** Owner-only approvals must not be answered by a channel's Allow All mode. */
export interface AskOptions {
  alwaysAsk?: boolean;
}

/**
 * Arguments as the owner sees them in an approval prompt. Up to 4,000
 * characters are shown whole. Longer ones keep the start AND the end, with
 * the size of the hidden middle, so a payload can't hide after a cut.
 */
const MCP_ARGS_SHOW_ALL = 4000;
const MCP_ARGS_HEAD = 2400;
const MCP_ARGS_TAIL = 1200;

export function formatMcpArgs(args: unknown): string {
  let text: string;
  try {
    text = JSON.stringify(args ?? {}, null, 2) ?? '{}';
  } catch {
    text = String(args);
  }
  text = redactSecrets(text);
  if (text.length <= MCP_ARGS_SHOW_ALL) return text;
  const hidden = text.length - MCP_ARGS_HEAD - MCP_ARGS_TAIL;
  return `${text.slice(0, MCP_ARGS_HEAD)}\n… [${hidden.toLocaleString('en-US')} characters not shown; the start and end are] …\n${text.slice(-MCP_ARGS_TAIL)}`;
}

/**
 * A shell segment that changes MCP setup: `mercury mcp add|remove|enable|
 * disable|allow|disallow`, or anything that names mercury.yaml (sed -i,
 * tee, cp, mv, echo >>). Reading it is caught too; that only costs a prompt.
 */
export function changesMcpSetup(segment: string): boolean {
  return /\bmcp\s+(add|remove|rm|enable|disable|allow|disallow)\b/.test(segment)
    || /mercury\.ya?ml/i.test(segment);
}

function protectedConfigPaths(): string[] {
  const home = getMercuryHome();
  return [
    join(home, 'mercury.yaml'),
    join(home, 'permissions.yaml'),
    join(home, '.env'),
    join(homedir(), '.mercury', '.env'),
  ];
}

/** Result of a shell permission check. */
export interface ShellCheckResult {
  allowed: boolean;
  reason?: string;
  needsApproval: boolean;
  /**
   * `argv`: auto-approved through the argv lane — the caller must execute
   * it with execFile (see planArgvExecution), never a shell. `shell`:
   * approved through the approval lane (prompt, allow-all, elevation, bot
   * grant) — the exact string the user saw may run through a shell.
   */
  lane?: 'argv' | 'shell';
}

/**
 * Command-pattern glob → anchored, case-insensitive RegExp. `*` matches any
 * text, `?` one character; everything else is literal. Regex metacharacters
 * are escaped so `C:\\*` means "C:\ then anything" (not "C: + any char"),
 * `curl * | sh` is one pattern (not an alternation), and `rm -rf .` matches
 * only a literal dot.
 */
export function globToRegExp(pattern: string): RegExp {
  const source = pattern
    .split(/([*?])/)
    .map((part) => (part === '*' ? '.*' : part === '?' ? '.' : part.replace(/[.+^${}()|[\]\\\/]/g, '\\$&')))
    .join('');
  return new RegExp(`^${source}$`, 'i');
}

export interface FileScope {
  path: string;
  read: boolean;
  write: boolean;
  /**
   * Explicit execute grant (fail-closed bots): shell commands whose path
   * arguments all resolve inside this scope may run. The global
   * blocked-command list always wins; commands without path arguments stay
   * approval-gated.
   */
  execute?: boolean;
}

export interface ShellPermissions {
  enabled: boolean;
  blocked: string[];
  autoApproved: string[];
  needsApproval: string[];
  cwdOnly: boolean;
}

export interface FsPermissions {
  enabled: boolean;
  scopes: FileScope[];
}

export interface GitPermissions {
  enabled: boolean;
  autoApproveRead: boolean;
  approveWrite: boolean;
}

export interface PermissionsManifest {
  capabilities: {
    filesystem: FsPermissions;
    shell: ShellPermissions;
    git: GitPermissions;
    /** Installed-browser read-only rendering is opt-in; no engine is bundled. */
    browser?: { enabled: boolean; executable?: string };
  };
}

/** Device/inode pair identifying the file a read was authorised against. */
export interface FileIdentity {
  dev: number;
  ino: number;
}

export interface FsAccessResult {
  allowed: boolean;
  reason?: string;
  /**
   * Why a read was refused: `symlink-escape` (the canonical target lies
   * outside every readable scope), `hardlink` (nlink > 1 and no approval),
   * or `denied` (ordinary scope/user denial).
   */
  code?: 'symlink-escape' | 'hardlink' | 'denied';
  /**
   * Reads only: the canonical (realpath) target the check was made against.
   * Tools must open THIS path, never the lexical one, so a symlink swapped in
   * after the check cannot redirect the read.
   */
  canonical?: string;
  /**
   * Reads of existing files only: lstat identity of `canonical` at check
   * time. Tools compare it with `fstat` on the opened descriptor to defeat a
   * swap between check and open (TOCTOU).
   */
  fileId?: FileIdentity;
}

const DEFAULT_MANIFEST: PermissionsManifest = {
  capabilities: {
    filesystem: {
      enabled: true,
      scopes: [
        { path: '.', read: true, write: true },
      ],
    },
    shell: {
      enabled: true,
      // Single source of truth: shell/blocklist.ts (also carries the
      // PowerShell forms — Set-ExecutionPolicy, Remove-Item -Recurse roots).
      blocked: [...BLOCKED_COMMANDS],
      autoApproved: [
        'ls *',
        'cat *',
        'pwd',
        'which *',
        'node *',
        'npm run *',
        'npm test *',
        'npm list *',
        'git status *',
        'git diff *',
        'git log *',
        'git branch *',
        'echo *',
        'head *',
        'tail *',
        'wc *',
        'find *',
        'grep *',
        'rg *',
        'ps *',
        'df *',
        'du *',
        'uname *',
        'curl *',
        'wget *',
        'dir *',
        'type *',
        'cd *',
        'where *',
        'tree *',
        'findstr *',
        'tasklist *',
        'systeminfo *',
      ],
      needsApproval: [
        'npm publish *',
        'git push *',
        'docker *',
        'curl * | sh',
        'curl * | bash',
        'wget * | sh',
        'pip install *',
        'pip3 install *',
        'rm -r *',
        'rm -rf *',
        'mv *',
        'cp -r *',
        'chmod *',
        'mkdir *',
        'rmdir *',
        'xcopy *',
        'robocopy *',
        'del *',
        'rd /s *',
        'powershell *',
        'cmd /c *',
      ],
      cwdOnly: true,
    },
    git: {
      enabled: true,
      autoApproveRead: true,
      approveWrite: true,
    },
  },
};

/** Where the owner's permissions live. Looked up each time: MERCURY_HOME can change after this module loads (tests, a profile switch), and the folder is created from the current one. */
function permissionsFile(): string {
  return join(getMercuryHome(), 'permissions.yaml');
}

// Split a command into shell-segment strings so each pipeline/chain/substitution
// is checked separately. Without this, a single auto-approved base command
// (e.g. "echo *") would auto-approve the entire string including chained
// or substituted destructive commands like `echo $(rm -rf ~)` or `ls; reboot`.
// We are deliberately conservative: any segment we cannot fully decompose
// is returned as-is so the regular pattern checks decide its fate.
export function splitShellSegments(command: string): string[] {
  const out: string[] = [];
  let buf = '';
  let i = 0;
  let single = false;
  let double = false;
  let backtick = false;

  const flush = () => {
    const seg = buf.trim();
    if (seg.length > 0) out.push(seg);
    buf = '';
  };

  while (i < command.length) {
    const ch = command[i];
    const next = command[i + 1];

    if (single) {
      buf += ch;
      if (ch === "'") single = false;
      i++;
      continue;
    }
    if (double) {
      if (ch === '\\' && next !== undefined) {
        buf += ch + next;
        i += 2;
        continue;
      }
      if (ch === '"') {
        buf += ch;
        double = false;
        i++;
        continue;
      }
      // Inside double quotes, bash still expands $(...) and `...` —
      // pull them out as their own segments so a covering "echo *" can't
      // launder a substituted destructive command.
      if (ch === '$' && next === '(') {
        i += 2;
        let depth = 1;
        let inner = '';
        while (i < command.length && depth > 0) {
          const c = command[i];
          if (c === '(') depth++;
          else if (c === ')') { depth--; if (depth === 0) break; }
          inner += c;
          i++;
        }
        i++;
        for (const seg of splitShellSegments(inner)) out.push(seg);
        continue;
      }
      if (ch === '`') {
        i++;
        let inner = '';
        while (i < command.length && command[i] !== '`') {
          inner += command[i];
          i++;
        }
        i++;
        for (const seg of splitShellSegments(inner)) out.push(seg);
        continue;
      }
      buf += ch;
      i++;
      continue;
    }
    if (backtick) {
      if (ch === '`') {
        backtick = false;
        if (buf.trim().length > 0) {
          for (const inner of splitShellSegments(buf)) out.push(inner);
          buf = '';
        }
        i++;
        continue;
      }
      buf += ch;
      i++;
      continue;
    }

    if (ch === "'") { single = true; buf += ch; i++; continue; }
    if (ch === '"') { double = true; buf += ch; i++; continue; }
    if (ch === '`') {
      flush();
      backtick = true;
      i++;
      continue;
    }

    if (ch === '$' && next === '(') {
      flush();
      i += 2;
      let depth = 1;
      let inner = '';
      while (i < command.length && depth > 0) {
        const c = command[i];
        if (c === '(') depth++;
        else if (c === ')') { depth--; if (depth === 0) break; }
        inner += c;
        i++;
      }
      i++;
      for (const seg of splitShellSegments(inner)) out.push(seg);
      continue;
    }

    // Subshell ( ... ) and brace block { ... ; } both execute their contents,
    // so treat the boundaries as segment breaks rather than opaque text.
    if (ch === '(' || ch === ')' || ch === '{' || ch === '}') { flush(); i++; continue; }

    if (ch === ';' || ch === '\n') { flush(); i++; continue; }
    if (ch === '|' && next === '|') { flush(); i += 2; continue; }
    if (ch === '&' && next === '&') { flush(); i += 2; continue; }
    if (ch === '|') { flush(); i++; continue; }
    if (ch === '&') { flush(); i++; continue; }

    buf += ch;
    i++;
  }

  flush();
  if (out.length === 0) out.push(command.trim());
  return out;
}

export class PermissionManager {
  private manifest: PermissionsManifest;
  private readonly cwd: string;
  private askHandler?: (prompt: string, options?: AskOptions) => Promise<string>;
  private approvedMcpResourcesByContext = new Map<string, Set<string>>();
  private turnAnswers: Array<{ action: string; answer: 'yes' | 'no' | 'always' }> = [];
  /**
   * The main agent's (root) context: replaced, never mutated, by the
   * legacy setters below. Sub-agents never read it while they run — they
   * carry their own context through AsyncLocalStorage (`withContext`).
   */
  private session: PermissionContext = makeContext();
  /** Grant of the internal turn in progress (agent.ts), layered over `session`. */
  private turnGrant: { scopes: ContextScope[] } | null = null;
  private rootCache: PermissionContext | null = null;
  private binaryResolver: BinaryResolver = pinnedBinary;
  private approvedCommandsByContext = new Map<string, Set<string>>();
  /** "Always" on a shell prompt: command families (`pandoc`, `git commit`) allowed for the rest of that chat. */
  private approvedFamiliesByContext = new Map<string, Set<string>>();
  /**
   * Which contexts may widen "Always" to a command family. Default: only the
   * local terminal. The runtime also allows the owner's attached terminal and
   * dashboard (web, but not remote Mercury Cloud requests, which stay exact).
   */
  private familyApprovalAllowed: (ctx: { channelType: string; channelId: string }) => boolean = (ctx) => ctx.channelType === 'cli';

  setFamilyApprovalPolicy(fn: (ctx: { channelType: string; channelId: string }) => boolean): void {
    this.familyApprovalAllowed = fn;
  }
  /** "Always allow" choices for plugin tools, per channel (see approvePluginTool). */
  private approvedPluginToolsByContext = new Map<string, Set<string>>();
  private approvedWritesByContext = new Map<string, Set<string>>();
  private approvedMcpByContext = new Map<string, Set<string>>();
  /** Hard-linked files the user answered "always" for, per interaction context. */
  private approvedHardlinkReadsByContext = new Map<string, Set<string>>();
  /**
   * Fail-closed mode (unattended agents, e.g. Mercury Bots): no interactive
   * approvals exist. Explicitly granted scopes apply without prompting;
   * everything else denies. Never combined with autoApproveAll.
   */
  private failClosed = false;

  /**
   * Bot-scoped shell allow-list (fail-closed runtimes): patterns the bot's
   * permissions.yaml explicitly granted. Kept separate from the manifest's
   * autoApproved so an ambient global list (e.g. a user-approved "node *")
   * can never silently elevate an unattended context.
   */
  private botShellAllowList?: string[];

  constructor() {
    this.cwd = process.cwd();
    this.manifest = this.load();
  }

  setFailClosed(value: boolean): void {
    this.failClosed = value;
  }

  /**
   * Bot-only shell allow-list (fail-closed contexts): explicit grants from
   * the bot's permissions.yaml. A literal "*" is dropped — allow-all is an
   * interactive-mode concept, not a bot grant.
   */
  setBotShellAllowList(patterns: string[]): void {
    this.botShellAllowList = (patterns ?? [])
      .map(p => p.trim())
      .filter(p => p.length > 0 && p !== '*');
  }

  getBotShellAllowList(): string[] {
    return [...(this.botShellAllowList ?? [])];
  }

  isFailClosed(): boolean {
    return this.failClosed;
  }

  // ─── Permission context (ADR-016) ─────────────────────────────────────────

  /**
   * The context of the agent whose code is running: a sub-agent's own
   * context inside `withContext`, otherwise the main agent's root context
   * (session plus any internal-turn grant).
   */
  currentContext(): PermissionContext {
    const cell = permissionContextStore.getStore();
    if (cell && cell.owner === this) return cell.turn ? this.turnContext(cell.turn) : cell.ctx;
    return this.rootContext();
  }

  private rootContext(): PermissionContext {
    if (this.rootCache) return this.rootCache;
    const ctx = applyTurnGrant(this.session, this.turnGrant);
    this.rootCache = ctx;
    return ctx;
  }

  /** A concurrent turn's view: the live session with the turn's own identity and grant over it. */
  private turnContext(turn: TurnOverlay): PermissionContext {
    if (turn.cache && turn.cache.session === this.session) return turn.cache.ctx;
    const ctx = applyTurnGrant(withChanges(this.session, turn.fields), turn.grant);
    turn.cache = { session: this.session, ctx };
    return ctx;
  }

  /** The calling code's turn overlay, when it runs in a main-agent turn of this manager. */
  private currentTurn(): TurnOverlay | null {
    const cell = permissionContextStore.getStore();
    return cell && cell.owner === this && cell.turn ? cell.turn : null;
  }

  /**
   * Run one main-agent turn (and everything it awaits or spawns) with its
   * own identity, elevation, internal grant and plugin grants (ADR-037), so
   * concurrent turns never see each other's. Sub-agents started inside get
   * their own context as before (`withContext`).
   */
  withTurn<T>(fn: () => T): T {
    return permissionContextStore.run({ owner: this, ctx: this.session, turn: newTurnOverlay() }, fn);
  }

  private ctx(): PermissionContext {
    return this.currentContext();
  }

  /**
   * Replace the calling agent's context: its ALS cell when it is a
   * sub-agent, otherwise the root session. The patch is computed from that
   * base (never from the merged root, so a turn grant is not baked into
   * the session).
   */
  private updateContext(patch: (base: PermissionContext) => Partial<PermissionContext>): void {
    const cell = permissionContextStore.getStore();
    if (cell && cell.owner === this && cell.turn) {
      // A concurrent turn: identity/elevation stay with the turn; everything
      // else (Allow All, scopes the owner approved) is the shared session's,
      // exactly as it was with one turn at a time. The base never includes
      // the turn grant, so a grant is never baked into the session.
      const turn = cell.turn;
      const changes = patch(withChanges(this.session, turn.fields));
      const shared: Partial<PermissionContext> = {};
      for (const [key, value] of Object.entries(changes) as Array<[keyof PermissionContext, unknown]>) {
        if ((TURN_OWNED_FIELDS as readonly string[]).includes(key)) (turn.fields as Record<string, unknown>)[key] = value;
        else (shared as Record<string, unknown>)[key] = value;
      }
      if (Object.keys(shared).length > 0) {
        this.session = withChanges(this.session, shared);
        this.rootCache = null;
      }
      turn.cache = null;
      return;
    }
    if (cell && cell.owner === this) {
      cell.ctx = withChanges(cell.ctx, patch(cell.ctx));
      return;
    }
    this.session = withChanges(this.session, patch(this.session));
    this.rootCache = null;
  }

  /**
   * Run `fn` (and everything it awaits or schedules) under `ctx`. Used for
   * sub-agents; their tools resolve permissions against `ctx` even while
   * the main agent's root context changes concurrently.
   */
  withContext<T>(ctx: PermissionContext, fn: () => T): T {
    return permissionContextStore.run({ owner: this, ctx: Object.isFrozen(ctx) ? ctx : makeContext(ctx) }, fn);
  }

  /**
   * Start the grant of one internal (scheduled/background) turn on the
   * root context: allow-all plus `scopes`, origin `turn`. Not visible to
   * sub-agents already running, and not inherited by ones spawned during
   * the turn. `endTurnGrant()` removes it and leaves the session (e.g. a
   * user's Allow All) untouched.
   */
  beginTurnGrant(grant: { scopes?: Array<{ path: string; read: boolean; write: boolean }> } = {}): void {
    const next = { scopes: (grant.scopes ?? []).map((s) => ({ ...s, path: resolve(s.path) })) };
    const turn = this.currentTurn();
    if (turn) {
      turn.grant = next;
      turn.cache = null;
      return;
    }
    this.turnGrant = next;
    this.rootCache = null;
  }

  endTurnGrant(): void {
    const turn = this.currentTurn();
    if (turn) {
      turn.grant = null;
      turn.cache = null;
      return;
    }
    this.turnGrant = null;
    this.rootCache = null;
  }

  /** Test hook: resolve argv-lane binaries with `resolver` instead of the pinned table. */
  setBinaryResolver(resolver: BinaryResolver): void {
    this.binaryResolver = resolver;
  }

  // ─── Legacy setters (shims over the context) ──────────────────────────────

  setCurrentChannelType(type: string): void {
    this.updateContext(() => ({ channelType: type }));
  }

  setCurrentContext(type: string, id: string, sessionId?: string): void {
    this.updateContext(() => ({ channelType: type, channelId: id, sessionId }));
  }

  getCurrentChannelType(): string {
    return this.ctx().channelType;
  }

  getCurrentChannelId(): string {
    return this.ctx().channelId;
  }

  setCurrentSenderRole(role: 'admin' | 'member' | undefined): void {
    this.updateContext(() => ({ senderRole: role }));
  }

  getCurrentSenderRole(): 'admin' | 'member' | undefined {
    return this.ctx().senderRole;
  }

  /** Someone can be asked in this context (a bot's runtime routes it to the owner). */
  canAsk(): boolean {
    return this.askHandler !== null && this.askHandler !== undefined;
  }

  onAsk(handler: (prompt: string, options?: AskOptions) => Promise<string>): void {
    // Every answer the owner gives is evidence for the Owner Model (autonomy,
    // risk per action type); the learning loop drains it once per turn.
    this.askHandler = async (prompt: string, options?: AskOptions) => {
      // The owner already said yes to this very call at the injection guard
      // (ADR-044): the tool's own approval doesn't ask a second time.
      if (ownerApprovedThisCall()) return 'yes';
      const answer = await (options ? handler(prompt, options) : handler(prompt));
      if (answer === 'yes' || answer === 'no' || answer === 'always') {
        const action = prompt.split('\n')[0].replace(/:.*$/, '').trim().slice(0, 40) || 'action';
        this.turnAnswers.push({ action, answer });
        if (this.turnAnswers.length > 20) this.turnAnswers.shift();
      }
      return answer;
    };
  }

  /** Permission answers given since the last drain (the learning loop reads them each turn). */
  drainAnswers(): Array<{ action: string; answer: 'yes' | 'no' | 'always' }> {
    const out = this.turnAnswers;
    this.turnAnswers = [];
    return out;
  }

  async requestApproval(prompt: string, options?: AskOptions): Promise<boolean> {
    const ctx = this.ctx();
    // No one can answer on the internal channel: only an allow-all context
    // (the internal turn's own grant) approves; a child of it does not.
    if (ctx.channelType === 'internal') return ctx.autoApprove;
    if (!this.askHandler) return false;
    const result = await (options ? this.askHandler(prompt, options) : this.askHandler(prompt));
    return result === 'yes' || result === 'always';
  }

  /**
   * Approval for a plugin tool call (src/plugins). Same rules as the shell
   * approval lane:
   * - fail-closed (bots): the tool already passed the bot's explicit
   *   permissions.yaml allow list (filterBotTools), so it runs; there is no
   *   one to ask and no prompt mid-run.
   * - internal/scheduled turns: only an allow-all context approves.
   * - session Allow All approves, except web requests (never inherit local).
   * - "always" is remembered per channel for this plugin tool.
   * - otherwise the user sees the plugin, tool and arguments.
   */
  /** Plugin tools pre-approved for the current turn only (a scheduled task's allowTools). */
  private turnPluginGrants = new Set<string>();

  /** Did the owner pre-approve this plugin tool for the current turn (a scheduled task's allowTools)? */
  hasTurnPluginGrant(toolKey: string): boolean {
    return (this.currentTurn()?.pluginGrants ?? this.turnPluginGrants).has(toolKey);
  }

  setTurnPluginGrants(tools: string[]): void {
    const turn = this.currentTurn();
    if (turn) turn.pluginGrants = new Set(tools);
    else this.turnPluginGrants = new Set(tools);
  }

  async approvePluginTool(toolKey: string, prompt: string): Promise<boolean> {
    const ctx = this.ctx();
    if (this.failClosed) return true;
    if ((this.currentTurn()?.pluginGrants ?? this.turnPluginGrants).has(toolKey)) return true;
    if (ctx.channelType === 'internal') return ctx.autoApprove;
    if (this.isGlobalAutoApproveActive()) return true;
    if (this.approvedPluginToolsByContext.get(ctx.channelId)?.has(toolKey)) return true;
    if (!this.askHandler) return false;
    const result = await this.askHandler(prompt);
    if (result === 'always') {
      const approved = this.approvedPluginToolsByContext.get(ctx.channelId) ?? new Set<string>();
      approved.add(toolKey);
      this.approvedPluginToolsByContext.set(ctx.channelId, approved);
      return true;
    }
    return result === 'yes';
  }

  /** Session-level Allow All (user choice). Inside a sub-agent it only changes that sub-agent. */
  setAutoApproveAll(value: boolean): void {
    this.updateContext(() => ({ autoApprove: value, autoApproveOrigin: value ? 'session' : null }));
  }

  isAutoApproveAll(): boolean {
    return this.ctx().autoApprove;
  }

  private isGlobalAutoApproveActive(): boolean {
    // Web/Cloud grants are resolved per session by WebChannel; a Local CLI
    // allow-all setting must never silently elevate remote requests.
    const ctx = this.ctx();
    return ctx.autoApprove && ctx.channelType !== 'web';
  }

  elevateForSkill(allowedTools: string[]): void {
    // Fail-closed mode (bots): skill elevation must never widen the granted
    // scopes — elevation is checked BEFORE the fail-closed gates in
    // checkFsAccess/checkShellCommand, so honoring it here would hand any
    // skill with allowed-tools an unrestricted bypass. Skills guide; they do
    // not re-permission.
    if (this.failClosed) {
      logger.info({ allowedTools }, 'Skill elevation ignored in fail-closed mode (granted scopes rule)');
      return;
    }
    const grants: string[] = [];
    if (allowedTools.includes('run_command')) grants.push('run_command');
    if (allowedTools.includes('read_file') || allowedTools.includes('list_dir')) grants.push('fs_read');
    if (allowedTools.includes('write_file') || allowedTools.includes('create_file') || allowedTools.includes('delete_file')) {
      grants.push('fs_write');
    }
    if (grants.length === 0) return;
    // Elevation lands on the calling agent's own context only.
    this.updateContext((base) => ({ elevated: [...new Set([...base.elevated, ...grants])] }));
  }

  clearElevation(): void {
    if (this.ctx().elevated.length === 0) return;
    this.updateContext(() => ({ elevated: [] }));
  }

  isElevated(tool: string): boolean {
    return this.ctx().elevated.includes(tool);
  }

  isShellElevated(): boolean {
    return this.isElevated('run_command');
  }

  private load(): PermissionsManifest {
    if (existsSync(permissionsFile())) {
      try {
        const raw = readFileSync(permissionsFile(), 'utf-8');
        const parsed = parseYaml(raw) as PermissionsManifest;
        return this.mergeDefaults(parsed);
      } catch (err) {
        logger.warn({ err }, 'Failed to parse permissions.yaml, using defaults');
        return { ...DEFAULT_MANIFEST };
      }
    }
    this.save(DEFAULT_MANIFEST);
    return { ...DEFAULT_MANIFEST };
  }

  save(manifest?: PermissionsManifest): void {
    const m = manifest || this.manifest;
    const dir = getMercuryHome();
    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
    writeFileSync(permissionsFile(), stringifyYaml(m, { lineWidth: 0 }), 'utf-8');
    this.manifest = m;
  }

  getManifest(): PermissionsManifest {
    return this.manifest;
  }

  addApprovedCommand(baseCommand: string): void {
    const cmdName = baseCommand.trim().split(/\s+/)[0];
    const pattern = `${cmdName} *`;
    const shell = this.manifest.capabilities.shell;
    if (!shell.autoApproved.includes(pattern) && !shell.autoApproved.includes(cmdName)) {
      shell.autoApproved.push(pattern);
      this.save();
      logger.info({ pattern }, 'Shell command pattern auto-approved and saved');
    }
  }

  /**
   * Authorise a filesystem access. Writes: the lexical path must sit in a
   * writable scope and its canonical target must not escape (#105). Reads:
   * the same two conditions against readable scopes (an in-scope symlink to
   * `~/.ssh/id_rsa` is denied), plus a hard-link alias prompt (#104) and a
   * `canonical` + `fileId` the caller must verify at open time.
   *
   * Cost per read: one `realpath` and one `lstat`; nothing is cached across
   * calls, because the file system can change between them.
   */
  async checkFsAccess(path: string, mode: 'read' | 'write'): Promise<FsAccessResult> {
    // Mercury's login credentials are off limits to its own tools, whatever the scopes or mode.
    if (isMercuryCredentialPath(path)) {
      return { allowed: false, reason: "Permission denied: that is one of Mercury's login credential files (device tokens, password, sessions). Manage devices with /server.", code: 'denied' };
    }
    if (mode === 'write') return this.checkScopedAccess(path, mode);

    const resolved = resolve(path);
    const canonical = this.canonicalizePath(resolved);

    // Skill elevation is an explicit "read anywhere" grant, so neither the
    // scope checks nor the alias prompt apply — but the caller still gets the
    // canonical path and identity so the open is verified like any other.
    if (this.isElevated('fs_read')) {
      return this.describeRead(canonical).result;
    }

    const fs = this.manifest.capabilities.filesystem;
    if (!fs.enabled) {
      return { allowed: false, reason: 'Filesystem capability is disabled', code: 'denied' };
    }

    const lexicallyReadable = this.isLexicallyReadable(resolved);
    if (lexicallyReadable && canonical !== resolved && !this.isWithinScope(canonical, 'read')) {
      // The lexical path is approved but it is a symlink (or sits under one)
      // whose target is not. Treat it exactly like a read of the target: ask
      // the user for the target when a prompt is possible, otherwise deny —
      // the model is told the canonical path so it can request that scope.
      const reason = `Permission denied: read of ${path} resolves outside the approved scopes (${canonical})`;
      if (!this.failClosed && !this.isGlobalAutoApproveActive() && this.askHandler && this.ctx().channelType !== 'internal') {
        const granted = await this.requestScopeExternal(canonical, 'read');
        if (!granted.allowed) return { allowed: false, reason, code: 'symlink-escape', canonical };
      } else {
        return { allowed: false, reason, code: 'symlink-escape', canonical };
      }
    } else if (!lexicallyReadable) {
      const scoped = await this.checkScopedAccess(path, mode);
      if (!scoped.allowed) return { ...scoped, code: 'denied', canonical };
      // A freshly approved scope covers the lexical path; the canonical
      // target must be covered too (an approval for a directory of symlinks
      // must not reach through them).
      if (canonical !== resolved && !this.isWithinScope(canonical, 'read')) {
        return {
          allowed: false,
          reason: `Permission denied: read of ${path} resolves outside the approved scopes (${canonical})`,
          code: 'symlink-escape',
          canonical,
        };
      }
    }

    return this.finishRead(path, canonical);
  }

  /** Lexical read check against the manifest and temp scopes. */
  private isLexicallyReadable(resolved: string): boolean {
    const scope = this.findScope(resolved);
    if (scope && scope.read) return true;
    const tempScope = this.findTempScope(resolved);
    return tempScope?.read === true;
  }

  /**
   * Post-scope read checks on the canonical target: a regular file with more
   * than one hard link may be an alias of a file outside every scope (the
   * inode carries no path, so the scope check cannot tell), so it goes
   * through the approval handler and is denied when nothing can ask (#104).
   */
  private async finishRead(path: string, canonical: string): Promise<FsAccessResult> {
    const described = this.describeRead(canonical);
    const nlink = described.nlink;
    if (nlink === undefined || nlink <= 1 || this.isGlobalAutoApproveActive()) return described.result;

    const channelId = this.ctx().channelId;
    const approvedAliases = this.approvedHardlinkReadsByContext.get(channelId);
    if (approvedAliases?.has(canonical)) return described.result;

    const reason = `Permission denied for read access to ${path}: the file has ${nlink} hard links and may alias a file outside the approved scopes`;
    if (this.failClosed || !this.askHandler || this.ctx().channelType === 'internal') {
      return { allowed: false, reason, code: 'hardlink', canonical };
    }
    const response = await this.askHandler(
      `Read hard-linked file: ${canonical}\n(${nlink} links — it may be an alias of a file outside the approved scopes)`,
    );
    if (response === 'always') {
      const approved = approvedAliases ?? new Set<string>();
      approved.add(canonical);
      this.approvedHardlinkReadsByContext.set(channelId, approved);
      return described.result;
    }
    if (response === 'yes') return described.result;
    return { allowed: false, reason: `User denied read of hard-linked file ${path}`, code: 'hardlink', canonical };
  }

  /** One lstat on the canonical target: identity for the open-time check plus the link count. */
  private describeRead(canonical: string): { result: FsAccessResult; nlink?: number } {
    try {
      const st = lstatSync(canonical);
      return {
        result: { allowed: true, canonical, fileId: { dev: st.dev, ino: st.ino } },
        nlink: st.isFile() ? st.nlink : undefined,
      };
    } catch {
      // Missing file: the tool reports "not found" itself.
      return { result: { allowed: true, canonical } };
    }
  }

  private async checkScopedAccess(path: string, mode: 'read' | 'write'): Promise<FsAccessResult> {
    if (mode === 'write' && this.isProtectedConfigPath(path)) {
      return this.confirmConfigWrite(path);
    }
    if (mode === 'read' && this.isElevated('fs_read')) {
      return { allowed: true };
    }
    if (mode === 'write' && this.isElevated('fs_write')) {
      return { allowed: true };
    }

    const fs = this.manifest.capabilities.filesystem;
    if (!fs.enabled) {
      return { allowed: false, reason: 'Filesystem capability is disabled' };
    }

    const resolved = resolve(path);
    const scope = this.findScope(resolved);
    const tempScope = this.findTempScope(resolved);

    // A path that is lexically inside a scope can still leave it through a
    // symlink, because Node follows symlinks at the write sink. Reject writes
    // whose canonicalised target falls outside every writable scope.
    if (mode === 'write') {
      const canonical = this.canonicalizePath(resolved);
      if (canonical !== resolved && !this.isWithinScope(canonical, 'write')) {
        return {
          allowed: false,
          reason: `Permission denied: write to ${path} resolves outside the approved scopes (${canonical})`,
        };
      }
    }

    // Read access: allow if any scope covers it (reads are safe in any mode)
    if (mode === 'read') {
      if (scope && scope.read) return { allowed: true };
      if (tempScope && tempScope.read) return { allowed: true };
    }

    // Write access: in auto-approve-all mode, allow if scope covers it
    const channelId = this.ctx().channelId;
    const channelType = this.ctx().channelType;
    const contextWriteApproved = this.approvedWritesByContext.get(channelId)?.has(resolved) === true;
    if (mode === 'write' && (this.isGlobalAutoApproveActive() || contextWriteApproved)) {
      if (scope && scope.write) return { allowed: true };
      if (tempScope && tempScope.write) return { allowed: true };
    }

    // Fail-closed mode (bots): the explicitly granted scope IS the approval —
    // in-scope access runs without prompting. Outside it, a bot whose runtime
    // set an ask handler (Bots 2.0) asks the owner, who may not be there: the
    // handler answers "no" when nobody replies in time, and the access denies.
    // Nothing here ever writes the global permissions file.
    if (this.failClosed) {
      if (scope && scope.write) return { allowed: true };
      if (tempScope && tempScope.write) return { allowed: true };
      if (this.askHandler && channelType === 'bot' && !this.isProtectedConfigPath(path)) {
        const answer = await this.askHandler(`${mode === 'write' ? 'Write to file' : 'Read file'}: ${resolved}`);
        if (answer === 'yes' || answer === 'always') {
          // Covers the rest of this run; "always" is made durable by the bot runtime.
          this.addTempScope(resolved, true, mode === 'write');
          return { allowed: true };
        }
        return { allowed: false, reason: `The owner didn't allow ${mode === 'write' ? 'writing' : 'reading'} ${path}` };
      }
      return { allowed: false, reason: `Fail-closed: no granted ${mode} scope covers ${path}` };
    }

    // Write access in ask-me mode: ALWAYS prompt the user, even if scope exists
    if (mode === 'write' && !this.isGlobalAutoApproveActive() && this.askHandler && channelType !== 'internal') {
      const scopeAllows = (scope && scope.write) || (tempScope && tempScope.write);
      if (scopeAllows) {
        // Scope allows it, but user wants to confirm — prompt with file path
        const result = await this.askHandler(`Write to file: ${resolved}`);
        if (result === 'yes') return { allowed: true };
        if (result === 'always') {
          const approved = this.approvedWritesByContext.get(channelId) ?? new Set<string>();
          approved.add(resolved);
          this.approvedWritesByContext.set(channelId, approved);
          return { allowed: true };
        }
        return { allowed: false, reason: `User denied write to ${path}` };
      }
      // No scope covers it — request scope expansion
      return this.requestScopeExternal(path, mode);
    }

    // No scope matched — deny or ask
    if (scope) {
      return { allowed: false, reason: `Permission denied: ${mode} access to ${path} (scope has ${mode}=false)` };
    }
    if (tempScope) {
      return { allowed: false, reason: `Permission denied: ${mode} access to ${path}` };
    }

    if (!this.isGlobalAutoApproveActive() && this.askHandler && channelType !== 'internal') {
      return this.requestScopeExternal(path, mode);
    }

    return { allowed: false, reason: `Permission denied for ${mode} access to ${path}` };
  }

  /**
   * Shell permission check. Two lanes (ADR-016):
   *
   * - **argv lane** (no prompt): the command tokenises into argv with no
   *   shell syntax, `argv[0]` is allowlisted, its flags pass the per-command
   *   policy, and every path argument stays inside the cwd or a readable
   *   scope. The caller executes it with execFile from the pinned PATH.
   * - **approval lane**: everything else, including pipelines and chains.
   *   The user sees the exact string; once approved it may use a shell.
   *
   * Hard blocks win over both, and Allow All / skill elevation / an
   * "always" answer / a bot allow-list grant approve through the approval
   * lane without prompting.
   */
  async checkShellCommand(command: string, options: { cwd?: string } = {}): Promise<ShellCheckResult> {
    const shell = this.manifest.capabilities.shell;
    if (!shell.enabled) {
      return { allowed: false, reason: 'Shell capability is disabled', needsApproval: false };
    }

    const trimmed = command.trim();
    if (commandTouchesMercuryCredentials(trimmed)) {
      return { allowed: false, reason: "Blocked: the command names one of Mercury's login credential files (device tokens, password, sessions). Manage devices with /server.", needsApproval: false };
    }
    const segments = splitShellSegments(trimmed);
    const ctx = this.ctx();
    const cwd = options.cwd ?? this.cwd;

    // Always block dangerous commands — check each segment so an
    // auto-approved base command can't launder a chained destructive one
    // (e.g. `echo *; rm -rf ~`).
    for (const segment of segments) {
      for (const pattern of shell.blocked) {
        if (this.matchPattern(segment, pattern)) {
          return { allowed: false, reason: `Blocked command: matches "${pattern}"`, needsApproval: false };
        }
      }
    }

    // Adding or changing an MCP server is an owner action (ADR-029): a shell
    // command that does it asks every time, Allow All and earlier "always"
    // answers included, and never runs unattended. Otherwise an injected
    // prompt could add a server whose autoApprove tools then run in
    // scheduled turns.
    if (segments.some(changesMcpSetup)) {
      if (!this.askHandler || ctx.channelType === 'internal' || this.failClosed) {
        return { allowed: false, reason: 'Changing MCP servers or mercury.yaml from a shell command needs the owner; run it yourself in a terminal', needsApproval: false };
      }
      const answer = await this.askOwner(`Run command (changes Mercury's MCP servers or config, so it always asks): ${trimmed}`);
      return answer === 'yes' || answer === 'always'
        ? { allowed: true, needsApproval: false, lane: 'shell' }
        : { allowed: false, reason: `User denied: ${trimmed}`, needsApproval: false };
    }

    if (this.isGlobalAutoApproveActive()) {
      logger.info({ cmd: trimmed }, 'Shell command auto-approved (Local allow-all mode)');
      return { allowed: true, needsApproval: false, lane: 'shell' };
    }

    if (this.isShellElevated()) {
      logger.info({ cmd: trimmed }, 'Shell command auto-approved (skill elevation)');
      return { allowed: true, needsApproval: false, lane: 'shell' };
    }

    if (this.approvedCommandsByContext.get(ctx.channelId)?.has(trimmed)) {
      logger.info({ cmd: trimmed }, 'Shell command auto-approved for this interaction context');
      return { allowed: true, needsApproval: false, lane: 'shell' };
    }

    if (shell.cwdOnly) {
      // The files the command touches, read as the shell reads it (shell-paths.ts):
      // heredoc bodies are data, quotes are honoured, /dev/null is not a file,
      // and `ls dir` is a read, not a write.
      for (const segment of splitShellSegments(stripHeredocs(trimmed))) {
        for (const { path: raw, mode } of shellPaths(segment)) {
          const target = resolve(cwd, raw.replace(/^~(?=\/|$)/, homedir()));
          if (target.startsWith(this.cwd)) continue;
          const scopeCheck = await this.checkFsAccess(target, mode);
          if (!scopeCheck.allowed && !this.isExecuteScoped(target)) {
            return { allowed: false, reason: `No permission to ${mode} ${target}. Use approve_scope tool with path="${target}" and mode="${mode}" to request access.`, needsApproval: false };
          }
        }
      }
    }

    // Bot allow-list (fail-closed only): set explicitly by the bot runtime
    // (registry-factory from permissions.yaml autoApproveCommands) — never
    // the ambient global autoApproved list, which stays decorative for
    // unattended contexts. Placement AFTER the cwd-containment gate means a
    // broad pattern like "cat *" can never launder a path outside granted
    // scopes; needsApproval wins (the same pattern in both lists means
    // deny); a bare "*" is rejected at grant time — allow-all is an
    // interactive-mode concept, not a bot grant. Read-only commands stay
    // covered by the argv lane below.
    if (this.failClosed && this.botShellAllowList && this.botShellAllowList.length > 0) {
      const needsApprovalList = shell.needsApproval ?? [];
      const botList = this.botShellAllowList;
      const allSegmentsApproved = segments.every((segment) =>
        botList.some((pattern) =>
          pattern.trim() !== '*' && this.matchPattern(segment, pattern)
        )
        && !needsApprovalList.some((pattern) => this.matchPattern(segment, pattern))
      );
      if (allSegmentsApproved) {
        logger.info({ cmd: trimmed }, 'Shell command auto-approved (bot allow-list)');
        return { allowed: true, needsApproval: false, lane: 'shell' };
      }
    }

    // "Always" on an earlier prompt in this chat covers the same command
    // family (every segment), after the hard blocks and the cwd gate above.
    const families = this.familyApprovalAllowed(ctx) ? this.approvedFamiliesByContext.get(ctx.channelId) : undefined;
    if (families && families.size > 0) {
      const needsApprovalList = shell.needsApproval ?? [];
      const covered = segments.every((segment) => {
        const family = commandFamily(segment);
        return family !== null && families.has(family)
          && !needsApprovalList.some((pattern) => this.matchPattern(segment, pattern));
      });
      if (covered) {
        logger.info({ cmd: trimmed }, 'Shell command auto-approved (command family approved with Always in this chat)');
        return { allowed: true, needsApproval: false, lane: 'shell' };
      }
    }

    // Argv lane: the only path to a prompt-free approval in Ask Me mode.
    const argvLane = this.classifyArgvLane(trimmed, cwd);
    if (argvLane.ok) {
      logger.info({ cmd: trimmed }, 'Shell command auto-approved (argv lane)');
      return { allowed: true, needsApproval: false, lane: 'argv' };
    }

    // Fail-closed execute grants (bots): an explicitly granted execute scope
    // lets the bot run commands whose path arguments ALL live inside it — the
    // blocked list already won above. Commands with no path argument stay
    // approval-gated: an unscoped `npm install` mutates cwd and can reach
    // anywhere via the network, so it is not covered by a directory grant.
    if (this.failClosed) {
      const pathSegments = splitShellSegments(stripHeredocs(trimmed));
      const paths = pathSegments.flatMap((s) => shellPaths(s)).map((p) => ({ ...p, path: resolve(cwd, p.path.replace(/^~(?=\/|$)/, homedir())) }));
      if (paths.length > 0 && paths.every((p) => this.isExecuteScoped(p.path))) {
        logger.info({ cmd: trimmed, paths: paths.length }, 'Shell command allowed by execute scope');
        return { allowed: true, needsApproval: false, lane: 'shell' };
      }
      // Only reading, only where it may read (`ls … | grep`, `find … 2>/dev/null | head`):
      // no question. These used to ask the owner every time a pipe or redirect was used.
      if (pathSegments.length > 0 && pathSegments.every(isReadOnlySegment)
        && paths.every((p) => p.path.startsWith(this.cwd) || this.isWithinScope(this.canonicalizePath(p.path), 'read'))) {
        logger.info({ cmd: trimmed, paths: paths.length }, 'Shell command allowed: read-only within granted scopes');
        return { allowed: true, needsApproval: false, lane: 'shell' };
      }
    }

    // Approval lane: the user sees the exact string.
    if (this.askHandler && ctx.channelType !== 'internal') {
      const result = await this.askHandler(`Run command: ${trimmed}`);
      if (result === 'yes') {
        return { allowed: true, needsApproval: false, lane: 'shell' };
      }
      if (result === 'always') {
        const approved = this.approvedCommandsByContext.get(ctx.channelId) ?? new Set<string>();
        approved.add(trimmed);
        this.approvedCommandsByContext.set(ctx.channelId, approved);
        // Also remember the command family (`pandoc`, `git commit`) so the
        // next pandoc call in this chat doesn't ask again. Wrappers that can
        // run anything (sudo, sh -c, env, xargs…) are never generalised.
        const familyList = segments.map(commandFamily);
        if (this.familyApprovalAllowed(ctx) && familyList.every((f): f is string => f !== null)) {
          const set = this.approvedFamiliesByContext.get(ctx.channelId) ?? new Set<string>();
          for (const f of familyList) set.add(f);
          this.approvedFamiliesByContext.set(ctx.channelId, set);
        }
        return { allowed: true, needsApproval: false, lane: 'shell' };
      }
      return { allowed: false, reason: `User denied: ${trimmed}`, needsApproval: false };
    }

    return { allowed: false, reason: 'Command not in auto-approve list — requires approval', needsApproval: true };
  }

  async checkMcpTool(request: McpGateRequest): Promise<McpGateResult> {
    const { serverId, toolName } = request;
    const label = `${serverId}/${toolName}`;
    if (request.autoApprove) return { allowed: true };
    if (this.failClosed) {
      return { allowed: false, reason: `Fail-closed: MCP tool ${label} is not in tools.autoApprove` };
    }
    const ctx = this.ctx();
    if (this.approvedMcpByContext.get(ctx.channelId)?.has(label)) return { allowed: true };
    if (!this.askHandler || ctx.channelType === 'internal') {
      return {
        allowed: false,
        reason: `MCP tool ${label} needs approval; add "${toolName}" to tools.autoApprove for server "${serverId}" to run it unattended`,
      };
    }
    const answer = await this.askOwner(
      `MCP tool call\nServer: ${serverId}\nTool:   ${toolName}\nArguments:\n${formatMcpArgs(request.args)}`,
    );
    if (answer === 'yes') return { allowed: true };
    if (answer === 'always') {
      const approved = this.approvedMcpByContext.get(ctx.channelId) ?? new Set<string>();
      approved.add(label);
      this.approvedMcpByContext.set(ctx.channelId, approved);
      return { allowed: true };
    }
    return { allowed: false, reason: `User denied MCP tool ${label}` };
  }

  async checkMcpResource(request: McpResourceGateRequest): Promise<McpGateResult> {
    const { operation, signal } = request;
    if (signal?.aborted) return { allowed: false, reason: 'MCP resource request was cancelled' };
    const ctx = this.ctx();
    if (ctx.senderRole === 'member' || this.failClosed) {
      return { allowed: false, reason: 'MCP resources are unavailable to members and fail-closed agents' };
    }
    const toolName = operation === 'read' ? MCP_READ_RESOURCE_TOOL : MCP_LIST_RESOURCES_TOOL;
    if (ctx.allowedTools && !ctx.allowedTools.includes(toolName)) {
      return { allowed: false, reason: `MCP resource helper ${toolName} is not allowed in this context` };
    }
    // Local server enumeration needs no owner prompt, but retained helpers
    // must still respect the current caller's role and exact tool allowlist.
    if (operation === 'servers') return { allowed: true };
    const { serverId, uri } = request;
    if (operation === 'read' && uri && request.autoApprove) return { allowed: true };
    // Resource grants never collide with tool grants, other protocols, or
    // another URI on the same server. The caller's scoped source channel is
    // used, so concurrent turns retain their own approval identity.
    const channel = JSON.stringify([ctx.channelType, ctx.channelId]);
    const key = JSON.stringify([serverId, operation, operation === 'read' ? uri : null]);
    if (ctx.rememberApprovals && this.approvedMcpResourcesByContext.get(channel)?.has(key)) return { allowed: true };
    if (!this.askHandler || ctx.channelType === 'internal') {
      return { allowed: false, reason: 'MCP resources need owner approval; unattended reads require the exact URI in resources.autoApprove' };
    }
    const answer = await this.askHandler(
      `MCP resource ${operation}\nServer: ${serverId}${operation === 'read' ? `\nURI: ${JSON.stringify(redactSecrets(uri ?? ''))}` : '\nList the allowed resource names and URIs (contents are not read).'}`,
      { alwaysAsk: true },
    );
    if (signal?.aborted) return { allowed: false, reason: 'MCP resource request was cancelled' };
    if (answer === 'always' && ctx.rememberApprovals) {
      const approved = this.approvedMcpResourcesByContext.get(channel) ?? new Set<string>();
      approved.add(key);
      this.approvedMcpResourcesByContext.set(channel, approved);
    }
    return answer === 'yes' || answer === 'always'
      ? { allowed: true }
      : { allowed: false, reason: `User denied MCP resource ${operation} on ${serverId}` };
  }

  private isProtectedConfigPath(path: string): boolean {
    const caseInsensitive = process.platform === 'win32' || process.platform === 'darwin';
    const normalize = (p: string) => (caseInsensitive ? p.toLowerCase() : p);
    const protectedPaths = new Set(
      protectedConfigPaths().flatMap((p) => [resolve(p), this.canonicalizePath(resolve(p))]).map(normalize),
    );
    const resolved = resolve(path);
    return [resolved, this.canonicalizePath(resolved)].some((candidate) => protectedPaths.has(normalize(candidate)));
  }

  private async confirmConfigWrite(path: string): Promise<FsAccessResult> {
    const resolved = resolve(path);
    if (this.failClosed || !this.askHandler || this.ctx().channelType === 'internal') {
      return {
        allowed: false,
        reason: `Permission denied: ${resolved} is a Mercury config file and can only be changed with the owner's confirmation`,
      };
    }
    const answer = await this.askOwner(
      `Write to Mercury config file: ${resolved}\n(it controls MCP servers, permissions and secrets)`,
    );
    if (answer === 'yes' || answer === 'always') return { allowed: true };
    return { allowed: false, reason: `User denied write to ${path}` };
  }

  private askOwner(prompt: string): Promise<string> {
    return this.askHandler ? this.askHandler(prompt, { alwaysAsk: true }) : Promise.resolve('no');
  }

  /**
   * Argv-lane classification: policy (tokenizer, allowlist, flag policy),
   * binary availability in the pinned PATH, and a path gate over the
   * tokenised arguments (after quote removal, so `cat "/etc/passwd"` is
   * seen as the absolute path it is).
   */
  classifyArgvLane(command: string, cwd: string = this.cwd): { ok: true; argv: string[] } | { ok: false; reason: string } {
    const verdict = evaluateArgvPolicy(command);
    if (!verdict.ok) return verdict;
    const argv = verdict.argv;
    if (!IN_PROCESS_BUILTINS.has(argv[0]) && !this.binaryResolver(argv[0])) {
      return { ok: false, reason: `${argv[0]} is not installed in the pinned system PATH` };
    }
    for (const arg of argv.slice(1)) {
      for (const candidate of this.argvPathCandidates(arg)) {
        const resolved = resolve(cwd, candidate.replace(/^~/, homedir()));
        if (resolved === cwd || resolved.startsWith(cwd.endsWith(sep) ? cwd : cwd + sep)) continue;
        if (this.isLexicallyReadable(resolved)) continue;
        return { ok: false, reason: `path ${candidate} is outside the working directory and readable scopes` };
      }
    }
    return { ok: true, argv };
  }

  /** Path-like parts of one argv element: the element itself and an `--opt=value` value. */
  private argvPathCandidates(arg: string): string[] {
    const parts = [arg];
    const eq = arg.indexOf('=');
    if (arg.startsWith('-') && eq > 0) parts.push(arg.slice(eq + 1));
    return parts.filter((p) =>
      p.startsWith('/')
      || /^[A-Za-z]:[\\/]/.test(p)
      || p.startsWith('\\\\')
      || /(?:^|[\\/])\.\.(?:[\\/]|$)/.test(p),
    );
  }

  isGitReadAllowed(): boolean {
    return this.manifest.capabilities.git.enabled && this.manifest.capabilities.git.autoApproveRead;
  }

  isGitWriteNeedsApproval(): boolean {
    return this.manifest.capabilities.git.enabled && this.manifest.capabilities.git.approveWrite;
  }

  addScope(path: string, read: boolean, write: boolean): void {
    const resolved = resolve(path);
    const existing = this.findScope(resolved);
    if (existing) {
      existing.read = existing.read || read;
      existing.write = existing.write || write;
    } else {
      this.manifest.capabilities.filesystem.scopes.push({
        path: resolved,
        read,
        write,
      });
    }
    this.save();
    logger.info({ path: resolved, read, write }, 'Permission scope added');
  }

  private findScope(resolvedPath: string): FileScope | undefined {
    const scopes = this.manifest.capabilities.filesystem.scopes;
    // Most-specific scope wins: a deep grant (e.g. ~/.mercury/tam rwx) must
    // not be shadowed by a broad read-only ancestor (e.g. ~/.mercury r).
    let best: FileScope | undefined;
    let bestLen = -1;
    for (const scope of scopes) {
      const scopeResolved = resolve(scope.path.replace(/^~/, homedir()));
      if (resolvedPath === scopeResolved || resolvedPath.startsWith(scopeResolved + sep)) {
        if (scopeResolved.length > bestLen) {
          best = scope;
          bestLen = scopeResolved.length;
        }
      }
    }
    return best;
  }

  async requestScopeExternal(path: string, mode: 'read' | 'write'): Promise<{ allowed: boolean; reason?: string }> {
    if (!this.askHandler) {
      return { allowed: false, reason: `Permission denied for ${mode} access to ${path}` };
    }

    const prompt = `Mercury needs ${mode} access to:\n${path}\n\nAllow access?`;
    const response = await this.askHandler(prompt);

    if (response === 'always') {
      this.addScope(path, mode === 'read', mode === 'write');
      return { allowed: true };
    }

    if (response === 'yes') {
      this.addTempScope(path, mode === 'read', mode === 'write');
      return { allowed: true };
    }

    return { allowed: false, reason: `Permission denied for ${mode} access to ${path}` };
  }

  /**
   * Session-only scope on the calling agent's context (the main agent's
   * session, or a sub-agent's own context — never shared with siblings).
   */
  addTempScope(path: string, read: boolean, write: boolean): void {
    const resolved = resolve(path);
    this.updateContext((base) => ({ scopes: [...base.scopes, { path: resolved, read, write }] }));
    logger.info({ path: resolved, read, write }, 'Temp permission scope added (session only)');
  }

  private findTempScope(resolvedPath: string): ContextScope | undefined {
    for (const scope of this.ctx().scopes) {
      const scopeResolved = resolve(scope.path.replace(/^~/, homedir()));
      if (resolvedPath === scopeResolved || resolvedPath.startsWith(scopeResolved + sep)) {
        return scope;
      }
    }
    return undefined;
  }

  /**
   * Canonicalise a path by resolving symlinks, tolerating paths that do not
   * exist yet (e.g. create_file): the deepest existing ancestor is resolved
   * and the remaining tail re-appended.
   */
  private canonicalizePath(resolved: string): string {
    try {
      return realpathSync(resolved);
    } catch {
      const parent = dirname(resolved);
      if (parent === resolved) return resolved;
      return join(this.canonicalizePath(parent), basename(resolved));
    }
  }

  /**
   * True when a canonical path falls inside a scope granting `mode`. Scope
   * bases are canonicalised too so a scope declared through a symlinked
   * directory (macOS `/tmp` → `/private/tmp`) still covers its own files.
   */
  private isWithinScope(canonicalPath: string, mode: 'read' | 'write'): boolean {
    const granting = [...this.manifest.capabilities.filesystem.scopes, ...this.ctx().scopes].filter(
      (scope) => (mode === 'write' ? scope.write : scope.read),
    );
    for (const scope of granting) {
      const base = this.canonicalizePath(resolve(scope.path.replace(/^~/, homedir())));
      if (canonicalPath === base || canonicalPath.startsWith(base + sep)) {
        return true;
      }
    }
    return false;
  }

  private matchPattern(command: string, pattern: string): boolean {
    try {
      return globToRegExp(pattern).test(command);
    } catch {
      return command.startsWith(pattern.replace(/ \*$/, ''));
    }
  }

  /** A resolved path is covered by an explicit execute grant. */
  private isExecuteScoped(resolvedPath: string): boolean {
    if (this.findScope(resolvedPath)?.execute) return true;
    return this.findTempScope(resolvedPath)?.execute === true;
  }

  private mergeDefaults(parsed: Partial<PermissionsManifest>): PermissionsManifest {
    const mergeArray = (existing: string[] | undefined, defaults: string[]): string[] => {
      if (!existing) return [...defaults];
      const combined = new Set([...defaults, ...existing]);
      return [...combined];
    };

    return {
      capabilities: {
        ...(parsed.capabilities?.browser ? { browser: {
          enabled: parsed.capabilities.browser.enabled === true,
          ...(typeof parsed.capabilities.browser.executable === 'string' ? { executable: parsed.capabilities.browser.executable } : {}),
        } } : {}),
        filesystem: {
          enabled: parsed.capabilities?.filesystem?.enabled ?? DEFAULT_MANIFEST.capabilities.filesystem.enabled,
          scopes: parsed.capabilities?.filesystem?.scopes ?? DEFAULT_MANIFEST.capabilities.filesystem.scopes,
        },
        shell: {
          enabled: parsed.capabilities?.shell?.enabled ?? DEFAULT_MANIFEST.capabilities.shell.enabled,
          blocked: mergeArray(parsed.capabilities?.shell?.blocked, DEFAULT_MANIFEST.capabilities.shell.blocked),
          autoApproved: mergeArray(parsed.capabilities?.shell?.autoApproved, DEFAULT_MANIFEST.capabilities.shell.autoApproved),
          needsApproval: mergeArray(parsed.capabilities?.shell?.needsApproval, DEFAULT_MANIFEST.capabilities.shell.needsApproval),
          cwdOnly: parsed.capabilities?.shell?.cwdOnly ?? DEFAULT_MANIFEST.capabilities.shell.cwdOnly,
        },
        git: {
          enabled: parsed.capabilities?.git?.enabled ?? DEFAULT_MANIFEST.capabilities.git.enabled,
          autoApproveRead: parsed.capabilities?.git?.autoApproveRead ?? DEFAULT_MANIFEST.capabilities.git.autoApproveRead,
          approveWrite: parsed.capabilities?.git?.approveWrite ?? DEFAULT_MANIFEST.capabilities.git.approveWrite,
        },
      },
    };
  }
}

const NEVER_GENERALISE = new Set(['sudo', 'su', 'doas', 'eval', 'exec', 'sh', 'bash', 'zsh', 'fish', 'dash', 'env', 'xargs', 'nohup', 'time', 'watch', 'command', 'builtin', 'powershell', 'pwsh', 'cmd']);
const EXACT_ONLY_SUBCOMMANDS = new Set(['install', 'i', 'add', 'exec', 'dlx', 'x', 'global', 'upgrade', 'update', 'run-script']);
const SUBCOMMAND_TOOLS = new Set(['git', 'npm', 'pnpm', 'yarn', 'bun', 'npx', 'pnpx', 'docker', 'cargo', 'go', 'kubectl', 'brew', 'pip', 'pip3', 'uv', 'gh', 'deno', 'poetry', 'apt', 'apt-get', 'systemctl', 'launchctl']);

/**
 * The family an "Always" answer covers: the program (`pandoc`), or the
 * program and its subcommand for multi-command tools (`git commit`, `npm
 * install`). Null for wrappers that can run anything, and for segments with
 * no plain program name.
 */
export function commandFamily(segment: string): string | null {
  const tokens = segment.trim().split(/\s+/).filter(Boolean);
  let i = 0;
  while (i < tokens.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(tokens[i])) i++;
  const first = tokens[i];
  if (!first || /[^A-Za-z0-9._/+-]/.test(first)) return null;
  const base = first.split('/').pop() ?? '';
  if (!base || NEVER_GENERALISE.has(base)) return null;
  if (SUBCOMMAND_TOOLS.has(base)) {
    const sub = tokens[i + 1];
    // Installing or executing arbitrary packages stays exact-match only.
    if (sub && EXACT_ONLY_SUBCOMMANDS.has(sub)) return null;
    return sub && /^[A-Za-z][A-Za-z0-9:_-]*$/.test(sub) ? `${base} ${sub}` : base;
  }
  return base;
}