@openagentid/claude-agent API

export declare const openAgentPlugin: (opts: OpenAgentPluginOptions) => OpenAgentPlugin;

/** Shape returned by {@link openAgentPlugin}. */
export interface OpenAgentPlugin {
    /** Stable plugin identifier. */
    readonly name: '@openagentid/claude-agent';
    /** Plugin schema version. */
    readonly version: string;
    /** Bound hook handlers — wired to the Claude Agent SDK lifecycle. */
    readonly hooks: PluginHooks;
    /**
     * Inspect the in-memory audit buffer (only populated when `audit: true`
     * with the default sink). Returns an empty array otherwise.
     */
    inspectAudit(): readonly import('./types.js').AuditRecord[];
}

/** Configuration accepted by {@link openAgentPlugin}. */
export interface OpenAgentPluginOptions {
    /** Verified OpenAgent identity to attach to the session. Required. */
    agent: OpenAgentIdentity;
    /** Capability checker — Arsenal-backed in production. Required. */
    capabilities: CapabilityChecker;
    /** Skills policy. Defaults to {@link DenyUnlessScopedSkillsPolicy}. */
    skillsPolicy?: SkillsPolicy;
    /**
     * Audit configuration:
     *   - `false`            → no audit (records are dropped)
     *   - `true`             → in-memory + stdout console sink
     *   - {@link AuditSink}  → custom sink
     */
    audit?: boolean | AuditSink;
    /**
     * Sign every outbound message with the agent's Ed25519 key. Defaults
     * to `false` because most agent flows don't need it.
     */
    signMessages?: boolean;
    /**
     * Behaviour on a denied tool / skill:
     *   - `'throw'`  (default) — throws {@link ToolDeniedError} or {@link SkillDeniedError}
     *   - `'block'`  — returns a blocking decision object the SDK can interpret
     */
    denyMode?: 'throw' | 'block';
}

/**
 * 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.
 */
export 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;
    }>;
}

/** Decision object returned by gating hooks (preToolUse, onSkillInvoke). */
export interface HookDecision {
    allow: boolean;
    reason?: string;
    /**
     * Hash of the canonicalised tool input (preToolUse only) — thread it into
     * the matching postToolUse call so the audit chain links preflight to
     * completion.
     */
    inputHash?: string;
}

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

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

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

export declare const GENESIS_PREV_HASH: string;

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

export declare const hashRecord: (record: AuditRecord) => string;

export declare const verifyChain: (records: readonly AuditRecord[]) => { valid: boolean; brokenAt?: number; };

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

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

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

export declare const SKILL_SCOPE_PREFIX: "skills:invoke:";

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

export declare const TOOL_SCOPE_PREFIX: "tools:invoke:";

export declare const skillScope: (name: string) => string;

export declare const toolScope: (name: string) => string;

export declare const onMessage: (input: MessageInput, ctx: HookContext) => Promise<OnMessageResult>;

export declare const onSessionEnd: (ctx: HookContext) => Promise<AuditRecord>;

export declare const onSessionStart: (input: SessionStartInput, ctx: Omit<HookContext, "chain"> & { sink: AuditSink; }) => Promise<SessionStartResult>;

export declare const onSkillInvoke: (input: SkillInvokeInput, ctx: HookContext) => Promise<SkillInvokeResult>;

export declare const onSkillInvokeOrThrow: (input: SkillInvokeInput, ctx: HookContext) => Promise<SkillInvokeResult>;

export declare const postToolUse: (input: PostToolUseInput, ctx: HookContext) => Promise<AuditRecord>;

export declare const preToolUse: (input: ToolUseInput, ctx: HookContext) => Promise<PreToolUseResult>;

export declare const preToolUseOrThrow: (input: ToolUseInput, ctx: HookContext) => Promise<PreToolUseResult>;

/**
 * Per-session state that the hooks share. Constructed once when the
 * session starts and disposed when it ends.
 */
export interface HookContext {
    readonly identity: OpenAgentIdentity;
    readonly capabilities: CapabilityChecker;
    readonly skillsPolicy: SkillsPolicy;
    readonly chain: AuditChain;
    readonly signMessages: boolean;
}

/** Input shape for {@link onMessage}. */
export interface MessageInput {
    /** Plain-text or already-serialised message body. */
    body: string | Uint8Array;
    /** Direction of the message — used for the audit context only. */
    direction: 'in' | 'out';
}

/** Result of {@link onMessage}. */
export interface OnMessageResult {
    /** Hex-encoded Ed25519 signature, when message signing is enabled. */
    signature?: string;
    /** Audit record emitted for this message. */
    record: AuditRecord;
}

/** Input shape for {@link postToolUse}. */
export interface PostToolUseInput {
    toolName: string;
    /** Tool result (any shape). */
    result: unknown;
    /** Was the underlying call successful? */
    ok: boolean;
    /** Optional error description if the call failed. */
    error?: string;
    /** Hash of the original input — typically threaded from preToolUse. */
    inputHash?: string;
}

/** Result of a pre-tool-use evaluation. */
export interface PreToolUseResult {
    /** Whether the tool call may proceed. */
    allow: boolean;
    /** Reason on deny. */
    reason?: string;
    /** The audit record emitted (preflight). */
    record: AuditRecord;
    /** Hash of the canonicalised input — reused by post hook. */
    inputHash: string;
}

/** Input shape for {@link onSessionStart}. */
export interface SessionStartInput {
    sessionId: string;
}

/** Result of {@link onSessionStart}. */
export interface SessionStartResult {
    /** The audit record emitted for the session start. */
    record: AuditRecord;
    /** The hook context to be threaded through subsequent hooks. */
    context: HookContext;
}

/** Input shape for {@link onSkillInvoke}. */
export interface SkillInvokeInput {
    skillName: string;
    args?: unknown;
    metadata?: Record<string, unknown>;
}

/** Result of {@link onSkillInvoke}. */
export interface SkillInvokeResult {
    decision: SkillDecision;
    record: AuditRecord;
}

/** Input shape for {@link preToolUse}. */
export interface ToolUseInput {
    /** Tool name as advertised by the Claude Agent SDK. */
    toolName: string;
    /** The arguments the agent intends to pass to the tool. */
    args: unknown;
}

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

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

export 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"; };

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

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

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

/** Categories of audit events. */
export type AuditKind = 'session.start' | 'session.stop' | 'tool.preflight' | 'tool.complete' | 'skill.preflight' | 'skill.complete' | 'message.signed' | 'policy.deny';

/** A single tamper-evident audit record. */
export interface AuditRecord {
    /** Monotonic sequence number within a session. */
    seq: number;
    /** ISO-8601 timestamp the record was emitted. */
    timestamp: string;
    /** Session id this record belongs to. */
    sessionId: string;
    /** Agent DID that performed the action. */
    agentDid: string;
    /** What kind of event this is. */
    kind: AuditKind;
    /** Tool or skill name (when applicable). */
    name?: string;
    /** Allow / deny outcome. */
    outcome: 'allow' | 'deny' | 'ok' | 'error';
    /** Hash of the request payload (BLAKE3 hex, lowercase). */
    inputHash?: string;
    /** Hash of the response payload (BLAKE3 hex, lowercase). */
    outputHash?: string;
    /** Hash chain pointer to the previous record. */
    prevHash: string;
    /** This record's hash. */
    hash: string;
    /** Free-form context (matched scope, error message, etc.). */
    context?: Record<string, unknown>;
}

/** Audit sink — receives one record per tool / skill invocation. */
export interface AuditSink {
    /** Append an audit record. MUST be best-effort and non-throwing. */
    append(record: AuditRecord): Promise<void> | void;
}

/** Anything implementing this can authorise tool / skill invocations. */
export interface CapabilityChecker {
    /**
     * Check whether the agent currently holds the requested scope.
     *
     * Implementations should be deterministic and side-effect free —
     * Arsenal-backed checkers may cache, but MUST NOT mutate.
     */
    check(scope: string): Promise<ScopeDecision> | ScopeDecision;
}

/**
 * Shared types for the OpenAgent x Claude Agent SDK plugin.
 *
 * These mirror the public surface of `@openagentid/sdk` but are duplicated
 * here so the plugin can run in environments where the SDK is not yet
 * resolved (e.g., bun's optional peer dep handling, dev installs).
 *
 * When `@openagentid/sdk` is present, the runtime objects passed by the
 * caller are structurally compatible with the interfaces below.
 */
/** A verified OpenAgent identity, anchored on a `did:oas:*` string. */
export interface OpenAgentIdentity {
    /** Decentralised identifier, e.g. `did:oas:test:agent:refactor-bot`. */
    did: string;
    /** Entity kind: `hmr`, `mhr`, `agent`, `tool`, `skill`, etc. */
    kind: string;
    /** Optional human-readable display name (not authoritative). */
    displayName?: string;
    /** Public Ed25519 verification key, hex-encoded (32 bytes). */
    publicKey: string;
    /**
     * Sign a payload with the agent's Ed25519 secret key.
     *
     * The signing key MUST live behind this function — it is never
     * exposed to plugin code directly.
     */
    sign(payload: Uint8Array): Promise<Uint8Array> | Uint8Array;
    /** Optional lineage chain (HMR -> ... -> this agent). */
    lineage?: readonly string[];
}

/** Result of a credential / scope check. */
export interface ScopeDecision {
    /** Whether the request is allowed. */
    allowed: boolean;
    /** Matched scope string (e.g. `tools:invoke:bash`), if any. */
    matchedScope?: string;
    /** Human-readable reason for denial. */
    reason?: string;
}

/** Result of a skills policy evaluation. */
export interface SkillDecision {
    /** Allow / deny. */
    allowed: boolean;
    /** Reason on deny. */
    reason?: string;
    /** The scope that authorised the call. */
    matchedScope?: string;
}

/** Context passed to a skills policy evaluation. */
export interface SkillEvaluationContext {
    /** The agent's verified identity. */
    identity: OpenAgentIdentity;
    /** Capability checker (Arsenal-backed) for scope lookups. */
    capabilities: CapabilityChecker;
    /** Optional metadata about the call site. */
    metadata?: Record<string, unknown>;
}

/** SKILLS.md entry as parsed from a manifest. */
export interface SkillsManifestEntry {
    /** Stable skill identifier (e.g. `web.search`). */
    name: string;
    /** Human description. */
    description?: string;
    /** Required scope to invoke. Defaults to `skills:invoke:<name>`. */
    requiredScope?: string;
}

/** Skills policy: decides whether a SKILLS.md skill may be invoked. */
export interface SkillsPolicy {
    /**
     * Check whether the named skill may be invoked by the current agent.
     *
     * Default behaviour for any concrete implementation: deny unless the
     * agent holds `skills:invoke:<skill-name>`.
     */
    evaluate(skillName: string, ctx: SkillEvaluationContext): Promise<SkillDecision> | SkillDecision;
}

export declare const canonicalJson: (value: unknown) => string;

export declare const getHashAlgo: () => HashAlgo;

export declare const hashHex: (data: string | Uint8Array) => string;