fix(ENG-12332): export ToolSanitizationRule and add tier2Fields option

[hiskudin]

Summary

• Exports ToolSanitizationRule from the public API so consumers can type custom toolRules without reaching into internal modules
• Adds tier2Fields?: string[] to PromptDefenseOptions and PromptDefenseConfig.tier2 — when set, Tier 2 only classifies strings extracted from matching field keys (while still descending into non-matching keys to find them deeper). This lets callers focus Tier 2 on user-controlled fields (e.g. subject, body) and skip encoded or structural fields, reducing latency and false-negative risk.

Test plan

• All existing tests pass
• Lint and typecheck clean
• Consumers can import type { ToolSanitizationRule } from '@stackone/defender'
• createPromptDefense({ enableTier2: true, tier2Fields: ['subject', 'body'] }) only runs Tier 2 on those fields

🤖 Generated with Claude Code

---

Summary by cubic

Exported ToolSanitizationRule, added tier2Fields to scope Tier 2 to specific fields, enabled Tier 2 by default, and surfaced a skip reason when Tier 2 is skipped. Addresses ENG-12332.

• New Features

  • Export ToolSanitizationRule from @stackone/defender for typing custom toolRules.
  • Add tier2Fields?: string[] to PromptDefenseOptions and PromptDefenseConfig.tier2; when set, Tier 2 only classifies strings under those keys; when unset, all strings are scanned.
  • Enable Tier 2 by default; docs updated to reflect the new default and tier2Fields.

• Bug Fixes

  • extractStrings treats empty tier2Fields as scan-all, falls back to config.tier2.tier2Fields, and uses a Set for faster lookups.
  • Handle plain strings when tier2Fields is set so they aren’t dropped during extraction.
  • Add tier2SkipReason to DefenseResult and set it when Tier 2 is skipped (e.g., no strings in tier2Fields or classifier skip).
  • Remove unused enabled from PromptDefenseConfig.tier2 and defaults.

^{Written for commit 82c9e81. Summary will update on new commits.}

[Copilot]

Pull request overview

This PR expands the public API and adds an option to scope Tier 2 classification to specific tool-result fields, aiming to improve consumer ergonomics and reduce Tier 2 latency/noise.

Changes:

• Export ToolSanitizationRule from the package entrypoint for external typing.
• Add tier2Fields?: string[] to configuration/types and PromptDefenseOptions.
• Update Tier 2 text extraction to optionally collect strings only under matching field keys.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.

File	Description
src/types.ts	Extends PromptDefenseConfig.tier2 with tier2Fields and documents the behavior.
src/index.ts	Exposes ToolSanitizationRule via the public entrypoint type exports.
src/core/prompt-defense.ts	Implements filtered string extraction for Tier 2 and wires tier2Fields into defendToolResult.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

[cubic-dev-ai]

No issues found across 3 files

[cubic-dev-ai]

1 issue found across 2 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="src/core/prompt-defense.ts">

<violation number="1" location="src/core/prompt-defense.ts:169">
P2: This makes Tier 2 classification run by default when `enableTier2` is omitted, which conflicts with the documented default of `false` and can add unexpected model initialization/latency for existing consumers. Keep the default off unless explicitly enabled.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[glebedel]

LGTM