ompchamber 0.3.0

package/src/server/lib/fs/shell.ts

@@ -0,0 +1,71 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Bun-native replacement for the former `util.promisify(exec)` pattern.
+ *
+ * Runs a command through /bin/sh (matching node's `exec` shell semantics) and
+ * captures stdout/stderr as text. Exit handling is explicit: unlike the
+ * promisified node API, Bun never throws for non-zero exits — callers check
+ * `exitCode`. `error` carries the spawn failure only (ENOENT, timeout kill is
+ * surfaced via signalCode instead).
+ */
+
+export interface ShellResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number | null;
+  signalCode: NodeJS.Signals | null;
+  killed: boolean;
+  error?: Error;
+}
+
+export interface ShellOptions {
+  cwd?: string;
+  /** Kill the process after this many milliseconds (Bun-native). */
+  timeout?: number;
+  /** Kill the process once it has emitted more than this many bytes (Bun-native). */
+  maxBuffer?: number;
+  env?: Record<string, string | undefined>;
+}
+
+export function runShell(command: string, options: ShellOptions = {}): Promise<ShellResult> {
+  const proc = Bun.spawn({
+    cmd: ['sh', '-c', command],
+    cwd: options.cwd,
+    stdout: 'pipe',
+    stderr: 'pipe',
+    timeout: options.timeout,
+    maxBuffer: options.maxBuffer,
+    env: options.env ? { ...Bun.env, ...options.env } : undefined,
+  });
+  return (async () => {
+    let error: Error | undefined;
+    let stdout = '';
+    let stderr = '';
+    try {
+      [stdout, stderr] = await Promise.all([
+        new Response(proc.stdout).text(),
+        new Response(proc.stderr).text(),
+      ]);
+    } catch (err) {
+      error = err instanceof Error ? err : new Error(String(err));
+    }
+    const exitCode = await proc.exited;
+    return {
+      stdout,
+      stderr,
+      exitCode,
+      signalCode: proc.signalCode,
+      killed: proc.killed,
+      error,
+    };
+  })();
+}
+
+/** True when the result represents a usable success (exit 0 and no spawn error). */
+export function shellOk(result: ShellResult): boolean {
+  return result.error === undefined && result.exitCode === 0;
+}

package/src/server/lib/fs/terminal-cwd.ts

@@ -0,0 +1,49 @@
+import path from 'path';
+import { isWithinRoot } from '@/server/lib/fs/root';
+
+/** True when `dir` resolves to an existing directory (async stat probe). */
+export async function isDirectory(dir: string): Promise<boolean> {
+  const stat = await Bun.file(dir).stat().catch(() => null);
+  return stat?.isDirectory() ?? false;
+}
+
+/**
+ * Resolve the directory a terminal command should run in. `requestedCwd` is
+ * honored only when it stays within `rootDir` and names a real directory;
+ * otherwise the command runs at the root.
+ */
+export async function resolveTerminalCwd(rootDir: string, requestedCwd: string): Promise<string> {
+  if (!requestedCwd) return rootDir;
+  const resolved = path.isAbsolute(requestedCwd)
+    ? path.resolve(requestedCwd)
+    : path.resolve(rootDir, requestedCwd);
+  if (isWithinRoot(rootDir, resolved) && (await isDirectory(resolved))) return resolved;
+  return rootDir;
+}
+
+export type CdResult =
+  | { ok: true; cwd: string }
+  | { ok: false; reason: 'above-root' | 'missing' };
+
+/**
+ * Resolve a `cd <target>` against the current directory. The containment test
+ * mirrors the original `startsWith(rootDir)` (no separator) exactly, so an
+ * out-of-root sibling is still rejected the same way it always was.
+ */
+export async function resolveCdTarget(
+  rootDir: string,
+  currentDir: string,
+  target: string,
+): Promise<CdResult> {
+  const nextDir = path.resolve(currentDir, target);
+  if (!nextDir.startsWith(rootDir)) return { ok: false, reason: 'above-root' };
+  if (!(await isDirectory(nextDir))) return { ok: false, reason: 'missing' };
+  return { ok: true, cwd: path.relative(rootDir, nextDir) || '.' };
+}
+
+/** Match a bare `cd` invocation; returns the trimmed target or null. */
+export function matchCdCommand(command: string): string | null {
+  const match = command.match(/^cd(?:\s+(.*))?$/);
+  if (!match) return null;
+  return (match[1] || '').trim();
+}

package/src/server/lib/models/provider-registry.server.ts

@@ -0,0 +1,269 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Provider registry assembly for the provider settings. Folds the three omp
+ * sources — auth login providers, models.yml registrations, config.yml
+ * disabledProviders — with the chamber's local SQLite overlay into the
+ * ProviderItem list the settings UI renders. Server-only: reads omp config
+ * files and drives the shared utility RPC process.
+ */
+
+import { readDisabledProviders } from '@/server/lib/omp/config/roles';
+import { getModelsConfigPath, readNativeProviders } from '@/server/lib/omp/config/providers';
+import { runUtilityCommand, type OmpModel } from '@/server/lib/omp/rpc/utility';
+import { isKenariProvider, removeLegacyKenariModels } from '@/shared/lib/models/provider-cleanup';
+import { formatContextWindow } from '@/shared/lib/code/format';
+import type { ProviderItem } from '@/shared/types';
+
+/** app_settings key holding the chamber-local provider overlay. */
+export const PROVIDERS_SETTINGS_KEY = 'omp_providers_config';
+
+const RPC_CACHE_TTL_MS = 60_000;
+
+interface LoginProvider {
+  id: string;
+  name: string;
+  authenticated: boolean;
+}
+
+/**
+ * Provider registry straight from the omp agent: authenticated login providers
+ * (omp auth) plus their registered models (get_available_models). This is the
+ * source the composer's model dropdown already uses via /api/models.
+ */
+async function loadRpcProviderItems(): Promise<ProviderItem[]> {
+  const cached = globalThis.__ompChamberProvidersRpcCache;
+  if (cached && cached.expiresAt > Date.now()) return cached.data;
+  try {
+    const [loginResponse, modelsResponse] = await Promise.all([
+      runUtilityCommand<{ providers?: unknown }>({ type: 'get_login_providers' }, 30_000),
+      runUtilityCommand<{ models?: unknown }>({ type: 'get_available_models' }, 60_000),
+    ]);
+    const loginProviders = Array.isArray(loginResponse.providers)
+      ? loginResponse.providers.filter((provider): provider is LoginProvider => (
+          typeof provider === 'object' && provider !== null
+          && typeof (provider as { id?: unknown }).id === 'string'
+          && typeof (provider as { name?: unknown }).name === 'string'
+          && typeof (provider as { authenticated?: unknown }).authenticated === 'boolean'
+        ))
+      : [];
+    const available = Array.isArray(modelsResponse.models)
+      ? modelsResponse.models.filter((model): model is OmpModel => (
+          typeof model === 'object' && model !== null
+          && typeof (model as OmpModel).id === 'string'
+          && typeof (model as OmpModel).provider === 'string'
+        ))
+      : [];
+    const disabled = await readDisabledProviders().catch(() => new Set<string>());
+
+    const items = loginProviders.map((provider) => {
+      const providerModels = available.filter((model) => model.provider === provider.id);
+      const isDisabled = disabled.has(provider.id);
+      return {
+        id: `omp-auth-${provider.id}`,
+        name: provider.name,
+        slug: provider.id,
+        icon: 'plug',
+        status: (provider.authenticated && !isDisabled ? 'connected' : 'disconnected') as ProviderItem['status'],
+        disabled: isDisabled,
+        configuredIn: 'omp auth credentials',
+        models: providerModels.map((model) => ({
+          id: model.id,
+          name: typeof model.name === 'string' && model.name.length > 0 ? model.name : model.id,
+          contextWindow: model.contextWindow ? `${Math.round(model.contextWindow / 1000)}K ctx` : '',
+          hasTools: true,
+          hasVision: false,
+          isVisible: true,
+        })),
+      };
+    });
+    globalThis.__ompChamberProvidersRpcCache = { data: items, expiresAt: Date.now() + RPC_CACHE_TTL_MS };
+    return items;
+  } catch {
+    // RPC unavailable (cold start / omp busy) — degrade to the remaining sources.
+    return [];
+  }
+}
+
+/**
+ * Build a disabled-native ProviderItem for a provider the omp agent reports as
+ * disabled (config.yml disabledProviders). The UI treats these as
+ * "disconnected" — re-enabling via POST { enableProvider } flips config.yml.
+ */
+function disabledProviderItem(slug: string): ProviderItem {
+  return {
+    id: `omp-disabled-${slug}`,
+    name: slug,
+    slug,
+    icon: 'plug',
+    status: 'disconnected',
+    disabled: true,
+    configuredIn: 'omp disabledProviders',
+    models: [],
+  };
+}
+
+/**
+ * Native provider entry discovered from models.yml. Credentials never leave
+ * omp's own stores — chamber only surfaces registration info.
+ */
+function nativeProviderItem(
+  slug: string,
+  baseUrl: string | undefined,
+  nativeModels: Array<{
+    id: string;
+    name?: string;
+    contextWindow?: number;
+    maxTokens?: number;
+    reasoning?: boolean;
+    imageInput?: boolean;
+  }>,
+  isDisabled = false,
+): ProviderItem {
+  const models = nativeModels.map((model) => ({
+    id: model.id,
+    name: model.name || model.id,
+    contextWindow: model.contextWindow
+      ? `${formatContextWindow(model.contextWindow) || Math.round(model.contextWindow / 1000)} ctx`
+      : '',
+    hasTools: true,
+    hasVision: model.imageInput === true,
+    hasReasoning: model.reasoning,
+    isVisible: true,
+    maxTokens: model.maxTokens,
+  }));
+  return {
+    id: `omp-native-${slug}`,
+    name: slug,
+    slug,
+    icon: 'plug',
+    status: isDisabled ? 'disconnected' : 'connected',
+    disabled: isDisabled,
+    configuredIn: baseUrl ? `models.yml · ${baseUrl}` : 'models.yml',
+    models: removeLegacyKenariModels({ name: slug, slug, baseUrl }, models),
+  };
+}
+
+function providerIdentityKey(provider: ProviderItem): string {
+  const slug = provider.slug.trim().toLowerCase();
+  const name = provider.name.trim().toLowerCase();
+  const baseUrl = provider.baseUrl?.trim().toLowerCase() || '';
+  if (isKenariProvider({ name, slug, baseUrl })) return 'kenari';
+  return slug;
+}
+
+function mergeProviderItems(existing: ProviderItem, incoming: ProviderItem): ProviderItem {
+  const primary = existing.id.startsWith('omp-auth-') || !incoming.id.startsWith('omp-auth-')
+    ? existing
+    : incoming;
+  const secondary = primary === existing ? incoming : existing;
+  const knownModelIds = new Set<string>();
+  const models = [...primary.models, ...secondary.models].filter((model) => {
+    if (knownModelIds.has(model.id)) return false;
+    knownModelIds.add(model.id);
+    return true;
+  });
+  // Disable is a union, not a winner-takes-all: the two sources see different
+  // halves of config.yml (auth sees login providers, native sees models.yml), so
+  // a flag set on either side must survive the merge — otherwise the provider
+  // re-enters the chat picker on the next reload.
+  const disabled = primary.disabled === true || secondary.disabled === true;
+
+  return {
+    ...primary,
+    name: primary.name === primary.slug && secondary.name !== secondary.slug
+      ? secondary.name
+      : primary.name,
+    status: disabled
+      ? 'disconnected'
+      : primary.status === 'connected' || secondary.status === 'connected'
+        ? 'connected'
+        : primary.status,
+    disabled,
+    baseUrl: primary.baseUrl || secondary.baseUrl,
+    apiKey: primary.apiKey || secondary.apiKey,
+    configuredIn: primary.apiKey || primary.baseUrl ? primary.configuredIn : secondary.configuredIn,
+    models,
+  };
+}
+
+export function deduplicateProviderItems(items: ProviderItem[]): ProviderItem[] {
+  const bySlug = new Map<string, ProviderItem>();
+  for (const item of items) {
+    const normalizedItem = {
+      ...item,
+      models: removeLegacyKenariModels(item, item.models),
+    };
+    const key = providerIdentityKey(normalizedItem);
+    const existing = bySlug.get(key);
+    bySlug.set(key, existing ? mergeProviderItems(existing, normalizedItem) : normalizedItem);
+  }
+  return [...bySlug.values()];
+}
+
+/**
+ * Re-apply the chamber-local overlay onto freshly built registry entries. The
+ * registry is authoritative for which providers/models exist, but the user's
+ * own per-model choices (visibility, sampling config) exist only in SQLite —
+ * without this, every reload rebuilds the list with isVisible: true and the
+ * eye toggles silently reset.
+ *
+ * `disabled` is deliberately NOT pulled from the overlay: it is native state
+ * (config.yml disabledProviders), and letting a stale SQLite row clear it would
+ * put a provider the user disabled back into the chat picker.
+ */
+function applyStoredOverrides(registry: ProviderItem[], stored: ProviderItem[]): ProviderItem[] {
+  if (stored.length === 0) return registry;
+  const storedBySlug = new Map(stored.map((provider) => [provider.slug.trim().toLowerCase(), provider]));
+  return registry.map((provider) => {
+    const saved = storedBySlug.get(provider.slug.trim().toLowerCase());
+    if (!saved) return provider;
+    const savedModels = new Map(saved.models.map((model) => [model.id, model]));
+    return {
+      ...provider,
+      models: provider.models.map((model) => {
+        const previous = savedModels.get(model.id);
+        if (!previous) return model;
+        return {
+          ...model,
+          isVisible: previous.isVisible !== false,
+          ...(previous.temperature !== undefined ? { temperature: previous.temperature } : {}),
+          ...(previous.maxTokens !== undefined ? { maxTokens: previous.maxTokens } : {}),
+          ...(previous.topP !== undefined ? { topP: previous.topP } : {}),
+          ...(previous.reasoningEffort !== undefined ? { reasoningEffort: previous.reasoningEffort } : {}),
+        };
+      }),
+    };
+  });
+}
+
+/** Merge all three omp provider sources with app-local custom SQLite entries. */
+export async function mergeProviders(custom: ProviderItem[]): Promise<{ providers: ProviderItem[]; modelsConfigPath: string }> {
+  const disabled = await readDisabledProviders().catch(() => new Set<string>());
+  const authItems = await loadRpcProviderItems();
+  const native = await readNativeProviders();
+  const nativeItems = native.map((info) => nativeProviderItem(
+    info.slug,
+    info.baseUrl,
+    info.models,
+    disabled.has(info.slug),
+  ));
+  const disabledItems = [...disabled]
+    .filter((slug) => !nativeItems.some((n) => n.slug === slug) && !authItems.some((a) => a.slug === slug))
+    .map(disabledProviderItem);
+  const registryItems = applyStoredOverrides(
+    deduplicateProviderItems([...authItems, ...nativeItems, ...disabledItems]),
+    custom,
+  );
+  const nativeSlugs = new Set(registryItems.map((provider) => provider.slug.toLowerCase()));
+  return {
+    providers: deduplicateProviderItems([
+      ...registryItems,
+      ...custom.filter((p) => !nativeSlugs.has(p.slug.toLowerCase())),
+    ]),
+    modelsConfigPath: await getModelsConfigPath(),
+  };
+}

package/src/server/lib/omp/config/agents.ts

@@ -0,0 +1,162 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Native OMP agent discovery — reads agent definition markdown files from
+ * ~/.omp/agent/agents and <project>/.omp/agents so the settings agents list
+ * surfaces the same agent definitions the omp agent loads. Discovery is
+ * read-only: chamber never mutates native agent files.
+ */
+
+import fs from 'fs';
+import { join } from 'path';
+import { getAgentDir, pathExists } from '@/server/lib/omp/core/paths';
+import { writeFileAtomic } from '@/server/lib/fs/atomic-write';
+import { parseFrontmatter } from '@/server/lib/omp/config/yaml';
+
+export interface DiscoveredAgent {
+  id: string;
+  name: string;
+  description: string;
+  mode: 'primary' | 'subagent' | 'all';
+  overrideModel?: string;
+  thinkingVariant?: string;
+  temperature?: number | null;
+  topP?: number | null;
+  systemPrompt: string;
+  /** Which disk root the agent was discovered from. */
+  sourceRoot: 'user' | 'project';
+  filePath: string;
+}
+
+function toMode(value: string | undefined): 'primary' | 'subagent' | 'all' {
+  return value === 'primary' || value === 'subagent' || value === 'all' ? value : 'all';
+}
+
+async function parseAgentFile(filePath: string, sourceRoot: 'user' | 'project'): Promise<DiscoveredAgent | undefined> {
+  try {
+    const file = Bun.file(filePath);
+    if ((await file.stat()).size > 512 * 1024) return undefined;
+    const text = await file.text();
+    const { data, body } = parseFrontmatter(text);
+    const base = filePath.split('/').pop()?.replace(/\.md$/, '') || filePath;
+    const name = data.name || base;
+    if (!name) return undefined;
+    const temperature = data.temperature !== undefined && data.temperature !== '' ? Number(data.temperature) : null;
+    const topP = data.top_p !== undefined && data.top_p !== '' ? Number(data.top_p) : null;
+    return {
+      id: `omp-${sourceRoot}-${base}`,
+      name,
+      description: data.description || '',
+      mode: toMode(data.mode),
+      overrideModel: data.model || undefined,
+      thinkingVariant: data.thinking || undefined,
+      temperature: Number.isFinite(temperature) ? temperature : null,
+      topP: Number.isFinite(topP) ? topP : null,
+      systemPrompt: body.trim(),
+      sourceRoot,
+      filePath,
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+async function scanAgentsDir(dir: string, sourceRoot: 'user' | 'project'): Promise<DiscoveredAgent[]> {
+  if (!(await pathExists(dir))) return [];
+  try {
+    const found: DiscoveredAgent[] = [];
+    for (const entry of await fs.promises.readdir(dir, { withFileTypes: true })) {
+      if (!entry.isFile() || !entry.name.endsWith('.md')) continue;
+      const agent = await parseAgentFile(join(dir, entry.name), sourceRoot);
+      if (agent) found.push(agent);
+    }
+    return found;
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Discover native agents from both disk roots. User agents win over project
+ * agents with the same file base name. Never throws.
+ */
+export async function discoverNativeAgents(projectDir?: string): Promise<DiscoveredAgent[]> {
+  const userDir = join(getAgentDir(), 'agents');
+  const byBase = new Map<string, DiscoveredAgent>();
+  for (const agent of await scanAgentsDir(userDir, 'user')) {
+    byBase.set(agent.filePath.split('/').pop() ?? agent.id, agent);
+  }
+  if (projectDir) {
+    for (const agent of await scanAgentsDir(projectDir, 'project')) {
+      const base = agent.filePath.split('/').pop() ?? agent.id;
+      if (!byBase.has(base)) byBase.set(base, agent);
+    }
+  }
+  return [...byBase.values()];
+}
+
+/** Escape a frontmatter scalar value into a safe quoted string. */
+function fmValue(value: string): string {
+  return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+
+function optionalFmLine(lines: string[], key: string, value: string | number | null | undefined): void {
+  if (value === null || value === undefined || value === '') return;
+  lines.push(`${key}: ${typeof value === 'number' ? value : fmValue(String(value))}`);
+}
+
+export interface AgentFileInput {
+  /** File base name without .md (also the agent name unless name is given). */
+  fileName: string;
+  name?: string;
+  description?: string;
+  mode?: string;
+  model?: string;
+  thinking?: string;
+  temperature?: number | null;
+  topP?: number | null;
+  tools?: string[];
+  systemPrompt: string;
+}
+
+/**
+ * Write (create or replace) a user-level agent definition markdown file.
+ * Project agents are intentionally not writable from the chamber — the agent
+ * dir belongs to omp.
+ */
+export async function writeAgentDefinition(input: AgentFileInput): Promise<{ path: string }> {
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(input.fileName)) {
+    throw new Error('Agent file name may contain letters, numbers, dots, dashes, and underscores');
+  }
+  if (!input.systemPrompt.trim()) {
+    throw new Error('Agent system prompt cannot be empty');
+  }
+  const dir = join(getAgentDir(), 'agents');
+  const path = join(dir, `${input.fileName}.md`);
+  const lines: string[] = ['---'];
+  optionalFmLine(lines, 'name', input.name ?? input.fileName);
+  optionalFmLine(lines, 'description', input.description);
+  optionalFmLine(lines, 'mode', input.mode);
+  optionalFmLine(lines, 'model', input.model);
+  optionalFmLine(lines, 'thinking-level', input.thinking);
+  optionalFmLine(lines, 'temperature', input.temperature ?? null);
+  optionalFmLine(lines, 'top_p', input.topP ?? null);
+  if (input.tools && input.tools.length > 0) {
+    lines.push(`tools: ${input.tools.map(fmValue).join(', ')}`);
+  }
+  lines.push('---');
+  const content = `${lines.join('\n')}\n\n${input.systemPrompt.trim()}\n`;
+  await writeFileAtomic(path, content);
+  return { path };
+}
+
+export async function deleteAgentDefinition(fileName: string): Promise<boolean> {
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(fileName)) throw new Error('Invalid agent file name');
+  const path = join(getAgentDir(), 'agents', `${fileName}.md`);
+  if (!(await Bun.file(path).exists())) return false;
+  await fs.promises.unlink(path);
+  return true;
+}

package/src/server/lib/omp/config/behavior.ts

@@ -0,0 +1,113 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Behavior-rules → native OMP approval mapping. Parses simple line-based
+ * directives from the freeform behavior editor and persists them into
+ * ~/.omp/agent/config.yml tools.approval.* with an atomic read-modify-write,
+ * preserving all other keys (same technique as roles.ts).
+ *
+ * Values must be omp's ApprovalPolicy — `allow | deny | prompt`. Anything else
+ * is dropped silently by normalizePolicy, which is how `ask` became a no-op.
+ * Field names must be real omp tool names, since `tools.approval.<key>` is only
+ * consulted when the key matches the tool's `policyKey`.
+ *
+ * omp honours these per-tool overrides ahead of the approval mode in every
+ * mode, so a blanket "allow everything" belongs in tools.approvalMode (the
+ * composer's access control), not here.
+ */
+
+import { writeFileAtomic } from '@/server/lib/fs/atomic-write';
+import { asMapping, getOmpConfigPath } from '@/server/lib/omp/config/yaml';
+import { isRecord } from '@/shared/lib/util/guards';
+
+export type ApprovalValue = 'allow' | 'deny' | 'prompt';
+
+export interface ApprovalFields {
+  bash?: ApprovalValue;
+  read?: ApprovalValue;
+  edit?: ApprovalValue;
+  write?: ApprovalValue;
+  web_search?: ApprovalValue;
+}
+
+interface Directive {
+  pattern: RegExp;
+  field: keyof ApprovalFields;
+  value: ApprovalValue;
+}
+
+const SUBJECTS: Array<{ fields: Array<keyof ApprovalFields>; subject: string }> = [
+  { fields: ['bash'], subject: 'bash|shell|terminal(?:\\s+commands)?' },
+  { fields: ['read'], subject: '(?:safe\\s+)?(?:reads?|read[- ]?only(?:\\s+commands)?)' },
+  // One phrasing governs both: the editor has no way to tell a patch from a
+  // new file, and leaving `write` uncovered let a "writes" rule miss it.
+  { fields: ['edit', 'write'], subject: 'edits?|writes?|patches?' },
+  { fields: ['web_search'], subject: 'web(?:\\s*search)?|http|network' },
+];
+
+/** "ask" stays a valid phrasing but maps to omp's real `prompt` value. */
+const VERBS: Array<{ value: ApprovalValue; verb: string }> = [
+  { value: 'allow', verb: 'auto[- ]?approve|allow' },
+  { value: 'deny', verb: 'deny|block|forbid' },
+  { value: 'prompt', verb: 'ask|prompt|confirm' },
+];
+
+// Ordered directives — first matching line for a field wins.
+const DIRECTIVES: Directive[] = SUBJECTS.flatMap(({ fields, subject }) =>
+  fields.flatMap((field) =>
+    VERBS.map(({ value, verb }) => ({
+      field,
+      value,
+      pattern: new RegExp(`^\\s*(?:${verb})\\s+(?:(?:before|for)\\s+)?(?:${subject})\\s*$`, 'i'),
+    })),
+  ),
+);
+
+/**
+ * Parse freeform behavior rules into native approval fields. Returns null
+ * when no recognizable directive is found (nothing to write natively).
+ */
+export function parseApprovalRules(text: string): ApprovalFields | null {
+  const fields: ApprovalFields = {};
+  for (const line of text.split(/\r?\n/)) {
+    for (const directive of DIRECTIVES) {
+      if (fields[directive.field] === undefined && directive.pattern.test(line)) {
+        fields[directive.field] = directive.value;
+      }
+    }
+  }
+  return Object.keys(fields).length > 0 ? fields : null;
+}
+
+/**
+ * Merge approval fields into config.yml tools.approval atomically. Only the
+ * parsed fields are touched; unrelated keys are preserved. Throws on invalid
+ * YAML — callers should treat this as best-effort.
+ */
+export async function writeToolsApproval(fields: ApprovalFields): Promise<void> {
+  if (Object.keys(fields).length === 0) return;
+  const path = getOmpConfigPath();
+  const source = (await Bun.file(path).exists()) ? await Bun.file(path).text() : '';
+  const doc = asMapping(Bun.YAML.parse(source), path);
+  const tools = doc.tools;
+  if (tools !== undefined && !isRecord(tools)) {
+    throw new Error(`${path} tools section must be a mapping`);
+  }
+  if (isRecord(tools)) {
+    const approval = tools.approval;
+    if (approval !== undefined && !isRecord(approval)) {
+      throw new Error(`${path} tools.approval must be a mapping`);
+    }
+    if (isRecord(approval)) {
+      Object.assign(approval, fields);
+    } else {
+      tools.approval = fields;
+    }
+  } else {
+    doc.tools = { approval: fields };
+  }
+  await writeFileAtomic(path, Bun.YAML.stringify(doc, null, 2));
+}