examples: add ACS + Agent Threat Rules (ATR) annotator (#3018)

[Adam Lin (eeee2345)]

Closes #3018.

Adds examples/acs-atr-annotator/ — a custom ACS policy backed by a host annotator dispatcher that runs the open-source Agent Threat Rules engine (pyatr) over the policy target and denies on a match. This is the runtime/behavioral enforcement counterpart to the static control mapping in docs/mappings/atr-agt-mapping.md; they sit at different levels and don't overlap.

Following the guidance in #3018:

• ATRAnnotator.dispatch runs ATR and returns a free-form annotation; the thin ATRPolicy.evaluate translates it into an ACS verdict (deny on match, else allow). The adapter only does shape translation — it does not re-implement detection.
• Verdicts use only decision/reason/evidence; no effects[] (AGT D1). The evidence payload carries the matched rule IDs plus a verification pointer per rule.
• pyatr is an optional, pre-1.0 dependency: imported lazily with a clear ImportError; tests use pytest.importorskip. A dispatcher exception fails closed (runtime_error:annotation_failed).
• A sample manifest.yaml uses type: custom with a configurable rules_dir / min_severity in adapter_config, wired at both the input and pre_tool_call intervention points.

Validated against the ACS runtime, not just unit-mocked. demo.py and test_atr_annotator.py load the manifest through agent_control_specification and assert deny on injection / allow on benign at both intervention points:

[input / prompt injection]      decision=deny   (ATR matched 6 rules, critical)
[input / benign]                decision=allow
[pre_tool_call / injected args] decision=deny   (ATR matched 7 rules, critical)
[pre_tool_call / benign]        decision=allow

pytest test_atr_annotator.py → 4 passed (dispatcher logic + ACS runtime e2e). License headers added per scripts/check_license_headers.py; commit is DCO-signed.

Imran Siddique (@imran-siddique) — ready for review per your note on #3018. Happy to adjust naming, placement, or the annotator/policy split.

[github-actions]

🤖 AI Agent: test-generator — `examples/acs-atr-annotator/atr_adapter.py`

AI-generated review output. Treat it as untrusted analysis and verify before acting.

examples/acs-atr-annotator/atr_adapter.py

• test_dispatch_without_pyatr -- Test ATRAnnotator.dispatch behavior when pyatr is not installed, ensuring it raises ImportError.
• test_dispatch_with_invalid_input -- Test ATRAnnotator.dispatch with malformed or missing preliminary_policy_input to ensure proper error handling.
• test_evaluate_with_no_annotations -- Test ATRPolicy.evaluate when no annotations are present in the policy_input.
• test_evidence_generation -- Test _evidence function with edge cases, such as empty or malformed rule_ids.

examples/acs-atr-annotator/demo.py

• test_demo_input_injection -- Validate that the demo script correctly denies a prompt injection at the input intervention point.
• test_demo_pre_tool_call_injection -- Validate that the demo script correctly denies injected arguments at the pre_tool_call intervention point.
• test_demo_benign_cases -- Validate that the demo script correctly allows benign inputs at both intervention points.

[github-actions]

🤖 AI Agent: docs-sync-checker — Docs Sync

AI-generated review output. Treat it as untrusted analysis and verify before acting.

Docs Sync

• atr_adapter.py -- ATRAnnotator.dispatch and ATRPolicy.evaluate have docstrings, so no issue here.
• README.md in examples/acs-atr-annotator/ is newly added and aligns with the changes.
• docs/mappings/atr-agt-mapping.md is referenced in the PR body but not modified. Ensure it does not need updates for consistency with the new functionality.
• No CHANGELOG entry is present for this behavioral addition. A new entry should be added to document the addition of the ACS + ATR annotator example.

[github-actions]

🤖 AI Agent: security-scanner — View details

AI-generated review output. Treat it as untrusted analysis and verify before acting.

No security issues found.

[github-actions]

🤖 AI Agent: code-reviewer — Action items:

AI-generated review output. Treat it as untrusted analysis and verify before acting.

TL;DR: 0 blockers, 2 warnings. The pull request introduces a new example for integrating the Agent Threat Rules (ATR) engine with the ACS runtime. The implementation appears sound, but there are minor areas for improvement.

#	Sev	Issue	Where
1	Warn	No validation of rules_dir path in ATRAnnotator or make_control.	atr_adapter.py
2	Warn	Potential for excessive memory usage in _text_from_value when handling large or deeply nested inputs.	atr_adapter.py

Action items:

1. Validate the rules_dir path in ATRAnnotator and make_control to ensure it exists and is accessible.
2. Add safeguards in _text_from_value to handle large or deeply nested inputs to prevent potential memory issues.

| Warnings: fine as follow-up PRs. |

[github-actions]

🤖 AI Agent: breaking-change-detector — API Compatibility

AI-generated review output. Treat it as untrusted analysis and verify before acting.

API Compatibility

Severity	Change	Impact
High	pyatr is introduced as an optional dependency.	Users must ensure pyatr is installed if they intend to use the new ATRAnnotator and ATRPolicy functionalities. Otherwise, an ImportError will be raised.
High	New ATRAnnotator class introduced.	Users relying on the ATRAnnotator must ensure compatibility with the pyatr library and its APIs.
High	New ATRPolicy class introduced.	Users implementing custom policies must account for the new ATRPolicy behavior, which denies access based on matches from the ATRAnnotator.
Medium	New make_control function introduced.	Users leveraging this function must ensure they provide appropriate arguments or rely on defaults from manifest.yaml.
Medium	ATRAnnotator.dispatch raises ImportError if pyatr is not installed.	This behavior may cause runtime failures if pyatr is not installed and the annotator is invoked.
Medium	ATRPolicy.evaluate returns a deny decision if the ATRAnnotator reports a match.	This may result in previously allowed inputs being denied based on the new policy.

[github-actions]

PR Review Summary

Check	Status	Details
🔍 Code Review	⚠️ Missing	No current-run comment
🛡️ Security Scan	⚠️ Missing	No current-run comment
🔄 Breaking Changes	⚠️ Missing	No current-run comment
📝 Docs Sync	⚠️ Missing	No current-run comment
🧪 Test Coverage	⚠️ Missing	No current-run comment

Verdict: ⚠️ AI review incomplete; ready for human review

AI review comments are untrusted advisory output. The summary reports workflow-generated completion status only, not model-authored pass/fail claims.

[github-actions]

🔴 Contributor Check: HIGH

Check	Result
Profile	HIGH
Credential	HIGH
Overall	HIGH

Automated check by AGT Contributor Check.

[Imran Siddique (imran-siddique)]

Examples-only, clean design — annotator dispatches detection, policy translates verdict shape, no reimplementation of detection logic. Lazy import for the optional pyatr dep is correct. Fails closed on dispatcher exception. No effects[] post-D1. Smoke tests cover dispatcher logic with the real engine skipped when unavailable. Good work.