@myagentroam/agent 0.10.24 → 0.10.26

package/dist/agent-core/subagent/session-controller.js

@@ -522,6 +522,7 @@ export class SubagentSessionController {
         state.status = 'queued';
         this.#touchResource(state);
         delete state.summary;
+        delete state.permissionStop;
         delete state.errorCode;
         delete state.errorMessage;
         state.changedFiles = [];
@@ -613,6 +614,10 @@ export class SubagentSessionController {
             if (result.status === 'completed') {
                 state.status = 'completed';
                 state.summary = result.finalAnswer;
+                if (result.permissionStop)
+                    state.permissionStop = result.permissionStop;
+                else
+                    delete state.permissionStop;
             }
             else if (result.status === 'cancelled')
                 state.status = 'cancelled';
@@ -855,6 +860,9 @@ export class SubagentSessionController {
                     ...(state.extensionId === undefined ? {} : { extensionId: state.extensionId })
                 }
                 : {}),
+            ...(includeTerminalDetails && state.permissionStop
+                ? { permissionStop: state.permissionStop }
+                : {}),
             ...state.receipt,
             ...(state.modelId === undefined ? {} : { modelId: state.modelId }),
             ...(state.modelName === undefined ? {} : { modelName: state.modelName }),
@@ -1017,6 +1025,11 @@ function restoreAgentState(session) {
         terminalObserved: false,
         resourceRevision: 0
     };
+    if (terminalType === 'execution.completed' && terminal) {
+        const event = terminal.payload;
+        if (event.permissionStop)
+            state.permissionStop = event.permissionStop;
+    }
     for (const record of currentRecords) {
         if (!isRecord(record.payload) ||
             !['message.completed', 'tool.started', 'tool.completed', 'tool.failed'].includes(eventType(record) ?? ''))

package/dist/agent-core/tools/code-mode/cells.js

@@ -1,4 +1,5 @@
 import { randomUUID } from 'node:crypto';
+import { permissionStopFromError } from '../permissions.js';
 import { MarAgentError, describeMarAgentError } from '../../error.js';
 import { truncateModelText } from '../../runtime/token-budget.js';
 import { TOOL_EXECUTION_LIMITS as limits } from '../execution-limits.js';
@@ -122,7 +123,13 @@ export class CodeCells {
         })
             .then(async () => {
             try {
-                await context.codeMode?.onSettled?.({ cellId: cell.cellId, status: outcome });
+                await context.codeMode?.onSettled?.({
+                    cellId: cell.cellId,
+                    status: outcome,
+                    ...(permissionStopFromError(cell.error)
+                        ? { permissionStop: permissionStopFromError(cell.error) }
+                        : {})
+                });
             }
             catch (error) {
                 cell.error = error;
@@ -263,6 +270,9 @@ export class CodeCells {
         const data = {
             cellId: cell.cellId,
             status: cell.status,
+            ...(permissionStopFromError(cell.error)
+                ? { permissionStop: permissionStopFromError(cell.error) }
+                : {}),
             output: bounded.content,
             observations: remapped,
             calls: [...cell.calls.values()],

package/dist/agent-core/tools/code-mode/dispatch.js

@@ -5,6 +5,7 @@ import { allowsToolCaller } from '../callers.js';
 import { boundedModelToolOutput, structuredToolEventData, structuredToolFailureData } from '../output-projection.js';
 import { executeRegisteredTool } from '../runtime.js';
 import { failedToolResultExtensions } from '../result-extensions.js';
+import { permissionStopFromError } from '../permissions.js';
 /** Capture only the cell's immutable dispatch identity, never the model loop or its AbortSignal. */
 export function createCodeToolDispatch(input) {
     const definitions = new Map(input.tools.map((tool) => [tool.name, tool]));
@@ -25,6 +26,7 @@ export function createCodeToolDispatch(input) {
                 const expected = input.expectations.get(call.name);
                 const result = await executeRegisteredTool(call.name, call.arguments, callId, {
                     ...input.context,
+                    parentCallId: input.parentCallId,
                     signal,
                     ...(expected ? { expectedMcpTool: expected } : {})
                 }, 'programmatic');
@@ -65,6 +67,9 @@ export function createCodeToolDispatch(input) {
                     ...identity,
                     code: diagnostic.code,
                     message: diagnostic.message,
+                    ...(permissionStopFromError(error)
+                        ? { permissionStop: permissionStopFromError(error) }
+                        : {}),
                     ...(data === undefined ? {} : { data })
                 });
                 throw error;

package/dist/agent-core/tools/code-mode/index.js

@@ -1,4 +1,5 @@
 import { randomUUID } from 'node:crypto';
+import { isToolPermissionFailure, permissionStopFromError, ToolPermissionStopError } from '../permissions.js';
 import { readFile } from 'node:fs/promises';
 import { createRequire } from 'node:module';
 import { dirname, sep } from 'node:path';
@@ -31,9 +32,9 @@ export const codeModeToolDefinition = {
 - Use only standard ECMAScript built-ins and the explicitly documented tools, observe, state, catalog and cell namespaces. Do not use Node.js, browser or Web APIs. Module imports, filesystem and network APIs are unavailable. Obtain external capabilities only through available tools. Use tools.exec to start managed processes when permitted; use tools.exec_wait afterward to wait, write stdin or cancel.
 
 Tool calls:
-- tools.NAME(input) returns a Promise. Use the existing tool input schema; freeform tools such as apply_patch accept a raw string, not a JSON wrapper. For parameterless tools prefer tools.NAME({}); tools.NAME() is accepted only for explicitly closed empty-object schemas.
+- tools.NAME(input) returns a Promise. Use the current catalog input schema: raw text only when inputMode is freeform; use the declared JSON form when inputMode is json. For parameterless tools prefer tools.NAME({}); tools.NAME() is accepted only for explicitly closed empty-object schemas.
 - Results use the MAR envelope: { content?: string, data?: unknown, images?: Array<{mimeType:string,dataBase64:string}>, truncated?: boolean }. Redundant JSON content is omitted when it exactly renders data; independent text remains in content. Prefer data for programmatic results: result.data.results[0].text for read source text and result.data.exitCode/result.data.stdout for exec. content, when present, is rendered text, not raw file bytes. Use only fields documented by that tool; do not invent success or ok flags.
-- Tool errors reject with code/message and may be caught. A failed cell preserves already emitted output alongside its status and error; completed tool effects are not rolled back. Inspect it before retrying completed work. Await every call; unawaited calls fail the cell. Use Promise.all for independent calls and sequential await for dependencies. Runtime preserves safe/serial barriers and Host checks.
+- Tool errors reject with code/message and may be caught, except nested Auto deny, which skips only that call and resolves with data.error/data.message. A failed cell preserves already emitted output alongside its status and error; completed tool effects are not rolled back. Inspect it before retrying completed work. Await every call; unawaited calls fail the cell. Use Promise.all for independent calls and sequential await for dependencies. Runtime preserves safe/serial barriers and Host checks.
 - skill, tool_search, question, code_exec, code_exec_wait and direct-only tools cannot be called here. Load Skills directly and read their instructions before the next tool call. Use direct tool_search before a later code cell for deferred tools; the current cell's tools do not change.
 
 Built-in namespaces:
@@ -525,18 +526,26 @@ export class CodeModeTool {
                                 : {}),
                             error: { code: diagnostic.code, message: diagnostic.message }
                         });
-                        toolResults.set(operationId, {
-                            source,
-                            outcome: 'failed',
-                            result: {
-                                content: JSON.stringify({
-                                    error: diagnostic.code,
-                                    message: diagnostic.message,
-                                    ...(data === undefined ? {} : { data })
-                                }),
+                        const failureResult = {
+                            content: JSON.stringify({
+                                error: diagnostic.code,
+                                message: diagnostic.message,
                                 ...(data === undefined ? {} : { data })
-                            }
-                        });
+                            }),
+                            ...(data === undefined ? {} : { data })
+                        };
+                        const permissionStop = permissionStopFromError(error);
+                        if (isToolPermissionFailure(error))
+                            failureResult.data = { error: diagnostic.code, message: diagnostic.message };
+                        toolResults.set(operationId, { source, outcome: 'failed', result: failureResult });
+                        if (isToolPermissionFailure(error)) {
+                            await write({ id, ok: true, output: { data: failureResult.data } });
+                            return;
+                        }
+                        if (permissionStop) {
+                            fail(error);
+                            return;
+                        }
                         await write({
                             id,
                             ok: false,
@@ -625,6 +634,7 @@ export class CodeModeTool {
                         name: tool.name,
                         description: tool.description,
                         inputSchema: tool.inputSchema,
+                        ...(tool.parameterless ? { parameterless: true } : {}),
                         inputMode: tool.inputMode ?? 'json'
                     })),
                     state: context.codeMode.state ?? [],
@@ -643,6 +653,9 @@ export class CodeModeTool {
                     }
                 });
             await exit;
+            const permissionStop = context.codeMode?.permissionStop?.();
+            if (permissionStop)
+                throw new ToolPermissionStopError(permissionStop);
             if (failure !== undefined)
                 throw failure;
             if (!complete)

package/dist/agent-core/tools/code-mode/quickjs-engine.js

@@ -749,6 +749,8 @@ function compilerCaret(source, prefix, endOfInput = false) {
     return ` (code-mode.js:${line}${endOfInput ? ', end of input' : ''})\nSyntax location: line ${line}, column ${column}\n${line} | ${preview}${token}\n${' '.repeat(String(line).length)} | ${' '.repeat(preview.length)}^`;
 }
 function isParameterlessTool(tool) {
+    if (tool.parameterless === true)
+        return true;
     const schema = tool.inputSchema;
     return (tool.inputMode === 'json' &&
         schema?.type === 'object' &&

package/dist/agent-core/tools/contracts.d.ts

@@ -12,6 +12,8 @@ export interface ClientToolDefinition {
     allowedCallers?: readonly ToolCaller[];
     inputMode?: 'json' | 'freeform';
     parallelSafety?: 'safe' | 'serial';
+    /** Preserved business-schema eligibility after framework metadata projection. */
+    parameterless?: boolean;
     /** Runtime-only Agent catalog scope; never forwarded as an upstream tool field. */
     agentScope?: 'ROOT_AND_SUBAGENTS' | 'ROOT_ONLY';
 }
@@ -19,6 +21,8 @@ export interface ToolCall {
     name: string;
     arguments: unknown;
     callId?: string;
+    /** Framework metadata for native invocations, never a business argument. */
+    permission?: import('./permissions.js').ToolPermission | null;
 }
 export interface ToolExecutionContext {
     mode: ExecutionMode;
@@ -35,6 +39,7 @@ export interface ToolExecutionContext {
         retainSession?(): Promise<() => Promise<void>>;
         onSettled?(result: CodeCellEventData): Promise<void>;
         supportsImages?: boolean;
+        permissionStop?(): import('./permissions.js').PermissionStop | undefined;
         tools: readonly ClientToolDefinition[];
         state?: readonly CodeModeStateEntry[];
         commitState?(mutations: readonly CodeModeStateMutation[]): Promise<readonly CodeModeStateEntry[]>;
@@ -99,6 +104,7 @@ export interface ToolExecutionResult {
     resultExtensions?: readonly import('./result-extensions.js').ToolResultExtension[];
 }
 export interface CodeCellEventData {
+    permissionStop?: import('./permissions.js').PermissionStop;
     calls?: readonly import('./code-mode/observations.js').CodeToolCallRecord[];
     cellId: string;
     status: 'running' | 'completed' | 'failed' | 'cancelled';

package/dist/agent-core/tools/execution.js

@@ -6,6 +6,7 @@ import { createCodeToolDispatch } from './code-mode/dispatch.js';
 import { boundedModelToolOutput, structuredToolArtifacts, structuredToolEventData, structuredToolFailureData } from './output-projection.js';
 import { executeRegisteredTool } from './runtime.js';
 import { failedToolResultExtensions } from './result-extensions.js';
+import { permissionStopFromError } from './permissions.js';
 import { scheduleToolCallBatch } from './scheduler.js';
 /** Shared raw context construction for physical tools and native calls in a real model round. */
 export async function createRoundToolRuntimeContext(scope, call, signal) {
@@ -131,6 +132,9 @@ export async function executeRoundTools(calls, scope) {
                 ...(parentCallId === undefined ? {} : { parentCallId }),
                 code: diagnostic.code,
                 message: diagnostic.message,
+                ...(permissionStopFromError(error)
+                    ? { permissionStop: permissionStopFromError(error) }
+                    : {}),
                 ...(eventData === undefined ? {} : { data: eventData })
             });
             return {
@@ -139,6 +143,9 @@ export async function executeRoundTools(calls, scope) {
                     ? boundedModelToolOutput(call.name, JSON.stringify({
                         error: diagnostic.code,
                         message: diagnostic.message,
+                        ...(permissionStopFromError(error)
+                            ? { permissionStop: permissionStopFromError(error) }
+                            : {}),
                         ...(failureData === undefined ? {} : { data: failureData }),
                         ...(error instanceof MarAgentError && error.retryable ? { retryable: true } : {})
                     }), failureData).content

package/dist/agent-core/tools/output-projection.js

@@ -42,6 +42,11 @@ export function structuredToolEventData(toolName, value) {
             cellId: value.cellId,
             status: value.status,
             cached: value.cached === true,
+            ...(isRecord(value.permissionStop)
+                ? {
+                    permissionStop: value.permissionStop
+                }
+                : {}),
             ...(Array.isArray(value.calls)
                 ? {
                     calls: value.calls.filter((entry) => isRecord(entry) &&

package/dist/agent-core/tools/permissions.d.ts

@@ -0,0 +1,85 @@
+import { MarAgentError } from '../error.js';
+import type { ClientToolDefinition, ToolCall } from './contracts.js';
+export type PermissionMode = 'auto' | 'full-access';
+export interface ToolPermission {
+    action: 'allow' | 'ask' | 'deny';
+    reason?: string | null;
+}
+export interface PermissionStop {
+    action: 'ask' | 'deny';
+    reason: string;
+    source: {
+        sessionId: string;
+        executionId: string;
+        callId: string;
+        toolName: string;
+        parentCallId?: string;
+    };
+}
+export interface ToolApprovalRequest {
+    readonly approvalId: string;
+    readonly reason: string;
+    readonly source: PermissionStop['source'];
+    readonly input: unknown;
+    readonly expiresAt: number;
+}
+export type ToolApprovalDecision = 'APPROVED' | 'REJECTED';
+export type ToolApprovalHandler = (request: ToolApprovalRequest, signal: AbortSignal) => Promise<ToolApprovalDecision>;
+type InvocationContext = {
+    sessionId: string;
+    executionId?: string;
+    actor: string;
+    entry?: string;
+    parentToolCallId?: string;
+    signal?: AbortSignal;
+};
+export declare const permissionSchema: {
+    type: string;
+    properties: {
+        action: {
+            type: string;
+            enum: string[];
+        };
+        reason: {
+            type: string;
+            description: string;
+        };
+    };
+    required: string[];
+    additionalProperties: boolean;
+};
+export declare function resolvePermissionMode(value: unknown): PermissionMode;
+export declare function projectPermissionTool(tool: ClientToolDefinition): ClientToolDefinition;
+export declare class ToolPermissionStopError extends MarAgentError {
+    readonly permissionStop: PermissionStop;
+    constructor(permissionStop: PermissionStop);
+}
+/** One captured Execution's policy, including its retained tool frames. Not an authorization ledger. */
+export declare class ExecutionToolPermissions {
+    #private;
+    readonly mode: PermissionMode;
+    readonly identity: {
+        sessionId: string;
+        executionId: string;
+    };
+    private readonly approval?;
+    constructor(mode: PermissionMode, identity: {
+        sessionId: string;
+        executionId: string;
+    }, approval?: {
+        readonly request: ToolApprovalHandler;
+        readonly signal: AbortSignal;
+    } | undefined);
+    get stop(): PermissionStop | undefined;
+    assertDispatch(): void;
+    prepare(call: ToolCall, context: InvocationContext, tool: ClientToolDefinition): ToolCall;
+    authorize(call: ToolCall, context: InvocationContext): Promise<ToolCall>;
+}
+export declare function isToolPermissionFailure(error: unknown): boolean;
+export declare function withToolPermissions<T>(policy: ExecutionToolPermissions, run: () => T): T;
+export declare function currentToolPermissions(context?: {
+    sessionId: string;
+    executionId?: string;
+}): ExecutionToolPermissions | undefined;
+export declare function permissionStopFromError(error: unknown): PermissionStop | undefined;
+export {};

package/dist/agent-core/tools/permissions.js

@@ -0,0 +1,237 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { randomUUID } from 'node:crypto';
+import { MarAgentError } from '../error.js';
+const permissionContext = new AsyncLocalStorage();
+const record = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const schemaKeys = new Set([
+    'type',
+    'properties',
+    'required',
+    'additionalProperties',
+    'description',
+    'title',
+    '$schema',
+    '$comment'
+]);
+export const permissionSchema = {
+    type: 'object',
+    properties: {
+        action: { type: 'string', enum: ['allow', 'ask', 'deny'] },
+        reason: {
+            type: 'string',
+            description: 'Brief public reason, required for ask/deny; never include secrets.'
+        }
+    },
+    required: ['action'],
+    additionalProperties: false
+};
+export function resolvePermissionMode(value) {
+    if (value === undefined)
+        return 'full-access';
+    if (value === 'auto' || value === 'full-access')
+        return value;
+    throw new MarAgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'Permission mode must be auto or full-access.');
+}
+function flatInput(tool) {
+    const schema = tool.inputSchema;
+    return (schema.type === 'object' &&
+        schema.additionalProperties === false &&
+        record(schema.properties) &&
+        !Object.hasOwn(schema.properties, 'permission') &&
+        Object.keys(schema).every((key) => schemaKeys.has(key)));
+}
+export function projectPermissionTool(tool) {
+    const flat = flatInput(tool);
+    const parameterless = flat &&
+        Object.keys(tool.inputSchema.properties).length === 0 &&
+        (!Array.isArray(tool.inputSchema.required) || tool.inputSchema.required.length === 0);
+    return {
+        ...tool,
+        inputMode: 'json',
+        ...(parameterless ? { parameterless: true } : {}),
+        description: tool.description +
+            '\nAuto mode: use the declared JSON input. Omit permission (or set null) for routine or already authorized work. Use {action:"ask"|"deny",reason:"brief public reason"} only when required. ' +
+            (flat
+                ? 'Permission is metadata, not a business argument.'
+                : 'Place the unchanged business arguments in input; permission is separate metadata.'),
+        inputSchema: flat
+            ? {
+                ...tool.inputSchema,
+                properties: {
+                    ...tool.inputSchema.properties,
+                    permission: permissionSchema
+                }
+            }
+            : {
+                type: 'object',
+                properties: { input: tool.inputSchema, permission: permissionSchema },
+                required: ['input'],
+                additionalProperties: false
+            }
+    };
+}
+function parsePermission(value) {
+    if (value === undefined || value === null)
+        return;
+    if (!record(value) ||
+        Object.keys(value).some((key) => key !== 'action' && key !== 'reason') ||
+        !['allow', 'ask', 'deny'].includes(String(value.action)) ||
+        typeof value.action !== 'string' ||
+        (value.reason !== undefined && value.reason !== null && typeof value.reason !== 'string'))
+        throw new MarAgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'Invalid tool permission declaration.');
+    const reason = typeof value.reason === 'string' ? value.reason.trim() : undefined;
+    if ((reason !== undefined && [...reason].length > 240) || (value.action !== 'allow' && !reason))
+        throw new MarAgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'ask/deny requires a public reason of 1 to 240 characters.');
+    return {
+        action: value.action,
+        ...(reason === undefined ? {} : { reason })
+    };
+}
+export class ToolPermissionStopError extends MarAgentError {
+    permissionStop;
+    constructor(permissionStop) {
+        super(permissionStop.action === 'ask' ? 'MAR_AGENT_PERMISSION_ASK' : 'MAR_AGENT_PERMISSION_DENIED', permissionStop.reason);
+        this.permissionStop = permissionStop;
+    }
+}
+/** One captured Execution's policy, including its retained tool frames. Not an authorization ledger. */
+export class ExecutionToolPermissions {
+    mode;
+    identity;
+    approval;
+    #stop;
+    constructor(mode, identity, approval) {
+        this.mode = mode;
+        this.identity = identity;
+        this.approval = approval;
+    }
+    get stop() {
+        return this.#stop;
+    }
+    assertDispatch() {
+        if (this.#stop)
+            throw new MarAgentError('MAR_AGENT_TOOL_SKIPPED_PERMISSION_STOP', 'Tool was not executed because this execution stopped for permission.');
+    }
+    prepare(call, context, tool) {
+        if (this.mode !== 'auto') {
+            if (call.permission !== undefined && call.permission !== null)
+                throw new MarAgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'Framework permission metadata requires an Auto execution.');
+            return call;
+        }
+        this.assertDispatch();
+        let business = call.arguments;
+        let declaration = call.permission;
+        if (context.actor === 'model' || context.actor === 'code-mode') {
+            if (!record(business))
+                throw new MarAgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'Auto tool input must be a JSON object.');
+            declaration = business.permission;
+            if (flatInput(tool)) {
+                const { permission: _permission, ...input } = business;
+                business = input;
+            }
+            else {
+                if (Object.keys(business).some((key) => key !== 'input' && key !== 'permission') ||
+                    !Object.hasOwn(business, 'input'))
+                    throw new MarAgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'Auto input requires the original business arguments in input.');
+                business = business.input;
+            }
+        }
+        const permission = parsePermission(declaration);
+        const { permission: _permission, ...input } = call;
+        const prepared = { ...input, arguments: business };
+        if (permission?.action === 'ask' && this.approval)
+            return { ...prepared, permission };
+        if (permission && permission.action !== 'allow') {
+            const stop = Object.freeze({
+                action: permission.action,
+                reason: permission.reason,
+                source: Object.freeze({
+                    sessionId: this.identity.sessionId,
+                    executionId: this.identity.executionId,
+                    callId: call.callId ?? randomUUID(),
+                    toolName: call.name,
+                    ...(context.parentToolCallId === undefined
+                        ? {}
+                        : { parentCallId: context.parentToolCallId })
+                })
+            });
+            if (permission.action === 'ask')
+                this.#stop = stop;
+            throw new ToolPermissionStopError(stop);
+        }
+        return prepared;
+    }
+    async authorize(call, context) {
+        if (call.permission?.action !== 'ask' || !this.approval)
+            return call;
+        const { permission, ...captured } = structuredClone(call);
+        const timeout = new AbortController();
+        const signal = AbortSignal.any([
+            this.approval.signal,
+            ...(context.signal ? [context.signal] : []),
+            timeout.signal
+        ]);
+        signal.throwIfAborted();
+        const request = {
+            approvalId: `mar-agent:${randomUUID()}`,
+            reason: permission.reason,
+            source: {
+                ...this.identity,
+                callId: call.callId ?? randomUUID(),
+                toolName: call.name,
+                ...(context.parentToolCallId ? { parentCallId: context.parentToolCallId } : {})
+            },
+            input: structuredClone(captured.arguments),
+            expiresAt: Date.now() + 10 * 60_000
+        };
+        const timer = setTimeout(() => timeout.abort(new MarAgentError('MAR_AGENT_APPROVAL_EXPIRED', 'Approval expired after 10 minutes without authorizing the tool call.')), 10 * 60_000);
+        timer.unref();
+        let abort = () => { };
+        try {
+            const decision = await new Promise((resolve, reject) => {
+                abort = () => reject(signal.reason);
+                signal.addEventListener('abort', abort, { once: true });
+                Promise.resolve()
+                    .then(() => {
+                    signal.throwIfAborted();
+                    return this.approval.request(request, signal);
+                })
+                    .then(resolve, reject);
+            });
+            signal.throwIfAborted();
+            if (Date.now() >= request.expiresAt)
+                throw new MarAgentError('MAR_AGENT_APPROVAL_EXPIRED', 'Approval expired after 10 minutes without authorizing the tool call.');
+            if (decision !== 'APPROVED')
+                throw new MarAgentError('MAR_AGENT_APPROVAL_REJECTED', `User rejected this tool call: ${permission.reason}`);
+            this.assertDispatch();
+            return captured;
+        }
+        finally {
+            clearTimeout(timer);
+            signal.removeEventListener('abort', abort);
+        }
+    }
+}
+export function isToolPermissionFailure(error) {
+    return (permissionStopFromError(error)?.action === 'deny' ||
+        (error instanceof MarAgentError &&
+            ['MAR_AGENT_APPROVAL_REJECTED', 'MAR_AGENT_APPROVAL_EXPIRED'].includes(error.code)));
+}
+export function withToolPermissions(policy, run) {
+    return permissionContext.run(policy, run);
+}
+export function currentToolPermissions(context) {
+    const policy = permissionContext.getStore();
+    return policy &&
+        (!context ||
+            (policy.identity.sessionId === context.sessionId &&
+                policy.identity.executionId === context.executionId))
+        ? policy
+        : undefined;
+}
+export function permissionStopFromError(error) {
+    for (let depth = 0; depth < 5 && error instanceof Error; depth++, error = error.cause)
+        if (error instanceof ToolPermissionStopError)
+            return error.permissionStop;
+    return;
+}

package/dist/agent-core/tools/runtime-context.d.ts

@@ -46,6 +46,8 @@ export interface ToolRuntimeContext {
     executionId: string;
     modelId?: string;
     signal: AbortSignal;
+    permissionPolicy?: import('./permissions.js').ExecutionToolPermissions;
+    parentCallId?: string;
     writeToolResultResource?: import('./result-extensions.js').ToolResultResourceWriter;
     codeMode?: import('./contracts.js').ToolExecutionContext['codeMode'];
     skills: ReadonlyMap<string, AgentSkill>;

package/dist/cli/main.js

@@ -17,7 +17,7 @@ const HELP = `maragent - MAR coding agent
 
 Usage:
   maragent [--model ID] [--reasoning-effort EFFORT] [--codex-auth-file PATH]
-  maragent run <prompt> [--reasoning-effort EFFORT] [--format text|json|stream-json] [--codex-auth-file PATH]
+  maragent run <prompt> [--permission-mode auto|full-access] [--reasoning-effort EFFORT] [--format text|json|stream-json] [--codex-auth-file PATH]
   maragent resume [sessionId] [--reasoning-effort EFFORT] [--codex-auth-file PATH]
   maragent sessions list|delete <sessionId>
   maragent models list|add|edit|remove|test [id] [--default-reasoning-effort EFFORT] [--code-mode|--no-code-mode] [--fast-mode|--no-fast-mode] [--codex-auth-file PATH]
@@ -249,6 +249,12 @@ async function main() {
         ? undefined
         : parseReasoningEffort(reasoningEffortOption, '--reasoning-effort');
     const legacyAccess = takeOption(arguments_, '--access');
+    const permissionModeOption = takeOption(arguments_, '--permission-mode');
+    if (permissionModeOption !== undefined &&
+        permissionModeOption !== 'auto' &&
+        permissionModeOption !== 'full-access')
+        throw new MarAgentError('MAR_AGENT_CLI_ARGUMENT_INVALID', '--permission-mode must be auto or full-access.');
+    const permissionMode = permissionModeOption;
     if (legacyAccess !== undefined && legacyAccess !== 'full-access')
         throw new MarAgentError('MAR_AGENT_CLI_ARGUMENT_INVALID', 'The deprecated --access option only accepts full-access.');
     const format = takeOption(arguments_, '--format') ?? 'text';
@@ -340,6 +346,7 @@ async function main() {
                     break;
                 const invocation = parseExecutionInvocation(prompt);
                 const runInput = {
+                    ...(permissionMode === undefined ? {} : { permissionMode }),
                     prompt: invocation.prompt,
                     ...(modelId === undefined ? {} : { modelId }),
                     ...(reasoningEffort === undefined ? {} : { reasoningEffort })
@@ -388,7 +395,11 @@ async function main() {
                 if (format === 'json')
                     stdout.write(`${JSON.stringify(result)}\n`);
                 else if (format === 'text')
-                    stdout.write('\n');
+                    stdout.write(result.permissionStop
+                        ? `\nNot executed (${result.permissionStop.action}): ${result.permissionStop.reason}\n${result.permissionStop.action === 'ask' ? 'Reply with allow or a scoped instruction to continue.\n' : ''}`
+                        : '\n');
+                if (!interactive && result.permissionStop)
+                    process.exitCode = result.permissionStop.action === 'ask' ? 3 : 1;
                 if (result.status !== 'completed')
                     process.exitCode = cliExitCode(result.errorCode);
             } while (interactive);

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export { MarAgentError } from './agent-core/error.js';
 export { MAR_AGENT_HOST_API_VERSION, negotiateHost, type HostDescription, type MarAgentHostCapability } from './agent-core/host/contracts.js';
+export type { PermissionMode, ToolApprovalRequest, ToolApprovalDecision, ToolApprovalHandler, ToolPermission, PermissionStop } from './agent-core/tools/permissions.js';
 export type { ToolResultExtension, FileChangeEvidence } from './agent-core/tools/result-extensions.js';
 export { parseToolResultExtensions } from './agent-core/tools/result-extensions.js';
 export type { ToolResultResourceInput, ToolResultResourcePage } from './agent-core/session/tool-result-resources.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myagentroam/agent",
-  "version": "0.10.24",
+  "version": "0.10.26",
   "description": "Embeddable MAR coding agent SDK and CLI.",
   "license": "Apache-2.0",
   "type": "module",