type: agent/inbox/spliced

target: next-turn

type: text

text: Inspect the exact tools service API and tools/pre-execute event with cordis_inspect_query, then reply with exactly CORDIS_INSPECT_JSDOC_OK.

kind: user

role: user


type: user/message

surfaceOp: append


text:
Current runtime context. This snapshot supersedes earlier runtime-context snapshots.

Current DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations.

Approval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`).

kind: plugin

form: snapshot


type: session/title

title: Inspect the exact tools service

kind: fallback


type: request/header

provider: deepseek-official

[System] {{system}}

tools: {{tools}}

reason: initial


type: assistant/chunk

type: tool-call-delta

platform: host

provider: Service

method: listService


type: block-end

type: tool-call


type: assistant/message

role: assistant

kind: model


type: tool/call

callId: inspect-tools-api


type: tool/result

kind: tool

type: tool-result

toolCallId: inspect-tools-api

mode: service

key: tools

description: Tool registry and execution pipeline. Scoped registrations shadow globals; one visibility resolver feeds presentation, lookup, and dispatch.

signature: presentAs(mode: ToolPresentationMode): () => void

description:
Present the calling scope's tools in `mode` instead of the deployment default. Nearest scope on the chain wins, so a preset's standing declaration covers every agent joined under it.

Scoped only, and one declaration per scope: this is how an agent preset composes PTC mode agents beside native ones in the same process, and a process-global override would be the `mode` config field instead.

mode

description: the presentation the covered agents' models see.

returns: the exact disposer that restores the deployment default.

signature: register(definition: ToolDefinition): () => void

description: Register globally or in the calling agent scope. Scoped tools shadow globals; duplicates within one layer and the reserved `run_code` name fail.

definition

description: tool schema, execution, and optional finalization/presentation callbacks.

returns: the exact disposer that unregisters the tool.

signature: restrict(filter: ToolRestriction): () => void

description: Restrict global tools for the calling agent scope. Empty filters, unknown names, scope-local names, and reserved transport names fail. Restrictions intersect; scoped registrations remain visible.

filter

description: global-tool mask: `allow` (keep only) and/or `deny` (remove).

returns: the exact disposer that lifts this restriction.

signature: guard(guard: ToolGuard): () => void

description: Register a monotonic guard after the extensible `tools/pre-execute` waterfall. A plain-context guard applies globally; one registered through `agent.ctx` applies only to that agent. Any matching guard may deny by returning a reason, while no guard can force-allow a call another guard denied. The exact effect disposer is returned for ordered ownership and HMR cleanup.

guard

description: synchronous check; a returned string denies the execution.

returns: the exact disposer that unregisters the guard.

signature: get(name: string, scope?: ScopeKey): ToolDefinition | undefined

description: Look up a tool as one scope sees it (scoped shadows global; a restricted-away global reads as absent). Presenters pass the calling agent so the rendered card matches the definition that actually executed.

name

description: the tool name as registered.

scope

description: the viewing scope (the agent); omitted = the global view.

returns: the definition the scope resolves, or undefined when none is visible.

signature: schemas(scope?: ScopeKey): ToolSchema[]

description: Project visible definitions onto the allowlisted model-facing schema fields, excluding execution and presentation callbacks.

returns: one deep-cloned schema per visible tool.

description: Classify a pending call through the caller's visible tool definition. Only an exact `true` is parallel; unknown, hidden, undeclared, invalid, or throwing classifiers are exclusive.

exec

description: call name, parsed arguments, and optional agent scope.

returns: the fail-closed scheduling mode.

signature: async execute(exec: ToolExecutionInput): Promise<ToolExecutionResult>

description: Execute through pre-policy, guards, around-dispatch, post-policy, definition-owned content finalization, and final notification. Tool and listener failures resolve as materialized error results; an invisible tool reports `UNKNOWN_TOOL`. The returned outcome is the same lossless, frozen snapshot final observers receive. Cancellation arriving after entry and before final result materialization skips a not-yet-started body with `ABORTED_BEFORE_DISPATCH` or replaces a successful started outcome with `ABORTED`; already-started work is still drained and may retain a tool-owned structured error.

description: the typed same-process call input. The registry assigns its correlation token before policy begins.

returns: the materialized final result.

Agent

declaration:
export interface Agent {
    readonly id: SessionId;
}

AssistantProvenance

declaration:
export interface AssistantProvenance {
    provider: string;
    model: string;
    replayState?: unknown;
}

Branded

declaration:
export type Branded<B extends string> = string & {
    readonly [BRAND]: B;
};

ContextFormed

declaration:
export type ContextFormed = {
    readonly form?: never;
} | {
    readonly form: 'instructions';
} | {
    readonly form: 'catalog';
} | {
    readonly form: 'snapshot';
    readonly sections: readonly ContextSnapshotSection[];
} | {
    readonly form: 'notice';
    readonly summary: string;
} | {
    readonly form: 'relay';
} | {
    readonly form: 'recall';
};

ContextSnapshotSection

declaration:
export interface ContextSnapshotSection {
    readonly name: string;
    readonly text: string;
}

DiffCallView

declaration:
export interface DiffCallView {
    card: 'diff';
    title: string;
    diffs: FileDiff[];
    locations?: FileLocation[];
}

DiffResultView

declaration:
export interface DiffResultView {
    card: 'diff';
    title?: string;
    diffs: FileDiff[];
}

FileDiff

declaration:
export interface FileDiff {
    path: string;
    oldText: string | null;
    newText: string;
}

FileLocation

declaration:
export interface FileLocation {
    path: string;
    line?: number;
}

GenericCallView

declaration:
export interface GenericCallView {
    card: 'generic';
    title: string;
    kind?: ToolCallKind;
    rawInput?: unknown;
    content?: ContentBlock[];
    locations?: FileLocation[];
}

GenericResultView

declaration:
export interface GenericResultView {
    card: 'generic';
    title?: string;
    content?: ContentBlock[];
}

JsonSchemaNode

declaration:
export interface JsonSchemaNode {
    type?: JsonSchemaType;
    oneOf?: JsonSchemaNode[];
    properties?: Record<string, JsonSchemaNode>;
    required?: string[];
    additionalProperties?: boolean;
    items?: JsonSchemaNode;
    enum?: JsonSchemaScalar[];
    const?: JsonSchemaScalar;
    description?: string;
    title?: string;
    default?: JsonValue;
    examples?: JsonValue;
}

JsonSchemaScalar

declaration: export type JsonSchemaScalar = string | number | boolean | null;

JsonSchemaType

declaration: export type JsonSchemaType = 'object' | 'array' | 'string' | 'number' | 'integer' | 'boolean' | 'null';

JsonValue

declaration:
export type JsonValue = null | boolean | number | string | JsonValue[] | {
    [key: string]: JsonValue;
};

Message

declaration:
export interface Message {
    readonly id: MessageId;
    readonly role: 'system' | 'user' | 'assistant';
    readonly content: ContentBlock[];
    readonly source: MessageSource;
}

MessageId

declaration: export type MessageId = Branded<'MessageId'>;

MessageSource

declaration: export type MessageSource = MessageSourceMap[keyof MessageSourceMap];

MessageSourceMap

declaration:
export interface MessageSourceMap {
    user: {
        kind: 'user';
    };
    plugin: {
        kind: 'plugin';
        plugin: string;
    } & ContextFormed;
    model: ModelMessageSource;
    tool: ToolMessageSource;
}

ModelMessageSource

declaration:
export interface ModelMessageSource extends AssistantProvenance {
    kind: 'model';
}

ReadFileLine

declaration:
export interface ReadFileLine {
    number: number;
    text: string;
}

ReadResultView

declaration:
export interface ReadResultView {
    card: 'read';
    title?: string;
    path: string;
    offset: number;
    lines: ReadFileLine[];
    totalLines: number;
    lang?: string;
    content?: ContentBlock[];
}

ScopeKey

declaration: export type ScopeKey = object;

SearchFileMatches

declaration:
export interface SearchFileMatches {
    path: string;
    matches: SearchLineMatch[];
}

SearchLineMatch

declaration:
export interface SearchLineMatch {
    lineNumber: number;
    line: string;
}

SearchMatchesResultView

declaration:
export interface SearchMatchesResultView {
    card: 'search';
    shape: 'matches';
    title?: string;
    files: SearchFileMatches[];
    truncated: boolean;
    total: number;
}

SearchPathsResultView

declaration:
export interface SearchPathsResultView {
    card: 'search';
    shape: 'paths';
    title?: string;
    paths: string[];
    truncated: boolean;
    total: number;
}

SearchResultView

declaration: export type SearchResultView = SearchMatchesResultView | SearchPathsResultView;

SessionId

declaration: export type SessionId = Branded<'SessionId'>;

TerminalCallView

declaration:
export interface TerminalCallView {
    card: 'terminal';
    title: string;
    description?: string;
    cwd?: string;
}

TerminalResultView

declaration:
export interface TerminalResultView {
    card: 'terminal';
    title?: string;
    output?: string;
    exitCode?: number;
    signal?: string;
}

ToolCallKind

declaration: export type ToolCallKind = 'read' | 'edit' | 'delete' | 'move' | 'search' | 'execute' | 'fetch' | 'other';

ToolCallView

declaration: export type ToolCallView = GenericCallView | TerminalCallView | DiffCallView;

ToolDefinition

declaration:
export interface ToolDefinition extends ToolSchema {
    readonly output: ToolOutputDefinition;
    execute(args: unknown, exec: ToolRunContext): Promise<unknown>;
    finalizeContent?(exec: Readonly<ToolExecution>, result: Readonly<ToolExecutionResult>): ContentBlock[] | undefined;
    timeoutMs?: number;
    isConcurrencySafe?(args: unknown): boolean;
    presentCall?(args: unknown): ToolCallView | undefined;
    presentResult?(args: unknown, result: ToolResult): ToolResultView | undefined;
}

ToolErrorInfo

declaration:
export interface ToolErrorInfo {
    name: string;
    code: string;
}

ToolExecution

declaration:
export interface ToolExecution extends ToolExecutionInput {
    readonly rootCallId: ToolCallId;
    readonly token: ToolExecutionToken;
}

ToolExecutionFailure

declaration:
export interface ToolExecutionFailure {
    readonly isError: true;
    readonly error: ToolFailure;
    readonly value?: never;
    readonly content: ContentBlock[];
    readonly meta?: JsonValue;
    readonly additionalContexts?: UserMessage[];
    readonly concludesTurn?: never;
}

ToolExecutionInput

declaration:
export interface ToolExecutionInput {
    readonly callId: ToolCallId;
    readonly rootCallId?: ToolCallId;
    readonly name: string;
    readonly arguments: unknown;
    readonly agent?: Agent;
    readonly parent?: ToolExecutionToken;
    readonly signal: AbortSignal;
}

ToolExecutionMode

declaration:
export type ToolExecutionMode = {
    kind: 'parallel';
} | {
    kind: 'exclusive';
};

ToolExecutionResult

declaration: export type ToolExecutionResult = ToolExecutionSuccess | ToolExecutionFailure;

ToolExecutionSuccess

declaration:
export interface ToolExecutionSuccess {
    readonly isError: false;
    readonly value: JsonValue;
    readonly content: ContentBlock[];
    readonly error?: never;
    readonly meta?: JsonValue;
    readonly additionalContexts?: UserMessage[];
    readonly concludesTurn?: true;
}

ToolExecutionToken

declaration:
export type ToolExecutionToken = symbol & {
    readonly [toolExecutionTokenBrand]: true;
};

ToolFailure

declaration:
export interface ToolFailure {
    message: string;
    info?: ToolErrorInfo;
}

ToolGuard

declaration: export type ToolGuard = (execution: Readonly<ToolExecution>) => string | undefined;

ToolMessageSource

declaration:
export interface ToolMessageSource {
    kind: 'tool';
    callId: ToolCallId;
}

ToolOutputDefinition

declaration:
export interface ToolOutputDefinition {
    readonly schema: JsonSchemaNode;
    render(args: unknown, value: JsonValue): ContentBlock[];
    presentationMeta?(args: unknown, value: JsonValue): JsonValue;
}

ToolPresentationMode

declaration: export type ToolPresentationMode = 'native' | 'ptc' | 'both';

ToolRestriction

declaration:
export interface ToolRestriction {
    readonly allow?: readonly string[];
    readonly deny?: readonly string[];
}

ToolResult

declaration:
export interface ToolResult {
    content: ContentBlock[];
    isError: boolean;
    meta?: JsonValue;
}

ToolResultView

declaration: export type ToolResultView = GenericResultView | TerminalResultView | DiffResultView | SearchResultView | ReadResultView | WebResultView;

ToolRunContext

declaration:
export interface ToolRunContext extends ToolExecution {
    deferContext(context: UserMessage): void;
    concludeTurn(): void;
}

ToolSchema

declaration:
export interface ToolSchema {
    name: string;
    description: string;
    parameters: Record<string, unknown>;
}

UserMessage

declaration:
export interface UserMessage extends Message {
    readonly role: 'user';
}

WebFetchResultView

declaration:
export interface WebFetchResultView {
    card: 'web';
    kind: 'fetch';
    title?: string;
    url: string;
    statusCode: number;
    truncated: boolean;
}

WebResultView

declaration: export type WebResultView = WebSearchResultView | WebFetchResultView;

WebSearchResultView

declaration:
export interface WebSearchResultView {
    card: 'web';
    kind: 'search';
    title?: string;
    sources: WebSource[];
    answer?: string;
    truncated: boolean;
}

WebSource

declaration:
export interface WebSource {
    url: string;
    title?: string;
    snippet?: string;
    publishedAt?: string;
}