fix(skills): enforce allowed-tools metadata (#2626)

* fix(skills): parse allowed-tools frontmatter

* fix(skills): validate allowed-tools metadata

* fix(skills): add shared allowed-tools policy

* fix(subagents): enforce skill allowed-tools

* fix(agent): enforce skill allowed-tools

* refactor(skills): dedupe TypeVar and reuse cached enabled skills

- Drop redundant module-level TypeVar in tool_policy; rely on PEP 695 syntax.
- Expose get_cached_enabled_skills() and have the lead agent reuse it
  instead of synchronously rescanning skills on every request.

* fix(agent): expose config-scoped skill cache

* fix(subagents): pass filtered tools explicitly

* fix(skills): clean allowed-tools policy feedback

backend/packages/harness/deerflow/skills/parser.py

@@ -9,6 +9,29 @@ from .types import SKILL_MD_FILE, Skill, SkillCategory
 logger = logging.getLogger(__name__)
 
 
+def parse_allowed_tools(raw: object, skill_file: Path) -> list[str] | None:
+    """Parse the optional allowed-tools frontmatter field.
+
+    Returns None when the field is omitted. Returns a list when the field is a
+    YAML sequence of strings, including an empty list for explicit no-tool
+    skills. Raises ValueError for malformed values.
+    """
+    if raw is None:
+        return None
+    if not isinstance(raw, list):
+        raise ValueError(f"allowed-tools in {skill_file} must be a list of strings")
+
+    allowed_tools: list[str] = []
+    for item in raw:
+        if not isinstance(item, str):
+            raise ValueError(f"allowed-tools in {skill_file} must contain only strings")
+        tool_name = item.strip()
+        if not tool_name:
+            raise ValueError(f"allowed-tools in {skill_file} cannot contain empty tool names")
+        allowed_tools.append(tool_name)
+    return allowed_tools
+
+
 def parse_skill_file(skill_file: Path, category: SkillCategory, relative_path: Path | None = None) -> Skill | None:
     """Parse a SKILL.md file and extract metadata.
 
@@ -64,6 +87,12 @@ def parse_skill_file(skill_file: Path, category: SkillCategory, relative_path: P
         if license_text is not None:
             license_text = str(license_text).strip() or None
 
+        try:
+            allowed_tools = parse_allowed_tools(metadata.get("allowed-tools"), skill_file)
+        except ValueError as exc:
+            logger.error("Invalid allowed-tools in %s: %s", skill_file, exc)
+            return None
+
         return Skill(
             name=name,
             description=description,
@@ -72,6 +101,7 @@ def parse_skill_file(skill_file: Path, category: SkillCategory, relative_path: P
             skill_file=skill_file,
             relative_path=relative_path or Path(skill_file.parent.name),
             category=category,
+            allowed_tools=allowed_tools,
             enabled=True,  # Actual state comes from the extensions config file.
         )
 

backend/packages/harness/deerflow/skills/tool_policy.py

@@ -0,0 +1,44 @@
+import logging
+from typing import Protocol
+
+from deerflow.skills.types import Skill
+
+logger = logging.getLogger(__name__)
+
+
+class NamedTool(Protocol):
+    name: str
+
+
+def allowed_tool_names_for_skills(skills: list[Skill]) -> set[str] | None:
+    """Return the union of explicit skill allowed-tools declarations.
+
+    None means legacy allow-all behavior. It is returned only when no loaded
+    skill declares allowed-tools. Once any skill declares the field, legacy
+    skills without the field contribute no tools instead of disabling the
+    explicit restrictions from other skills.
+    """
+    if not skills:
+        return None
+
+    allowed: set[str] = set()
+    has_explicit_declaration = False
+    for skill in skills:
+        if skill.allowed_tools is None:
+            continue
+        has_explicit_declaration = True
+        if not skill.allowed_tools:
+            logger.info("Skill %s declared empty allowed-tools", skill.name)
+        allowed.update(skill.allowed_tools)
+
+    if not has_explicit_declaration:
+        return None
+    return allowed
+
+
+def filter_tools_by_skill_allowed_tools[ToolT: NamedTool](tools: list[ToolT], skills: list[Skill]) -> list[ToolT]:
+    allowed = allowed_tool_names_for_skills(skills)
+    if allowed is None:
+        return tools
+
+    return [tool for tool in tools if tool.name in allowed]

backend/packages/harness/deerflow/skills/types.py

@@ -27,6 +27,7 @@ class Skill:
     skill_file: Path
     relative_path: Path  # Relative path from category root to skill directory
     category: SkillCategory  # 'public' or 'custom'
+    allowed_tools: list[str] | None = None
     enabled: bool = False  # Whether this skill is enabled
 
     @property

backend/packages/harness/deerflow/skills/validation.py

@@ -8,6 +8,7 @@ from pathlib import Path
 
 import yaml
 
+from deerflow.skills.parser import parse_allowed_tools
 from deerflow.skills.types import SKILL_MD_FILE
 
 # Allowed properties in SKILL.md frontmatter
@@ -84,4 +85,9 @@ def _validate_skill_frontmatter(skill_dir: Path) -> tuple[bool, str, str | None]
         if len(description) > 1024:
             return False, f"Description is too long ({len(description)} characters). Maximum is 1024 characters.", None
 
+    try:
+        parse_allowed_tools(frontmatter.get("allowed-tools"), skill_md)
+    except ValueError as e:
+        return False, str(e).replace(str(skill_md), SKILL_MD_FILE), None
+
     return True, "Skill is valid!", name