@njeybe/nativ 2.4.0 → 2.5.0

package/dist/runner/cli-config.d.ts

@@ -0,0 +1,84 @@
+import type { MasterPlanTask } from '../scanner/types.js';
+/** Credentials never reach the model's shell: it could print them. */
+export declare const SECRET_ENV_PATTERN: RegExp;
+export declare const CLAUDE_CODE_AUTH_ENV: RegExp;
+export declare const AWS_ENV: RegExp;
+/**
+ * What a dispatched agent may run without asking. `claude -p` cannot prompt, so anything not listed here is
+ * denied and the agent blocks or escalates instead of running it.
+ */
+export declare const RUNNER_BASE_ALLOWED_TOOLS: string[];
+/** The pieces of a compound command as Claude Code matches them: each must satisfy an allow rule on its own. */
+export declare function splitCompoundCommand(command: string): string[];
+/** Operator-supplied extra rules from NATIV_RUNNER_ALLOW, comma separated, e.g. `Bash(pnpm test *),Bash(cargo test *)`. */
+export declare function parseRunnerAllowList(raw: string | undefined): string[];
+export interface RunnerPermissions {
+    permissions: {
+        allow: string[];
+        deny: string[];
+        ask: string[];
+    };
+    /** Omitted when the project's own settings already run the enforcement hook, so it never runs (and logs) twice. */
+    hooks?: {
+        PreToolUse: Array<{
+            matcher: string;
+            hooks: Array<{
+                type: 'command';
+                command: string;
+                timeout: number;
+            }>;
+        }>;
+    };
+}
+/** True when `.claude/settings.json` already registers a nativ `hook check` command. */
+export declare function projectHasEnforcementHook(rootDir: string): boolean;
+/**
+ * Settings handed to a dispatched agent with `--settings`. The deny and ask rules and the enforcement hook come
+ * from the same source as `nativ setup`, so a dispatched agent is guarded even in a project where setup never ran.
+ */
+export declare function buildRunnerPermissions(task: Pick<MasterPlanTask, 'verificationCommand'>, rootDir: string, extraAllowed?: readonly string[]): RunnerPermissions;
+/** Where a task's runner settings live: a subdirectory, because run history parses every top-level .json in runs/. */
+export declare function runnerSettingsPath(runsDir: string, taskId: string): string;
+export declare function writeRunnerSettings(runsDir: string, taskId: string, settings: RunnerPermissions): string;
+/** The instructions text handed to the agent on its standard input. */
+export declare function buildRunnerPrompt(task: MasterPlanTask): string;
+/**
+ * Arguments for Claude Code CLI to run headless. The prompt goes on stdin, never in this string:
+ * quotes or symbols in task text would break the shell.
+ *
+ * It runs in `acceptEdits` mode with the rules in `settingsFile` (see buildRunnerPermissions); it does not bypass
+ * permissions. Without a settings file only the file-edit tools and read-only commands are pre-approved.
+ */
+export declare function buildDefaultClaudeCommand(_task: MasterPlanTask, model?: string | null, settingsFile?: string): string;
+/** True when a runner command asks Claude Code for its line-delimited JSON event stream. */
+export declare function usesClaudeStreamJson(command: string): boolean;
+/** Final `result` event of a Claude Code stream: grounded usage for cli runs. */
+export interface ClaudeStreamResult {
+    isError: boolean;
+    turns: number;
+    costUsd: number | null;
+    inputTokens: number;
+    outputTokens: number;
+    cacheCreationTokens: number;
+    cacheReadTokens: number;
+}
+export interface ClaudeStreamLine {
+    /** Human-readable log text (newline-terminated), or null when the event is not worth showing. */
+    text: string | null;
+    model?: string;
+    result?: ClaudeStreamResult;
+}
+/**
+ * Turns one line of `claude -p --output-format stream-json` into a log line. Anything that is not
+ * a recognised event (warnings, custom runners, future event types) passes through or is dropped,
+ * never thrown on.
+ */
+export declare function formatClaudeStreamLine(line: string): ClaudeStreamLine;
+/**
+ * Environment for cli runners. The agent inside can run the commands its allowlist permits (and any custom
+ * runner command runs unrestricted), so it can print anything it inherits: credential-looking variables are
+ * withheld, except the ones Claude Code itself authenticates with (and AWS credentials when it is configured for Bedrock).
+ * NATIV_RUNNER_PASS_ENV="NAME1,NAME2" passes extra variables through deliberately; variables an
+ * operator hands to dispatch() explicitly are also passed as-is.
+ */
+export declare function buildRunnerEnv(base: NodeJS.ProcessEnv, explicit?: Record<string, string>): NodeJS.ProcessEnv;

package/dist/runner/cli-config.js

@@ -0,0 +1,215 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { buildDesiredConfig, cliString, configuredInvocation, resolveCliInvocation, } from '../core/setup-assets.js';
+/** Credentials never reach the model's shell: it could print them. */
+export const SECRET_ENV_PATTERN = /^ANTHROPIC_|^CLAUDE_CODE_OAUTH|SECRET|TOKEN|PASSWORD|PASSWD|API_KEY|PRIVATE_KEY|DATABASE_URL|_DSN$|CREDENTIAL/i;
+export const CLAUDE_CODE_AUTH_ENV = /^(ANTHROPIC_(API_KEY|AUTH_TOKEN|BASE_URL|MODEL|SMALL_FAST_MODEL|CUSTOM_HEADERS|BETAS|VERTEX_PROJECT_ID)|CLAUDE_CODE_[A-Z0-9_]+|CLAUDE_CONFIG_DIR|CLOUD_ML_REGION|VERTEX_REGION_[A-Z0-9_]+)$/;
+export const AWS_ENV = /^AWS_[A-Z0-9_]+$/;
+/**
+ * What a dispatched agent may run without asking. `claude -p` cannot prompt, so anything not listed here is
+ * denied and the agent blocks or escalates instead of running it.
+ */
+export const RUNNER_BASE_ALLOWED_TOOLS = [
+    'Bash(nativ *)',
+    'Bash(git status *)',
+    'Bash(git diff *)',
+    'Bash(git log *)',
+    'Bash(git add *)',
+    'Bash(git commit *)',
+    'Bash(git checkout -- *)',
+];
+/** The pieces of a compound command as Claude Code matches them: each must satisfy an allow rule on its own. */
+export function splitCompoundCommand(command) {
+    return [...new Set(command.split(/&&|\|\||[;|\n]/).map((part) => part.trim()).filter(Boolean))];
+}
+/** Operator-supplied extra rules from NATIV_RUNNER_ALLOW, comma separated, e.g. `Bash(pnpm test *),Bash(cargo test *)`. */
+export function parseRunnerAllowList(raw) {
+    return String(raw ?? '')
+        .split(',')
+        .map((rule) => rule.trim())
+        .filter((rule) => /^[A-Za-z_][A-Za-z0-9_]*(\(.*\))?$/.test(rule));
+}
+/** True when `.claude/settings.json` already registers a nativ `hook check` command. */
+export function projectHasEnforcementHook(rootDir) {
+    try {
+        const text = fs.readFileSync(path.join(rootDir, '.claude', 'settings.json'), 'utf8');
+        return /"command"\s*:\s*"[^"]*\bhook check\b/.test(text);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Settings handed to a dispatched agent with `--settings`. The deny and ask rules and the enforcement hook come
+ * from the same source as `nativ setup`, so a dispatched agent is guarded even in a project where setup never ran.
+ */
+export function buildRunnerPermissions(task, rootDir, extraAllowed = []) {
+    const invocation = configuredInvocation(rootDir) ?? resolveCliInvocation({});
+    const desired = buildDesiredConfig(invocation);
+    const cli = cliString(invocation);
+    const allow = [
+        ...RUNNER_BASE_ALLOWED_TOOLS,
+        ...(cli === 'nativ' ? [] : [`Bash(${cli} *)`]),
+        ...splitCompoundCommand(task.verificationCommand ?? '').map((command) => `Bash(${command})`),
+        ...extraAllowed,
+    ];
+    return {
+        permissions: { allow: [...new Set(allow)], deny: desired.deny, ask: desired.ask },
+        ...(projectHasEnforcementHook(rootDir)
+            ? {}
+            : { hooks: { PreToolUse: [{ matcher: desired.preToolUse.matcher, hooks: [{ type: 'command', command: desired.preToolUse.command, timeout: desired.preToolUse.timeout }] }] } }),
+    };
+}
+/** Where a task's runner settings live: a subdirectory, because run history parses every top-level .json in runs/. */
+export function runnerSettingsPath(runsDir, taskId) {
+    return path.join(runsDir, 'permissions', `${taskId}.json`).replace(/\\/g, '/');
+}
+export function writeRunnerSettings(runsDir, taskId, settings) {
+    const file = runnerSettingsPath(runsDir, taskId);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(settings, null, 2) + '\n', 'utf8');
+    return file;
+}
+/** The instructions text handed to the agent on its standard input. */
+export function buildRunnerPrompt(task) {
+    return [
+        `Execute task ${task.id} (${task.title}).`,
+        task.description ? `Description: ${task.description}.` : '',
+        task.verificationCommand ? `Verify your work using: ${task.verificationCommand}.` : '',
+        `Start by running: nativ task start ${task.id}. When finished and verified, run: nativ task complete ${task.id}.`,
+        `If blocked, follow the Human-Centric Communication Protocol in CLAUDE.md: explain the user experience symptom, root cause in plain English, and clear options without technical jargon.`,
+    ]
+        .filter(Boolean)
+        .join(' ');
+}
+/**
+ * Arguments for Claude Code CLI to run headless. The prompt goes on stdin, never in this string:
+ * quotes or symbols in task text would break the shell.
+ *
+ * It runs in `acceptEdits` mode with the rules in `settingsFile` (see buildRunnerPermissions); it does not bypass
+ * permissions. Without a settings file only the file-edit tools and read-only commands are pre-approved.
+ */
+export function buildDefaultClaudeCommand(_task, model, settingsFile) {
+    const modelFlag = model ? ` --model ${model}` : '';
+    // Plain `claude -p` prints nothing until it finishes; stream-json emits every message and tool call as it happens.
+    const settingsFlag = settingsFile ? ` --settings "${settingsFile}"` : '';
+    return `claude -p${modelFlag} --output-format stream-json --verbose --permission-mode acceptEdits${settingsFlag}`;
+}
+/** True when a runner command asks Claude Code for its line-delimited JSON event stream. */
+export function usesClaudeStreamJson(command) {
+    return /--output-format(?:=|\s+)stream-json\b/.test(command);
+}
+function firstLine(text, max = 200) {
+    const line = String(text ?? '').split('\n').find((l) => l.trim()) ?? '';
+    return line.length > max ? `${line.slice(0, max)}...` : line.trim();
+}
+function describeToolInput(input) {
+    if (!input || typeof input !== 'object')
+        return '';
+    const i = input;
+    const pick = i.command ?? i.file_path ?? i.path ?? i.pattern ?? i.url ?? i.description;
+    return typeof pick === 'string' ? firstLine(pick, 160) : firstLine(JSON.stringify(input), 160);
+}
+const finiteCount = (value) => (typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : 0);
+/**
+ * Turns one line of `claude -p --output-format stream-json` into a log line. Anything that is not
+ * a recognised event (warnings, custom runners, future event types) passes through or is dropped,
+ * never thrown on.
+ */
+export function formatClaudeStreamLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed)
+        return { text: null };
+    let event;
+    try {
+        event = JSON.parse(trimmed);
+    }
+    catch {
+        return { text: `${line}\n` };
+    }
+    if (!event || typeof event !== 'object' || Array.isArray(event))
+        return { text: `${line}\n` };
+    switch (event.type) {
+        case 'system': {
+            if (event.subtype !== 'init')
+                return { text: null };
+            const model = typeof event.model === 'string' ? event.model : undefined;
+            const tools = Array.isArray(event.tools) ? ` · ${event.tools.length} tools` : '';
+            return { text: `[claude] session started · model ${model ?? 'default'}${tools}\n`, model };
+        }
+        case 'assistant': {
+            const lines = [];
+            for (const block of Array.isArray(event.message?.content) ? event.message.content : []) {
+                if (block?.type === 'text' && String(block.text ?? '').trim())
+                    lines.push(String(block.text).trim());
+                else if (block?.type === 'thinking' && String(block.thinking ?? '').trim())
+                    lines.push(`[claude:thinking] ${firstLine(block.thinking, 300)}`);
+                else if (block?.type === 'tool_use')
+                    lines.push(`[claude] ${block.name}: ${describeToolInput(block.input)}`);
+            }
+            return { text: lines.length ? `${lines.join('\n')}\n` : null };
+        }
+        case 'user': {
+            const lines = [];
+            for (const block of Array.isArray(event.message?.content) ? event.message.content : []) {
+                if (block?.type !== 'tool_result')
+                    continue;
+                const body = typeof block.content === 'string'
+                    ? block.content
+                    : Array.isArray(block.content) ? block.content.map((c) => c?.text ?? '').join('\n') : '';
+                const summary = firstLine(body, 160);
+                if (block.is_error)
+                    lines.push(`[claude]   error: ${summary || 'tool failed'}`);
+                else if (summary)
+                    lines.push(`[claude]   ${summary}`);
+            }
+            return { text: lines.length ? `${lines.join('\n')}\n` : null };
+        }
+        case 'result': {
+            const usage = event.usage ?? {};
+            const cost = typeof event.total_cost_usd === 'number' && Number.isFinite(event.total_cost_usd) ? event.total_cost_usd : null;
+            const turns = finiteCount(event.num_turns);
+            const seconds = finiteCount(event.duration_ms) ? ` · ${Math.round(event.duration_ms / 1000)}s` : '';
+            const kind = event.subtype && event.subtype !== 'success' ? ` (${event.subtype})` : '';
+            const text = `[claude] ${event.is_error ? 'finished with an error' : 'finished'}${kind}` +
+                (turns ? ` · ${turns} turns` : '') + (cost !== null ? ` · $${cost.toFixed(4)}` : '') + seconds + '\n';
+            return {
+                text,
+                result: {
+                    isError: Boolean(event.is_error),
+                    turns,
+                    costUsd: cost,
+                    inputTokens: finiteCount(usage.input_tokens),
+                    outputTokens: finiteCount(usage.output_tokens),
+                    cacheCreationTokens: finiteCount(usage.cache_creation_input_tokens),
+                    cacheReadTokens: finiteCount(usage.cache_read_input_tokens),
+                },
+            };
+        }
+        default:
+            return { text: null };
+    }
+}
+/**
+ * Environment for cli runners. The agent inside can run the commands its allowlist permits (and any custom
+ * runner command runs unrestricted), so it can print anything it inherits: credential-looking variables are
+ * withheld, except the ones Claude Code itself authenticates with (and AWS credentials when it is configured for Bedrock).
+ * NATIV_RUNNER_PASS_ENV="NAME1,NAME2" passes extra variables through deliberately; variables an
+ * operator hands to dispatch() explicitly are also passed as-is.
+ */
+export function buildRunnerEnv(base, explicit) {
+    const passThrough = new Set(String(base.NATIV_RUNNER_PASS_ENV ?? '')
+        .split(',')
+        .map((name) => name.trim())
+        .filter(Boolean));
+    const bedrock = Boolean(base.CLAUDE_CODE_USE_BEDROCK);
+    const env = {};
+    for (const [key, value] of Object.entries(base)) {
+        if (value === undefined)
+            continue;
+        const allowed = !SECRET_ENV_PATTERN.test(key) || CLAUDE_CODE_AUTH_ENV.test(key) || passThrough.has(key) || (bedrock && AWS_ENV.test(key));
+        if (allowed)
+            env[key] = value;
+    }
+    return { ...env, ...explicit };
+}

package/dist/runner/native-driver.d.ts

@@ -0,0 +1,18 @@
+import type { MasterPlanTask } from '../scanner/types.js';
+import { type ActualTokenUsage } from '../core/telemetry.js';
+import { type ActiveRun, type RunnerRecord } from './types.js';
+export interface NativeDriverContext {
+    rootDir: string;
+    nativeMaxTurns: number;
+    nativeToolTimeoutMs: number;
+    nativeAllowedCommands: ReadonlySet<string>;
+    toolShell: string | boolean;
+    appendLog: (run: ActiveRun, stream: 'stdout' | 'stderr', chunk: string) => void;
+    onTurnUsage: (record: RunnerRecord, delta: ActualTokenUsage, model: string) => void;
+}
+export declare function readRoleGuide(rootDir: string, task: MasterPlanTask): string | null;
+/**
+ * Manual agentic loop over the Messages API: stream a turn, capture usage,
+ * execute the requested local tools, repeat until the model ends its turn.
+ */
+export declare function runNativeLoop(ctx: NativeDriverContext, run: ActiveRun, useWorktree: boolean): Promise<void>;

package/dist/runner/native-driver.js

@@ -0,0 +1,208 @@
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { computeActualCostUsd, emptyActualUsage, mergeActualUsage, } from '../core/telemetry.js';
+import { NATIVE_MAX_OUTPUT_TOKENS, } from './types.js';
+import { killProcessTree } from './process-utils.js';
+import { NATIVE_TOOLS, ToolInputError, buildToolEnv, checkNativeBashCommand, clipToolOutput, requireString, runEditorCommand, } from './native-tools.js';
+import { NATIVE_SYSTEM_PROMPT, buildNativeTaskPrompt, supportsServerFallback, } from './native-engine.js';
+const NATIVE_TOOL_CAPTURE_LIMIT = 1024 * 1024;
+const ROLE_GUIDE_LIMIT = 20_000;
+const SERVER_FALLBACK_BETA = 'server-side-fallback-2026-07-01';
+export function readRoleGuide(rootDir, task) {
+    if (!/^[\w-]+$/.test(task.assignedSubagent || ''))
+        return null;
+    try {
+        const text = fs.readFileSync(path.join(rootDir, '.ai', 'subagents', `${task.assignedSubagent}.md`), 'utf8');
+        return text.length > ROLE_GUIDE_LIMIT ? `${text.slice(0, ROLE_GUIDE_LIMIT)}\n[... truncated ...]` : text;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Manual agentic loop over the Messages API: stream a turn, capture usage,
+ * execute the requested local tools, repeat until the model ends its turn.
+ */
+export async function runNativeLoop(ctx, run, useWorktree) {
+    const native = run.native;
+    const { thinking } = native;
+    const fallback = supportsServerFallback(native.model);
+    const messages = [
+        { role: 'user', content: buildNativeTaskPrompt(run.task, readRoleGuide(ctx.rootDir, run.task), useWorktree, ctx.rootDir) },
+    ];
+    for (let turn = 1;; turn++) {
+        if (run.settled)
+            return;
+        if (turn > ctx.nativeMaxTurns) {
+            throw new Error(`Native engine stopped after the ${ctx.nativeMaxTurns}-turn budget without finishing`);
+        }
+        const stream = native.client.beta.messages.stream({
+            model: native.model,
+            max_tokens: NATIVE_MAX_OUTPUT_TOKENS,
+            system: [{ type: 'text', text: NATIVE_SYSTEM_PROMPT, cache_control: { type: 'ephemeral' } }],
+            cache_control: { type: 'ephemeral' },
+            tools: NATIVE_TOOLS,
+            messages,
+            ...(thinking.budgetTokens
+                ? { thinking: { type: 'enabled', budget_tokens: thinking.budgetTokens } }
+                : thinking.effort
+                    ? { thinking: { type: 'adaptive', display: 'summarized' } }
+                    : {}),
+            ...(thinking.effort ? { output_config: { effort: thinking.effort } } : {}),
+            ...(fallback ? { betas: [SERVER_FALLBACK_BETA], fallbacks: 'default' } : {}),
+        }, { signal: native.controller.signal });
+        let streaming = null;
+        const switchTo = (kind) => {
+            if (streaming === kind)
+                return;
+            ctx.appendLog(run, 'stdout', `${streaming ? '\n' : ''}${kind === 'thinking' ? '[native:thinking] ' : ''}`);
+            streaming = kind;
+        };
+        stream.on('thinking', (delta) => {
+            if (!delta)
+                return;
+            switchTo('thinking');
+            ctx.appendLog(run, 'stdout', delta);
+        });
+        stream.on('text', (delta) => {
+            switchTo('text');
+            ctx.appendLog(run, 'stdout', delta);
+        });
+        const message = await stream.finalMessage();
+        if (streaming)
+            ctx.appendLog(run, 'stdout', '\n');
+        if (run.settled)
+            return;
+        recordTurnUsage(ctx, run, message);
+        if (message.stop_reason === 'refusal') {
+            const category = message.stop_details?.category;
+            throw new Error(`Model declined the task (refusal${category ? `: ${category}` : ''})`);
+        }
+        if (message.stop_reason === 'pause_turn') {
+            messages.push({ role: 'assistant', content: message.content });
+            continue;
+        }
+        const toolUses = message.content.filter((b) => b.type === 'tool_use');
+        if (message.stop_reason === 'max_tokens') {
+            throw new Error(`Model output hit max_tokens (${NATIVE_MAX_OUTPUT_TOKENS}) mid-turn`);
+        }
+        if (toolUses.length === 0)
+            return;
+        messages.push({ role: 'assistant', content: message.content });
+        const results = [];
+        for (const block of toolUses) {
+            if (run.settled)
+                return;
+            results.push(await executeNativeTool(ctx, run, block));
+        }
+        messages.push({ role: 'user', content: results });
+    }
+}
+function recordTurnUsage(ctx, run, message) {
+    const { record } = run;
+    const usage = message.usage;
+    const model = message.model || run.native.model;
+    const details = usage.output_tokens_details;
+    const slice = {
+        inputTokens: usage.input_tokens ?? 0,
+        outputTokens: usage.output_tokens ?? 0,
+        cacheCreationTokens: usage.cache_creation_input_tokens ?? 0,
+        cacheReadTokens: usage.cache_read_input_tokens ?? 0,
+    };
+    const delta = {
+        model,
+        turns: 1,
+        ...slice,
+        thinkingTokens: details?.thinking_tokens ?? 0,
+        costUsd: computeActualCostUsd(model, slice),
+    };
+    record.usage = mergeActualUsage(record.usage ?? emptyActualUsage(model), delta);
+    ctx.appendLog(run, 'stdout', `[native] turn ${record.usage.turns}: in ${delta.inputTokens} · out ${delta.outputTokens}` +
+        ` · cache read ${delta.cacheReadTokens} / write ${delta.cacheCreationTokens} · $${delta.costUsd.toFixed(4)}\n`);
+    ctx.onTurnUsage(record, delta, model);
+}
+async function executeNativeTool(ctx, run, block) {
+    const input = (block.input && typeof block.input === 'object' ? block.input : {});
+    try {
+        let content;
+        if (block.name === 'bash') {
+            content = await runBashTool(ctx, run, input);
+        }
+        else if (block.name === 'str_replace_based_edit_tool') {
+            ctx.appendLog(run, 'stdout', `[native] edit ${String(input.command)} ${String(input.path)}\n`);
+            content = runEditorCommand(run.record.worktreeDir, ctx.rootDir, input);
+        }
+        else {
+            throw new ToolInputError(`Unknown tool '${block.name}'.`);
+        }
+        return { type: 'tool_result', tool_use_id: block.id, content };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        ctx.appendLog(run, 'stderr', `[native] ${block.name} error: ${message.split('\n')[0]}\n`);
+        return { type: 'tool_result', tool_use_id: block.id, content: message, is_error: true };
+    }
+}
+async function runBashTool(ctx, run, input) {
+    if (input.restart === true)
+        return 'Shell restarted. Every command already starts in a fresh shell at the workspace root.';
+    const command = requireString(input, 'command').trim();
+    if (!command)
+        throw new ToolInputError('"command" must be a non-empty string.');
+    const rejection = checkNativeBashCommand(command, ctx.nativeAllowedCommands);
+    if (rejection)
+        throw new ToolInputError(`Command rejected: ${rejection}`);
+    ctx.appendLog(run, 'stdout', `[native] $ ${command}\n`);
+    const child = spawn(command, {
+        cwd: run.record.worktreeDir,
+        shell: ctx.toolShell,
+        detached: process.platform !== 'win32',
+        windowsHide: true,
+        stdio: ['ignore', 'pipe', 'pipe'],
+        env: {
+            ...buildToolEnv(process.env, run.native?.env),
+            NATIV_RUN_ID: run.record.runId,
+            NATIV_TASK_ID: run.record.taskId,
+            NATIV_PROJECT_ROOT: ctx.rootDir,
+        },
+    });
+    run.toolPid = child.pid ?? null;
+    let output = '';
+    let omitted = 0;
+    const capture = (chunk) => {
+        output += chunk.toString();
+        if (output.length > NATIVE_TOOL_CAPTURE_LIMIT) {
+            const head = Math.floor(NATIVE_TOOL_CAPTURE_LIMIT * 0.2);
+            const excess = output.length - NATIVE_TOOL_CAPTURE_LIMIT;
+            output = output.slice(0, head) + output.slice(head + excess);
+            omitted += excess;
+        }
+    };
+    child.stdout?.on('data', capture);
+    child.stderr?.on('data', capture);
+    let timedOut = false;
+    const timer = setTimeout(() => {
+        timedOut = true;
+        if (child.pid)
+            killProcessTree(child.pid, 'SIGKILL');
+    }, ctx.nativeToolTimeoutMs);
+    timer.unref?.();
+    const exitCode = await new Promise((resolve) => {
+        child.on('error', (err) => {
+            capture(Buffer.from(`\n${err.message}\n`));
+            resolve(null);
+        });
+        child.on('close', (code) => resolve(code));
+    });
+    clearTimeout(timer);
+    run.toolPid = null;
+    const clipped = clipToolOutput(output, omitted);
+    if (clipped)
+        ctx.appendLog(run, 'stdout', clipped.endsWith('\n') ? clipped : `${clipped}\n`);
+    if (timedOut) {
+        throw new ToolInputError(`Command exceeded the ${Math.round(ctx.nativeToolTimeoutMs / 1000)}s tool budget and was terminated.\n${clipped}`);
+    }
+    const body = clipped || '(no output)';
+    return exitCode === 0 ? body : `${body}\n[exit code ${exitCode ?? 'unknown'}]`;
+}

package/dist/runner/native-engine.d.ts

@@ -0,0 +1,27 @@
+import type { MasterPlanTask } from '../scanner/types.js';
+import { type RunnerEngine, type RunnerThinking, type ThinkingEffort } from './types.js';
+/** Models that predate adaptive thinking and still take `thinking.budget_tokens`. */
+export declare function usesLegacyThinkingBudget(model: string): boolean;
+/**
+ * Buckets a token budget into an effort level. Current models reject `budget_tokens`, so the
+ * contract's numeric `thinkingBudget` maps onto effort. The buckets follow the Studio's budget
+ * chips: 0 ("None, fast") is the least thinking a model allows, 2,048 ("Standard") is the
+ * standard effort, 4,096 ("Deep") is high, and larger budgets reach xhigh and max.
+ */
+export declare function thinkingBudgetToEffort(budget: number): ThinkingEffort;
+export declare function defaultNativeEffort(model: string): ThinkingEffort;
+export declare function resolveNativeThinking(model: string, budget: number | null): RunnerThinking;
+/** Models that opt into server-side refusal fallbacks by default. */
+export declare function supportsServerFallback(model: string): boolean;
+export declare const NATIVE_SYSTEM_PROMPT = "You are an autonomous engineering agent: a worker in the execution tier of a three-tier development pipeline, dispatched by nativ (the project-manager tier). You complete one task from .ai/master_plan.json on your own, with no human watching each step.\n\nYour environment:\n- The working directory is the task's workspace root. Each bash command runs in a fresh POSIX shell started there, so `cd` and exported variables do not persist between commands; chain with && when you need them.\n- Use str_replace_based_edit_tool with paths relative to the workspace root. Files under .ai/, node_modules/ and .git/ are read-only.\n- Commands are checked against an allowlist of executables. Command substitution, background jobs, absolute paths, parent-directory paths, secret files and publishing (git push, npm publish) are rejected with a reason; adjust and continue.\n\nHow to work:\n1. Run `nativ task start <taskId>` before changing code.\n2. Change only the files in the task's targetFiles. Follow the contracts in .ai/ exactly: table and column names, routes and schemas, and design tokens. Match the style of the surrounding code.\n3. Run the task's verificationCommand. If it fails, fix the cause and run it again; you have at most three fix attempts. If it still fails, run `git checkout -- <targetFiles>`, then `nativ task block <taskId> --reason \"Verification failed after 3 attempts: <short error>\"`, and stop.\n4. If a contract in .ai/ lacks something the task needs, do not edit it. Run `nativ task escalate <taskId> --type schema_flaw --details \"<the gap>\"` and stop.\n5. When verification passes, run `nativ task complete <taskId>`.\n\nCode style (the project's own formatter or linter config wins): lines 100 characters or fewer, hard max 120; functions about 40 lines, files about 300; split a growing UI file into components, one per file; comments at most 2 lines, say why not what, plain everyday words, no restating the code, no banner comments, no commented-out code; match the surrounding code.\n\nSecrets: never open .env files (.env.example is fine), *.pem, *.key or .nativ/*.local.json, and never print environment variables. For database structure use `nativ db status|inspect|diff --json`; never read table data.\n\nWhen you finish or get blocked, end with a short plain-English summary: what changed, the verification result, and anything the operator must decide. Do not call a tool in that final message.";
+export declare function buildSpecSlicesBlock(task: MasterPlanTask, rootDir: string | undefined): string;
+export declare function buildPriorEscalationsBlock(task: MasterPlanTask, rootDir: string | undefined): string;
+export declare function buildLearningsBlock(task: MasterPlanTask, rootDir: string | undefined): string;
+/** Keeps stored text from closing the block it sits in and passing as instructions. */
+export declare function untag(text: string, tag: string): string;
+export declare function buildNativeTaskPrompt(task: MasterPlanTask, roleGuide: string | null, useWorktree: boolean, rootDir?: string): string;
+export declare function describeNativeError(err: unknown): string;
+export declare function normalizeEngine(value: unknown, fallback: RunnerEngine): RunnerEngine;
+/** 0 is a valid budget: "as little thinking as the model allows". */
+export declare function normalizeThinkingBudget(value: unknown): number | null;
+export declare function normalizeModel(value: unknown): string | null;