feat: implement pluggable taxonomy and policy security plugin

[ViktorVeselov]

Have read the contribution guide before creating a pull request.

Link to Issue or Description of Change

Link to an existing issue / related PR:

• Related issue at adk-python-community: feature: pluggable policy & taxonomy for more accurate and more deterministic skill/tool execution #152
• • Closes: #5895 (on core at adk-python): feat: add pluggable policy & taxonomy adk-python#5898
• • Related core PR adk-python: feat: add pluggable policy & taxonomy adk-python#5898 (Closed on core to release as a pluggable community package) and marked with community-repo tag.
• • Related discussion adk-python: [RFC] Taxonomy-Driven Skill Routing & Dynamic Context Mutation adk-python#5891
• • Related issue from adk-python feature: Modular Domain Taxonomy adk-python#5895 that was transferred to adk-python-community as per the request of Rahityan's suggestion/recommendation: feat: add pluggable policy & taxonomy adk-python#5898 (comment)

Problem:
Developers and system administrators need a robust, standardized way to enforce security policies and access controls on skills based on organizational hierarchies and taxonomies (e.g., flat department structures or rich SKOS JSON-LD classifications).

Originally, we designed this to be embedded directly into the core adk-python SDK. However, in line with keeping the core framework minimalist, light, and secure, the core reviewers pointed me here to implement this as an official community extension plugin (referencing the closed PR adk-python/pull/5898).

Solution:
Implemented the Taxonomy & Policy Security Engine as a pluggable, opt-in plugin (TaxonomyPlugin) in adk-python-community. This gives developers enterprise-grade taxonomy controls and skill-access guardrails without cluttering the core SDK. Additionally, it can be used as a tool for usage reinforcers and for dynamic prompting that helps to provide an agent with well-polished context, skills/tools executions tailored toward determined cases.

Key design points include:

• Fallback Parsing: Uses a robust fallback _get_taxonomy_binds() pattern to read taxonomy-binds keys from Frontmatter.model_extra (natively populated because the core SDK's Frontmatter model has extra="allow"). This ensures perfect runtime compatibility with the unmodified core adk-python library.
• Path Isolation: Inlined all path safety validations within before_tool_callback instead of importing private core helper functions, making the plugin entirely resilient against future internal changes in core SDK versions.
• Dual-Schema Taxonomy Parsing: The TaxonomyRegistry parses both standard Flat Key-Value JSON (id/parentId/name/definition) and rich JSON-LD with SKOS (Concept, prefLabel, altLabel, definition, broader) standards to resolve organizational hierarchies.
• Pipeline Orchestration: Introduces TaxonomyPipeline and TaxonomyResolver interfaces to dynamically chain multiple contextual policy resolvers (e.g., checking active user directories, roles, and entitlements) during runtime execution.
• Event-Driven Integration: Hooks directly into BasePlugin lifecycle callbacks to intercept tool boundaries (list_skills, load_skill, etc.), returning filtered lists in the expected dictionary-wrapped XML response structure.
• Full Cognitive Steering & Prompt Tailoring: Unlike simple static permission checkers, this implementation supports dynamic prompt and tool modifications:
  • Dynamic System Prompt Refinement: Through shape_system_instruction(), the plugin dynamically tailors the global agent instructions at runtime based on active user context and classifications (e.g., automatically injecting compliance instructions).
  • Skill Customization Based on Taxonomy: Through shape_description(), policies can actively rewrite tool description properties to guide the LLM's action selection dynamically (e.g., adding warning prefixes).
  • Skill Prioritization: Through prioritize_skills(), the engine reorders available tools inside the formatted prompt XML, ensuring context-relevant or preferred skills are bubbled to the top of the LLM's consideration set.

---

Testing Plan

1. Unit & Integration Tests (Command & Logs)

Added a complete integration test suite in tests/plugins/test_taxonomy_plugin.py to match the community plugin testing conventions (e.g., alongside the existing test_agent_governance_plugin.py).

To run the tests, set the PYTHONPATH to include the community source files and your standard core SDK source directory:

$env:PYTHONPATH = "src;<path-to-core-adk-python-src>"
python -m pytest "tests"

Verifiable Test Execution Log Output:

============================= test session starts =============================
platform win32 -- Python 3.12.3, pytest-8.4.1, pluggy-1.6.0
rootdir: c:\adk-python-community
configfile: pyproject.toml
plugins: anyio-4.12.1, asyncio-1.3.0
asyncio: mode=Mode.AUTO, debug=False
collected 75 items / 1 skipped

adk-python-community\tests\plugins\test_agent_governance_plugin.py ..............                                                                                                 [ 18%]
adk-python-community\tests\plugins\test_taxonomy_plugin.py ......                                                                                                                 [ 26%]
adk-python-community\tests\unittests\memory\test_open_memory_service.py .............                                                                                             [ 44%]
adk-python-community\tests\unittests\sessions\test_redis_session_service.py ...............                                                                                       [ 64%]
adk-python-community\tests\unittests\test_sdc_agents_imports.py ssssssssssss                                                                                                      [ 80%]
adk-python-community\tests\unittests\tools\spraay\test_spraay_tools.py ...............                                                                                            [100%]

================================ warnings summary ==============================
  DeprecationWarning: BaseAgentConfig is deprecated and will be removed in future versions.

==================== 63 passed, 13 skipped, 4 warnings in 1.63s ================

Note

Environmental Package Mock Details:
Due to potential environment variations where the google-genai library is either outdated (lacking the expected AvatarConfig attribute) or completely absent, we pre-emptively mock/patch google.genai.types.AvatarConfig directly inside tests/conftest.py. This ensures that the test runner bypasses environment-level import conflicts and allows the unit test suite to compile cleanly in any CI/CD or local environment.

2. Manual Verification E2E

To manually verify the taxonomy filter pipeline:

1. Initialize the Registry with a SKOS JSON-LD or Flat JSON configuration:

   from google.adk_community.plugins.taxonomy import TaxonomyRegistry, TaxonomyPlugin, DefaultSkillPolicy
   
   registry = TaxonomyRegistry.from_flat_json([
       {"id": "engineering", "parentId": None, "name": "Engineering"},
       {"id": "machine-learning", "parentId": "engineering", "name": "Machine Learning"}
   ])

2. Instantiate the Plugin with a custom policy or the DefaultSkillPolicy:

   policy = DefaultSkillPolicy()
   plugin = TaxonomyPlugin(policy=policy, taxonomy_registry=registry)
   # Register plugin to the ADK instance

3. Add taxonomy-binds to your skill's frontmatter configuration:

   taxonomy-binds:
     - "engineering"
     - "machine-learning"

4. Invoke list_skills with a dynamic context (e.g. passing a user identity or role inside tool_context) and observe that skills bound to unauthorized taxonomies are securely filtered out of the response.

---

Checklist

• I have read the CONTRIBUTING.md document.
• I have performed a self-review of my own code.
• I have commented my code, particularly in hard-to-understand areas.
• I have added tests that prove my fix is effective or that my feature works.
• New and existing unit tests pass locally with my changes.
• I have manually tested my changes end-to-end.
• I have checked formatting matches styles (using autoformat.sh / standard formatting).

---

Additional context

• Built to satisfy strict pluggability constraints: when the plugin is not loaded, the ADK continues operating exactly as normal (100% opt-in).
• Returning filtered skill lists preserves the SDK's exact contract by returning a structured dict expected by __build_response_event.
• For focus purposes, there are no example files, and we will add them later once we agree on implementation.

[ViktorVeselov]

@zeroasterisk

[DeanChensj]

@gemini-cli /review

[github-actions]

🤖 Hi @DeanChensj, I've received your request, and I'm working on it now! You can track my progress in the logs for more details.

[github-actions]

Thanks for the detailed implementation of the Taxonomy & Policy Security Engine! The architecture looks solid and well-integrated into the ADK plugin lifecycle.

I found a few issues that should be addressed:

1. Missing Imports: policy.py is missing Any and Optional imports from typing, which will cause issues when the code is executed or type-checked.
2. Robustness in Skill Reconstruction: In _filter_list_skills, manually recreating Skill and Frontmatter might drop fields. Using model_copy is a safer approach.
3. Variable Interpolation: Consider adding some logging or keeping placeholders when interpolation fails to aid debugging.
4. Path Validation: The current path validation is a bit light for a security-focused plugin.

Overall, a great addition to the community plugins!

[github-actions]

The file_path validation here is quite basic. While it blocks some traversal attempts, it might not catch absolute paths on all operating systems (e.g., C:\path on Windows).

Since this plugin aims for resilience, consider using a more robust path validation or pathlib.Path.is_absolute() if possible, although keeping it dependency-light is also understood.

[ViktorVeselov]

That's a great catch, men.

[github-actions]

If a variable is not found in the registry, it is replaced with an empty string. This might make debugging difficult if there's a typo in the template (e.g., {taxonomy:typo}).

Consider logging a warning when a variable is not found, or keeping the placeholder text to make it obvious that interpolation failed.

[github-actions]

Missing imports for Any and Optional. Please add from typing import Any, Optional to ensure the type hints resolve correctly.

[github-actions]

Manually recreating the Skill and Frontmatter objects here is risky as it might drop other fields defined in the models (e.g., version, author, or other metadata) that aren't captured in model_extra.

Consider using skill.frontmatter.model_copy(update={"description": shaped_desc}) instead to preserve all existing fields.

[ViktorVeselov]

Let me think about it because one of the architectural goals is to use it and change prompts dynamically and enable devs. to apply their custom business roles, features, flags, entitlements, etc., without having too much of a headache. I will have to think about it.