@ngocsangairvds/vsaf 3.2.13 → 3.2.15

package/tools/vds-scripts/audit_orchestrator/src/vds_audit_orchestrator/agents/toolsets/skills_toolset.py

@@ -1,997 +0,0 @@
-"""AgentSkills toolset integration for Audit Orchestrator."""
-
-from __future__ import annotations
-
-import hashlib
-import inspect
-import os
-import re
-import warnings
-from dataclasses import dataclass, field
-from pathlib import Path
-from typing import Any, Literal, cast
-
-from pydantic import BaseModel, ConfigDict, Field
-from structlog import get_logger
-
-logger = get_logger(__name__)
-_SKILL_WARNING_FILTER_CONFIGURED = False
-
-
-class SkillContentHashMismatchError(RuntimeError):
-    """Raised when a skill's content hash does not match the expected value."""
-
-    def __init__(self, skill_name: str, expected: str, actual: str) -> None:
-        self.skill_name = skill_name
-        self.expected = expected
-        self.actual = actual
-        super().__init__(f"Skill '{skill_name}' content hash mismatch: expected={expected[:16]}… actual={actual[:16]}…")
-
-
-SkillTrustTier = Literal["internal", "external-verified", "external-unverified"]
-SkillDropReason = Literal[
-    "name_mismatch",
-    "trust_tier_rejected",
-    "script_policy_rejected",
-    "hash_validation_rejected",
-]
-_DEFAULT_ALLOWED_TRUST_TIERS: tuple[SkillTrustTier, ...] = ("internal",)
-
-
-def _discover_skill_dirs() -> list[str]:
-    candidates: list[Path] = []
-    env_value = str(os.getenv("VDS_SKILLS_PATH") or "").strip()
-    if env_value:
-        candidates.append(Path(env_value).expanduser())
-
-    for parent in Path(__file__).resolve().parents:
-        candidates.extend(
-            [
-                parent / "skills",
-                parent / "WHO-project" / "vds-skills" / "skills",
-                parent / "vds-skills" / "skills",
-            ]
-        )
-
-    discovered: list[str] = []
-    seen: set[str] = set()
-    for candidate in candidates:
-        try:
-            resolved = str(candidate.expanduser().resolve(strict=False))
-        except Exception:
-            resolved = str(candidate)
-        if resolved in seen:
-            continue
-        seen.add(resolved)
-        if Path(resolved).is_dir():
-            discovered.append(resolved)
-    return discovered
-
-
-DEFAULT_AUDIT_SKILLS = _discover_skill_dirs()
-
-
-@dataclass
-class SkillInfo:
-    """Lightweight skill metadata for reporting."""
-
-    name: str
-    metadata_name: str | None = None
-    frontmatter_name: str | None = None
-    runtime_name: str | None = None
-    canonical_name: str | None = None
-    description: str | None = None
-    path: str | None = None
-    trust_tier: SkillTrustTier = "external-unverified"
-    has_scripts: bool = False
-    content_hash: str | None = None
-
-
-@dataclass
-class SkillExecutionResult:
-    """Result of executing a skill via toolset."""
-
-    success: bool
-    output: Any | None = None
-    error: str | None = None
-
-
-@dataclass
-class SkillPolicyDrop:
-    """Per-skill policy drop reason for audit diagnostics."""
-
-    skill_name: str
-    reason: SkillDropReason
-    metadata_name: str | None = None
-    frontmatter_name: str | None = None
-    runtime_name: str | None = None
-    detail: str | None = None
-
-
-@dataclass
-class SkillPolicyDiagnostics:
-    """Policy diagnostics attached to skills toolset instances."""
-
-    metadata_count: int = 0
-    policy_eligible_count: int = 0
-    runtime_loaded_count: int = 0
-    blocked_tools: list[str] = field(default_factory=list)
-    dropped: list[SkillPolicyDrop] = field(default_factory=list)
-
-
-class SkillsToolsetConfig(BaseModel):
-    """Configuration for AgentSkills toolset."""
-
-    model_config = ConfigDict(populate_by_name=True)
-
-    directories: list[str] = Field(default_factory=list)
-    validate_skills: bool = Field(default=True, alias="validate")
-    script_timeout: int = Field(default=60, ge=1)
-    allowlist: list[str] = Field(default_factory=list)
-    allow_script_execution: bool = Field(
-        default=False,
-        description="Disable skill script execution by default unless explicitly enabled",
-    )
-    allowed_trust_tiers: list[SkillTrustTier] = Field(
-        default_factory=lambda: list(_DEFAULT_ALLOWED_TRUST_TIERS),
-        min_length=1,
-    )
-    default_trust_tier: SkillTrustTier = "external-unverified"
-    trust_tiers: dict[str, SkillTrustTier] = Field(default_factory=dict)
-
-
-def _apply_allowlist(toolset: Any, allowlist: set[str]) -> None:
-    skills = getattr(toolset, "skills", None)
-    if isinstance(skills, dict):
-        for name in list(skills):
-            if name not in allowlist:
-                skills.pop(name, None)
-        return
-    logger.debug("skills_allowlist_not_applied", reason="toolset_has_no_skills_dict")
-
-
-def _iter_skill_dirs(directories: list[str]) -> list[Path]:
-    skill_dirs: list[Path] = []
-    for base_dir in directories:
-        root = Path(base_dir).expanduser()
-        if not root.is_dir():
-            continue
-        for child in sorted(root.iterdir(), key=lambda path: path.name):
-            if child.is_dir() and (child / "SKILL.md").is_file():
-                skill_dirs.append(child)
-    return skill_dirs
-
-
-def _detect_has_scripts(skill_dir: Path) -> bool:
-    scripts_dir = skill_dir / "scripts"
-    if not scripts_dir.is_dir():
-        return False
-    return any(path.is_file() for path in scripts_dir.rglob("*"))
-
-
-def _normalize_skill_identifier(value: str) -> str:
-    text = value.strip().lower()
-    if not text:
-        return ""
-    text = re.sub(r"[\s_]+", "-", text)
-    text = re.sub(r"-{2,}", "-", text)
-    return text
-
-
-def _dedupe_preserve_order(values: list[str]) -> list[str]:
-    seen: set[str] = set()
-    output: list[str] = []
-    for value in values:
-        if value in seen:
-            continue
-        seen.add(value)
-        output.append(value)
-    return output
-
-
-def _build_skill_aliases(*values: str | None) -> list[str]:
-    aliases: list[str] = []
-    for value in values:
-        text = str(value or "").strip()
-        if not text:
-            continue
-        aliases.append(text)
-        normalized = _normalize_skill_identifier(text)
-        if normalized and normalized != text:
-            aliases.append(normalized)
-    return _dedupe_preserve_order(aliases)
-
-
-def _extract_frontmatter_fields(skill_md_path: Path) -> dict[str, str]:
-    try:
-        text = skill_md_path.read_text(encoding="utf-8")
-    except OSError:
-        return {}
-    lines = text.splitlines()
-    if len(lines) < 3 or lines[0].strip() != "---":
-        return {}
-    fields: dict[str, str] = {}
-    for line in lines[1:]:
-        stripped = line.strip()
-        if stripped == "---":
-            break
-        key, sep, value = stripped.partition(":")
-        if not sep:
-            continue
-        key_name = key.strip().lower()
-        value_text = value.strip().strip("'\"")
-        if key_name and value_text:
-            fields[key_name] = value_text
-    return fields
-
-
-def _extract_frontmatter_name(skill_md_path: Path) -> str | None:
-    return _extract_frontmatter_fields(skill_md_path).get("name")
-
-
-def _extract_frontmatter_description(skill_md_path: Path) -> str | None:
-    return _extract_frontmatter_fields(skill_md_path).get("description")
-
-
-def compute_skill_content_hash(skill_dir: Path) -> str:
-    """Compute deterministic integrity hash for SKILL.md + scripts content."""
-    digest = hashlib.sha256()
-    included_files: list[Path] = []
-    skill_md = skill_dir / "SKILL.md"
-    if skill_md.is_file():
-        included_files.append(skill_md)
-    scripts_dir = skill_dir / "scripts"
-    if scripts_dir.is_dir():
-        for path in sorted(scripts_dir.rglob("*"), key=lambda entry: str(entry.relative_to(skill_dir))):
-            if path.is_file():
-                included_files.append(path)
-    for path in included_files:
-        rel_path = path.relative_to(skill_dir).as_posix()
-        digest.update(rel_path.encode("utf-8"))
-        digest.update(b"\0")
-        digest.update(path.read_bytes())
-        digest.update(b"\0")
-    return digest.hexdigest()
-
-
-def get_skills_metadata(config: SkillsToolsetConfig) -> list[SkillInfo]:
-    """Collect skill metadata from configured directories for policy enforcement."""
-    metadata: list[SkillInfo] = []
-    for skill_dir in _iter_skill_dirs(config.directories):
-        skill_name = skill_dir.name
-        frontmatter_name = _extract_frontmatter_name(skill_dir / "SKILL.md")
-        canonical_name = frontmatter_name or skill_name
-        has_scripts = _detect_has_scripts(skill_dir)
-        metadata.append(
-            SkillInfo(
-                name=canonical_name,
-                metadata_name=skill_name,
-                frontmatter_name=frontmatter_name,
-                canonical_name=canonical_name,
-                description=_extract_frontmatter_description(skill_dir / "SKILL.md"),
-                path=str(skill_dir),
-                trust_tier=config.default_trust_tier,
-                has_scripts=has_scripts,
-                content_hash=compute_skill_content_hash(skill_dir),
-            )
-        )
-    return metadata
-
-
-def validate_skill_content_hash(
-    skill_info: SkillInfo,
-    *,
-    raise_on_mismatch: bool = True,
-) -> bool:
-    """Validate that a skill's current content matches its recorded hash.
-
-    Recomputes the SHA-256 hash from SKILL.md + scripts on disk and compares
-    it against ``skill_info.content_hash``.  This MUST be called before
-    executing any skill to ensure supply-chain integrity (FR-23).
-
-    Args:
-        skill_info: Metadata entry with ``path`` and ``content_hash`` set.
-        raise_on_mismatch: When *True* (default), raise
-            :class:`SkillContentHashMismatchError` on mismatch instead of
-            returning *False*.
-
-    Returns:
-        *True* when the hashes match or when the stored hash / path is absent
-        (nothing to validate).  *False* only when *raise_on_mismatch* is
-        disabled and the hashes diverge.
-    """
-    if not skill_info.path or not skill_info.content_hash:
-        logger.debug(
-            "skill_hash_validation_skipped",
-            skill=skill_info.name,
-            reason="missing_path_or_hash",
-        )
-        return True
-
-    actual_hash = compute_skill_content_hash(Path(skill_info.path))
-    if actual_hash == skill_info.content_hash:
-        return True
-
-    logger.warning(
-        "skill_content_hash_mismatch",
-        skill=skill_info.name,
-        expected=skill_info.content_hash[:16],
-        actual=actual_hash[:16],
-    )
-    if raise_on_mismatch:
-        raise SkillContentHashMismatchError(
-            skill_name=skill_info.name,
-            expected=skill_info.content_hash,
-            actual=actual_hash,
-        )
-    return False
-
-
-def _resolve_trust_tier_for_skill(
-    config: SkillsToolsetConfig,
-    *,
-    metadata_name: str | None,
-    frontmatter_name: str | None,
-    runtime_name: str | None,
-) -> SkillTrustTier:
-    alias_order = _build_skill_aliases(runtime_name, frontmatter_name, metadata_name)
-    for alias in alias_order:
-        if alias in config.trust_tiers:
-            return config.trust_tiers[alias]
-
-    normalized_tiers: dict[str, SkillTrustTier] = {}
-    for key, tier in config.trust_tiers.items():
-        normalized = _normalize_skill_identifier(key)
-        if normalized and normalized not in normalized_tiers:
-            normalized_tiers[normalized] = tier
-    for alias in alias_order:
-        tier = normalized_tiers.get(_normalize_skill_identifier(alias))
-        if tier is not None:
-            return tier
-    return config.default_trust_tier
-
-
-def _extract_runtime_skill_names(toolset: Any) -> set[str] | None:
-    skills = getattr(toolset, "skills", None)
-    if isinstance(skills, dict):
-        return {str(name).strip() for name in skills if str(name).strip()}
-    return None
-
-
-def _record_drop(
-    diagnostics: SkillPolicyDiagnostics,
-    *,
-    skill_name: str,
-    reason: SkillDropReason,
-    metadata_name: str | None = None,
-    frontmatter_name: str | None = None,
-    runtime_name: str | None = None,
-    detail: str | None = None,
-) -> None:
-    diagnostics.dropped.append(
-        SkillPolicyDrop(
-            skill_name=skill_name,
-            reason=reason,
-            metadata_name=metadata_name,
-            frontmatter_name=frontmatter_name,
-            runtime_name=runtime_name,
-            detail=detail,
-        )
-    )
-
-
-def _resolve_runtime_identity(
-    config: SkillsToolsetConfig,
-    metadata: list[SkillInfo],
-    runtime_skill_names: set[str] | None,
-    diagnostics: SkillPolicyDiagnostics,
-) -> list[SkillInfo]:
-    if not metadata:
-        return []
-    if not runtime_skill_names:
-        for item in metadata:
-            runtime_name = item.name
-            item.runtime_name = runtime_name
-            item.canonical_name = runtime_name
-            item.trust_tier = _resolve_trust_tier_for_skill(
-                config,
-                metadata_name=item.metadata_name,
-                frontmatter_name=item.frontmatter_name,
-                runtime_name=runtime_name,
-            )
-        return metadata
-
-    remaining = set(runtime_skill_names)
-    resolved: list[SkillInfo] = []
-    for item in metadata:
-        aliases = _build_skill_aliases(
-            item.frontmatter_name,
-            item.metadata_name,
-            item.canonical_name,
-            item.name,
-        )
-        runtime_name: str | None = None
-        for alias in aliases:
-            if alias in remaining:
-                runtime_name = alias
-                break
-        if runtime_name is None:
-            for alias in aliases:
-                normalized_alias = _normalize_skill_identifier(alias)
-                candidates = sorted(
-                    candidate for candidate in remaining if _normalize_skill_identifier(candidate) == normalized_alias
-                )
-                if candidates:
-                    runtime_name = candidates[0]
-                    break
-        if runtime_name is None:
-            _record_drop(
-                diagnostics,
-                skill_name=item.name,
-                reason="name_mismatch",
-                metadata_name=item.metadata_name,
-                frontmatter_name=item.frontmatter_name,
-                runtime_name=None,
-                detail="runtime_name_not_found",
-            )
-            continue
-        remaining.discard(runtime_name)
-        item.runtime_name = runtime_name
-        item.canonical_name = runtime_name
-        item.name = runtime_name
-        item.trust_tier = _resolve_trust_tier_for_skill(
-            config,
-            metadata_name=item.metadata_name,
-            frontmatter_name=item.frontmatter_name,
-            runtime_name=runtime_name,
-        )
-        resolved.append(item)
-
-    for runtime_name in sorted(remaining):
-        _record_drop(
-            diagnostics,
-            skill_name=runtime_name,
-            reason="name_mismatch",
-            runtime_name=runtime_name,
-            detail="runtime_without_metadata",
-        )
-    return resolved
-
-
-def _resolve_allowlist_runtime_names(config: SkillsToolsetConfig, metadata: list[SkillInfo]) -> set[str] | None:
-    if not config.allowlist:
-        return None
-    alias_to_runtime: dict[str, list[str]] = {}
-    normalized_alias_to_runtime: dict[str, list[str]] = {}
-    for item in metadata:
-        runtime_name = item.runtime_name or item.name
-        for alias in _build_skill_aliases(
-            runtime_name,
-            item.canonical_name,
-            item.frontmatter_name,
-            item.metadata_name,
-        ):
-            alias_to_runtime.setdefault(alias, []).append(runtime_name)
-            normalized = _normalize_skill_identifier(alias)
-            if normalized:
-                normalized_alias_to_runtime.setdefault(normalized, []).append(runtime_name)
-
-    resolved: set[str] = set()
-    for requested in config.allowlist:
-        requested_text = str(requested or "").strip()
-        if not requested_text:
-            continue
-        candidates = alias_to_runtime.get(requested_text, [])
-        if not candidates:
-            candidates = normalized_alias_to_runtime.get(_normalize_skill_identifier(requested_text), [])
-        if not candidates:
-            continue
-        resolved.add(sorted(set(candidates))[0])
-    return resolved
-
-
-def _compute_effective_allowlist(
-    config: SkillsToolsetConfig,
-    metadata: list[SkillInfo],
-    diagnostics: SkillPolicyDiagnostics,
-) -> set[str] | None:
-    if not metadata:
-        return set(config.allowlist) if config.allowlist else None
-
-    requested_runtime_allowlist = _resolve_allowlist_runtime_names(config, metadata)
-    allowed_trust_tiers = set(config.allowed_trust_tiers)
-    effective_allowlist: set[str] = set()
-    for item in metadata:
-        runtime_name = item.runtime_name or item.name
-        if requested_runtime_allowlist is not None and runtime_name not in requested_runtime_allowlist:
-            _record_drop(
-                diagnostics,
-                skill_name=item.name,
-                reason="name_mismatch",
-                metadata_name=item.metadata_name,
-                frontmatter_name=item.frontmatter_name,
-                runtime_name=item.runtime_name,
-                detail="allowlist_rejected",
-            )
-            continue
-        if item.trust_tier not in allowed_trust_tiers:
-            _record_drop(
-                diagnostics,
-                skill_name=item.name,
-                reason="trust_tier_rejected",
-                metadata_name=item.metadata_name,
-                frontmatter_name=item.frontmatter_name,
-                runtime_name=item.runtime_name,
-                detail=item.trust_tier,
-            )
-            continue
-        effective_allowlist.add(runtime_name)
-    return effective_allowlist
-
-
-def get_toolset_skill_metadata(toolset: Any) -> list[SkillInfo]:
-    """Return policy-scoped metadata attached to a created SkillsToolset."""
-    metadata = getattr(toolset, "_vds_skill_metadata", None)
-    if isinstance(metadata, list):
-        return [item for item in metadata if isinstance(item, SkillInfo)]
-    return []
-
-
-def get_toolset_policy_diagnostics(toolset: Any) -> SkillPolicyDiagnostics | None:
-    """Return policy diagnostics attached to a created SkillsToolset."""
-    diagnostics = getattr(toolset, "_vds_skill_policy_diagnostics", None)
-    if isinstance(diagnostics, SkillPolicyDiagnostics):
-        return diagnostics
-    return None
-
-
-def _extract_tool_name(candidate: Any, *, fallback: str = "") -> str:
-    if isinstance(candidate, str):
-        return candidate
-    for attr in ("name", "tool_name", "__name__"):
-        value = getattr(candidate, attr, None)
-        if isinstance(value, str) and value.strip():
-            return value.strip()
-    if callable(candidate):
-        value = getattr(candidate, "__name__", "")
-        if isinstance(value, str):
-            return value.strip()
-    return fallback
-
-
-def _filter_tool_container(container: Any, blocked_name: str) -> tuple[Any, bool]:
-    blocked_any = False
-    if isinstance(container, dict):
-        filtered: dict[Any, Any] = {}
-        for key, value in container.items():
-            name = _extract_tool_name(value, fallback=str(key))
-            if _normalize_skill_identifier(name) == _normalize_skill_identifier(blocked_name):
-                blocked_any = True
-                continue
-            filtered[key] = value
-        return filtered, blocked_any
-    if isinstance(container, list):
-        filtered_list: list[Any] = []
-        for item in container:
-            name = _extract_tool_name(item)
-            if _normalize_skill_identifier(name) == _normalize_skill_identifier(blocked_name):
-                blocked_any = True
-                continue
-            filtered_list.append(item)
-        return filtered_list, blocked_any
-    if isinstance(container, tuple):
-        filtered_items, blocked_any = _filter_tool_container(list(container), blocked_name)
-        if isinstance(filtered_items, list):
-            return tuple(filtered_items), blocked_any
-    if isinstance(container, set):
-        filtered_items, blocked_any = _filter_tool_container(list(container), blocked_name)
-        if isinstance(filtered_items, list):
-            return set(filtered_items), blocked_any
-    return container, blocked_any
-
-
-def _apply_read_only_script_policy(toolset: Any, diagnostics: SkillPolicyDiagnostics) -> None:
-    blocked_name = "run_skill_script"
-    blocked = False
-    for attr_name in ("tools", "_tools"):
-        container = getattr(toolset, attr_name, None)
-        if container is None:
-            continue
-        filtered_container, did_block = _filter_tool_container(container, blocked_name)
-        if did_block:
-            blocked = True
-            try:
-                setattr(toolset, attr_name, filtered_container)
-            except Exception:
-                logger.debug(
-                    "skills_toolset_read_only_block_failed",
-                    attribute=attr_name,
-                    tool_name=blocked_name,
-                )
-    if blocked and blocked_name not in diagnostics.blocked_tools:
-        diagnostics.blocked_tools.append(blocked_name)
-        diagnostics.dropped.append(
-            SkillPolicyDrop(
-                skill_name=blocked_name,
-                reason="script_policy_rejected",
-                detail="allow_script_execution=false",
-            )
-        )
-
-
-def _wrap_read_skill_resource_missing_resource_error(toolset: Any) -> None:
-    """Convert missing-skill-resource tool errors into deterministic soft-fail guidance.
-
-    Some LLM tool loops occasionally pass repository file names (for example
-    ``go_adapter.py``) as ``resource_name`` to ``read_skill_resource``.
-    The upstream tool raises ``SkillResourceNotFoundError`` which can surface as
-    noisy unhandled task warnings in runtime logs. This wrapper keeps execution
-    bounded by returning guidance text for this specific class of error.
-    """
-
-    tools = getattr(toolset, "tools", None)
-    if not isinstance(tools, dict):
-        return
-    read_tool = tools.get("read_skill_resource")
-    if read_tool is None:
-        return
-    original_function = getattr(read_tool, "function", None)
-    if not callable(original_function):
-        return
-    if bool(getattr(read_tool, "_vds_missing_resource_wrapped", False)):
-        return
-
-    async def _wrapped_read_skill_resource(*args: Any, **kwargs: Any) -> Any:
-        try:
-            result = original_function(*args, **kwargs)
-            if inspect.isawaitable(result):
-                return await result
-            return result
-        except Exception as exc:  # pragma: no cover - exercised via tests using stub toolsets
-            message = str(exc or "")
-            normalized = message.lower()
-            missing_resource = "resource '" in normalized and "not found in skill" in normalized
-            if not missing_resource:
-                raise
-
-            skill_name = ""
-            resource_name = ""
-            if isinstance(kwargs, dict):
-                skill_name = str(kwargs.get("skill_name") or kwargs.get("name") or "").strip()
-                resource_name = str(
-                    kwargs.get("resource_name") or kwargs.get("resource_path") or kwargs.get("path") or ""
-                ).strip()
-            if not skill_name or not resource_name:
-                string_args = [str(value).strip() for value in args if isinstance(value, str) and str(value).strip()]
-                if not skill_name and string_args:
-                    skill_name = string_args[0]
-                if not resource_name and len(string_args) >= 2:
-                    resource_name = string_args[1]
-
-            logger.warning(
-                "skills_toolset_missing_resource_soft_fail",
-                skill=skill_name or None,
-                resource=resource_name or None,
-                error=message,
-            )
-            return (
-                "[skill-resource-missing] Requested resource is unavailable for the selected skill. "
-                "Call load_skill first, then use one resource name exactly as listed in load_skill output."
-            )
-
-    read_tool.function = _wrapped_read_skill_resource
-    function_schema = getattr(read_tool, "function_schema", None)
-    if function_schema is not None and hasattr(function_schema, "function"):
-        try:
-            function_schema.function = _wrapped_read_skill_resource
-        except Exception:
-            logger.debug("skills_toolset_missing_resource_wrapper_schema_update_failed")
-    read_tool._vds_missing_resource_wrapped = True
-
-
-def create_skills_toolset_from_config(config: SkillsToolsetConfig) -> Any:
-    """Create a SkillsToolset instance from config."""
-    global _SKILL_WARNING_FILTER_CONFIGURED
-    if not _SKILL_WARNING_FILTER_CONFIGURED:
-        suppress_size_warnings = str(os.getenv("VDS_AUDIT_LLM__SKILLS_SUPPRESS_SIZE_WARNINGS", "true")).strip().lower()
-        if suppress_size_warnings in {"1", "true", "yes", "on"}:
-            warnings.filterwarnings(
-                "ignore",
-                message=r"SKILL\.md body exceeds recommended 500 lines.*",
-                module=r"pydantic_ai_skills\.directory",
-            )
-        _SKILL_WARNING_FILTER_CONFIGURED = True
-    try:
-        from pydantic_ai_skills import SkillsToolset
-    except ImportError as exc:  # pragma: no cover - depends on optional package
-        raise RuntimeError("pydantic-ai-skills is required: pip install pydantic-ai-skills") from exc
-
-    metadata = get_skills_metadata(config)
-    diagnostics = SkillPolicyDiagnostics(metadata_count=len(metadata))
-
-    toolset_kwargs: dict[str, Any] = {
-        "directories": [Path(path) for path in config.directories],
-        "validate": config.validate_skills,
-        "script_timeout": config.script_timeout,
-        "allow_script_execution": config.allow_script_execution,
-    }
-    optional_kwargs = ("allow_script_execution", "script_timeout")
-    constructor_params = set(inspect.signature(SkillsToolset.__init__).parameters.keys())
-    for optional_key in optional_kwargs:
-        if optional_key in toolset_kwargs and optional_key not in constructor_params:
-            toolset_kwargs.pop(optional_key, None)
-            logger.debug(
-                "skills_toolset_arg_not_supported",
-                arg=optional_key,
-                reason="constructor_signature",
-            )
-    toolset = SkillsToolset(**toolset_kwargs)
-
-    runtime_skill_names = _extract_runtime_skill_names(toolset)
-    resolved_metadata = _resolve_runtime_identity(config, metadata, runtime_skill_names, diagnostics)
-    effective_allowlist = _compute_effective_allowlist(config, resolved_metadata, diagnostics)
-
-    # FR-23: Validate content hashes before allowing execution.
-    # Skills whose hash no longer matches disk content are removed from the
-    # effective allowlist so they cannot be invoked.
-    if resolved_metadata and effective_allowlist is not None:
-        rejected: list[str] = []
-        for item in resolved_metadata:
-            runtime_name = item.runtime_name or item.name
-            if runtime_name not in effective_allowlist:
-                continue
-            if not validate_skill_content_hash(item, raise_on_mismatch=False):
-                rejected.append(runtime_name)
-                _record_drop(
-                    diagnostics,
-                    skill_name=item.name,
-                    reason="hash_validation_rejected",
-                    metadata_name=item.metadata_name,
-                    frontmatter_name=item.frontmatter_name,
-                    runtime_name=item.runtime_name,
-                    detail="content_hash_mismatch",
-                )
-        if rejected:
-            logger.warning(
-                "skills_rejected_by_hash_validation",
-                rejected=rejected,
-                remaining=sorted(effective_allowlist - set(rejected)),
-            )
-            effective_allowlist -= set(rejected)
-
-    if effective_allowlist is not None:
-        _apply_allowlist(toolset, effective_allowlist)
-    if not config.allow_script_execution:
-        _apply_read_only_script_policy(toolset, diagnostics)
-    _wrap_read_skill_resource_missing_resource_error(toolset)
-
-    if resolved_metadata:
-        allowed_names = (
-            effective_allowlist
-            if effective_allowlist is not None
-            else {(item.runtime_name or item.name) for item in resolved_metadata}
-        )
-        filtered_metadata = [item for item in resolved_metadata if (item.runtime_name or item.name) in allowed_names]
-        dynamic_toolset = cast("Any", toolset)
-        dynamic_toolset._vds_skill_metadata = filtered_metadata
-    current_runtime_loaded = _extract_runtime_skill_names(toolset)
-    if effective_allowlist is not None:
-        if resolved_metadata:
-            diagnostics.policy_eligible_count = len(effective_allowlist)
-        else:
-            diagnostics.policy_eligible_count = len(effective_allowlist.intersection(current_runtime_loaded or set()))
-    else:
-        diagnostics.policy_eligible_count = len(resolved_metadata)
-    diagnostics.runtime_loaded_count = len(current_runtime_loaded or set())
-    cast("Any", toolset)._vds_skill_policy_diagnostics = diagnostics
-    return toolset
-
-
-def get_default_skills_toolset(
-    *,
-    validate_skills: bool = True,
-    script_timeout: int = 60,
-    allowlist: list[str] | None = None,
-    allow_script_execution: bool = False,
-    allowed_trust_tiers: list[SkillTrustTier] | None = None,
-    default_trust_tier: SkillTrustTier = "external-unverified",
-    trust_tiers: dict[str, SkillTrustTier] | None = None,
-) -> Any:
-    """Return a default SkillsToolset from repo-local skills directory."""
-    directories = list(DEFAULT_AUDIT_SKILLS)
-    if not directories:
-        raise RuntimeError("No skills directory found for default toolset")
-    return create_skills_toolset_from_config(
-        SkillsToolsetConfig(
-            directories=directories,
-            validate_skills=validate_skills,
-            script_timeout=script_timeout,
-            allowlist=allowlist or [],
-            allow_script_execution=allow_script_execution,
-            allowed_trust_tiers=allowed_trust_tiers or list(_DEFAULT_ALLOWED_TRUST_TIERS),
-            default_trust_tier=default_trust_tier,
-            trust_tiers=trust_tiers or {},
-        )
-    )
-
-
-def create_pydantic_tools() -> list[Any]:
-    """Create PydanticAI tool callables for core skill helpers."""
-    from vds_agent_core.skills.executor import SkillExecutor
-
-    def vds_cli_exec(args: list[str]) -> str:
-        """Execute a vds-cli command and return stdout."""
-        return SkillExecutor.vds_cli_exec(args)
-
-    return [vds_cli_exec]
-
-
-# ---------------------------------------------------------------------------
-# Phase 172 — Resource fallback telemetry (P172-F, TSK-172.35/36)
-# ---------------------------------------------------------------------------
-
-
-@dataclass
-class SkillResourceResult:
-    """Result of a skill resource load, with explicit fallback observability."""
-
-    success: bool
-    content: str = ""
-    resource_path: str = ""
-    requested_resource: str = ""
-    requested_resource_fallback: bool = False
-    fallback_reason: str = ""
-
-
-def _find_skill_dir(skill_name: str, skill_dirs: list[str] | None = None) -> Path | None:
-    """Return the first skill directory whose name matches *skill_name*.
-
-    Scans the provided *skill_dirs* (or ``DEFAULT_AUDIT_SKILLS`` when absent)
-    for a subdirectory that matches the normalised form of *skill_name* and
-    contains a ``SKILL.md`` file (the canonical skill sentinel).
-    """
-    dirs: list[str] = list(skill_dirs or DEFAULT_AUDIT_SKILLS)
-    normalized = _normalize_skill_identifier(skill_name)
-    for base_dir in dirs:
-        root = Path(base_dir).expanduser()
-        if not root.is_dir():
-            continue
-        for child in sorted(root.iterdir(), key=lambda p: p.name):
-            if not child.is_dir():
-                continue
-            if not (child / "SKILL.md").is_file():
-                continue
-            if _normalize_skill_identifier(child.name) == normalized:
-                return child
-    return None
-
-
-def load_skill_resource(
-    skill_name: str,
-    resource_path: str,
-    skill_dirs: list[str] | None = None,
-) -> SkillResourceResult:
-    """Load a skill resource file, falling back to SKILL.md with telemetry.
-
-    When *resource_path* resolves to an existing file inside the skill
-    directory, that file is returned with ``requested_resource_fallback=False``.
-
-    When *resource_path* is missing but ``SKILL.md`` exists, the function
-    falls back to ``SKILL.md``, emits a ``skill_resource_fallback`` structured
-    log warning, and sets ``requested_resource_fallback=True``.  This makes
-    previously silent fallbacks observable in retrieval traces.
-
-    Returns a ``SkillResourceResult`` with ``success=False`` when the skill
-    cannot be located or neither file is readable.
-    """
-    skill_dir = _find_skill_dir(skill_name, skill_dirs)
-    if skill_dir is None:
-        return SkillResourceResult(
-            success=False,
-            requested_resource=resource_path,
-        )
-
-    abs_path = skill_dir / resource_path
-    if abs_path.exists():
-        return SkillResourceResult(
-            success=True,
-            resource_path=resource_path,
-            content=abs_path.read_text(encoding="utf-8"),
-            requested_resource=resource_path,
-            requested_resource_fallback=False,
-        )
-
-    # Fallback: load SKILL.md with explicit fallback flag and structured log.
-    fallback_path = skill_dir / "SKILL.md"
-    if fallback_path.exists():
-        logger.warning(
-            "skill_resource_fallback",
-            skill_name=skill_name,
-            requested_resource=resource_path,
-            actual_resource="SKILL.md",
-            fallback_reason="requested_file_not_found",
-        )
-        return SkillResourceResult(
-            success=True,
-            resource_path="SKILL.md",
-            content=fallback_path.read_text(encoding="utf-8"),
-            requested_resource=resource_path,
-            requested_resource_fallback=True,
-            fallback_reason="requested_file_not_found",
-        )
-
-    return SkillResourceResult(
-        success=False,
-        requested_resource=resource_path,
-    )
-
-
-# ---------------------------------------------------------------------------
-# Phase 172 — Skill content pattern extraction (P172-C, TSK-172.16)
-# ---------------------------------------------------------------------------
-
-_RECOMMENDED_PATTERNS_RE = re.compile(
-    r"^##\s+Recommended Search Patterns\s*$",
-    re.MULTILINE,
-)
-
-
-def parse_recommended_patterns(skill_content: str) -> list[str]:
-    """Parse the Recommended Search Patterns section from skill content.
-
-    Returns a list of pattern strings, one per bullet in the section.
-    Backtick-wrapped text is preferred when present (e.g. a bullet
-    containing backtick-rg 'foo'-backtick yields just that inner text).
-    Skills without the section return an empty list so callers degrade
-    gracefully. The parser handles bullet styles -, *, and +.
-    """
-    match = _RECOMMENDED_PATTERNS_RE.search(skill_content)
-    if not match:
-        return []
-    tail = skill_content[match.end() :]
-    end_match = re.search(r"^##\s", tail, re.MULTILINE)
-    section = tail[: end_match.start()] if end_match else tail
-    patterns: list[str] = []
-    for line in section.splitlines():
-        stripped = line.strip()
-        is_numbered = bool(re.match(r"^\d+\.\s", stripped))
-        if not (stripped.startswith(("- ", "* ", "+ ")) or is_numbered):
-            continue
-        body = re.sub(r"^\d+\.\s+", "", stripped) if is_numbered else stripped[2:].strip()
-        code_match = re.search(r"`([^`]+)`", body)
-        if code_match:
-            patterns.append(code_match.group(1))
-        elif body:
-            patterns.append(body)
-    return patterns
-
-
-# ---------------------------------------------------------------------------
-# Phase 172 — TSK-172.17: Cached recommended patterns lookup
-# ---------------------------------------------------------------------------
-
-_pattern_cache: dict[str, list[str]] = {}
-
-
-def get_recommended_patterns(
-    skill_name: str,
-    skill_dirs: list[str] | None = None,
-) -> list[str]:
-    """Return cached recommended search patterns for *skill_name*.
-
-    Loads the skill's SKILL.md via *load_skill_resource* and parses the
-    ``## Recommended Search Patterns`` section.  Results are cached by
-    skill name so repeated calls within a planning cycle are zero-cost.
-
-    Returns an empty list when the skill cannot be found or has no section.
-    """
-    cache_key = skill_name
-    if cache_key in _pattern_cache:
-        return _pattern_cache[cache_key]
-    result = load_skill_resource(skill_name, "SKILL.md", skill_dirs=skill_dirs)
-    if not result.success or not result.content:
-        _pattern_cache[cache_key] = []
-        return []
-    patterns = parse_recommended_patterns(result.content)
-    _pattern_cache[cache_key] = patterns
-    return patterns