@openagentid/claude-agent

All packages · Runnable examples · Start an agent

Entry points

• @openagentid/claude-agent/hooks
• @openagentid/claude-agent/policy
• @openagentid/claude-agent/audit

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

• AllowListSkillsPolicy
• AuditChain
• AuditKind — type
• AuditRecord — type
• AuditSink — type
• canonicalJson
• CapabilityChecker — type
• CompositeSkillsPolicy
• ConfigError
• ConsoleAuditSink
• DenyUnlessScopedSkillsPolicy
• FanOutAuditSink
• GENESIS_PREV_HASH
• getHashAlgo
• hashHex
• hashRecord
• HookContext — type
• HookDecision — type
• InMemoryAuditSink
• MessageInput — type
• onMessage
• OnMessageResult — type
• onSessionEnd
• onSessionStart
• onSkillInvoke
• onSkillInvokeOrThrow
• OpenAgentIdentity — type
• openAgentPlugin
• OpenAgentPlugin — type
• OpenAgentPluginOptions — type
• PluginError
• PluginErrorCode
• PluginErrorCodeValue — type
• PluginHooks — type
• postToolUse
• PostToolUseInput — type
• preToolUse
• preToolUseOrThrow
• PreToolUseResult — type
• ScopeDecision — type
• SessionStartInput — type
• SessionStartResult — type
• SKILL_SCOPE_PREFIX
• SkillDecision — type
• SkillDeniedError
• SkillEvaluationContext — type
• SkillInvokeInput — type
• SkillInvokeResult — type
• skillScope
• SkillsManifestEntry — type
• SkillsPolicy — type
• StaticCapabilityChecker
• TOOL_SCOPE_PREFIX
• ToolDeniedError
• toolScope
• ToolUseInput — type
• verifyChain

AllowListSkillsPolicy

Allow-listed skills policy: only the named skills are permitted, and the agent must additionally hold the right scope.

declare class AllowListSkillsPolicy implements SkillsPolicy {
    constructor(allowedSkills: Iterable<string>, inner?: SkillsPolicy);
    evaluate(skillName: string, ctx: SkillEvaluationContext): Promise<SkillDecision>;
}

Source: @openagentid/claude-agent@0.1.1, dist/policy.d.ts:52.

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.

canonicalJson

Stable JSON stringify (sorted keys) for deterministic hashing.

declare function canonicalJson(value: unknown): string;

Source: @openagentid/claude-agent@0.1.1, dist/index.d.ts:152.

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.

CompositeSkillsPolicy

Compose multiple policies — a skill is allowed only if every policy allows it. Useful for stacking allow-list + scope + custom policies.

declare class CompositeSkillsPolicy implements SkillsPolicy {
    constructor(policies: readonly SkillsPolicy[]);
    evaluate(skillName: string, ctx: SkillEvaluationContext): Promise<SkillDecision>;
}

Source: @openagentid/claude-agent@0.1.1, dist/policy.d.ts:62.

ConfigError

Configuration was invalid at plugin construction time.

declare class ConfigError extends PluginError {
    constructor(message: string, context?: Record<string, unknown>);
}

Source: @openagentid/claude-agent@0.1.1, dist/index.d.ts:130.

ConsoleAuditSink

Audit sink that writes structured JSON to stdout — handy for dev.

declare class ConsoleAuditSink implements AuditSink {
    append(record: AuditRecord): void;
}

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

DenyUnlessScopedSkillsPolicy

Deny-unless-scoped skills policy.

For a skill named foo, requires the agent to hold skills:invoke:foo (or a wildcard that subsumes it). This is the default policy when the caller passes audit: true without supplying their own.

declare class DenyUnlessScopedSkillsPolicy implements SkillsPolicy {
    evaluate(skillName: string, ctx: SkillEvaluationContext): Promise<SkillDecision>;
}

Source: @openagentid/claude-agent@0.1.1, dist/policy.d.ts:45.

FanOutAuditSink

Compose multiple sinks (records are dispatched to all in order).

declare class FanOutAuditSink implements AuditSink {
    constructor(sinks: readonly AuditSink[]);
    append(record: AuditRecord): Promise<void>;
}

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

GENESIS_PREV_HASH

Sentinel for the head of the chain.

declare const GENESIS_PREV_HASH: string;

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

getHashAlgo

Resolve which hash algorithm to use, attempting to load blake3 once. Subsequent calls are cached.

declare function getHashAlgo(): HashAlgo;

Source: @openagentid/claude-agent@0.1.1, dist/index.d.ts:148.

hashHex

Hash a string or byte buffer and return lowercase hex.

declare function hashHex(data: string | Uint8Array): string;

Source: @openagentid/claude-agent@0.1.1, dist/index.d.ts:150.

hashRecord

Compute the hash of a record (excludes the hash field itself).

declare function hashRecord(record: AuditRecord): string;

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

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.

HookDecision

Decision object returned by gating hooks (preToolUse, onSkillInvoke).

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

interface HookDecision {
    allow: boolean;
    reason?: string;
    inputHash?: string;
}

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

InMemoryAuditSink

In-memory audit sink (handy for tests + dry runs).

declare class InMemoryAuditSink implements AuditSink {
    readonly records: AuditRecord[];
    append(record: AuditRecord): void;
    clear(): void;
}

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

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.

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.

openAgentPlugin

Build a Claude Agent SDK plugin that wires OpenAgent identity, capability control, and tamper-evident audit logging into the agent lifecycle.

declare function openAgentPlugin(opts: OpenAgentPluginOptions): OpenAgentPlugin;

Source: @openagentid/claude-agent@0.1.1, dist/index.d.ts:89.

OpenAgentPlugin

Shape returned by {@link openAgentPlugin}.

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

interface OpenAgentPlugin {
    readonly name: '@openagentid/claude-agent';
    readonly version: string;
    readonly hooks: PluginHooks;
    inspectAudit(): readonly AuditRecord[];
}

Source: @openagentid/claude-agent@0.1.1, dist/index.d.ts:36.

OpenAgentPluginOptions

Configuration accepted by {@link openAgentPlugin}.

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

interface OpenAgentPluginOptions {
    agent: OpenAgentIdentity;
    capabilities: CapabilityChecker;
    skillsPolicy?: SkillsPolicy;
    audit?: boolean | AuditSink;
    signMessages?: boolean;
    denyMode?: 'throw' | 'block';
}

Source: @openagentid/claude-agent@0.1.1, dist/index.d.ts:9.

PluginError

Base error for the plugin.

declare class PluginError extends Error {
    readonly code: PluginErrorCodeValue;
    readonly context?: Record<string, unknown>;
    readonly cause?: unknown;
    constructor(message: string, code: PluginErrorCodeValue, options?: {
        context?: Record<string, unknown>;
        cause?: unknown;
    });
    toJSON(): Record<string, unknown>;
}

Source: @openagentid/claude-agent@0.1.1, dist/index.d.ts:109.

PluginErrorCode

Stable, machine-readable error codes.

declare const PluginErrorCode: {
    readonly CONFIG_INVALID: "openagent/claude-agent/config-invalid";
    readonly IDENTITY_MISSING: "openagent/claude-agent/identity-missing";
    readonly TOOL_DENIED: "openagent/claude-agent/tool-denied";
    readonly SKILL_DENIED: "openagent/claude-agent/skill-denied";
    readonly AUDIT_FAILED: "openagent/claude-agent/audit-failed";
    readonly HOOK_INTERNAL: "openagent/claude-agent/hook-internal";
    readonly SIGN_FAILED: "openagent/claude-agent/sign-failed";
};

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

PluginErrorCodeValue

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

type PluginErrorCodeValue = (typeof PluginErrorCode)[keyof typeof PluginErrorCode];

Source: @openagentid/claude-agent@0.1.1, dist/index.d.ts:107.

PluginHooks

Bound hook handlers. Each method receives the SDK's hook input plus the SDK-managed context object and returns a plain JS object the SDK can route. The shapes below are the documented Claude Agent SDK hook signatures; if Anthropic adds a new lifecycle stage we add a new method here without breaking existing wiring.

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

interface PluginHooks {
    onSessionStart(input: SessionStartInput): Promise<{
        allow: true;
    }>;
    preToolUse(input: ToolUseInput): Promise<HookDecision>;
    postToolUse(input: PostToolUseInput): Promise<{
        ok: true;
    }>;
    onMessage(input: MessageInput): Promise<{
        allow: true;
        signature?: string;
    }>;
    onSkillInvoke(input: SkillInvokeInput): Promise<HookDecision>;
    onSessionEnd(): Promise<{
        ok: true;
    }>;
}

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

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.

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.

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.

SKILL_SCOPE_PREFIX

Scope grammar for skill invocations.

declare const SKILL_SCOPE_PREFIX = "skills:invoke:";

Source: @openagentid/claude-agent@0.1.1, dist/policy.d.ts:18.

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.

SkillDeniedError

A skill invocation was rejected by the skills policy.

declare class SkillDeniedError extends PluginError {
    readonly skill: string;
    constructor(skill: string, reason?: string, context?: Record<string, unknown>);
}

Source: @openagentid/claude-agent@0.1.1, dist/index.d.ts:125.

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.

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.

skillScope

Build the canonical scope string for a skill name.

declare function skillScope(name: string): string;

Source: @openagentid/claude-agent@0.1.1, dist/policy.d.ts:22.

SkillsManifestEntry

SKILLS.md entry as parsed from a manifest.

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

interface SkillsManifestEntry {
    name: string;
    description?: string;
    requiredScope?: string;
}

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

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.

StaticCapabilityChecker

Capability checker backed by a fixed allowlist. Supports literal scopes and one wildcard form: prefix:* matches anything starting with prefix:.

Example: tools:invoke:* allows every tool, skills:invoke:web.* allows every skill whose name starts with web..

declare class StaticCapabilityChecker implements CapabilityChecker {
    constructor(scopes: Iterable<string>);
    check(scope: string): ScopeDecision;
}

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

TOOL_SCOPE_PREFIX

Scope grammar for tool invocations.

declare const TOOL_SCOPE_PREFIX = "tools:invoke:";

Source: @openagentid/claude-agent@0.1.1, dist/policy.d.ts:20.

ToolDeniedError

A tool call was rejected because the agent lacks the required scope.

declare class ToolDeniedError extends PluginError {
    readonly tool: string;
    constructor(tool: string, reason?: string, context?: Record<string, unknown>);
}

Source: @openagentid/claude-agent@0.1.1, dist/index.d.ts:120.

toolScope

Build the canonical scope string for a tool name.

declare function toolScope(name: string): string;

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

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.

verifyChain

Verify that a previously emitted chain has not been tampered with.

declare function verifyChain(records: readonly AuditRecord[]): {
    valid: boolean;
    brokenAt?: number;
};

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

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.

HashAlgo

Identifier for the hash primitive in use.

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

type HashAlgo = 'blake3' | 'sha256';

Source: @openagentid/claude-agent@0.1.1, dist/index.d.ts:143.

Package requirements

Peer dependencies

Archive verification

Pinned integrity:

sha512-kUX3T6aS6PYr0GqQmLG7t2DLeOquNBVAoDkXN1yk09ffh6S5TIuHQgA2jptxjgLetu4n3XXP0AmEFb+jgQ1Dow==

Machine-readable API manifest · Coverage