@openagentid/claude-agent/hooks

All packages · Runnable examples · Start an agent

This reference is generated from the integrity-verified npm archive for this exact version. Signatures describe the public contract; they are not standalone programs. Complete examples are checked separately.

Import conditions

Use the public entry point above. The package resolves it to these shipped files; do not import its internal files directly.

Exports

• HookContext — type
• MessageInput — type
• onMessage
• OnMessageResult — type
• onSessionEnd
• onSessionStart
• onSkillInvoke
• onSkillInvokeOrThrow
• postToolUse
• PostToolUseInput — type
• preToolUse
• preToolUseOrThrow
• PreToolUseResult — type
• SessionStartInput — type
• SessionStartResult — type
• SkillInvokeInput — type
• SkillInvokeResult — type
• ToolUseInput — type

HookContext

Per-session state that the hooks share. Constructed once when the session starts and disposed when it ends.

Type-only declaration; it is not a runtime value.

interface HookContext {
    readonly identity: OpenAgentIdentity;
    readonly capabilities: CapabilityChecker;
    readonly skillsPolicy: SkillsPolicy;
    readonly chain: AuditChain;
    readonly signMessages: boolean;
}

Source: @openagentid/claude-agent@0.1.1, dist/hooks.d.ts:21.

MessageInput

Input shape for {@link onMessage}.

Type-only declaration; it is not a runtime value.

interface MessageInput {
    body: string | Uint8Array;
    direction: 'in' | 'out';
}

Source: @openagentid/claude-agent@0.1.1, dist/hooks.d.ts:98.

onMessage

Sign an outbound message with the agent's Ed25519 key (if signing is enabled) and append an audit record.

declare function onMessage(input: MessageInput, ctx: HookContext): Promise<OnMessageResult>;

Source: @openagentid/claude-agent@0.1.1, dist/hooks.d.ts:115.

OnMessageResult

Result of {@link onMessage}.

Type-only declaration; it is not a runtime value.

interface OnMessageResult {
    signature?: string;
    record: AuditRecord;
}

Source: @openagentid/claude-agent@0.1.1, dist/hooks.d.ts:105.

onSessionEnd

Emit a closing record at session end.

declare function onSessionEnd(ctx: HookContext): Promise<AuditRecord>;

Source: @openagentid/claude-agent@0.1.1, dist/hooks.d.ts:138.

onSessionStart

Initialise the per-session hook context and emit the opening audit record. Call this once when the Claude Agent SDK fires the session start hook.

declare function onSessionStart(input: SessionStartInput, ctx: Omit<HookContext, 'chain'> & {
    sink: AuditSink;
}): Promise<SessionStartResult>;

Source: @openagentid/claude-agent@0.1.1, dist/hooks.d.ts:44.

onSkillInvoke

Consult the OpenAgent skills policy before a SKILLS.md skill runs.

The Claude Agent SDK loads skills from SKILLS.md files; we hook the invocation point and refuse anything the policy denies. Default policy is DenyUnlessScopedSkillsPolicy.

declare function onSkillInvoke(input: SkillInvokeInput, ctx: HookContext): Promise<SkillInvokeResult>;

Source: @openagentid/claude-agent@0.1.1, dist/hooks.d.ts:134.

onSkillInvokeOrThrow

Throw-on-deny variant of {@link onSkillInvoke}.

declare function onSkillInvokeOrThrow(input: SkillInvokeInput, ctx: HookContext): Promise<SkillInvokeResult>;

Source: @openagentid/claude-agent@0.1.1, dist/hooks.d.ts:136.

postToolUse

Emit a post-tool-use audit record with input + output hashes.

The record's hash chain prevents post-hoc tampering: a verifier can replay {@link import ('./audit.js').verifyChain} over an exported chain to detect any modification.

declare function postToolUse(input: PostToolUseInput, ctx: HookContext): Promise<AuditRecord>;

Source: @openagentid/claude-agent@0.1.1, dist/hooks.d.ts:96.

PostToolUseInput

Input shape for {@link postToolUse}.

Type-only declaration; it is not a runtime value.

interface PostToolUseInput {
    toolName: string;
    result: unknown;
    ok: boolean;
    error?: string;
    inputHash?: string;
}

Source: @openagentid/claude-agent@0.1.1, dist/hooks.d.ts:78.

preToolUse

Verify a tool call against Arsenal scopes and emit a preflight audit record.

Returns { allow: false } rather than throwing so the caller can decide whether to short-circuit the SDK or surface an error to the model. The plugin's hook adapter throws {@link ToolDeniedError } when the SDK requires an exception-based deny.

declare function preToolUse(input: ToolUseInput, ctx: HookContext): Promise<PreToolUseResult>;

Source: @openagentid/claude-agent@0.1.1, dist/hooks.d.ts:74.

preToolUseOrThrow

Throw-on-deny variant of {@link preToolUse}.

declare function preToolUseOrThrow(input: ToolUseInput, ctx: HookContext): Promise<PreToolUseResult>;

Source: @openagentid/claude-agent@0.1.1, dist/hooks.d.ts:76.

PreToolUseResult

Result of a pre-tool-use evaluation.

Type-only declaration; it is not a runtime value.

interface PreToolUseResult {
    allow: boolean;
    reason?: string;
    record: AuditRecord;
    inputHash: string;
}

Source: @openagentid/claude-agent@0.1.1, dist/hooks.d.ts:55.

SessionStartInput

Input shape for {@link onSessionStart}.

Type-only declaration; it is not a runtime value.

interface SessionStartInput {
    sessionId: string;
}

Source: @openagentid/claude-agent@0.1.1, dist/hooks.d.ts:29.

SessionStartResult

Result of {@link onSessionStart}.

Type-only declaration; it is not a runtime value.

interface SessionStartResult {
    record: AuditRecord;
    context: HookContext;
}

Source: @openagentid/claude-agent@0.1.1, dist/hooks.d.ts:33.

SkillInvokeInput

Input shape for {@link onSkillInvoke}.

Type-only declaration; it is not a runtime value.

interface SkillInvokeInput {
    skillName: string;
    args?: unknown;
    metadata?: Record<string, unknown>;
}

Source: @openagentid/claude-agent@0.1.1, dist/hooks.d.ts:117.

SkillInvokeResult

Result of {@link onSkillInvoke}.

Type-only declaration; it is not a runtime value.

interface SkillInvokeResult {
    decision: SkillDecision;
    record: AuditRecord;
}

Source: @openagentid/claude-agent@0.1.1, dist/hooks.d.ts:123.

ToolUseInput

Input shape for {@link preToolUse}.

Type-only declaration; it is not a runtime value.

interface ToolUseInput {
    toolName: string;
    args: unknown;
}

Source: @openagentid/claude-agent@0.1.1, dist/hooks.d.ts:48.

Supporting declarations

These package-owned declarations are referenced by the exports above. Their presence here does not make them importable from this entry point. Import only the names in Exports.

AuditChain

Builds and signs (hash-chains) audit records. The chain is owned by a single session — callers should construct one chain per session.

declare class AuditChain {
    constructor(opts: {
        sessionId: string;
        agentDid: string;
        sink: AuditSink;
    });
    append(input: {
        kind: AuditKind;
        name?: string;
        outcome: AuditRecord["outcome"];
        inputHash?: string;
        outputHash?: string;
        context?: Record<string, unknown>;
    }): Promise<AuditRecord>;
    head(): string;
}

Source: @openagentid/claude-agent@0.1.1, dist/audit.d.ts:24.

AuditKind

Categories of audit events.

Type-only declaration; it is not a runtime value.

type AuditKind = 'session.start' | 'session.stop' | 'tool.preflight' | 'tool.complete' | 'skill.preflight' | 'skill.complete' | 'message.signed' | 'policy.deny';

Source: @openagentid/claude-agent@0.1.1, dist/types-BH6j5Zy9.d.ts:83.

AuditRecord

A single tamper-evident audit record.

Type-only declaration; it is not a runtime value.

interface AuditRecord {
    seq: number;
    timestamp: string;
    sessionId: string;
    agentDid: string;
    kind: AuditKind;
    name?: string;
    outcome: 'allow' | 'deny' | 'ok' | 'error';
    inputHash?: string;
    outputHash?: string;
    prevHash: string;
    hash: string;
    context?: Record<string, unknown>;
}

Source: @openagentid/claude-agent@0.1.1, dist/types-BH6j5Zy9.d.ts:56.

AuditSink

Audit sink — receives one record per tool / skill invocation.

Type-only declaration; it is not a runtime value.

interface AuditSink {
    append(record: AuditRecord): Promise<void> | void;
}

Source: @openagentid/claude-agent@0.1.1, dist/types-BH6j5Zy9.d.ts:51.

CapabilityChecker

Anything implementing this can authorise tool / skill invocations.

Type-only declaration; it is not a runtime value.

interface CapabilityChecker {
    check(scope: string): Promise<ScopeDecision> | ScopeDecision;
}

Source: @openagentid/claude-agent@0.1.1, dist/types-BH6j5Zy9.d.ts:41.

OpenAgentIdentity

A verified OpenAgent identity, anchored on a did:oas:* string.

Type-only declaration; it is not a runtime value.

interface OpenAgentIdentity {
    did: string;
    kind: string;
    displayName?: string;
    publicKey: string;
    sign(payload: Uint8Array): Promise<Uint8Array> | Uint8Array;
    lineage?: readonly string[];
}

Source: @openagentid/claude-agent@0.1.1, dist/types-BH6j5Zy9.d.ts:12.

ScopeDecision

Result of a credential / scope check.

Type-only declaration; it is not a runtime value.

interface ScopeDecision {
    allowed: boolean;
    matchedScope?: string;
    reason?: string;
}

Source: @openagentid/claude-agent@0.1.1, dist/types-BH6j5Zy9.d.ts:32.

SkillDecision

Result of a skills policy evaluation.

Type-only declaration; it is not a runtime value.

interface SkillDecision {
    allowed: boolean;
    reason?: string;
    matchedScope?: string;
}

Source: @openagentid/claude-agent@0.1.1, dist/types-BH6j5Zy9.d.ts:113.

SkillEvaluationContext

Context passed to a skills policy evaluation.

Type-only declaration; it is not a runtime value.

interface SkillEvaluationContext {
    identity: OpenAgentIdentity;
    capabilities: CapabilityChecker;
    metadata?: Record<string, unknown>;
}

Source: @openagentid/claude-agent@0.1.1, dist/types-BH6j5Zy9.d.ts:104.

SkillsPolicy

Skills policy: decides whether a SKILLS.md skill may be invoked.

Type-only declaration; it is not a runtime value.

interface SkillsPolicy {
    evaluate(skillName: string, ctx: SkillEvaluationContext): Promise<SkillDecision> | SkillDecision;
}

Source: @openagentid/claude-agent@0.1.1, dist/types-BH6j5Zy9.d.ts:94.

Package requirements

Peer dependencies

Archive verification

Pinned integrity:

sha512-kUX3T6aS6PYr0GqQmLG7t2DLeOquNBVAoDkXN1yk09ffh6S5TIuHQgA2jptxjgLetu4n3XXP0AmEFb+jgQ1Dow==

Machine-readable API manifest · Coverage