Lifecycle hooks

What hooks are

Hooks are async callbacks you register at startup. KavachOS calls them at specific points in the authorization and agent lifecycle. They let you add custom logic without patching the SDK: log denials to Slack, block agents from running in unsandboxed environments, fire webhooks, or update your own database.

Hooks are async. beforeAuthorize and beforeAgentCreate can block requests by returning { allow: false }. All other hooks are fire-and-forget from KavachOS’s perspective, but any unhandled exception in a hook will propagate to the caller.

Available hooks

Fires before every authorize() call. Return { allow: false, reason } to block. Return void or { allow: true } to proceed.

Fires after authorize() completes with the final result. Useful for logging and alerting.

Fires before an agent is created. Return { allow: false } to reject the creation.

Fires after an agent is successfully created.

Fires when an agent is revoked.

Fires when a permission denial, rate limit, or policy violation is detected.

Violation types

The onViolation hook receives a typed type field so you can route each category to a different handler.

Type	When it fires
`permission_denied`	The agent lacks the required permission
`rate_limited`	The agent hit a rate limit
`ip_blocked`	The request IP is on a blocklist
`time_restricted`	The request is outside the allowed time window
`approval_required`	The action needs human approval before proceeding

Registering hooks

Pass a hooks object to createKavach:

import { createKavach } from 'kavachos';

const kavach = await createKavach({
  database: { provider: 'sqlite', url: 'kavach.db' },
  hooks: {
    async beforeAuthorize({ agentId, action, resource }) {
      // Example: block calls outside business hours
      const hour = new Date().getUTCHours();
      if (hour < 8 || hour >= 20) {
        return {
          allow: false,
          reason: `Agent ${agentId} cannot run outside business hours (08:00–20:00 UTC)`,
        };
      }
      // Return nothing (or { allow: true }) to let the request proceed
    },

    async afterAuthorize({ agentId, action, resource, result }) {
      if (!result.allowed) {
        console.warn(`[kavach] Denied: agent=${agentId} action=${action} resource=${resource} reason=${result.reason}`);
      }
    },
  },
});

Logging every denial

const kavach = await createKavach({
  database: { provider: 'sqlite', url: 'kavach.db' },
  hooks: {
    async afterAuthorize({ agentId, action, resource, result }) {
      if (!result.allowed) {
        await logger.warn('Authorization denied', {
          agentId,
          action,
          resource,
          reason: result.reason,
          auditId: result.auditId,
        });
      }
    },
  },
});

The result.auditId links this log line to the immutable audit entry. You can use it to correlate your own logs with the KavachOS audit trail.

Enforcing a sandbox check

const kavach = await createKavach({
  database: { provider: 'sqlite', url: 'kavach.db' },
  hooks: {
    async beforeAgentCreate(input) {
      // Require sandbox metadata on all autonomous agents
      if (input.type === 'autonomous' && !input.metadata?.sandboxId) {
        return {
          allow: false,
          reason: 'Autonomous agents must declare a sandboxId in metadata',
        };
      }
    },
  },
});

Returning { allow: false } from beforeAgentCreate causes the kavach.agent.create() call to throw a KavachError with the reason you provided.

Reacting to violations

The onViolation hook fires for any denial that fits a known violation category. Use it to send alerts or update your observability platform.

const kavach = await createKavach({
  database: { provider: 'sqlite', url: 'kavach.db' },
  hooks: {
    async onViolation({ type, agentId, action, resource, reason }) {
      // Send to your alerting system
      await alerts.send({
        severity: type === 'rate_limited' ? 'warning' : 'error',
        title: `KavachOS violation: ${type}`,
        fields: { agentId, action, resource, reason },
      });

      // For repeat offenders, you could revoke here
      if (type === 'ip_blocked') {
        await kavach.agent.revoke(agentId);
      }
    },
  },
});

Cleaning up after revocation

const kavach = await createKavach({
  database: { provider: 'sqlite', url: 'kavach.db' },
  hooks: {
    async onAgentRevoke(agentId) {
      // Remove the agent's discovery card
      await kavach.discovery.removeCard(agentId);

      // Notify your own systems
      await internalApi.notifyAgentRevoked(agentId);
    },
  },
});

Next steps

Budget policies

Block agents when they exceed token or call limits.

Event streaming

Stream authorization events to Kafka, NATS, or Webhooks.

Audit log

Query the immutable record of every authorization decision.

Compliance and security

Lifecycle

Identity primitives

Standards

What hooks are

Available hooks

Violation types

Registering hooks

Logging every denial

Enforcing a sandbox check

Reacting to violations

Cleaning up after revocation

Next steps

Budget policies

Event streaming

Audit log

​What hooks are

​Available hooks

​Violation types

​Registering hooks

​Logging every denial

​Enforcing a sandbox check

​Reacting to violations

​Cleaning up after revocation

​Next steps

Budget policies

Event streaming

Audit log

What hooks are

Available hooks

Violation types

Registering hooks

Logging every denial

Enforcing a sandbox check

Reacting to violations

Cleaning up after revocation

Next steps