mcp-yieldshell 0.2.0__tar.gz → 0.3.0__tar.gz

{mcp_yieldshell-0.2.0 → mcp_yieldshell-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcp-yieldshell
-Version: 0.2.0
+Version: 0.3.0
 Summary: A drop-in shell MCP that auto-yields long-running commands into managed background processes.
 Requires-Python: >=3.11
 Requires-Dist: mcp<2,>=1.9.0
@@ -144,6 +144,8 @@ Execute a shell command. If the command runs longer than `yield_ms`, it yields a
 
 *   **Parameters**:
     *   `command` (string, **required**): The command string to execute in the shell.
+    *   `side_effects` (array of string, **required**): The side-effect categories this command may plausibly have. Must contain at least one entry drawn from the enum below. Use `["NONE"]` for commands with no meaningful side effects. `NONE` is exclusive and must not be combined with any other category. The server rejects the call with `failed_to_start` if any declared category is configured as blocked.
+        *   Allowed values: `NONE`, `MODIFIES_WORKSPACE_FILES`, `MODIFIES_PROTECTED_FILES`, `MODIFIES_OUTSIDE_WORKSPACE`, `DELETES_FILES`, `INSTALLS_DEPENDENCIES`, `CHANGES_SYSTEM_CONFIGURATION`, `BREAKS_OPERATING_SYSTEM`, `AFFECTS_PRODUCTION_SERVICES`, `STOPS_OR_RESTARTS_SERVICES`, `EXPOSES_SECRETS`, `CREATES_SECURITY_RISK`, `CHANGES_NETWORK_CONFIGURATION`, `MAKES_NETWORK_REQUESTS`, `RUNS_PRIVILEGED_COMMANDS`, `USES_DESTRUCTIVE_GIT_OPERATION`, `CONSUMES_SIGNIFICANT_RESOURCES`, `OTHER`, `UNKNOWN`.
     *   `cwd` (string, optional): Working directory for the command. Must be under allowed roots if `YIELDSHELL_ALLOWED_CWDS` is set. Defaults to `YIELDSHELL_DEFAULT_CWD`.
     *   `env` (object of string to string, optional): Additive environment variable overlay. Merged into the parent environment.
     *   `shell` (string, optional): Accepted but has no effect in v1. Commands always run via the platform's default shell.
@@ -253,12 +255,14 @@ Configure the server by setting these environment variables prior to launch:
 | `YIELDSHELL_DENY_COMMAND_REGEX` | *(none)* | A regular expression pattern. Commands matching this pattern are blocked before starting. |
 | `YIELDSHELL_ALLOW_COMMAND_REGEX` | *(none)* | A regular expression pattern. If set, only commands matching this pattern are permitted. |
 | `YIELDSHELL_REDACT_ENV_REGEX` | `TOKEN\|KEY\|SECRET\|PASSWORD` | Regex to identify sensitive environment variable keys. Their values are redacted in stdout/stderr outputs. |
+| `MCP_YIELDSHELL_BLOCKED_SIDE_EFFECTS` | `MODIFIES_PROTECTED_FILES,BREAKS_OPERATING_SYSTEM` | Comma-separated list of `side_effects` enum names the server should reject. Names are case-sensitive. Surrounding whitespace is trimmed and empty entries are ignored. Invalid names cause startup to fail. Set to `,` (or any value that resolves to no entries) to clear the default blocklist. |
 
 ---
 
 ## Security Notes
 
 *   **Arbitrary Code Execution**: This server executes shell commands on the host system. Always run the server inside a container, sandbox, or isolated development VM.
+*   **Side-Effect Declarations**: Every `exec` call must declare its plausible side-effect categories via `side_effects`. By default, `MODIFIES_PROTECTED_FILES` and `BREAKS_OPERATING_SYSTEM` are blocked. Operators can adjust the blocklist via `MCP_YIELDSHELL_BLOCKED_SIDE_EFFECTS`. This is an explicit risk signal — it is not a complete sandbox, and LLM under-declaration remains possible.
 *   **Path Validation**: CWD path verification uses absolute paths (`resolve()`), preventing path-traversal attacks (`../`) outside the allowed roots.
 *   **Additive Environments**: The `env` argument overlays existing env parameters. It merges with the parent process environment instead of completely replacing it, protecting critical OS vars.
 *   **Best-effort Redaction**: While values of variables matching `YIELDSHELL_REDACT_ENV_REGEX` are scrubbed from outputs, this is a best-effort system. Sensitive data printed through complex formats or argument lists might not be caught.

{mcp_yieldshell-0.2.0 → mcp_yieldshell-0.3.0}/README.md

@@ -136,6 +136,8 @@ Execute a shell command. If the command runs longer than `yield_ms`, it yields a
 
 *   **Parameters**:
     *   `command` (string, **required**): The command string to execute in the shell.
+    *   `side_effects` (array of string, **required**): The side-effect categories this command may plausibly have. Must contain at least one entry drawn from the enum below. Use `["NONE"]` for commands with no meaningful side effects. `NONE` is exclusive and must not be combined with any other category. The server rejects the call with `failed_to_start` if any declared category is configured as blocked.
+        *   Allowed values: `NONE`, `MODIFIES_WORKSPACE_FILES`, `MODIFIES_PROTECTED_FILES`, `MODIFIES_OUTSIDE_WORKSPACE`, `DELETES_FILES`, `INSTALLS_DEPENDENCIES`, `CHANGES_SYSTEM_CONFIGURATION`, `BREAKS_OPERATING_SYSTEM`, `AFFECTS_PRODUCTION_SERVICES`, `STOPS_OR_RESTARTS_SERVICES`, `EXPOSES_SECRETS`, `CREATES_SECURITY_RISK`, `CHANGES_NETWORK_CONFIGURATION`, `MAKES_NETWORK_REQUESTS`, `RUNS_PRIVILEGED_COMMANDS`, `USES_DESTRUCTIVE_GIT_OPERATION`, `CONSUMES_SIGNIFICANT_RESOURCES`, `OTHER`, `UNKNOWN`.
     *   `cwd` (string, optional): Working directory for the command. Must be under allowed roots if `YIELDSHELL_ALLOWED_CWDS` is set. Defaults to `YIELDSHELL_DEFAULT_CWD`.
     *   `env` (object of string to string, optional): Additive environment variable overlay. Merged into the parent environment.
     *   `shell` (string, optional): Accepted but has no effect in v1. Commands always run via the platform's default shell.
@@ -245,12 +247,14 @@ Configure the server by setting these environment variables prior to launch:
 | `YIELDSHELL_DENY_COMMAND_REGEX` | *(none)* | A regular expression pattern. Commands matching this pattern are blocked before starting. |
 | `YIELDSHELL_ALLOW_COMMAND_REGEX` | *(none)* | A regular expression pattern. If set, only commands matching this pattern are permitted. |
 | `YIELDSHELL_REDACT_ENV_REGEX` | `TOKEN\|KEY\|SECRET\|PASSWORD` | Regex to identify sensitive environment variable keys. Their values are redacted in stdout/stderr outputs. |
+| `MCP_YIELDSHELL_BLOCKED_SIDE_EFFECTS` | `MODIFIES_PROTECTED_FILES,BREAKS_OPERATING_SYSTEM` | Comma-separated list of `side_effects` enum names the server should reject. Names are case-sensitive. Surrounding whitespace is trimmed and empty entries are ignored. Invalid names cause startup to fail. Set to `,` (or any value that resolves to no entries) to clear the default blocklist. |
 
 ---
 
 ## Security Notes
 
 *   **Arbitrary Code Execution**: This server executes shell commands on the host system. Always run the server inside a container, sandbox, or isolated development VM.
+*   **Side-Effect Declarations**: Every `exec` call must declare its plausible side-effect categories via `side_effects`. By default, `MODIFIES_PROTECTED_FILES` and `BREAKS_OPERATING_SYSTEM` are blocked. Operators can adjust the blocklist via `MCP_YIELDSHELL_BLOCKED_SIDE_EFFECTS`. This is an explicit risk signal — it is not a complete sandbox, and LLM under-declaration remains possible.
 *   **Path Validation**: CWD path verification uses absolute paths (`resolve()`), preventing path-traversal attacks (`../`) outside the allowed roots.
 *   **Additive Environments**: The `env` argument overlays existing env parameters. It merges with the parent process environment instead of completely replacing it, protecting critical OS vars.
 *   **Best-effort Redaction**: While values of variables matching `YIELDSHELL_REDACT_ENV_REGEX` are scrubbed from outputs, this is a best-effort system. Sensitive data printed through complex formats or argument lists might not be caught.

{mcp_yieldshell-0.2.0 → mcp_yieldshell-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mcp-yieldshell"
-version = "0.2.0"
+version = "0.3.0"
 description = "A drop-in shell MCP that auto-yields long-running commands into managed background processes."
 readme = "README.md"
 requires-python = ">=3.11"

{mcp_yieldshell-0.2.0 → mcp_yieldshell-0.3.0}/src/mcp_yieldshell/config.py

@@ -5,6 +5,8 @@ from __future__ import annotations
 import os
 import re
 
+from .types import DEFAULT_BLOCKED_SIDE_EFFECTS, SideEffect
+
 
 class Config:
     def __init__(self) -> None:
@@ -37,6 +39,9 @@ class Config:
             os.environ.get("YIELDSHELL_REDACT_ENV_REGEX", ""),
             r"TOKEN|KEY|SECRET|PASSWORD",
         )
+        self.blocked_side_effects: frozenset[SideEffect] = _parse_blocked_side_effects(
+            os.environ.get("MCP_YIELDSHELL_BLOCKED_SIDE_EFFECTS", "")
+        )
 
 
 def _parse_pathsep(value: str) -> list[str]:
@@ -64,3 +69,35 @@ def _parse_regex_required(value: str, default: str) -> re.Pattern[str]:
     if not value:
         return re.compile(default)
     return re.compile(value)
+
+
+def _parse_blocked_side_effects(value: str) -> frozenset[SideEffect]:
+    """Parse ``MCP_YIELDSHELL_BLOCKED_SIDE_EFFECTS`` into a frozenset.
+
+    Empty entries are ignored. Surrounding whitespace is trimmed. Names are
+    case-sensitive. Invalid names raise ``ValueError`` with a clear message.
+    """
+    if value is None or not value.strip():
+        return DEFAULT_BLOCKED_SIDE_EFFECTS
+
+    valid_names = {member.name for member in SideEffect}
+    blocked: set[SideEffect] = set()
+    invalid: list[str] = []
+    for entry in value.split(","):
+        name = entry.strip()
+        if not name:
+            continue
+        if name in valid_names:
+            blocked.add(SideEffect[name])
+        else:
+            invalid.append(name)
+
+    if invalid:
+        names_list = ", ".join(repr(n) for n in invalid)
+        valid_list = ", ".join(sorted(valid_names))
+        raise ValueError(
+            f"MCP_YIELDSHELL_BLOCKED_SIDE_EFFECTS contains invalid value(s): "
+            f"{names_list}. Valid values (case-sensitive): {valid_list}."
+        )
+
+    return frozenset(blocked)

{mcp_yieldshell-0.2.0 → mcp_yieldshell-0.3.0}/src/mcp_yieldshell/process/manager.py

@@ -7,11 +7,11 @@ import os
 import sys
 import time
 import uuid
-from typing import Any
+from typing import Any, Iterable
 
 from ..config import Config
 from ..security import redact_text
-from ..types import ProcessInfo, ProcessStatus
+from ..types import ProcessInfo, ProcessStatus, SideEffect
 from .ring_buffer import RingBuffer
 from .spawn import kill_process, spawn_process, terminate_process
 
@@ -81,9 +81,74 @@ class ProcessManager:
             return self._config.default_timeout_ms
         return max(0, requested)
 
+    def _normalize_side_effects(
+        self, side_effects: Iterable[Any] | None
+    ) -> list[SideEffect] | None:
+        """Coerce ``side_effects`` entries into ``SideEffect`` enum members.
+
+        Accepts ``SideEffect`` instances or strings. Returns ``None`` when
+        ``side_effects`` itself is ``None``. Raises ``TypeError`` when an
+        entry is not a string and not a ``SideEffect``.
+        """
+        if side_effects is None:
+            return None
+        normalized: list[SideEffect] = []
+        for item in side_effects:
+            if isinstance(item, SideEffect):
+                normalized.append(item)
+            elif isinstance(item, str):
+                normalized.append(SideEffect(item))
+            else:
+                raise TypeError(
+                    f"side_effects entries must be SideEffect or str, got {type(item).__name__}"
+                )
+        return normalized
+
+    def _check_side_effects(
+        self, side_effects: Iterable[SideEffect] | None
+    ) -> str | None:
+        """Validate the side-effect declaration.
+
+        Returns an error message if the declaration is invalid (empty list,
+        ``NONE`` combined with another value, or any declared category is
+        configured as blocked). Returns ``None`` when the declaration is
+        allowed and execution can proceed.
+        """
+        try:
+            declared = self._normalize_side_effects(side_effects)
+        except ValueError as exc:
+            return f"Invalid side_effects: {exc}"
+        except TypeError as exc:
+            return str(exc)
+        if declared is None:
+            return "side_effects is required"
+        if not declared:
+            return (
+                'side_effects must not be empty; pass ["NONE"] for commands '
+                "with no side effects"
+            )
+        has_none = SideEffect.NONE in declared
+        non_none = [s for s in declared if s is not SideEffect.NONE]
+        if has_none and non_none:
+            return (
+                "side_effects=NONE is exclusive and cannot be combined with other "
+                f"categories: {[s.name for s in non_none]}"
+            )
+
+        blocked = self._config.blocked_side_effects
+        hits = [s for s in declared if s in blocked]
+        if hits:
+            names = ", ".join(s.name for s in hits)
+            return (
+                f"Side-effect category blocked by policy: {names}. "
+                "Re-declare with an allowed category or update operator policy."
+            )
+        return None
+
     async def exec_command(
         self,
         command: str,
+        side_effects: list[SideEffect] | Iterable[SideEffect],
         cwd: str | None = None,
         env_overlay: dict[str, str] | None = None,
         shell: str | None = None,
@@ -93,9 +158,21 @@ class ProcessManager:
         timeout_ms: int | None = None,
         max_output_bytes: int | None = None,
     ) -> dict[str, Any]:
-        """Execute a shell command with auto-yield behavior."""
+        """Execute a shell command with auto-yield behavior.
+
+        The ``side_effects`` declaration is validated before any cwd or command
+        policy check, before process-limit checks, before environment overlay
+        construction, and before subprocess spawn.
+        """
         from ..security import build_env, resolve_cwd, validate_command
 
+        # Validate side-effect declaration first so blocked categories never
+        # reach cwd resolution, command policy, process limits, env overlay
+        # building, or process spawn.
+        side_effects_error = self._check_side_effects(side_effects)
+        if side_effects_error:
+            return {"status": "failed_to_start", "error": side_effects_error}
+
         # Validate command policy
         cmd_error = validate_command(self._config, command)
         if cmd_error:

{mcp_yieldshell-0.2.0 → mcp_yieldshell-0.3.0}/src/mcp_yieldshell/server.py

@@ -6,6 +6,7 @@ from mcp.server.fastmcp import FastMCP
 
 from .config import Config
 from .process.manager import ProcessManager
+from .types import SideEffect
 
 mcp = FastMCP("YieldShell MCP")
 
@@ -22,6 +23,7 @@ def _get_manager() -> ProcessManager:
 @mcp.tool()
 async def exec(
     command: str,
+    side_effects: list[SideEffect],
     cwd: str | None = None,
     env: dict[str, str] | None = None,
     shell: str | None = None,
@@ -31,9 +33,17 @@ async def exec(
     timeout_ms: int | None = None,
     max_output_bytes: int | None = None,
 ) -> dict:
-    """Execute a shell command with auto-yield for long-running processes."""
+    """Execute a shell command with auto-yield for long-running processes.
+
+    Callers must declare every plausible side effect category in ``side_effects``.
+    If no meaningful side effect is expected, pass ``[SideEffect.NONE]`` or
+    ``["NONE"]``. ``NONE`` is exclusive and must not be combined with any other
+    category. The server rejects the command before spawning a process if any
+    declared category is configured as blocked.
+    """
     return await _get_manager().exec_command(
         command=command,
+        side_effects=side_effects,
         cwd=cwd,
         env_overlay=env,
         shell=shell,

mcp_yieldshell-0.3.0/src/mcp_yieldshell/types.py

@@ -0,0 +1,65 @@
+"""Types for process status, tool response shapes, and side-effect taxonomy."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+
+
+class ProcessStatus(str, Enum):
+    RUNNING = "running"
+    COMPLETED = "completed"
+    STOPPED = "stopped"
+    TIMED_OUT = "timed_out"
+    FAILED = "failed"
+
+
+class SideEffect(str, Enum):
+    """Taxonomy of side effects a shell command may plausibly have.
+
+    Callers of ``exec_command`` must declare every category that plausibly
+    applies. If no meaningful side effect is expected, callers must pass
+    ``[SideEffect.NONE]``. ``NONE`` is exclusive and must not be combined
+    with any other category.
+    """
+
+    NONE = "NONE"
+    MODIFIES_WORKSPACE_FILES = "MODIFIES_WORKSPACE_FILES"
+    MODIFIES_PROTECTED_FILES = "MODIFIES_PROTECTED_FILES"
+    MODIFIES_OUTSIDE_WORKSPACE = "MODIFIES_OUTSIDE_WORKSPACE"
+    DELETES_FILES = "DELETES_FILES"
+    INSTALLS_DEPENDENCIES = "INSTALLS_DEPENDENCIES"
+    CHANGES_SYSTEM_CONFIGURATION = "CHANGES_SYSTEM_CONFIGURATION"
+    BREAKS_OPERATING_SYSTEM = "BREAKS_OPERATING_SYSTEM"
+    AFFECTS_PRODUCTION_SERVICES = "AFFECTS_PRODUCTION_SERVICES"
+    STOPS_OR_RESTARTS_SERVICES = "STOPS_OR_RESTARTS_SERVICES"
+    EXPOSES_SECRETS = "EXPOSES_SECRETS"
+    CREATES_SECURITY_RISK = "CREATES_SECURITY_RISK"
+    CHANGES_NETWORK_CONFIGURATION = "CHANGES_NETWORK_CONFIGURATION"
+    MAKES_NETWORK_REQUESTS = "MAKES_NETWORK_REQUESTS"
+    RUNS_PRIVILEGED_COMMANDS = "RUNS_PRIVILEGED_COMMANDS"
+    USES_DESTRUCTIVE_GIT_OPERATION = "USES_DESTRUCTIVE_GIT_OPERATION"
+    CONSUMES_SIGNIFICANT_RESOURCES = "CONSUMES_SIGNIFICANT_RESOURCES"
+    OTHER = "OTHER"
+    UNKNOWN = "UNKNOWN"
+
+
+DEFAULT_BLOCKED_SIDE_EFFECTS: frozenset[SideEffect] = frozenset(
+    {SideEffect.MODIFIES_PROTECTED_FILES, SideEffect.BREAKS_OPERATING_SYSTEM}
+)
+
+
+@dataclass
+class ProcessInfo:
+    process_id: str
+    pid: int | None
+    command: str
+    cwd: str
+    name: str | None
+    status: ProcessStatus
+    exit_code: int | None = None
+    signal: str | None = None
+    started_at: float = 0.0
+    ended_at: float | None = None
+    duration_ms: float = 0.0
+    start_monotonic: float = 0.0

mcp_yieldshell-0.3.0/tests/test_config.py

@@ -0,0 +1,220 @@
+"""Unit tests for configuration parsing."""
+
+import os
+
+import pytest
+
+from mcp_yieldshell.config import Config
+from mcp_yieldshell.types import DEFAULT_BLOCKED_SIDE_EFFECTS, SideEffect
+
+
+class TestConfigDefaults:
+    def test_default_cwd(self):
+        config = Config()
+        assert config.default_cwd == os.getcwd()
+
+    def test_default_max_output_bytes(self):
+        config = Config()
+        assert config.max_output_bytes == 20000
+
+    def test_default_max_processes(self):
+        config = Config()
+        assert config.max_processes == 50
+
+    def test_default_yield_ms(self):
+        config = Config()
+        assert config.default_yield_ms == 5000
+
+    def test_default_max_yield_ms(self):
+        config = Config()
+        assert config.max_yield_ms == 300000
+
+    def test_default_timeout_ms(self):
+        config = Config()
+        assert config.default_timeout_ms == 0
+
+    def test_empty_allowed_cwds(self):
+        config = Config()
+        assert config.allowed_cwd_roots == []
+
+    def test_none_deny_regex(self):
+        config = Config()
+        assert config.deny_command_regex is None
+
+    def test_none_allow_regex(self):
+        config = Config()
+        assert config.allow_command_regex is None
+
+    def test_default_redact_regex(self):
+        config = Config()
+        assert config.redact_env_regex is not None
+        assert config.redact_env_regex.search("MY_TOKEN")
+        assert config.redact_env_regex.search("API_KEY")
+        assert config.redact_env_regex.search("MY_SECRET")
+        assert config.redact_env_regex.search("DB_PASSWORD")
+
+
+class TestConfigFromEnv:
+    def test_custom_max_output_bytes(self, monkeypatch):
+        monkeypatch.setenv("YIELDSHELL_MAX_OUTPUT_BYTES", "5000")
+        config = Config()
+        assert config.max_output_bytes == 5000
+
+    def test_custom_max_processes(self, monkeypatch):
+        monkeypatch.setenv("YIELDSHELL_MAX_PROCESSES", "10")
+        config = Config()
+        assert config.max_processes == 10
+
+    def test_custom_default_yield_ms(self, monkeypatch):
+        monkeypatch.setenv("YIELDSHELL_DEFAULT_YIELD_MS", "2000")
+        config = Config()
+        assert config.default_yield_ms == 2000
+
+    def test_deny_command_regex(self, monkeypatch):
+        monkeypatch.setenv("YIELDSHELL_DENY_COMMAND_REGEX", r"rm\s+-rf")
+        config = Config()
+        assert config.deny_command_regex is not None
+        assert config.deny_command_regex.search("rm -rf /")
+        assert not config.deny_command_regex.search("ls -la")
+
+    def test_allow_command_regex(self, monkeypatch):
+        monkeypatch.setenv("YIELDSHELL_ALLOW_COMMAND_REGEX", r"^git\s+")
+        config = Config()
+        assert config.allow_command_regex is not None
+        assert config.allow_command_regex.search("git status")
+        assert not config.allow_command_regex.search("ls -la")
+
+    def test_allowed_cwds(self, monkeypatch):
+        monkeypatch.setenv("YIELDSHELL_ALLOWED_CWDS", "/tmp:/home")
+        config = Config()
+        assert len(config.allowed_cwd_roots) == 2
+
+    def test_invalid_int_uses_default(self, monkeypatch):
+        monkeypatch.setenv("YIELDSHELL_MAX_PROCESSES", "abc")
+        config = Config()
+        assert config.max_processes == 50
+
+
+class TestBlockedSideEffectsDefaults:
+    def test_unset_uses_default_blocked_set(self, monkeypatch):
+        monkeypatch.delenv("MCP_YIELDSHELL_BLOCKED_SIDE_EFFECTS", raising=False)
+        config = Config()
+        assert config.blocked_side_effects == DEFAULT_BLOCKED_SIDE_EFFECTS
+
+    def test_unset_default_blocks_modifies_protected_files(self, monkeypatch):
+        monkeypatch.delenv("MCP_YIELDSHELL_BLOCKED_SIDE_EFFECTS", raising=False)
+        config = Config()
+        assert SideEffect.MODIFIES_PROTECTED_FILES in config.blocked_side_effects
+
+    def test_unset_default_blocks_breaks_operating_system(self, monkeypatch):
+        monkeypatch.delenv("MCP_YIELDSHELL_BLOCKED_SIDE_EFFECTS", raising=False)
+        config = Config()
+        assert SideEffect.BREAKS_OPERATING_SYSTEM in config.blocked_side_effects
+
+    def test_empty_string_uses_default_blocked_set(self, monkeypatch):
+        monkeypatch.setenv("MCP_YIELDSHELL_BLOCKED_SIDE_EFFECTS", "")
+        config = Config()
+        assert config.blocked_side_effects == DEFAULT_BLOCKED_SIDE_EFFECTS
+
+    def test_whitespace_only_uses_default_blocked_set(self, monkeypatch):
+        monkeypatch.setenv("MCP_YIELDSHELL_BLOCKED_SIDE_EFFECTS", "   ")
+        config = Config()
+        assert config.blocked_side_effects == DEFAULT_BLOCKED_SIDE_EFFECTS
+
+
+class TestBlockedSideEffectsFromEnv:
+    def test_single_value_parsed(self, monkeypatch):
+        monkeypatch.setenv(
+            "MCP_YIELDSHELL_BLOCKED_SIDE_EFFECTS", "DELETES_FILES"
+        )
+        config = Config()
+        assert config.blocked_side_effects == frozenset({SideEffect.DELETES_FILES})
+
+    def test_multiple_values_parsed(self, monkeypatch):
+        monkeypatch.setenv(
+            "MCP_YIELDSHELL_BLOCKED_SIDE_EFFECTS",
+            "DELETES_FILES,MAKES_NETWORK_REQUESTS,INSTALLS_DEPENDENCIES",
+        )
+        config = Config()
+        assert config.blocked_side_effects == frozenset(
+            {
+                SideEffect.DELETES_FILES,
+                SideEffect.MAKES_NETWORK_REQUESTS,
+                SideEffect.INSTALLS_DEPENDENCIES,
+            }
+        )
+
+    def test_whitespace_trimmed(self, monkeypatch):
+        monkeypatch.setenv(
+            "MCP_YIELDSHELL_BLOCKED_SIDE_EFFECTS",
+            "  DELETES_FILES  ,\t MAKES_NETWORK_REQUESTS \t",
+        )
+        config = Config()
+        assert config.blocked_side_effects == frozenset(
+            {SideEffect.DELETES_FILES, SideEffect.MAKES_NETWORK_REQUESTS}
+        )
+
+    def test_empty_entries_ignored(self, monkeypatch):
+        monkeypatch.setenv(
+            "MCP_YIELDSHELL_BLOCKED_SIDE_EFFECTS",
+            ",,DELETES_FILES, ,,",
+        )
+        config = Config()
+        assert config.blocked_side_effects == frozenset({SideEffect.DELETES_FILES})
+
+    def test_can_clear_blocked_categories(self, monkeypatch):
+        monkeypatch.setenv("MCP_YIELDSHELL_BLOCKED_SIDE_EFFECTS", ",")
+        config = Config()
+        assert config.blocked_side_effects == frozenset()
+
+    def test_override_default_to_unblock_modifies_protected_files(self, monkeypatch):
+        monkeypatch.setenv(
+            "MCP_YIELDSHELL_BLOCKED_SIDE_EFFECTS", "BREAKS_OPERATING_SYSTEM"
+        )
+        config = Config()
+        assert config.blocked_side_effects == frozenset(
+            {SideEffect.BREAKS_OPERATING_SYSTEM}
+        )
+
+
+class TestBlockedSideEffectsInvalid:
+    def test_lowercase_value_fails_clearly(self, monkeypatch):
+        monkeypatch.setenv(
+            "MCP_YIELDSHELL_BLOCKED_SIDE_EFFECTS", "modifies_protected_files"
+        )
+        with pytest.raises(ValueError) as excinfo:
+            Config()
+        message = str(excinfo.value)
+        assert "modifies_protected_files" in message
+        assert "MCP_YIELDSHELL_BLOCKED_SIDE_EFFECTS" in message
+        assert "case-sensitive" in message
+
+    def test_typo_value_fails_clearly(self, monkeypatch):
+        monkeypatch.setenv(
+            "MCP_YIELDSHELL_BLOCKED_SIDE_EFFECTS", "DELETES_FILE"
+        )
+        with pytest.raises(ValueError) as excinfo:
+            Config()
+        message = str(excinfo.value)
+        assert "DELETES_FILE" in message
+        assert "DELETES_FILES" in message  # listed in the valid set
+
+    def test_completely_unknown_value_fails_clearly(self, monkeypatch):
+        monkeypatch.setenv(
+            "MCP_YIELDSHELL_BLOCKED_SIDE_EFFECTS", "TELEPORT_COWS"
+        )
+        with pytest.raises(ValueError) as excinfo:
+            Config()
+        message = str(excinfo.value)
+        assert "TELEPORT_COWS" in message
+        assert "Valid values" in message
+
+    def test_mixed_valid_and_invalid_fails_clearly(self, monkeypatch):
+        monkeypatch.setenv(
+            "MCP_YIELDSHELL_BLOCKED_SIDE_EFFECTS",
+            "DELETES_FILES,TELEPORT_COWS,MAKES_NETWORK_REQUESTS",
+        )
+        with pytest.raises(ValueError) as excinfo:
+            Config()
+        message = str(excinfo.value)
+        assert "TELEPORT_COWS" in message