pirl-framework-cli 0.0.0-stage → 1.0.1

package/dist/engine/claudeRunner.js

@@ -0,0 +1,118 @@
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import spawn from 'cross-spawn';
+import { createStreamParser } from './claudeStream.js';
+/**
+ * The built-in tools a run gets: everything the coordinator and the roles use. Every tool's definition is sent
+ * with every model request, and Claude Code's full set (with the user's MCP servers) is about 25k tokens of
+ * context, while these come to about 7k. MCP tools would be refused by the run's permission rules anyway.
+ */
+export const RUN_TOOLS = ['Read', 'Write', 'Edit', 'Bash', 'Glob', 'Grep', 'Agent'];
+/**
+ * Runs the coordinator with the user's own, unmodified Claude Code. The prompt goes through stdin and
+ * the long arguments through files, so Vietnamese text and quotes survive Windows command lines.
+ * Claude Code 2.1.281 or later reads `--agents` from a file.
+ */
+export function claudeArgs(request, files) {
+    return [
+        '-p',
+        '--output-format',
+        'stream-json',
+        '--verbose',
+        '--append-system-prompt-file',
+        files.systemPrompt,
+        '--agents',
+        files.agents,
+        '--tools',
+        RUN_TOOLS.join(','),
+        '--strict-mcp-config',
+        // The framework's skills are plain files the coordinator reads; the user's own skills and commands are not loaded.
+        '--disable-slash-commands',
+        '--permission-mode',
+        'dontAsk',
+        '--permission-prompts',
+        'none',
+        '--allowedTools',
+        request.permissions.allow.join(','),
+        '--disallowedTools',
+        request.permissions.deny.join(','),
+        ...request.addDirs.flatMap(dir => ['--add-dir', dir]),
+        ...(request.model ? ['--model', request.model] : []),
+        ...(request.effort ? ['--effort', request.effort] : []),
+        ...(request.resumeSessionId ? ['--resume', request.resumeSessionId] : []),
+    ];
+}
+/** Provider processes still running; ended when PIRL CLI exits so none keeps working unseen. */
+const running = new Set();
+process.once('exit', () => {
+    for (const child of running)
+        child.kill('SIGTERM');
+});
+export function createClaudeRunner(command = 'claude') {
+    return {
+        start(request, onEvent) {
+            const dir = mkdtempSync(join(tmpdir(), 'pirl-run-'));
+            const files = { systemPrompt: join(dir, 'host.md'), agents: join(dir, 'agents.json') };
+            writeFileSync(files.systemPrompt, request.systemPrompt, 'utf8');
+            writeFileSync(files.agents, JSON.stringify(request.agents), 'utf8');
+            const child = spawn(command, claudeArgs(request, files), {
+                cwd: request.cwd,
+                // Background commands and subagents would keep the headless run open after its last turn.
+                env: { ...process.env, CLAUDE_CODE_DISABLE_BACKGROUND_TASKS: '1' },
+                stdio: ['pipe', 'pipe', 'pipe'],
+                windowsHide: true,
+            });
+            const parseStreamLine = createStreamParser();
+            running.add(child);
+            child.once('close', () => running.delete(child));
+            let buffer = '';
+            let stderr = '';
+            const emit = (event) => {
+                try {
+                    onEvent(event);
+                }
+                catch { }
+            };
+            child.stdout?.setEncoding('utf8').on('data', (chunk) => {
+                buffer += chunk;
+                let newline = buffer.indexOf('\n');
+                while (newline >= 0) {
+                    const line = buffer.slice(0, newline).trim();
+                    buffer = buffer.slice(newline + 1);
+                    if (line)
+                        for (const event of parseStreamLine(line))
+                            emit(event);
+                    newline = buffer.indexOf('\n');
+                }
+            });
+            child.stderr?.setEncoding('utf8').on('data', (chunk) => (stderr += chunk));
+            child.stdin?.on('error', () => { });
+            child.stdin?.end(request.prompt);
+            const done = new Promise(resolve => {
+                const finish = (code, error) => {
+                    if (buffer.trim())
+                        for (const event of parseStreamLine(buffer.trim()))
+                            emit(event);
+                    buffer = '';
+                    rmSync(dir, { recursive: true, force: true });
+                    resolve({ code, stderr: error ?? stderr });
+                };
+                child.on('error', error => finish(null, error.message));
+                child.on('close', code => finish(code));
+            });
+            let stopping = false;
+            return {
+                done,
+                stop() {
+                    if (stopping)
+                        return;
+                    stopping = true;
+                    // SIGINT ends the turn cleanly so the session can be resumed; SIGTERM follows if it hangs.
+                    child.kill('SIGINT');
+                    setTimeout(() => child.exitCode === null && child.kill('SIGTERM'), 5_000).unref();
+                },
+            };
+        },
+    };
+}

package/dist/engine/claudeStream.js

@@ -0,0 +1,205 @@
+import { costUsd } from './pricing.js';
+/**
+ * Turns one line of `claude -p --output-format stream-json --verbose` into run events.
+ * Subagents are started with the Agent tool (named Task before Claude Code 2.1.63); their own messages
+ * carry `parent_tool_use_id`, the id of that Agent call, which is how activity is attributed to a role.
+ */
+const SPAWN_TOOLS = new Set(['Agent', 'Task']);
+const short = (value, max = 80) => {
+    const text = String(value ?? '').replace(/\s+/g, ' ').trim();
+    return text.length > max ? `${text.slice(0, max - 1)}…` : text;
+};
+/** A plain-language line for one tool call, shown as the role's latest activity. */
+export function describeTool(name, input = {}) {
+    const path = input['file_path'] ?? input['path'] ?? input['notebook_path'];
+    switch (name) {
+        case 'Read':
+            return `Đọc ${short(path)}`;
+        case 'Edit':
+        case 'MultiEdit':
+            return `Sửa ${short(path)}`;
+        case 'Write':
+            return `Ghi ${short(path)}`;
+        case 'Grep':
+            return `Tìm "${short(input['pattern'], 40)}"`;
+        case 'Glob':
+            return `Liệt kê ${short(input['pattern'], 60)}`;
+        case 'Bash':
+            return `Chạy ${short(input['command'])}`;
+        case 'TodoWrite':
+            return 'Cập nhật danh sách việc';
+        default:
+            return name;
+    }
+}
+/**
+ * A parser for one run's stream. It remembers each tool call by id, so a denial, which Claude Code reports
+ * with the tool's name only, can say which command was refused; and the tokens of each model request, which
+ * Claude Code reports several times while the request streams.
+ */
+export function createStreamParser() {
+    const state = { calls: new Map(), requests: new Map() };
+    return line => parseLine(line, state);
+}
+/** One line on its own, without the calls seen before it. */
+export const parseStreamLine = (line) => parseLine(line, { calls: new Map(), requests: new Map() });
+/**
+ * Tokens of one model request as they stream in, for the live count. A request's usage arrives with its start
+ * (input only), its end (`message_delta`, with the output) and its content blocks; each report holds totals so
+ * far, so only the growth since the last report is new. Some role requests never show their end in the
+ * stream; the result's `modelUsage` gives the exact totals when the provider call ends.
+ */
+function usageEvent(id, model, raw, requests) {
+    if (typeof id !== 'string' || !raw || typeof raw !== 'object')
+        return null;
+    const usage = raw;
+    const split = (usage['cache_creation'] ?? {});
+    const before = requests.get(id);
+    const read = (key, previous = 0) => Math.max(previous, Number(usage[key] ?? 0) || 0);
+    const now = {
+        model: typeof model === 'string' ? model : before?.model ?? 'unknown',
+        inputTokens: read('input_tokens', before?.inputTokens),
+        cacheWriteTokens: read('cache_creation_input_tokens', before?.cacheWriteTokens),
+        cacheReadTokens: read('cache_read_input_tokens', before?.cacheReadTokens),
+        outputTokens: read('output_tokens', before?.outputTokens),
+        cacheWrite1h: Math.max(before?.cacheWrite1h ?? 0, Number(split['ephemeral_1h_input_tokens'] ?? 0) || 0),
+    };
+    requests.set(id, now);
+    const added = {
+        inputTokens: now.inputTokens - (before?.inputTokens ?? 0),
+        cacheWriteTokens: now.cacheWriteTokens - (before?.cacheWriteTokens ?? 0),
+        cacheReadTokens: now.cacheReadTokens - (before?.cacheReadTokens ?? 0),
+        outputTokens: now.outputTokens - (before?.outputTokens ?? 0),
+    };
+    if (before && added.inputTokens + added.cacheWriteTokens + added.cacheReadTokens + added.outputTokens === 0)
+        return null;
+    const cacheWrite1h = now.cacheWrite1h - (before?.cacheWrite1h ?? 0);
+    return { type: 'usage', model: now.model, request: !before, costUsd: costUsd(now.model, { ...added, cacheWrite1h }), ...added };
+}
+/** The result's per-model totals: every request of the provider session, the roles' included. */
+function usageTotals(data) {
+    const raw = data['modelUsage'];
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const models = {};
+    for (const [model, value] of Object.entries(raw)) {
+        models[model] = {
+            inputTokens: Number(value['inputTokens'] ?? 0) || 0,
+            cacheWriteTokens: Number(value['cacheCreationInputTokens'] ?? 0) || 0,
+            cacheReadTokens: Number(value['cacheReadInputTokens'] ?? 0) || 0,
+            outputTokens: Number(value['outputTokens'] ?? 0) || 0,
+            costUsd: typeof value['costUSD'] === 'number' ? value['costUSD'] : null,
+        };
+    }
+    return Object.keys(models).length ? { type: 'usage-totals', models } : null;
+}
+const WINDOW_LABELS = { five_hour: '5 giờ', seven_day: 'Tuần', seven_day_opus: 'Tuần (Opus)', seven_day_sonnet: 'Tuần (Sonnet)' };
+/** The plan's usage windows Claude Code reports with each provider call (`rate_limit_event`). */
+function quotaEvent(data) {
+    const info = (data['rate_limit_info'] ?? {});
+    const windows = (info['unifiedWindows'] ?? {});
+    const entries = Object.entries(windows).filter(([, value]) => typeof value?.['utilization'] === 'number');
+    if (entries.length === 0 && typeof info['utilization'] === 'number' && typeof info['rateLimitType'] === 'string') {
+        entries.push([info['rateLimitType'], info]);
+    }
+    if (entries.length === 0)
+        return null;
+    return {
+        type: 'quota',
+        rows: entries.map(([kind, value]) => ({
+            kind,
+            label: WINDOW_LABELS[kind] ?? kind,
+            percent: value['utilization'] * 100,
+            resetsAt: typeof value['resetsAt'] === 'number' ? new Date(value['resetsAt'] * 1000).toISOString() : null,
+        })),
+    };
+}
+const isEvent = (event) => event !== null;
+function parseLine(line, { calls, requests }) {
+    let data;
+    try {
+        data = JSON.parse(line);
+    }
+    catch {
+        return [];
+    }
+    const type = data['type'];
+    if (type === 'stream_event') {
+        const event = (data['event'] ?? {});
+        const message = (event['message'] ?? {});
+        if (event['type'] === 'message_start')
+            return [usageEvent(message['id'], message['model'], message['usage'], requests)].filter(isEvent);
+        if (event['type'] === 'message_delta')
+            return [usageEvent(data['api_message_id'], null, event['usage'], requests)].filter(isEvent);
+        return [];
+    }
+    if (type === 'rate_limit_event')
+        return [quotaEvent(data)].filter(isEvent);
+    if (type === 'system') {
+        const subtype = data['subtype'];
+        if (subtype === 'init' && typeof data['session_id'] === 'string')
+            return [{ type: 'session', sessionId: data['session_id'] }];
+        if (subtype === 'api_retry')
+            return [{ type: 'retry', attempt: Number(data['attempt'] ?? 0), error: String(data['error'] ?? 'unknown') }];
+        if (subtype === 'permission_denied') {
+            const id = typeof data['tool_use_id'] === 'string' ? data['tool_use_id'] : null;
+            return [{ type: 'denied', id, detail: (id && calls.get(id)) || short(data['tool_name'] ?? data['message'] ?? 'tool', 120) }];
+        }
+        return [];
+    }
+    if (type === 'result') {
+        const denials = Array.isArray(data['permission_denials']) ? data['permission_denials'] : [];
+        return [
+            ...denials.map(denial => ({
+                type: 'denied',
+                id: typeof denial['tool_use_id'] === 'string' ? denial['tool_use_id'] : null,
+                detail: describeTool(String(denial['tool_name'] ?? ''), (denial['tool_input'] ?? {})),
+            })),
+            ...[usageTotals(data)].filter(isEvent),
+            {
+                type: 'result',
+                // A failed run has no `result`; its reasons are in `errors`.
+                text: typeof data['result'] === 'string' ? data['result'] : Array.isArray(data['errors']) ? data['errors'].map(String).join('; ') : '',
+                isError: data['is_error'] === true || (typeof data['subtype'] === 'string' && data['subtype'] !== 'success'),
+                sessionId: typeof data['session_id'] === 'string' ? data['session_id'] : null,
+            },
+        ];
+    }
+    if (type !== 'assistant' && type !== 'user')
+        return [];
+    const message = (data['message'] ?? {});
+    const blocks = Array.isArray(message['content']) ? message['content'] : [];
+    const parent = typeof data['parent_tool_use_id'] === 'string' ? data['parent_tool_use_id'] : null;
+    const events = [];
+    if (type === 'assistant') {
+        const usage = usageEvent(message['id'], message['model'], message['usage'], requests);
+        if (usage)
+            events.push(usage);
+    }
+    for (const block of blocks) {
+        if (type === 'assistant' && block.type === 'tool_use' && block.name) {
+            if (SPAWN_TOOLS.has(block.name) && block.id) {
+                events.push({
+                    type: 'role-start',
+                    toolUseId: block.id,
+                    role: String(block.input?.['subagent_type'] ?? 'general-purpose'),
+                    description: short(block.input?.['description'] ?? '', 100),
+                });
+            }
+            else {
+                const text = describeTool(block.name, block.input);
+                if (block.id)
+                    calls.set(block.id, text);
+                events.push({ type: 'activity', agent: parent, text });
+            }
+        }
+        else if (type === 'assistant' && block.type === 'text' && block.text && parent === null) {
+            events.push({ type: 'text', text: block.text });
+        }
+        else if (type === 'user' && block.type === 'tool_result' && block.tool_use_id) {
+            // Only the end of a subagent matters; other tool results are left out.
+            events.push({ type: 'role-end', toolUseId: block.tool_use_id, ok: block.is_error !== true });
+        }
+    }
+    return events;
+}

package/dist/engine/hubData.js

@@ -0,0 +1,176 @@
+import { existsSync, readdirSync, readFileSync, rmSync, statSync } from 'node:fs';
+import { isAbsolute, join, relative, resolve } from 'node:path';
+import { exec as defaultExec, succeeded } from '../core/exec.js';
+import { parsePorcelain } from '../hub/hub.js';
+/**
+ * What the layers leave in the Hub, read for /plans, /records and the checks after a run.
+ * Plan packages sit at the Hub root by default and records under .agents/evals/records/; both are ignored by
+ * Git and never leave the user's machine. Each is matched to the current target repository by its target_repo.
+ */
+export const PLAN_SET = /^[a-z0-9]+(?:-[a-z0-9]+)*_\d{8}-\d{6}$/;
+export const RECORDS_DIR = '.agents/evals/records';
+const GIT_FLAGS = ['-c', 'core.autocrlf=false', '-c', 'commit.gpgsign=false'];
+export function readFrontmatter(text) {
+    const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text);
+    const fields = {};
+    for (const line of match?.[1]?.split(/\r?\n/) ?? []) {
+        const field = /^([a-z_]+):\s*(.*)$/.exec(line);
+        if (field)
+            fields[field[1]] = unquote(field[2].trim());
+    }
+    return fields;
+}
+/** A quoted value as the framework's validator reads it: backslashes kept, so Windows paths stay intact. */
+function unquote(value) {
+    if (value.length >= 2 && value[0] === "'" && value.endsWith("'"))
+        return value.slice(1, -1).replace(/''/g, "'");
+    if (value.length >= 2 && value[0] === '"' && value.endsWith('"'))
+        return value.slice(1, -1).replace(/\\(["\\])/g, '$1');
+    return value;
+}
+/** A target_repo value names the same repository as `target`: absolute, or relative to the Hub root. */
+export function sameRepo(value, hub, target) {
+    if (!value)
+        return false;
+    const path = isAbsolute(value) || /^[A-Za-z]:[\\/]/.test(value) ? value : join(hub, value);
+    const a = resolve(path).replace(/[\\/]+$/, '');
+    const b = resolve(target).replace(/[\\/]+$/, '');
+    return process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b;
+}
+const markdownFiles = (dir) => readdirSync(dir, { withFileTypes: true }).flatMap(entry => entry.isDirectory() ? markdownFiles(join(dir, entry.name)) : entry.name.endsWith('.md') ? [join(dir, entry.name)] : []);
+export function listPlanSets(hub) {
+    if (!existsSync(hub))
+        return [];
+    return readdirSync(hub, { withFileTypes: true })
+        .filter(entry => entry.isDirectory() && PLAN_SET.test(entry.name))
+        .map(entry => entry.name);
+}
+/** Plan packages at the Hub root whose tasks target `target`, newest first. */
+export function readPlanPackages(hub, target) {
+    const packages = [];
+    for (const planSet of listPlanSets(hub)) {
+        const dir = join(hub, planSet);
+        const tasks = [];
+        const reports = [];
+        let createdAt = '';
+        let matches = false;
+        for (const file of markdownFiles(dir)) {
+            const fields = readFrontmatter(readFileSync(file, 'utf8'));
+            if (fields['schema'] === 'pirl-plan/v1') {
+                matches ||= sameRepo(fields['target_repo'], hub, target);
+                createdAt ||= fields['created_at'] ?? '';
+                tasks.push({ taskId: fields['task_id'] ?? '?', title: fields['title'] ?? '', status: fields['status'] ?? '?', file });
+            }
+            else if (fields['schema'] === 'pirl-review/v1') {
+                reports.push({ taskId: fields['task_id'] ?? '?', round: Number(fields['review_round'] ?? 0), verdict: fields['verdict'] ?? '?', file });
+            }
+        }
+        if (matches) {
+            tasks.sort((a, b) => a.taskId.localeCompare(b.taskId));
+            reports.sort((a, b) => a.taskId.localeCompare(b.taskId) || a.round - b.round);
+            packages.push({ planSet, dir, createdAt, tasks, reports });
+        }
+    }
+    return packages.sort((a, b) => b.planSet.slice(-15).localeCompare(a.planSet.slice(-15)));
+}
+/** Self-evaluation records whose target_repo is `target`, newest first. Unreadable lines are skipped. */
+export function readRecords(hub, target) {
+    const root = join(hub, RECORDS_DIR);
+    if (!existsSync(root))
+        return [];
+    const records = [];
+    for (const layer of readdirSync(root)) {
+        const dir = join(root, layer);
+        if (!statSync(dir).isDirectory())
+            continue;
+        for (const file of readdirSync(dir).filter(name => name.endsWith('.jsonl'))) {
+            for (const line of readFileSync(join(dir, file), 'utf8').split('\n')) {
+                if (!line.trim())
+                    continue;
+                try {
+                    const data = JSON.parse(line);
+                    if (target && !sameRepo(data['target_repo'], hub, target))
+                        continue;
+                    const fixes = Array.isArray(data['fixes']) ? data['fixes'] : [];
+                    records.push({
+                        recordId: String(data['record_id'] ?? ''),
+                        layer: String(data['layer'] ?? layer),
+                        recordedAt: String(data['recorded_at'] ?? ''),
+                        status: String(data['outcome']?.['status'] ?? ''),
+                        summary: String(data['outcome']?.['summary'] ?? ''),
+                        planSet: data['task']?.['plan_set'] ?? null,
+                        fixes: fixes.filter((fix) => fix?.status === 'applied').length,
+                        pending: fixes.filter((fix) => fix?.status === 'pending_user').length,
+                        data,
+                    });
+                }
+                catch { }
+            }
+        }
+    }
+    return records.sort((a, b) => Date.parse(b.recordedAt) - Date.parse(a.recordedAt));
+}
+export function countRecords(hub, layer) {
+    const dir = join(hub, RECORDS_DIR, layer);
+    if (!existsSync(dir))
+        return 0;
+    return readdirSync(dir)
+        .filter(name => name.endsWith('.jsonl'))
+        .reduce((sum, name) => sum + readFileSync(join(dir, name), 'utf8').split('\n').filter(line => line.trim()).length, 0);
+}
+/** Paths with uncommitted changes in a repository (the Hub, or the target after Implement). */
+export async function changedPaths(repo, exec = defaultExec) {
+    const result = await exec('git', [...GIT_FLAGS, 'status', '--porcelain', '-z', '--untracked-files=all'], { cwd: repo, timeoutMs: 30_000 });
+    return succeeded(result) ? parsePorcelain(result.stdout) : [];
+}
+/**
+ * Commits framework improvements the user approved, with trailers that let /framework explain each change later.
+ * Uses the user's Git identity, or a neutral one when none is configured.
+ */
+export async function commitImprovements(hub, files, info, exec = defaultExec) {
+    const add = await exec('git', [...GIT_FLAGS, 'add', '--', ...files], { cwd: hub, timeoutMs: 30_000 });
+    if (!succeeded(add))
+        return { ok: false, error: add.stderr || add.error };
+    const name = await exec('git', ['config', 'user.name'], { cwd: hub });
+    const identity = succeeded(name) && name.stdout.trim() ? [] : ['-c', 'user.name=PIRL CLI user', '-c', 'user.email=pirl-cli@localhost'];
+    const message = [
+        `Framework improvement from a ${info.kind} run`,
+        '',
+        info.summary,
+        '',
+        ...(info.recordId ? [`Pirl-Record: ${info.recordId}`] : []),
+        'Pirl-Source: auditor',
+    ].join('\n');
+    const commit = await exec('git', [...GIT_FLAGS, ...identity, 'commit', '--quiet', '-m', message, '--', ...files], { cwd: hub, timeoutMs: 30_000 });
+    return succeeded(commit) ? { ok: true } : { ok: false, error: commit.stderr || commit.error };
+}
+/** Throws away improvements the user rejected: tracked files go back to the last commit, new files are removed. */
+export async function discardImprovements(hub, files, exec = defaultExec) {
+    const tracked = [];
+    for (const file of files) {
+        const known = await exec('git', ['ls-files', '--error-unmatch', '--', file], { cwd: hub });
+        if (succeeded(known))
+            tracked.push(file);
+        else
+            rmSync(join(hub, file), { force: true });
+    }
+    if (tracked.length === 0)
+        return { ok: true };
+    const restore = await exec('git', [...GIT_FLAGS, 'restore', '--source=HEAD', '--staged', '--worktree', '--', ...tracked], { cwd: hub, timeoutMs: 30_000 });
+    return succeeded(restore) ? { ok: true } : { ok: false, error: restore.stderr || restore.error };
+}
+/** Paths from the Plan's "Allowed paths" line, in backticks. A trailing slash or /** covers a whole directory. */
+export function allowedPaths(planText) {
+    const line = planText.split('\n').find(text => /allowed paths:/i.test(text));
+    return line ? [...line.matchAll(/`([^`]+)`/g)].map(match => match[1].trim()).filter(Boolean) : [];
+}
+export function outsideAllowed(changed, allowed) {
+    if (allowed.length === 0)
+        return [];
+    const normalized = allowed.map(path => path.replace(/\\/g, '/').replace(/\/\*\*$/, '/').replace(/^\.\//, ''));
+    return changed.filter(file => {
+        const path = file.replace(/\\/g, '/');
+        return !normalized.some(allow => (allow.endsWith('/') ? path.startsWith(allow) : path === allow || path.startsWith(`${allow}/`)));
+    });
+}
+export const relativeTo = (base, path) => relative(base, path) || '.';

package/dist/engine/permissions.js

@@ -0,0 +1,67 @@
+/**
+ * Claude Code permission rules for one run (proposal section 7.2). The run uses permission mode `dontAsk`:
+ * anything not allowed here is refused, so no prompt can stall a run nobody can answer.
+ * Absolute paths are written as `//path`; Windows paths become `//d/Project/...`.
+ */
+export function ruleRoot(path) {
+    const posix = path.replace(/\\/g, '/');
+    const drive = /^([A-Za-z]):\/?(.*)$/.exec(posix);
+    const absolute = drive ? `/${drive[1].toLowerCase()}/${drive[2]}` : posix;
+    return `/${absolute.replace(/\/+$/, '')}`;
+}
+/** Commands the framework's tools need, from the Hub: record, validator, helper scripts, framework tests. */
+export function pythonRules(python) {
+    const prefix = [python.command, ...python.args, '-B'].join(' ');
+    return [`Bash(${prefix} .agents/evals/*)`, `Bash(${prefix} .skills/*)`, `Bash(${prefix} -m unittest *)`];
+}
+const READ_TOOLS = ['Read', 'Grep', 'Glob', 'Agent', 'TodoWrite'];
+const GIT_READ_SUBCOMMANDS = ['log', 'show', 'diff', 'status', 'ls-files', 'rev-parse', 'blame'];
+const GIT_READ = GIT_READ_SUBCOMMANDS.map(command => `Bash(git ${command} *)`);
+/** Read-only Git in another repository, as `git -C <path> log ...` with the path written exactly as given. */
+const gitReadIn = (path) => GIT_READ_SUBCOMMANDS.map(command => `Bash(git -C ${path} ${command} *)`);
+/**
+ * Tools that make a headless run wait: scheduled wakeups, timers and watches keep `claude -p` open until they
+ * fire, so a run would never end. Removed from every run; the runner also turns background work off.
+ */
+export const WAITING_TOOLS = ['ScheduleWakeup', 'CronCreate', 'CronDelete', 'Monitor', 'RemoteTrigger'];
+/** Functional tests under FUT; the target repository's documentation says which one applies. */
+export const TEST_RUNNERS = [
+    'npm test',
+    'npm run test',
+    'pnpm test',
+    'pnpm run test',
+    'yarn test',
+    'bun test',
+    'npx vitest',
+    'npx jest',
+    'pytest',
+    'python -m pytest',
+    'python3 -m pytest',
+    'py -m pytest',
+    'go test',
+    'cargo test',
+    'dotnet test',
+    'mvn test',
+    'gradle test',
+    './gradlew test',
+    'php artisan test',
+    'vendor/bin/phpunit',
+].map(command => `Bash(${command} *)`);
+/** Never allowed in any run: the framework leaves commits, pushes and destructive Git operations to the user. */
+const ALWAYS_DENY = ['git commit', 'git push', 'git reset', 'git clean', 'git checkout', 'git switch', 'git stash', 'git rebase', 'git merge', 'git tag', 'rm'].map(command => `Bash(${command} *)`);
+export function permissionsFor(kind, paths, python) {
+    const hub = ruleRoot(paths.hub);
+    const target = paths.target ? ruleRoot(paths.target) : null;
+    const sameRoot = target === hub;
+    const allow = [...READ_TOOLS, ...GIT_READ, ...gitReadIn(paths.hub), ...(paths.target ? gitReadIn(paths.target) : []), ...(python ? pythonRules(python) : []), `Edit(${hub}/**)`];
+    const deny = [...WAITING_TOOLS, ...ALWAYS_DENY];
+    if (target && !sameRoot) {
+        if (kind === 'implement' || kind === 'chat')
+            allow.push(`Edit(${target}/**)`);
+        else
+            deny.push(`Edit(${target}/**)`);
+    }
+    if (kind === 'implement')
+        allow.push(...TEST_RUNNERS);
+    return { allow, deny };
+}

package/dist/engine/pricing.js

@@ -0,0 +1,24 @@
+const PRICES = [
+    { match: /fable|mythos/, price: { input: 10, write5m: 12.5, write1h: 20, read: 0.25, output: 50 } },
+    { match: /opus-5-5/, price: { input: 4, write5m: 5, write1h: 8, read: 0.2, output: 20 } },
+    { match: /opus/, price: { input: 5, write5m: 6.25, write1h: 10, read: 0.5, output: 25 } },
+    { match: /sonnet-5-5/, price: { input: 2, write5m: 2.5, write1h: 4, read: 0.1, output: 10 } },
+    { match: /sonnet/, price: { input: 2, write5m: 2.5, write1h: 4, read: 0.2, output: 10 } },
+    // Haiku 5.5 costs more for prompts over 100k tokens; a role's prompt rarely gets there.
+    { match: /haiku-5-5/, price: { input: 0.1, write5m: 0.125, write1h: 0.2, read: 0.01, output: 0.5 } },
+    { match: /haiku/, price: { input: 1, write5m: 1.25, write1h: 2, read: 0.1, output: 5 } },
+];
+export const priceOf = (model) => PRICES.find(entry => entry.match.test(model.toLowerCase()))?.price ?? null;
+/** `cacheWrite1h` is the part of the cache writes kept for an hour; the rest is priced as 5-minute writes. */
+export function costUsd(model, usage) {
+    const price = priceOf(model);
+    if (!price)
+        return null;
+    const long = Math.min(usage.cacheWrite1h ?? 0, usage.cacheWriteTokens);
+    return ((usage.inputTokens * price.input +
+        long * price.write1h +
+        (usage.cacheWriteTokens - long) * price.write5m +
+        usage.cacheReadTokens * price.read +
+        usage.outputTokens * price.output) /
+        1_000_000);
+}