bazis 0.121.0 → 0.123.0

package/cli/templates/module.ts

@@ -49,7 +49,7 @@ export function buildModuleTemplates(
   return [
     ...base,
     { relativePath: `background/${naming.module}.reporter.ts`, content: statsReporterFile(naming) },
-    { relativePath: `ai/tools/${naming.module}Summary.tool.ts`, content: aiToolFile(naming) },
+    { relativePath: `tools/${naming.module}Summary.tool.ts`, content: toolFile(naming) },
   ];
 }
 
@@ -57,7 +57,7 @@ function moduleFile(n: ModuleNaming, profile: ModuleTemplateProfile): string {
   const moduleImport = "import { Module, scoped } from \"bazis/core/di\";";
   const backgroundImport = profile === "full" ? `import { ${n.module}Reporter } from "./background/${n.module}.reporter";\n` : "";
   const aiImports = profile === "full"
-    ? `import { ${n.module}SummaryTool } from "./ai/tools/${n.module}Summary.tool";
+    ? `import { ${n.module}SummaryTool } from "./tools/${n.module}Summary.tool";
 `
     : "";
   const backgroundLine = profile === "full" ? `  background: [${n.module}Reporter],\n` : "";
@@ -397,10 +397,10 @@ export class ${n.module}Reporter extends PeriodicBackgroundService {
 }
 
 
-function aiToolFile(n: ModuleNaming): string {
+function toolFile(n: ModuleNaming): string {
   return `import { Tool, type AgentToolExecutionContext } from "bazis/core/agent";
 import { Validator } from "bazis/library/validation";
-import type { I${n.module}Service } from "../../services/I${n.module}.service";
+import type { I${n.module}Service } from "../services/I${n.module}.service";
 
 export class ${n.module}SummaryToolInput {
   @Validator({ required: true, minLength: 3 })
@@ -420,6 +420,7 @@ export class ${n.module}SummaryToolOutput {
   input: ${n.module}SummaryToolInput,
   output: ${n.module}SummaryToolOutput,
   sideEffect: "read",
+  callers: ["agent"],
 })
 export class ${n.module}SummaryTool {
   constructor(private readonly ${n.collection}: I${n.module}Service) {}

package/cli/templates/passport.ts

@@ -66,7 +66,7 @@ adapters that access it.
 | ${e}Response / ${m}Summary / to${e}Response | [responses](http/contracts/${m}.responses.ts) | ORM entity | Public data projection |
 | ${m}ListQuery | [list](http/contracts/${m}List.query.ts) | Query string | ListQuery, filters/sorting/pages |
 ${profile === "full" ? `| ${m}Reporter | [background](background/${m}.reporter.ts) | ServiceProvider, Logger, AbortSignal | Runs count and logs it |
-| ${m}SummaryTool | [tool](ai/tools/${m}Summary.tool.ts) | I${m}Service, input, context | Summary for an agent |
+| ${m}SummaryTool | [tool](tools/${m}Summary.tool.ts) | I${m}Service, input, context | Summary for an agent |
 ` : ""}
 
 ## Wiring, DI and data

package/core/agent/AgentRuntime.ts

@@ -1,11 +1,13 @@
 import { createToken, type ServiceProvider } from "../di";
 import { modelValidatorAdapter } from "../../library/validation";
 import { AgentSetupError } from "./errors";
+import { TOOL_EXECUTION_OPTIONS } from "./toolExecutionOptions";
 import type { AgentDataDefinition } from "./AgentDataDefinition";
 import { AgentRegistry, type ToolDefinition } from "./AgentRegistry";
 import {
   AgentExecutionDriver,
   type AgentRuntimeInvokeOptions,
+  type AgentExecutionDriverOptions,
   type AgentRuntimeOptions,
   type AgentRuntimeResult,
 } from "./internal/AgentExecutionDriver";
@@ -13,6 +15,7 @@ import type { AgentModelProvider } from "./ModelProvider";
 
 export {
   type AgentRuntimeInvokeOptions,
+  type AgentExecutionDriverOptions,
   type AgentRuntimeOptions,
   type AgentRuntimeResult,
   type AgentRuntimeStatus,
@@ -42,7 +45,7 @@ export const AGENT_RUNTIME_OPTIONS = createToken<AgentRuntimeOptions>("AgentRunt
  */
 export class AgentRuntime {
   private readonly catalog: AgentRegistry;
-  private readonly options: AgentRuntimeOptions;
+  private readonly options: AgentExecutionDriverOptions;
 
   constructor(
     private readonly services: ServiceProvider,
@@ -50,9 +53,11 @@ export class AgentRuntime {
     options: AgentRuntimeOptions = {},
   ) {
     this.catalog = AgentRegistry.fromContainer(services);
+    // One Tool execution setup for agents and ToolRunner (TOOLS-001 §6).
+    const { logger: _toolLogger, ...toolExecutorOptions } = services.has(TOOL_EXECUTION_OPTIONS) ? services.resolve(TOOL_EXECUTION_OPTIONS) : {};
     this.options = {
       ...options,
-      toolExecutorOptions: { schemaValidator: modelValidatorAdapter, ...options.toolExecutorOptions },
+      toolExecutorOptions: { schemaValidator: modelValidatorAdapter, ...toolExecutorOptions },
     };
     // Invalid options and hook setup fail here, at the first resolve, not on the first run.
     new AgentExecutionDriver(services, this.catalog, modelProvider, this.options);

package/core/agent/AgentToolExecutor.ts

@@ -1,4 +1,5 @@
 import { ToolContractValidator, toolContractName, toolErrorMessage as errorMessageOf, type AgentToolSchemaValidator } from "./internal/ToolContract.validator";
+import type { ToolActor } from "./metadata";
 import { ToolAuditProjector, type AgentToolAuditEntry, type AgentToolAuditFailureMode } from "./internal/ToolAudit.projector";
 export type { AgentToolValidationIssue, AgentToolValidationResult, AgentToolSchemaValidator } from "./internal/ToolContract.validator";
 export type { AgentToolAuditPhase, AgentToolAuditFailureMode, AgentToolAuditToolInfo, AgentToolAuditEntry } from "./internal/ToolAudit.projector";
@@ -69,6 +70,9 @@ export interface AgentToolApprovalRequest {
   readonly call: AgentToolCall;
   readonly tool: ToolDefinition;
   readonly reason: AgentToolApprovalReason;
+  /** `"agent"` for an agent call, otherwise the runner's caller id. */
+  readonly caller: string;
+  readonly actor?: ToolActor;
   readonly agentName?: string;
   readonly invocationId?: string;
   readonly idempotencyKey?: string;
@@ -111,7 +115,6 @@ export interface AgentToolExecutorOptions {
   readonly defaultTimeoutMs?: number;
   /** Maximum time to wait for a tool DI scope disposer after execution settles. */
   readonly scopeDisposeTimeoutMs?: number;
-  readonly allowUnboundTools?: boolean;
   readonly allowUnvalidatedSchemas?: boolean;
   /** Side-effecting tools require an audit sink unless this explicit escape hatch is set. */
   readonly allowUnauditedSideEffects?: boolean;
@@ -123,6 +126,13 @@ export interface AgentToolExecutorOptions {
 
 export interface AgentToolExecutionOptions {
   readonly agentName?: string;
+  /**
+   * Who calls the Tool when there is no agent (`ToolRunner.as("workflow")`).
+   * An agent call is the `"agent"` caller. The Tool's `callers` must list it.
+   */
+  readonly caller?: string;
+  /** On whose behalf the call runs; reaches the approval policy and the audit. */
+  readonly actor?: ToolActor;
   readonly invocationId?: string;
   readonly metadata?: unknown;
   readonly approvalPolicy?: AgentToolApprovalPolicy;
@@ -135,7 +145,6 @@ export interface AgentToolExecutionOptions {
   readonly timeoutMs?: number;
   /** Per-call override for the bounded DI scope disposal wait. */
   readonly scopeDisposeTimeoutMs?: number;
-  readonly allowUnboundTools?: boolean;
   readonly allowUnvalidatedSchemas?: boolean;
   readonly allowUnauditedSideEffects?: boolean;
   readonly signal?: AbortSignal;
@@ -418,7 +427,6 @@ export class AgentToolExecutor {
   private readonly retryPolicy: RetrySettings;
   private readonly defaultTimeoutMs?: number;
   private readonly scopeDisposeTimeoutMs: number;
-  private readonly allowUnboundTools: boolean;
   private readonly allowUnvalidatedSchemas: boolean;
   private readonly allowUnauditedSideEffects: boolean;
   private readonly auditProjector: ToolAuditProjector;
@@ -445,7 +453,6 @@ export class AgentToolExecutor {
       ? undefined
       : options.defaultTimeoutMs ?? DEFAULT_TOOL_TIMEOUT_MS;
     this.scopeDisposeTimeoutMs = options.scopeDisposeTimeoutMs ?? DEFAULT_SCOPE_DISPOSE_TIMEOUT_MS;
-    this.allowUnboundTools = options.allowUnboundTools === true;
     this.allowUnvalidatedSchemas = options.allowUnvalidatedSchemas === true;
     this.allowUnauditedSideEffects = options.allowUnauditedSideEffects === true;
     this.auditProjector = new ToolAuditProjector(options.auditRedaction ?? {});
@@ -1240,18 +1247,27 @@ export class AgentToolExecutor {
     tool: ToolDefinition,
     options: AgentToolExecutionOptions,
   ): AgentVisibilityDecision {
-    const allowUnboundTools = options.allowUnboundTools ?? this.allowUnboundTools;
-    if (!options.agentName) {
-      if (allowUnboundTools) {
-        return { allowed: true };
-      }
+    // Who may call is declared on the Tool (TOOLS-001); tags never decide it.
+    const caller = callerOf(options);
+    if (caller === undefined) {
       return {
         allowed: false,
-        code: "TOOL_AGENT_REQUIRED",
-        message: `Tool "${tool.metadata.name}" execution requires agentName.`,
+        code: "TOOL_CALLER_REQUIRED",
+        message: `Tool "${tool.metadata.name}" execution requires an agent or a caller.`,
         status: "error",
       };
     }
+    if (!tool.metadata.callers.includes(caller)) {
+      return {
+        allowed: false,
+        code: "TOOL_CALLER_NOT_ALLOWED",
+        message: `Tool "${tool.metadata.name}" may not be called by "${caller}" (callers: ${tool.metadata.callers.join(", ")}).`,
+        status: "denied",
+      };
+    }
+    if (!options.agentName) {
+      return { allowed: true };
+    }
 
     const agent = this.registry.getAgent(options.agentName);
     if (!agent) {
@@ -1314,6 +1330,8 @@ export class AgentToolExecutor {
         call,
         tool,
         reason,
+        caller: callerOf(options) ?? "",
+        ...(options.actor === undefined ? {} : { actor: options.actor }),
         agentName: options.agentName,
         invocationId: options.invocationId,
         idempotencyKey,
@@ -2206,3 +2224,8 @@ export class AgentToolExecutor {
     return Math.max(0, Date.now() - startedAt);
   }
 }
+
+/** The caller of a call: an agent call is `"agent"`, otherwise the explicit caller. */
+function callerOf(options: AgentToolExecutionOptions): string | undefined {
+  return options.agentName ? "agent" : options.caller;
+}

package/core/agent/README.md

@@ -79,24 +79,25 @@ A class schema comes from codegen (the class must be reachable for OpenAPI or
 be a Tool contract); `agentJsonSchema(name, schema)` takes a JSON Schema
 directly.
 
-Runtime settings — limits, approval policy, audit sink, context builder —
-are registered once:
+Runtime settings (limits, context builder) and Tool execution settings
+(approval policy, audit sink, retries) are registered once; the Tool settings
+are shared by agents and `ToolRunner`:
 
 ```ts
 @Module({
-  providers: [DI.singleton(DI.valueProvider(AGENT_RUNTIME_OPTIONS, {
-    maxSteps: 6,
-    toolExecutorOptions: {
-      approvalPolicy: (request) => request.tool.sideEffect === "read",
+  providers: [
+    DI.singleton(DI.valueProvider(AGENT_RUNTIME_OPTIONS, { maxSteps: 6 })),
+    DI.singleton(DI.valueProvider(TOOL_EXECUTION_OPTIONS, {
+      approvalPolicy: (request) => request.tool.metadata.sideEffect === "read",
       auditSink: (entry) => auditStore.write(entry),
-    },
-  }))],
+    })),
+  ],
 })
 export class AgentSettingsModule {}
 ```
 
 Tool input and output are validated by the model validator
-(`modelValidatorAdapter`) unless `toolExecutorOptions.schemaValidator` says
+(`modelValidatorAdapter`) unless `TOOL_EXECUTION_OPTIONS.schemaValidator` says
 otherwise. Audit entries redact `input`, `result` and execution `metadata`
 by default using `bazis/library/redaction`.
 

package/core/agent/ToolRunner.ts

@@ -0,0 +1,135 @@
+import { DI, DiError, Global, HOSTED_SERVICE, Module, registerModuleMetadataExpander, SERVICE_PROVIDER, type BazisModuleMetadata, type ServiceProvider } from "../di";
+import { LOGGER } from "../kernel/logging/Logger";
+import { modelValidatorAdapter } from "../../library/validation";
+import { AgentRegistry, type ToolDefinition } from "./AgentRegistry";
+import { AgentToolExecutor, type AgentToolExecutionOptions } from "./AgentToolExecutor";
+import { AgentSetupError } from "./errors";
+import { callerId, type ToolActor } from "./metadata";
+import { describeTool } from "./Tool.contract";
+import { agentToolCall, agentToolResult, type AgentToolContract, type AgentToolResult } from "./semantic";
+import { TOOL_EXECUTION_OPTIONS, type ToolExecutionOptions } from "./toolExecutionOptions";
+
+/** One call of {@link BoundToolRunner.run}. */
+export interface ToolRunOptions extends Omit<AgentToolExecutionOptions, "agentName" | "caller" | "actor"> {
+  /** Id of the call in audit and hooks; a random uuid by default. */
+  readonly callId?: string;
+  /** On whose behalf the Tool runs. Required for `write` and `external` Tools. */
+  readonly actor?: ToolActor;
+}
+
+/**
+ * Runs the application's Tools without a model (TOOLS-001 §4). The framework
+ * registers it whenever a module declares `tools`; code binds it to its caller
+ * id and sees only the Tools whose `callers` list that id:
+ *
+ * ```ts
+ * constructor(runner: ToolRunner) { this.tools = runner.as("workflow"); }
+ * const result = await this.tools.run(step.toolName, input, { actor, idempotencyKey: stepId });
+ * ```
+ *
+ * The call goes through the same executor as an agent's call: input and output
+ * validation, DI scope, approval, audit, hooks, retries and deadline, configured
+ * once with `TOOL_EXECUTION_OPTIONS`.
+ */
+export class ToolRunner {
+  private readonly catalog: AgentRegistry;
+  private readonly executor: AgentToolExecutor;
+
+  constructor(services: ServiceProvider, options: ToolExecutionOptions = {}) {
+    const { logger, ...executorOptions } = options;
+    this.catalog = AgentRegistry.fromContainer(services);
+    // Invalid options and hook setup fail here, when the runner is built at start.
+    this.executor = new AgentToolExecutor(services, this.catalog, { schemaValidator: modelValidatorAdapter, ...executorOptions }, logger);
+  }
+
+  /** A view of the Tools this caller may run. `"agent"` is refused: agents run through `AgentRuntime`. */
+  as(caller: string): BoundToolRunner {
+    let id: string;
+    try {
+      id = callerId(caller);
+    } catch {
+      throw new AgentSetupError(`ToolRunner.as(${JSON.stringify(caller)}): a caller id is lower-case, such as "workflow".`);
+    }
+    if (id === "agent") throw new AgentSetupError('ToolRunner.as("agent"): agents run Tools through AgentRuntime.');
+    return new BoundToolRunner(id, this.catalog, this.executor);
+  }
+}
+
+/** {@link ToolRunner} bound to one caller id: it sees and runs only that caller's Tools. */
+export class BoundToolRunner {
+  constructor(
+    readonly caller: string,
+    private readonly catalog: AgentRegistry,
+    private readonly executor: AgentToolExecutor,
+  ) {}
+
+  /** The Tools this caller may run, optionally only those that carry every one of `tags`. */
+  listTools(tags: readonly string[] = []): readonly ToolDefinition[] {
+    return this.catalog.listTools().filter((tool) => tool.metadata.callers.includes(this.caller) && tags.every((tag) => tool.metadata.tags.includes(tag)));
+  }
+
+  /** The Tool registered under `name` if this caller may run it, otherwise `undefined`. */
+  getTool(name: string): ToolDefinition | undefined {
+    const tool = this.catalog.getTool(name);
+    return tool?.metadata.callers.includes(this.caller) ? tool : undefined;
+  }
+
+  /** The contract with the generated input and output JSON schemas, or `undefined`. */
+  describe(name: string): AgentToolContract | undefined {
+    const tool = this.getTool(name);
+    return tool === undefined ? undefined : describeTool(tool);
+  }
+
+  /**
+   * Runs the Tool `name` with `input`. Never throws for a Tool failure: an
+   * unknown name, a Tool this caller may not run (TOOL_CALLER_NOT_ALLOWED),
+   * invalid input, denial, timeout or an exception comes back as the result.
+   */
+  run(name: string, input: unknown, options: ToolRunOptions = {}): Promise<AgentToolResult> {
+    const { callId, actor, ...execution } = options;
+    const call = agentToolCall({ id: callId ?? crypto.randomUUID(), name, input: input as never });
+    const tool = this.catalog.getTool(name);
+    if (tool !== undefined && actor === undefined && (tool.metadata.sideEffect === "write" || tool.metadata.sideEffect === "external") && tool.metadata.callers.includes(this.caller)) {
+      return Promise.resolve(agentToolResult({
+        callId: call.id,
+        name,
+        status: "error",
+        error: { code: "TOOL_ACTOR_REQUIRED", message: `Tool "${name}" changes data: pass actor, the user or system the call runs for.` },
+        durationMs: 0,
+        metadata: {},
+      }));
+    }
+    return this.executor.execute(call, { ...execution, caller: this.caller, ...(actor === undefined ? {} : { actor }) });
+  }
+}
+
+/** Provides ToolRunner once per application and builds it at start, so wrong options stop the start. */
+@Global()
+@Module({
+  providers: [
+    DI.singleton(DI.factoryProviderWithResolver(ToolRunner, [], (resolver) => {
+      const services = resolver.resolve(SERVICE_PROVIDER);
+      const options = services.has(TOOL_EXECUTION_OPTIONS) ? services.resolve(TOOL_EXECUTION_OPTIONS) : {};
+      return new ToolRunner(services, { ...options, logger: options.logger ?? services.tryResolve(LOGGER) });
+    })),
+    DI.singleton(DI.factoryProviderWithResolver(HOSTED_SERVICE, [], (resolver) => ({
+      start() {
+        try {
+          resolver.resolve(ToolRunner);
+        } catch (error) {
+          if (error instanceof DiError) throw error;
+          throw new DiError(`ToolRunner: ${error instanceof Error ? error.message : String(error)}`);
+        }
+      },
+      stop() {},
+    }))),
+  ],
+  exports: [ToolRunner],
+})
+class ToolRunnerModule {}
+
+// A module that declares Tools brings the runner; importing it twice is one module.
+registerModuleMetadataExpander((metadata: BazisModuleMetadata) => {
+  const tools = (metadata as { readonly tools?: readonly unknown[] }).tools;
+  return Array.isArray(tools) && tools.length > 0 ? [ToolRunnerModule] : [];
+});

package/core/agent/index.ts

@@ -36,6 +36,8 @@ export {
   type AgentRuntimeToolCallContext,
   type AgentRuntimeToolExecutionOptions,
 } from "./AgentRuntime";
+export { BoundToolRunner, ToolRunner, type ToolRunOptions } from "./ToolRunner";
+export { TOOL_EXECUTION_OPTIONS, type ToolExecutionOptions } from "./toolExecutionOptions";
 export {
   ApproximateAgentContextTokenEstimator,
   DefaultAgentContextBuilder,

package/core/agent/internal/AgentExecutionDriver.ts

@@ -80,7 +80,6 @@ export interface AgentRuntimeOptions {
   readonly timeoutMs?: number;
   readonly contextBuilder?: AgentContextBuilder;
   readonly contextLimits?: AgentContextLimits;
-  readonly toolExecutorOptions?: AgentToolExecutorOptions;
   /**
    * Where failures of the model and unexpected tool failures go, with their
    * stack. The LLM connectors pass the application logger.
@@ -88,6 +87,14 @@ export interface AgentRuntimeOptions {
   readonly logger?: Logger;
 }
 
+/**
+ * @internal The driver also takes the Tool execution settings; `AgentRuntime`
+ * reads them from `TOOL_EXECUTION_OPTIONS`, shared with `ToolRunner`.
+ */
+export interface AgentExecutionDriverOptions extends AgentRuntimeOptions {
+  readonly toolExecutorOptions?: AgentToolExecutorOptions;
+}
+
 export interface AgentRuntimeInvokeOptions {
   readonly id?: string;
   readonly input?: unknown;
@@ -515,7 +522,7 @@ export class AgentExecutionDriver {
     services: ServiceProvider,
     private readonly registry: AgentRegistry,
     private readonly modelProvider: AgentModelProvider,
-    options: AgentRuntimeOptions = {},
+    options: AgentExecutionDriverOptions = {},
   ) {
     assertPositiveInteger(options.maxSteps, "AgentRuntime.maxSteps");
     assertPositiveInteger(options.maxToolCallsPerStep, "AgentRuntime.maxToolCallsPerStep");

package/core/agent/internal/ToolAudit.projector.ts

@@ -1,4 +1,5 @@
 import type { SensitiveRedactionOptions } from "../../../library/redaction";
+import type { ToolActor } from "../metadata";
 import { redactSensitive } from "../../../library/redaction";
 import type { ToolDefinition } from "../AgentRegistry";
 import type { AgentToolAuditHookProjectionV1 } from "../AgentToolHooks";
@@ -23,6 +24,10 @@ export interface AgentToolAuditEntry {
   readonly phase: AgentToolAuditPhase;
   readonly callId: string;
   readonly toolName: string;
+  /** `"agent"` for an agent call, otherwise the runner's caller id. */
+  readonly caller?: string;
+  /** On whose behalf the call ran. */
+  readonly actor?: ToolActor;
   readonly agentName?: string;
   readonly invocationId?: string;
   readonly attempt?: number;
@@ -39,6 +44,8 @@ export interface AgentToolAuditEntry {
 }
 
 interface ToolAuditOptions {
+  readonly caller?: string;
+  readonly actor?: ToolActor;
   readonly agentName?: string;
   readonly invocationId?: string;
   readonly auditRedaction?: SensitiveRedactionOptions | false;
@@ -70,6 +77,8 @@ export class ToolAuditProjector {
       phase: AgentToolAuditPhase;
       callId: string;
       toolName: string;
+      caller?: string;
+      actor?: ToolActor;
       agentName?: string;
       invocationId?: string;
       attempt?: number;
@@ -92,6 +101,13 @@ export class ToolAuditProjector {
       metadata: this.redactAuditValue(metadata, options) as JsonObject,
     };
 
+    const caller = options.agentName !== undefined || agentName !== undefined ? "agent" : options.caller;
+    if (caller !== undefined) {
+      entry.caller = caller;
+    }
+    if (options.actor !== undefined) {
+      entry.actor = options.actor;
+    }
     if (agentName !== undefined || options.agentName !== undefined) {
       entry.agentName = agentName ?? options.agentName;
     }

package/core/agent/metadata.ts

@@ -8,6 +8,12 @@ import { AgentSetupError } from "./errors";
 const TOOL_META = Symbol.for("bazis:agent:tool");
 
 export type ToolSideEffect = "none" | "read" | "write" | "external";
+
+/** On whose behalf a Tool runs: a user, or the system (a process, a job). */
+export interface ToolActor {
+  readonly kind: "user" | "system";
+  readonly id: string;
+}
 export type ToolApproval = "never" | "policy" | "required";
 
 export interface ToolOptions {
@@ -18,6 +24,13 @@ export interface ToolOptions {
   readonly sideEffect?: ToolSideEffect;
   readonly approval?: ToolApproval;
   readonly timeoutMs?: number;
+  /**
+   * Who may call the Tool: `"agent"` for LLM agents, any other id for code that
+   * runs Tools itself (`ToolRunner.as("workflow")`). Required and non-empty;
+   * a caller not listed is refused with TOOL_CALLER_NOT_ALLOWED.
+   */
+  readonly callers: readonly string[];
+  /** Grouping and search only; tags never decide who may call a Tool. */
   readonly tags?: readonly string[];
 }
 
@@ -29,6 +42,7 @@ export interface ToolMetadata {
   readonly sideEffect: ToolSideEffect;
   readonly approval: ToolApproval;
   readonly timeoutMs?: number;
+  readonly callers: readonly string[];
   readonly tags: readonly string[];
 }
 
@@ -51,6 +65,14 @@ function readonlyTextList(values: readonly string[] | undefined, field: string):
   return Object.freeze(values.map((value) => text(value, field)));
 }
 
+/** A caller id: `agent` or an application id such as `workflow`. */
+export function callerId(value: unknown): string {
+  if (typeof value !== "string" || !/^[a-z][a-z0-9_.-]{0,63}$/u.test(value)) {
+    throw new AgentSetupError(`@Tool.callers: ${JSON.stringify(value)} is not a caller id such as "agent" or "workflow".`);
+  }
+  return value;
+}
+
 function positiveInteger(value: number | undefined, field: string): number | undefined {
   if (value === undefined) {
     return undefined;
@@ -89,6 +111,9 @@ export function defineToolMetadata(_target: object, metadata: object, options: T
     sideEffect,
     approval: approvalFor(sideEffect, options.approval),
     timeoutMs: positiveInteger(options.timeoutMs, "@Tool.timeoutMs"),
+    // Checked when the module registers the Tool, so a missing list prints as
+    // one configuration-error line at start instead of failing the import.
+    callers: Array.isArray(options.callers) ? Object.freeze(options.callers.map((caller) => callerId(caller))) : Object.freeze([]),
     tags: readonlyTextList(options.tags, "@Tool.tags"),
   });
   (metadata as MetadataCarrier)[TOOL_META] = normalized;

package/core/agent/moduleContributions-v1.ts

@@ -60,7 +60,11 @@ registerModuleOwnedProviderContributor((metadata: BazisModuleMetadata, context)
   const owner = metadata as BazisModuleRef;
   const fields = metadata as BazisModuleMetadata & AgentModuleFields;
   for (const target of classValues(fields.tools, "tools")) {
-    if (!toolMetadataOf(target)) throw new AgentSetupError(`${target.name || "<anonymous class>"} is listed as a tool but is not decorated with @Tool(...).`);
+    const tool = toolMetadataOf(target);
+    if (!tool) throw new AgentSetupError(`${target.name || "<anonymous class>"} is listed as a tool but is not decorated with @Tool(...).`);
+    if (tool.callers.length === 0) {
+      throw new AgentSetupError(`Tool "${tool.name}" (${target.name || "<anonymous class>"}) declares no callers: list who may call it, for example callers: ["agent"] for LLM agents or ["workflow"] for a process engine.`);
+    }
     try {
       context.registerScoped(TOOL_CHANNEL, scoped(target), Object.freeze({ target, owner }));
     } catch (error) {

package/core/agent/toolExecutionOptions.ts

@@ -0,0 +1,15 @@
+import { createToken } from "../di";
+import type { Logger } from "../kernel/logging/Logger";
+import type { AgentToolExecutorOptions } from "./AgentToolExecutor";
+
+/**
+ * How Tools run for every caller: approval policy, audit sink, retries,
+ * deadlines and hooks. Register one value in any module; `AgentRuntime` and
+ * `ToolRunner` read it from the root container (TOOLS-001 §6).
+ */
+export interface ToolExecutionOptions extends AgentToolExecutorOptions {
+  /** Where unexpected Tool failures go with their stack. Defaults to the application logger. */
+  readonly logger?: Logger;
+}
+
+export const TOOL_EXECUTION_OPTIONS = createToken<ToolExecutionOptions>("ToolExecutionOptions");

package/core/infra/connectors/codex/CodexAppServerClient.ts

@@ -232,7 +232,7 @@ export class CodexAppServerClient implements CodexClient {
         if (method === "account/updated") this.modelCache = undefined;
       }, () => { this.clearLogin(); this.modelCache = undefined; });
       const initialized = await client.request("initialize", {
-        clientInfo: { name: "bazis", title: "Bazis", version: "0.121.0" }, capabilities: { experimentalApi: true },
+        clientInfo: { name: "bazis", title: "Bazis", version: "0.123.0" }, capabilities: { experimentalApi: true },
       }, 15_000, signal);
       if (resolve(text(initialized.codexHome, 4096)) !== this.paths.home) throw new CodexError("PROTOCOL_ERROR");
       client.notify("initialized");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bazis",
-  "version": "0.121.0",
+  "version": "0.123.0",
   "description": "Modular backend framework for Bun in TypeScript: DI wired by codegen, HTTP, a PostgreSQL ORM, JWT, WebSocket, agents and a CLI.",
   "license": "MIT",
   "author": "Alexander Alenin",