Rulvar API reference

---

Rulvar API reference / @rulvar/rulvar / 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/dist/index.d.ts

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/dist/index.d.ts
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/dist/index.d.ts
toolName	string	-	packages/core/dist/index.d.ts
type	"tool:start"	-	packages/core/dist/index.d.ts

---

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/dist/index.d.ts
decidedBy?	string	-	packages/core/dist/index.d.ts
durationMs	number	-	packages/core/dist/index.d.ts
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/dist/index.d.ts
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/dist/index.d.ts
outcome	"ok" | "error" | "denied"	-	packages/core/dist/index.d.ts
rule?	Json	-	packages/core/dist/index.d.ts
toolCallId?	string	-	packages/core/dist/index.d.ts
toolName	string	-	packages/core/dist/index.d.ts
type	"tool:end"	-	packages/core/dist/index.d.ts
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/dist/index.d.ts