Smoke Monkey Logo
Smoke Monkey
Docs
DocsLifecycle Hooks & Errors
Enterprise Observability & Security

Lifecycle Hooks & Error Hierarchy

Observe, audit, and guard every model call and tool execution. Smoke Monkey provides fail-closed security hooks and replaces bare string exceptions with a typed AgentErrorInfo structure.

Fail-Closed Hook Semantics

If a before* hook crashes, the call is blocked immediately as a safety invariant. If an after* hook crashes, it is safely logged and ignored to prevent disrupting ongoing runs.

hooks.tstypescript
import { createAgent } from '@smoke-monkey/harness';


const agent = createAgent({
  workspacePath: process.cwd(),
  hooks: {
    // 1. Fail-closed security interceptor: runs BEFORE tools execute
    async beforeToolCall({ toolName, input, userId }) {
      if (toolName === 'write_file' && input.path.includes('production.env')) {
        return { block: true, reason: 'Direct edits to production secrets are forbidden.' };
      }
      return { input };
    },


    // 2. Telemetry and cost tracking: runs AFTER model turns settle
    async afterModelCall({ usage, durationMs, error }) {
      metrics.record('llm.call', { tokens: usage.totalTokens, durationMs, failed: Boolean(error) });
    },
  },
});


// Handle structured errors
agent.on('run.failed', (e) => {
  const { code, layer, severity, message, retryable, hint } = e.data.errorInfo;
  console.error(`[${layer.toUpperCase()} - ${code}] ${message}`);
  if (retryable) showRetryPrompt(hint);
});

The 5 Error Layers

provider Layer

Upstream LLM errors (rate limits, timeouts, bad keys). 429 errors emit retryable hints.

tool Layer

Failures scoped to a single tool call. The loop continues and allows self-healing.

run Layer

Critical loop guards (runaway steps, repeated failure, empty response).

permission Layer

Human user clicked Deny on a mutating tool execution.

hook Layer

A beforeModelCall or beforeToolCall security hook blocked the call.

Next: Drop-In React Chat UI

Stream tokens, render tool cards, and test 14 themes with @smoke-monkey/ui.

Previous
Sub-Contexts & Memory
Next
Drop-In React Chat UI