Rulvar API reference

---

Rulvar API reference / @rulvar/core / ToolEvents

Type Alias: ToolEvents

type ToolEvents = 
  | {
  risk?: Json;
  toolCallId?: string;
  toolName: string;
  type: "tool:start";
}
  | {
  advisory?: Json;
  decidedBy?: string;
  durationMs: number;
  errorCode?: string;
  guard?: "repeated-signature" | "per-tool-cap" | "finalization-window";
  outcome: "ok" | "error" | "denied";
  rule?: Json;
  toolCallId?: string;
  toolName: string;
  type: "tool:end";
  verdict?: "allow" | "deny" | "ask";
};

Defined in: packages/core/src/l0/events.ts:521

Tool lifecycle (emitters arrive with the tool system, M3).

Union Members

Type Literal

{
  risk?: Json;
  toolCallId?: string;
  toolName: string;
  type: "tool:start";
}

Name	Type	Description	Defined in
risk?	Json	-	packages/core/src/l0/events.ts:539
toolCallId?	string	The model-minted id of this tool call (RV908): the same id the journal's messages and tool-result parts carry, so a consumer pairs start and end EXACTLY even among concurrent same-name calls, instead of FIFO-guessing by (spanId, toolName). Present on every live event this engine emits, and on every replayed reconstruction (whose events exist only when the turn checkpoint blob is retrievable; the id rides the checkpoint's tool-result parts, so even journals written before RV908 name their calls there). Absent only on streams recorded before RV908 or written by foreign emitters, where consumers keep their historical pairing.	packages/core/src/l0/events.ts:538
toolName	string	-	packages/core/src/l0/events.ts:524
type	"tool:start"	-	packages/core/src/l0/events.ts:523

---

Type Literal

{
  advisory?: Json;
  decidedBy?: string;
  durationMs: number;
  errorCode?: string;
  guard?: "repeated-signature" | "per-tool-cap" | "finalization-window";
  outcome: "ok" | "error" | "denied";
  rule?: Json;
  toolCallId?: string;
  toolName: string;
  type: "tool:end";
  verdict?: "allow" | "deny" | "ask";
}

Name	Type	Description	Defined in
advisory?	Json	-	packages/core/src/l0/events.ts:557
decidedBy?	string	-	packages/core/src/l0/events.ts:555
durationMs	number	-	packages/core/src/l0/events.ts:547
errorCode?	string	The structured failure reason on outcome 'error' (RV1807), so public telemetry distinguishes a not-settled child read from a genuine failure without the private transcript. Engine-stamped literals include 'unknown-tool', 'invalid-arguments', 'model-retry', 'non-serializable-result', 'executor-unregistered', 'unknown-handle', 'child-not-settled', and 'unknown-artifact'; a tool that throws a RulvarError carrying data.errorCode surfaces that string, a bare RulvarError surfaces its coarse code class, and anything else stays reasonless. Telemetry, never identity.	packages/core/src/l0/events.ts:577
guard?	"repeated-signature" | "per-tool-cap" | "finalization-window"	Present when an engine guard, not the permission chain, denied the call: the exploration guards (RV-210) or the finalization window (RV302). The outcome is 'denied' and the call was never dispatched.	packages/core/src/l0/events.ts:564
outcome	"ok" | "error" | "denied"	-	packages/core/src/l0/events.ts:546
rule?	Json	-	packages/core/src/l0/events.ts:556
toolCallId?	string	The same call id as the matching tool:start (RV908).	packages/core/src/l0/events.ts:545
toolName	string	-	packages/core/src/l0/events.ts:543
type	"tool:end"	-	packages/core/src/l0/events.ts:542
verdict?	"allow" | "deny" | "ask"	Audit fields (M5-T05): the chain verdict, the deciding layer, the matched rule, and advisory domain-rule matches. Telemetry, never identity; ask verdicts additionally journal as suspended approvals.	packages/core/src/l0/events.ts:554