traceforge-toolkit 0.1.0__py3-none-any.whl

traceforge/classify/core.py

@@ -0,0 +1,266 @@
+"""Universal classification dimensions — domain-agnostic root types.
+
+These enums define the abstract roots of each classification dimension.
+Domain plugins (like the built-in coding plugin) extend these hierarchically
+using dot-path subtypes (e.g., "validator.linter" extends "validator").
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import Any
+
+
+# ── Semantic classification dimensions ──
+
+
+class Mechanism(StrEnum):
+    """Primary resource domain the tool operates in.
+
+    Answers: "What kind of system resource does this tool interact with?"
+    NOT "how does the agent invoke it" (all tools are invoked via tool calls).
+    Domain plugins extend with dot-path subtypes (e.g., "process.shell").
+    """
+
+    FILESYSTEM = "filesystem"  # Direct filesystem access (read/write/search files)
+    PROCESS = "process"  # Spawns or interacts with OS processes
+    NETWORK = "network"  # Makes network requests (HTTP, WebSocket, etc.)
+    DATABASE = "database"  # Queries or mutates a database
+    DELEGATION = "delegation"  # Delegates work to another agent or system
+    COMMUNICATION = "communication"  # Exchanges messages (user or system)
+    UNKNOWN = "unknown"  # Tool mechanism could not be determined
+
+
+class Effect(StrEnum):
+    """Observable impact on state outside the agent.
+
+    Use None/absent on Classification when the effect cannot be determined
+    statically (e.g., a shell command whose behavior depends on arguments).
+    """
+
+    READ_ONLY = "read_only"  # No external state change; pure observation
+    MUTATING = "mutating"  # Changes external state (files, DB, services)
+    DESTRUCTIVE = "destructive"  # Irreversible state change (delete, drop, rm -rf)
+
+
+# Precedence for aggregating compound effects (highest wins)
+EFFECT_PRECEDENCE: dict[str, int] = {
+    Effect.READ_ONLY: 1,
+    Effect.MUTATING: 2,
+    Effect.DESTRUCTIVE: 3,
+}
+
+
+class Scope(StrEnum):
+    """What is being operated on — the subject matter domain.
+
+    Scopes identify the TYPE of thing being touched, not the specific instance.
+    Domain plugins extend with dot-paths (e.g., "artifact.source_code").
+    """
+
+    ARTIFACT = "artifact"  # A produced/maintained file or object (code, docs, images)
+    STATE = "state"  # Runtime/operational state (processes, deployments, sessions)
+    DATA = "data"  # Application-level data (user records, logs, metrics)
+    CONFIGURATION = "configuration"  # Settings that control behavior (env vars, configs)
+    KNOWLEDGE = "knowledge"  # Reference information (APIs, specs, documentation)
+    IDENTITY = "identity"  # Auth/identity artifacts (keys, tokens, certs)
+    MESSAGE = "message"  # Communication payloads (chat messages, notifications)
+
+
+class Role(StrEnum):
+    """What archetype of tool is performing this action.
+
+    Roles describe the tool's PURPOSE, not its implementation.
+    A tool's role is stable across invocations (a linter is always a validator).
+    """
+
+    VALIDATOR = "validator"  # Checks correctness without changing anything
+    RETRIEVER = "retriever"  # Finds and returns existing information
+    TRANSFORMER = "transformer"  # Converts input to a different form (compile, format, bundle)
+    GENERATOR = "generator"  # Produces new content from specifications
+    MODIFIER = "modifier"  # Makes targeted changes to existing content
+    EXECUTOR = "executor"  # Runs code/commands as a side effect
+    COMMUNICATOR = "communicator"  # Exchanges messages with humans or systems
+    ORCHESTRATOR = "orchestrator"  # Coordinates other tools or workflows
+    OBSERVER = "observer"  # Monitors/inspects without changing state (debug, profile)
+    PERSISTENCE = "persistence"  # Manages durable storage (VCS, DB, cache)
+
+
+class Action(StrEnum):
+    """The abstract operation being performed — the verb.
+
+    Actions are WHAT is done, independent of HOW (mechanism) or BY WHOM (role).
+    Domain plugins extend with dot-paths (e.g., "validate.lint").
+    """
+
+    VALIDATE = "validate"  # Check correctness, report pass/fail
+    RETRIEVE = "retrieve"  # Fetch existing data from a source
+    TRANSFORM = "transform"  # Convert data from one form to another
+    GENERATE = "generate"  # Create new content that didn't exist
+    EXECUTE = "execute"  # Run a process for its side effects
+    DELIVER = "deliver"  # Send/push data to an external destination
+    CONFIGURE = "configure"  # Set up or change system configuration
+    ANALYZE = "analyze"  # Inspect data to produce insights (not retrieve)
+    PERSIST = "persist"  # Save data durably (commit, write, store)
+    MODIFY = "modify"  # Change existing content in-place
+    REMOVE = "remove"  # Delete or tear down something
+
+
+class Capability(StrEnum):
+    """What system access the action requires — the permission model.
+
+    Capabilities are cumulative (a tool may need multiple).
+    Used for policy/gating decisions (e.g., "this action needs network access").
+    """
+
+    FILESYSTEM_READ = "filesystem_read"  # Read files from disk
+    FILESYSTEM_WRITE = "filesystem_write"  # Write/create/delete files on disk
+    NETWORK_INBOUND = "network_inbound"  # Accept incoming connections
+    NETWORK_OUTBOUND = "network_outbound"  # Make outgoing requests
+    SUBPROCESS = "subprocess"  # Spawn child processes
+    USES_CREDENTIALS = "uses_credentials"  # Accesses secrets/tokens
+    ELEVATED_PRIVILEGE = "elevated_privilege"  # Requires sudo/admin
+    HUMAN_INTERACTION = "human_interaction"  # Requires human response
+
+
+class Structure(StrEnum):
+    """Compositional properties of the invocation — how steps are arranged.
+
+    Describes the structural pattern of the operation, not its content.
+    """
+
+    SEQUENTIAL = "sequential"  # Steps execute one after another
+    PARALLEL = "parallel"  # Steps execute concurrently
+    CONDITIONAL = "conditional"  # Execution depends on a condition (if/then)
+    INTERACTIVE = "interactive"  # Requires back-and-forth interaction
+
+
+@dataclass(frozen=True)
+class PhaseSegment:
+    """One phase's contribution to a compound classification.
+
+    Groups the actions, scopes, and roles that together produced this phase.
+    Preserves the pairing so downstream consumers know which labels belong together.
+    """
+
+    phase: str
+    actions: frozenset[str] = frozenset()
+    scopes: frozenset[str] = frozenset()
+    roles: frozenset[str] = frozenset()
+
+
+@dataclass(frozen=True)
+class Classification:
+    """Multi-dimensional classification of an agent action.
+
+    All dimension values are dot-path strings from registered enums.
+    Use the registry to validate values and query hierarchy.
+
+    For compound commands, `phase_map` groups labels by their derived phase —
+    each segment contains the actions/scopes/roles that produced that phase.
+    The top-level `action`, `scope`, `role` sets are the aggregate union
+    for quick flat queries.
+    """
+
+    mechanism: str
+    effect: str | None = None
+    scope: frozenset[str] = frozenset()
+    role: frozenset[str] = frozenset()
+    action: frozenset[str] = frozenset()
+    capability: frozenset[str] = frozenset()
+    structure: frozenset[str] = frozenset()
+    source_labels: frozenset[str] = frozenset()
+    shell_dialect: str | None = None
+    binaries: tuple[str, ...] = ()
+    phase_map: tuple[PhaseSegment, ...] = ()
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize to a JSON-safe dictionary."""
+        d: dict[str, Any] = {
+            "mechanism": self.mechanism,
+        }
+        if self.effect is not None:
+            d["effect"] = self.effect
+        if self.scope:
+            d["scope"] = sorted(self.scope)
+        if self.role:
+            d["role"] = sorted(self.role)
+        if self.action:
+            d["action"] = sorted(self.action)
+        if self.capability:
+            d["capability"] = sorted(self.capability)
+        if self.structure:
+            d["structure"] = sorted(self.structure)
+        if self.source_labels:
+            d["source_labels"] = sorted(self.source_labels)
+        if self.shell_dialect:
+            d["shell_dialect"] = self.shell_dialect
+        if self.binaries:
+            d["binaries"] = list(self.binaries)
+        if self.phase_map:
+            d["phase_map"] = [
+                {
+                    "phase": seg.phase,
+                    "actions": sorted(seg.actions),
+                    "scopes": sorted(seg.scopes),
+                    "roles": sorted(seg.roles),
+                }
+                for seg in self.phase_map
+            ]
+        return d
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> Classification:
+        """Deserialize from a dictionary."""
+        phase_map_raw = d.get("phase_map") or ()
+        phase_map = tuple(
+            PhaseSegment(
+                phase=seg["phase"],
+                actions=frozenset(seg.get("actions") or ()),
+                scopes=frozenset(seg.get("scopes") or ()),
+                roles=frozenset(seg.get("roles") or ()),
+            )
+            for seg in phase_map_raw
+            if isinstance(seg, dict)
+        )
+        return cls(
+            mechanism=d["mechanism"],
+            effect=d.get("effect"),
+            scope=frozenset(d.get("scope") or ()),
+            role=frozenset(d.get("role") or ()),
+            action=frozenset(d.get("action") or ()),
+            capability=frozenset(d.get("capability") or ()),
+            structure=frozenset(d.get("structure") or ()),
+            source_labels=frozenset(d.get("source_labels") or ()),
+            shell_dialect=d.get("shell_dialect"),
+            binaries=tuple(d.get("binaries") or ()),
+            phase_map=phase_map,
+        )
+
+    def has_role(self, ancestor: str) -> bool:
+        """Check if any role matches or descends from ancestor."""
+        return any(r == ancestor or r.startswith(ancestor + ".") for r in self.role)
+
+    def has_action(self, ancestor: str) -> bool:
+        """Check if any action matches or descends from ancestor."""
+        return any(a == ancestor or a.startswith(ancestor + ".") for a in self.action)
+
+    def has_scope(self, ancestor: str) -> bool:
+        """Check if any scope matches or descends from ancestor."""
+        return any(s == ancestor or s.startswith(ancestor + ".") for s in self.scope)
+
+
+def aggregate_effect(*effects: str) -> str | None:
+    """Return the highest-precedence effect from a set of effects.
+
+    Returns None if no effects are provided or all are unrecognized.
+    """
+    best: str | None = None
+    best_p = 0
+    for e in effects:
+        p = EFFECT_PRECEDENCE.get(e, 0)
+        if p > best_p:
+            best_p = p
+            best = e
+    return best

traceforge/classify/data/binary_info.yaml

@@ -0,0 +1,358 @@
+# Binary metadata - role and default effect for known CLI binaries.
+# Used by shell classification to determine effect and role when
+# no specific rule matches.
+#
+# IMPORTANT: role values MUST match CodingRole enum values in coding.py.
+# Valid prefixes: validator.*, transformer.*, generator.*, executor.*,
+# orchestrator.*, observer.*, retriever.*, modifier.*, persistence.*,
+# communicator.*
+
+binary_info:
+  # --- Test runners ---
+  bats: { role: validator.test_runner, default_effect: read_only }
+  invoke-pester: { role: validator.test_runner, default_effect: read_only }
+  jest: { role: validator.test_runner, default_effect: read_only }
+  mocha: { role: validator.test_runner, default_effect: read_only }
+  nox: { role: validator.test_runner, default_effect: null, network: true }
+  pest: { role: validator.test_runner, default_effect: read_only }
+  phpunit: { role: validator.test_runner, default_effect: read_only }
+  playwright: { role: validator.test_runner, default_effect: read_only }
+  pytest: { role: validator.test_runner, default_effect: read_only }
+  rspec: { role: validator.test_runner, default_effect: read_only }
+  tox: { role: validator.test_runner, default_effect: null, network: true }
+  vitest: { role: validator.test_runner, default_effect: read_only }
+
+  # --- Type checkers ---
+  mypy: { role: validator.type_checker, default_effect: read_only }
+  pyright: { role: validator.type_checker, default_effect: read_only }
+
+  # --- Linters ---
+  clippy: { role: validator.linter, default_effect: read_only }
+  eslint: { role: validator.linter, default_effect: read_only }
+  flake8: { role: validator.linter, default_effect: read_only }
+  golangci-lint: { role: validator.linter, default_effect: read_only }
+  invoke-scriptanalyzer: { role: validator.linter, default_effect: read_only }
+  pylint: { role: validator.linter, default_effect: read_only }
+  rubocop: { role: validator.linter, default_effect: read_only }
+  ruff: { role: validator.linter, default_effect: read_only }
+
+  # --- Security scanners ---
+  bandit: { role: validator.security_scanner, default_effect: read_only }
+  safety: { role: validator.security_scanner, default_effect: read_only, network: true }
+  semgrep: { role: validator.security_scanner, default_effect: read_only }
+  snyk: { role: validator.security_scanner, default_effect: read_only, network: true }
+  trivy: { role: validator.security_scanner, default_effect: read_only }
+
+  # --- Build checkers ---
+  bazel: { role: validator.build_checker, default_effect: null, network: true }
+  build-module: { role: validator.build_checker, default_effect: mutating }
+  cmake: { role: validator.build_checker, default_effect: mutating }
+  invoke-build: { role: validator.build_checker, default_effect: mutating }
+  ninja: { role: validator.build_checker, default_effect: mutating }
+
+  # --- Formatters ---
+  black: { role: transformer.formatter, default_effect: mutating }
+  prettier: { role: transformer.formatter, default_effect: read_only }
+
+  # --- Compilers ---
+  clang: { role: transformer.compiler, default_effect: mutating }
+  clang++: { role: transformer.compiler, default_effect: mutating }
+  g++: { role: transformer.compiler, default_effect: mutating }
+  gcc: { role: transformer.compiler, default_effect: mutating }
+  javac: { role: transformer.compiler, default_effect: mutating }
+  rustc: { role: transformer.compiler, default_effect: mutating }
+
+  # --- Bundlers ---
+  vite: { role: transformer.bundler, default_effect: null }
+  webpack: { role: transformer.bundler, default_effect: mutating }
+
+  # --- Transpilers / encoding ---
+  b64encode: { role: transformer.transpiler, default_effect: read_only }
+  base64: { role: transformer.transpiler, default_effect: read_only }
+  gpg: { role: transformer.transpiler, default_effect: null }
+  hexdump: { role: transformer.transpiler, default_effect: read_only }
+  od: { role: transformer.transpiler, default_effect: read_only }
+  openssl: { role: transformer.transpiler, default_effect: null }
+  tsc: { role: transformer.transpiler, default_effect: null }
+  xxd: { role: transformer.transpiler, default_effect: read_only }
+
+  # --- Package managers ---
+  apt: { role: orchestrator.package_manager, default_effect: mutating, network: true }
+  apt-get: { role: orchestrator.package_manager, default_effect: mutating, network: true }
+  asdf: { role: orchestrator.package_manager, default_effect: mutating }
+  brew: { role: orchestrator.package_manager, default_effect: mutating, network: true }
+  choco: { role: orchestrator.package_manager, default_effect: mutating, network: true }
+  conda: { role: orchestrator.package_manager, default_effect: null, network: true }
+  dnf: { role: orchestrator.package_manager, default_effect: mutating, network: true }
+  dpkg: { role: orchestrator.package_manager, default_effect: mutating }
+  emerge: { role: orchestrator.package_manager, default_effect: mutating, network: true }
+  flatpak: { role: orchestrator.package_manager, default_effect: mutating, network: true }
+  fnm: { role: orchestrator.package_manager, default_effect: mutating }
+  helm: { role: orchestrator.package_manager, default_effect: null, network: true }
+  install-module: { role: orchestrator.package_manager, default_effect: mutating, network: true }
+  install-package: { role: orchestrator.package_manager, default_effect: mutating, network: true }
+  install-psresource: { role: orchestrator.package_manager, default_effect: mutating, network: true }
+  mise: { role: orchestrator.package_manager, default_effect: mutating }
+  nix: { role: orchestrator.package_manager, default_effect: null, network: true }
+  nvm: { role: orchestrator.package_manager, default_effect: mutating }
+  pacman: { role: orchestrator.package_manager, default_effect: mutating, network: true }
+  pip: { role: orchestrator.package_manager, default_effect: mutating, network: true }
+  pip-compile: { role: orchestrator.package_manager, default_effect: mutating }
+  pip3: { role: orchestrator.package_manager, default_effect: mutating, network: true }
+  pipx: { role: orchestrator.package_manager, default_effect: mutating, network: true }
+  poetry: { role: orchestrator.package_manager, default_effect: mutating, network: true }
+  pyenv: { role: orchestrator.package_manager, default_effect: mutating }
+  rbenv: { role: orchestrator.package_manager, default_effect: mutating }
+  register-psrepository: { role: orchestrator.package_manager, default_effect: mutating, network: true }
+  rpm: { role: orchestrator.package_manager, default_effect: mutating }
+  rtx: { role: orchestrator.package_manager, default_effect: mutating }
+  rustup: { role: orchestrator.package_manager, default_effect: mutating, network: true }
+  scoop: { role: orchestrator.package_manager, default_effect: mutating, network: true }
+  snap: { role: orchestrator.package_manager, default_effect: mutating, network: true }
+  update-module: { role: orchestrator.package_manager, default_effect: mutating, network: true }
+  uv: { role: orchestrator.package_manager, default_effect: mutating, network: true }
+  virtualenv: { role: orchestrator.package_manager, default_effect: mutating }
+  winget: { role: orchestrator.package_manager, default_effect: mutating, network: true }
+  yum: { role: orchestrator.package_manager, default_effect: mutating, network: true }
+  zypper: { role: orchestrator.package_manager, default_effect: mutating, network: true }
+
+  # --- Task runners ---
+  ansible: { role: orchestrator.task_runner, default_effect: null, network: true }
+  bun: { role: orchestrator.task_runner, default_effect: null, network: true }
+  bunx: { role: orchestrator.task_runner, default_effect: null, network: true }
+  cargo: { role: orchestrator.task_runner, default_effect: null, network: true }
+  dart: { role: orchestrator.task_runner, default_effect: null, network: true }
+  deno: { role: orchestrator.task_runner, default_effect: null, network: true }
+  dotnet: { role: orchestrator.task_runner, default_effect: null, network: true }
+  go: { role: orchestrator.task_runner, default_effect: null, network: true }
+  gradle: { role: orchestrator.task_runner, default_effect: null, network: true }
+  make: { role: orchestrator.task_runner, default_effect: null }
+  mvn: { role: orchestrator.task_runner, default_effect: null, network: true }
+  npm: { role: orchestrator.task_runner, default_effect: null, network: true }
+  npx: { role: orchestrator.task_runner, default_effect: null, network: true }
+  pnpm: { role: orchestrator.task_runner, default_effect: null, network: true }
+  pulumi: { role: orchestrator.task_runner, default_effect: null, network: true }
+  swift: { role: orchestrator.task_runner, default_effect: null, network: true }
+  terraform: { role: orchestrator.task_runner, default_effect: null, network: true }
+  tofu: { role: orchestrator.task_runner, default_effect: null, network: true }
+  twine: { role: orchestrator.task_runner, default_effect: null, network: true }
+  yarn: { role: orchestrator.task_runner, default_effect: null, network: true }
+
+  # --- Container runtimes ---
+  docker: { role: executor.container_runtime, default_effect: null, network: true }
+  docker-compose: { role: executor.container_runtime, default_effect: null, network: true }
+  eksctl: { role: executor.container_runtime, default_effect: null, network: true }
+  kind: { role: executor.container_runtime, default_effect: null, network: true }
+  kubectl: { role: executor.container_runtime, default_effect: null, network: true }
+  minikube: { role: executor.container_runtime, default_effect: null, network: true }
+  podman: { role: executor.container_runtime, default_effect: null, network: true }
+  vagrant: { role: executor.container_runtime, default_effect: null, network: true }
+
+  # --- Script runners / process control ---
+  bash: { role: executor.script_runner, default_effect: null }
+  crontab: { role: executor.script_runner, default_effect: mutating }
+  iptables: { role: executor.script_runner, default_effect: null, network: true }
+  kill: { role: executor.script_runner, default_effect: destructive, destructive: true }
+  killall: { role: executor.script_runner, default_effect: destructive, destructive: true }
+  pkill: { role: executor.script_runner, default_effect: destructive, destructive: true }
+  mount: { role: executor.script_runner, default_effect: mutating }
+  node: { role: executor.script_runner, default_effect: null }
+  perl: { role: executor.script_runner, default_effect: null }
+  php: { role: executor.script_runner, default_effect: null, network: true }
+  python: { role: executor.script_runner, default_effect: null }
+  python3: { role: executor.script_runner, default_effect: null }
+  restart-service: { role: executor.script_runner, default_effect: mutating }
+  ruby: { role: executor.script_runner, default_effect: null }
+  sh: { role: executor.script_runner, default_effect: null }
+  ssh: { role: executor.script_runner, default_effect: null, network: true }
+  start-process: { role: executor.script_runner, default_effect: mutating }
+  start-service: { role: executor.script_runner, default_effect: mutating }
+  stop-process: { role: executor.script_runner, default_effect: destructive, destructive: true }
+  stop-service: { role: executor.script_runner, default_effect: mutating }
+  sudo: { role: executor.script_runner, default_effect: null }
+  systemctl: { role: executor.script_runner, default_effect: null }
+  umount: { role: executor.script_runner, default_effect: mutating }
+  xargs: { role: executor.script_runner, default_effect: null }
+  zsh: { role: executor.script_runner, default_effect: null }
+
+  # --- Version control ---
+  git: { role: persistence.version_control, default_effect: null }
+  hg: { role: persistence.version_control, default_effect: null, network: true }
+  svn: { role: persistence.version_control, default_effect: null, network: true }
+
+  # --- Databases ---
+  mongosh: { role: persistence.database, default_effect: null, network: true }
+  mysql: { role: persistence.database, default_effect: null, network: true }
+  psql: { role: persistence.database, default_effect: null, network: true }
+  redis-cli: { role: persistence.cache, default_effect: null, network: true }
+  sqlite3: { role: persistence.database, default_effect: null }
+
+  # --- API clients / network ---
+  aws: { role: retriever.api_client, default_effect: null, network: true }
+  aws-vault: { role: retriever.api_client, default_effect: null, network: true }
+  az: { role: retriever.api_client, default_effect: null, network: true }
+  azd: { role: retriever.api_client, default_effect: null, network: true }
+  copilot-cli: { role: retriever.api_client, default_effect: null, network: true }
+  curl: { role: retriever.api_client, default_effect: read_only, network: true }
+  dig: { role: retriever.api_client, default_effect: read_only, network: true }
+  doctl: { role: retriever.api_client, default_effect: null, network: true }
+  ftp: { role: retriever.api_client, default_effect: null, network: true }
+  gcloud: { role: retriever.api_client, default_effect: null, network: true }
+  gsutil: { role: retriever.api_client, default_effect: null, network: true }
+  gh: { role: retriever.api_client, default_effect: null, network: true }
+  oci: { role: retriever.api_client, default_effect: null, network: true }
+  sam: { role: retriever.api_client, default_effect: null, network: true }
+  invoke-restmethod: { role: retriever.api_client, default_effect: null, network: true }
+  invoke-webrequest: { role: retriever.api_client, default_effect: null, network: true }
+  nc: { role: retriever.api_client, default_effect: null, network: true }
+  ncat: { role: retriever.api_client, default_effect: null, network: true }
+  nslookup: { role: retriever.api_client, default_effect: read_only, network: true }
+  ping: { role: retriever.api_client, default_effect: read_only, network: true }
+  socat: { role: retriever.api_client, default_effect: null, network: true }
+  telnet: { role: retriever.api_client, default_effect: null, network: true }
+  test-connection: { role: retriever.api_client, default_effect: read_only, network: true }
+  test-netconnection: { role: retriever.api_client, default_effect: read_only, network: true }
+  traceroute: { role: retriever.api_client, default_effect: read_only, network: true }
+  wget: { role: retriever.api_client, default_effect: mutating, network: true }
+
+  # --- File browsers / system info ---
+  bat: { role: retriever.file_browser, default_effect: read_only }
+  cat: { role: retriever.file_browser, default_effect: read_only }
+  date: { role: retriever.file_browser, default_effect: read_only }
+  df: { role: retriever.file_browser, default_effect: read_only }
+  dir: { role: retriever.file_browser, default_effect: read_only }
+  du: { role: retriever.file_browser, default_effect: read_only }
+  env: { role: retriever.file_browser, default_effect: read_only }
+  exa: { role: retriever.file_browser, default_effect: read_only }
+  eza: { role: retriever.file_browser, default_effect: read_only }
+  fd: { role: retriever.file_browser, default_effect: read_only }
+  fdfind: { role: retriever.file_browser, default_effect: read_only }
+  find: { role: retriever.file_browser, default_effect: read_only }
+  format-list: { role: retriever.file_browser, default_effect: read_only }
+  format-table: { role: retriever.file_browser, default_effect: read_only }
+  free: { role: retriever.file_browser, default_effect: read_only }
+  get-childitem: { role: retriever.file_browser, default_effect: read_only }
+  get-command: { role: retriever.file_browser, default_effect: read_only }
+  get-content: { role: retriever.file_browser, default_effect: read_only }
+  get-help: { role: retriever.file_browser, default_effect: read_only }
+  get-item: { role: retriever.file_browser, default_effect: read_only }
+  get-itemproperty: { role: retriever.file_browser, default_effect: read_only }
+  get-module: { role: retriever.file_browser, default_effect: read_only }
+  get-process: { role: retriever.file_browser, default_effect: read_only }
+  get-service: { role: retriever.file_browser, default_effect: read_only }
+  get-variable: { role: retriever.file_browser, default_effect: read_only }
+  head: { role: retriever.file_browser, default_effect: read_only }
+  hostname: { role: retriever.file_browser, default_effect: read_only }
+  less: { role: retriever.file_browser, default_effect: read_only }
+  ll: { role: retriever.file_browser, default_effect: read_only }
+  ls: { role: retriever.file_browser, default_effect: read_only }
+  lsd: { role: retriever.file_browser, default_effect: read_only }
+  man: { role: retriever.file_browser, default_effect: read_only }
+  more: { role: retriever.file_browser, default_effect: read_only }
+  netstat: { role: retriever.file_browser, default_effect: read_only }
+  printenv: { role: retriever.file_browser, default_effect: read_only }
+  ps: { role: retriever.file_browser, default_effect: read_only }
+  pwd: { role: retriever.file_browser, default_effect: read_only }
+  set: { role: retriever.file_browser, default_effect: null }
+  ss: { role: retriever.file_browser, default_effect: read_only }
+  tail: { role: retriever.file_browser, default_effect: read_only }
+  test-path: { role: retriever.file_browser, default_effect: read_only }
+  tree: { role: retriever.file_browser, default_effect: read_only }
+  type: { role: retriever.file_browser, default_effect: read_only }
+  uname: { role: retriever.file_browser, default_effect: read_only }
+  uptime: { role: retriever.file_browser, default_effect: read_only }
+  where: { role: retriever.file_browser, default_effect: read_only }
+  whereis: { role: retriever.file_browser, default_effect: read_only }
+  which: { role: retriever.file_browser, default_effect: read_only }
+  whoami: { role: retriever.file_browser, default_effect: read_only }
+  write-host: { role: retriever.file_browser, default_effect: read_only }
+  write-output: { role: retriever.file_browser, default_effect: read_only }
+
+  # --- Search / text processing ---
+  ag: { role: retriever.search_index, default_effect: read_only }
+  awk: { role: retriever.search_index, default_effect: read_only }
+  comm: { role: retriever.search_index, default_effect: read_only }
+  cut: { role: retriever.search_index, default_effect: read_only }
+  diff: { role: retriever.search_index, default_effect: read_only }
+  egrep: { role: retriever.search_index, default_effect: read_only }
+  fgrep: { role: retriever.search_index, default_effect: read_only }
+  findstr: { role: retriever.search_index, default_effect: read_only }
+  gawk: { role: retriever.search_index, default_effect: read_only }
+  grep: { role: retriever.search_index, default_effect: read_only }
+  jq: { role: retriever.search_index, default_effect: read_only }
+  mawk: { role: retriever.search_index, default_effect: read_only }
+  measure-object: { role: retriever.search_index, default_effect: read_only }
+  nawk: { role: retriever.search_index, default_effect: read_only }
+  out-string: { role: retriever.search_index, default_effect: read_only }
+  paste: { role: retriever.search_index, default_effect: read_only }
+  rg: { role: retriever.search_index, default_effect: read_only }
+  ripgrep: { role: retriever.search_index, default_effect: read_only }
+  sed: { role: retriever.search_index, default_effect: read_only }
+  select-object: { role: retriever.search_index, default_effect: read_only }
+  select-string: { role: retriever.search_index, default_effect: read_only }
+  sort: { role: retriever.search_index, default_effect: read_only }
+  sort-object: { role: retriever.search_index, default_effect: read_only }
+  tr: { role: retriever.search_index, default_effect: read_only }
+  uniq: { role: retriever.search_index, default_effect: read_only }
+  wc: { role: retriever.search_index, default_effect: read_only }
+  where-object: { role: retriever.search_index, default_effect: read_only }
+  yq: { role: retriever.search_index, default_effect: read_only }
+
+  # --- Debuggers / profilers ---
+  gdb: { role: observer.debugger, default_effect: null }
+  lsof: { role: observer.debugger, default_effect: read_only }
+  ltrace: { role: observer.debugger, default_effect: read_only }
+  strace: { role: observer.debugger, default_effect: read_only }
+
+  # --- File editors / modifiers ---
+  add-content: { role: modifier.file_editor, default_effect: mutating }
+  bzip2: { role: modifier.file_editor, default_effect: null }
+  chgrp: { role: modifier.file_editor, default_effect: mutating }
+  chmod: { role: modifier.file_editor, default_effect: mutating }
+  chown: { role: modifier.file_editor, default_effect: mutating }
+  copy: { role: modifier.file_editor, default_effect: mutating }
+  copy-item: { role: modifier.file_editor, default_effect: mutating }
+  cp: { role: modifier.file_editor, default_effect: mutating }
+  cpio: { role: modifier.file_editor, default_effect: null }
+  dd: { role: modifier.file_editor, default_effect: destructive, destructive: true }
+  del: { role: modifier.file_editor, default_effect: destructive, destructive: true }
+  emacs: { role: modifier.file_editor, default_effect: mutating }
+  erase: { role: modifier.file_editor, default_effect: destructive, destructive: true }
+  gunzip: { role: modifier.file_editor, default_effect: null }
+  gzip: { role: modifier.file_editor, default_effect: null }
+  icacls: { role: modifier.file_editor, default_effect: mutating }
+  ln: { role: modifier.file_editor, default_effect: mutating }
+  mkdir: { role: modifier.file_editor, default_effect: mutating }
+  mkfs: { role: modifier.file_editor, default_effect: destructive, destructive: true }
+  mkfs.ext2: { role: modifier.file_editor, default_effect: destructive, destructive: true }
+  mkfs.ext3: { role: modifier.file_editor, default_effect: destructive, destructive: true }
+  mkfs.ext4: { role: modifier.file_editor, default_effect: destructive, destructive: true }
+  mkfs.xfs: { role: modifier.file_editor, default_effect: destructive, destructive: true }
+  mkfs.btrfs: { role: modifier.file_editor, default_effect: destructive, destructive: true }
+  mkfs.vfat: { role: modifier.file_editor, default_effect: destructive, destructive: true }
+  move: { role: modifier.file_editor, default_effect: mutating }
+  move-item: { role: modifier.file_editor, default_effect: mutating }
+  mv: { role: modifier.file_editor, default_effect: mutating }
+  nano: { role: modifier.file_editor, default_effect: mutating }
+  new-item: { role: modifier.file_editor, default_effect: mutating }
+  out-file: { role: modifier.file_editor, default_effect: mutating }
+  patch: { role: modifier.file_editor, default_effect: mutating }
+  rd: { role: modifier.file_editor, default_effect: destructive, destructive: true }
+  remove-item: { role: modifier.file_editor, default_effect: destructive, destructive: true }
+  rename: { role: modifier.file_editor, default_effect: mutating }
+  rename-item: { role: modifier.file_editor, default_effect: mutating }
+  rm: { role: modifier.file_editor, default_effect: destructive, destructive: true }
+  rmdir: { role: modifier.file_editor, default_effect: destructive, destructive: true }
+  rsync: { role: modifier.file_editor, default_effect: mutating, network: true }
+  scp: { role: modifier.file_editor, default_effect: mutating, network: true }
+  set-content: { role: modifier.file_editor, default_effect: mutating }
+  set-itemproperty: { role: modifier.file_editor, default_effect: mutating }
+  tar: { role: modifier.file_editor, default_effect: null }
+  tee: { role: modifier.file_editor, default_effect: mutating }
+  touch: { role: modifier.file_editor, default_effect: mutating }
+  truncate: { role: modifier.file_editor, default_effect: destructive, destructive: true }
+  unzip: { role: modifier.file_editor, default_effect: null }
+  vi: { role: modifier.file_editor, default_effect: mutating }
+  vim: { role: modifier.file_editor, default_effect: mutating }
+  xz: { role: modifier.file_editor, default_effect: null }
+  zip: { role: modifier.file_editor, default_effect: null }