Advanced (optional)

Advanced: optional filtering and sanitization

Most integrations can use the default setup without custom rules. The SDK already redacts common secret patterns locally. Use beforeSend only when your application knows an error is expected or needs to remove domain-specific data that general secret redaction cannot recognize.

Define the hook in your MCP server or CLI code, alongside SDK initialization. There are no rules to configure in the Problems UI.

const problems = createProblems({
  slug: "acme",
  beforeSend(report, { error }) {
    // Your application's expected cancellation error.
    if (error instanceof UserCancelledError) return null;

    if (error instanceof DocumentImportError) {
      return {
        ...report,
        message: `Document import failed: ${error.code}`,
        stack: undefined, // the original stack also contains the error message
      };
    }
    return report;
  },
});

UserCancelledError and DocumentImportError are example error classes defined by your application. The hook receives a mutable copy containing message, optional stack, context, toolName, runtime, and agentName. It also gets the original error for inspection; do not mutate that error. Nested context arrays and version maps are copied. If sensitive information also appears in context, remove it there too. Unknown extra fields are not sent.

Return the report to send it, a modified report to sanitize it, or null to drop it. A drop returns { ok: false, reason: "filtered" }. The hook is synchronous: keep it fast and local. Throwing, returning an invalid report, or returning a Promise drops the report with reason hook_error; the SDK never falls back to sending the unsanitized original.

Built-in redaction runs after the hook, including on modified fields. Reports are then deduplicated and checked against delivery limits. Filtered reports and hook failures do not consume delivery attempts. Reporting opt-out takes precedence and prevents the hook from running.

The hook applies to report() and automatic reports from MCP wrappers, fetch wrappers, and process hooks. It changes the report sent to Problems, not the original tool result, HTTP response, or exception. It does not sanitize MCP messages shown directly to the agent, and does not run for getProblem() or verify(); verification notes still receive built-in redaction.