fix(ENG-12707, ENG-12708): make boundary annotation opt-in (annotateBoundary flag)

[hiskudin]

Summary

Opt-in boundary annotation (annotateBoundary)

• Boundary wrapping ([UD-<id>]...[/UD-<id>]) is now opt-in via annotateBoundary on PromptDefenseOptions / ToolResultSanitizerConfig / SanitizerConfig. Default: false.
• Hard gate across all risk levels — the old alwaysAnnotate flag only gated low risk; medium/high still wrapped. New flag is unconditional.
• Explicit methods: ['boundary_annotation'] in SanitizeOptions still wraps regardless of the flag (per-call escape hatch).
• When disabled, generateDataBoundary() is skipped entirely — no nanoid() call per tool result, no "boundary_annotation" entries in metadata.methodsByField.
• Exported generateBoundaryInstructions() and containsBoundaryPatterns() from the package entrypoint for callers that opt in.

generateBoundaryInstructions() — the system-prompt template that teaches an LLM to treat [UD-*] content as untrusted data — had zero downstream consumers across defender, connect, connect-handler, and unified-cloud-api. The tags were inert scaffolding, so making them opt-in removes per-field metadata noise and output bloat for all existing callers while preserving the feature for anyone who adds the system-prompt half of the contract.

Fix: SFE filtering is classifier-only

SFE was replacing the output with the filtered payload, permanently dropping metadata/identifier fields from DefenseResult.sanitized. This meant the LLM received a truncated tool result whenever useSfe was enabled — losing IDs, cursors, and other fields the agent might need for follow-up calls.

Fix: sfeFilteredValue now feeds Tier 2 string extraction only. Tier 1 sanitization and the returned sanitized payload always operate on the original value. fieldsDropped is now accurately documented as "fields excluded from classification" not "fields absent from output".

Non-breaking

• No known caller relies on [UD-*] tags appearing in output (confirmed by grepping all downstream repos).
• Tier 2 still strips boundary markers on input (v0.6.2 fix(ENG-12702): strip boundary markers from input before classification #55), so the self-flagging feedback loop is unaffected.
• SFE fix is purely additive correctness — callers not using useSfe are unaffected.

Downstream

connect-sdk DefenderSettings will gain annotateBoundary in a follow-up PR for exposure in unified-cloud-api project settings.

Test plan

• Existing sanitizer + integration specs updated to opt-in or assert default-off behavior.
• New tests: default off (no [UD- at any risk level), flag on (end-to-end via defendToolResult), explicit-methods escape hatch.
• npm test — 206/207 passing (pre-existing ONNX batch classification flake on clean main).
• npx tsc --noEmit — clean.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Makes boundary annotation ([UD-<id>]...[/UD-<id>]) opt-in across the sanitizer pipeline via a new annotateBoundary flag, defaulting to false, and updates tests/docs to reflect the new default behavior.

Changes:

• Replace risk-level/legacy gating with a hard opt-in annotateBoundary switch in Sanitizer, plus an explicit per-call methods: ["boundary_annotation"] escape hatch.
• Plumb annotateBoundary through PromptDefenseOptions → ToolResultSanitizerConfig, and skip generateDataBoundary() entirely when wrapping is disabled.
• Update specs and README to validate/document default-off behavior and opt-in wrapping.

Reviewed changes

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

Show a summary per file

File	Description
src/sanitizers/sanitizer.ts	Introduces annotateBoundary config, changes boundary wrapping to opt-in, keeps explicit method override behavior.
src/core/tool-result-sanitizer.ts	Adds annotateBoundary config and avoids boundary generation when disabled; passes flag into createSanitizer.
src/core/prompt-defense.ts	Adds annotateBoundary option to the public PromptDefenseOptions and forwards it to ToolResultSanitizer.
specs/sanitizers.spec.ts	Updates unit/integration expectations for default-off wrapping and adds opt-in/override coverage.
specs/integration.spec.ts	Adds PromptDefense-level assertions for default-off vs opt-in boundary wrapping; opts into wrapping in a scenario test.
README.md	Documents boundary annotation as opt-in and references system-prompt pairing guidance.

---

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

[cubic-dev-ai]

No issues found across 6 files

_{Requires human review: This change modifies the default output behavior of a core sanitization path in a security tool. Such changes to default behavior require human validation of downstream impact.}

[cubic-dev-ai]

0 issues found across 1 file (changes from recent commits).

_{Auto-approved: Makes boundary annotation opt-in to reduce output noise. Includes comprehensive test updates and documentation. Low risk as the feature had no downstream consumers.}

[glebedel]

LGTM

[cubic-dev-ai]

0 issues found across 1 file (changes from recent commits).

_{Requires human review: Modifies core sanitization logic and changes default behavior for boundary annotation. The SFE filtering fix also alters data flow in a core path, requiring human verification.}

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated no new comments.

---

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

[cubic-dev-ai]

0 issues found across 2 files (changes from recent commits).

_{Requires human review: Changes core sanitization logic and default output behavior in a security package. The data flow changes in the defense pipeline (SFE fix) warrant human verification.}

[OMauriStkOne]

LGTM