Option C Tools
Loading...
Searching...
No Matches
oct.mcp.safety Namespace Reference

Classes

class  SafetyDecision
class  SafetyGate

Functions

None _dbg (*args, **kwargs)
str _format_confirmation_request (str tool_name, ToolSpec spec, dict args)

Variables

str HITL_SENTINEL = "[oct-mcp requires_confirmation]"
dict _TOOL_RISK_DESCRIPTIONS

Detailed Description

Purpose
-------
Safety Gate (Layer 2.5) for the ``oct-mcp`` six-layer pipeline.
Enforces the Human-in-the-Loop (HITL) consent protocol for all
write/destructive tool calls, and applies dry-run defaults.

Responsibilities
----------------
- Define :class:`SafetyDecision` — the structured result of a safety
  check (proceed, requires_confirmation, dry_run, reason).
- Define :class:`SafetyGate` with a single :meth:`SafetyGate.check`
  entry point consumed by :func:`oct.mcp.tools._run_tool_write`.
- Define :func:`_format_confirmation_request` which produces the
  structured ``[oct-mcp requires_confirmation] …`` response string
  returned to the AI host when confirmation is needed.

HITL Protocol (D-5B-1 — stateless)
-----------------------------------
No server-side pending state.

- **First call** (``confirm=False``, default): safety gate returns
  ``proceed=False``. The caller returns a
  ``[oct-mcp requires_confirmation] …`` string to the AI host; no
  execution occurs.
- **Second call** (``confirm=True``): safety gate returns
  ``proceed=True``; full execution proceeds.

The AI host re-submits the identical call with ``confirm=True`` after
the user approves in the host UI. There is no replay window to exploit
(T-08) because each call is evaluated independently.

Dry-run rules (D-5B-2, D-5B-5)
--------------------------------
1. Non-destructive tools → always ``proceed=True``, ``dry_run=False``.
2. Destructive, ``confirm=False`` → ``proceed=False``,
   ``requires_confirmation=True``.
3. ``oct_format``, ``confirm=True``, ``apply=False`` → ``proceed=True``,
   ``dry_run=True``.
4. ``oct_format``, ``confirm=True``, ``apply=True`` → ``proceed=True``,
   ``dry_run=False``.
5. Other destructive, ``confirm=True`` → ``proceed=True``,
   ``dry_run=False``.
   (Tools with their own ``dry_run`` field honour that field directly
   — the executor reads it from the validated args dict.)

Diagnostics
-----------
Domain: MCP
Levels:
    L2 — lifecycle: safety decision
    L4 — deep trace: field values

Contracts
---------
- This module does not import ``click``, the MCP SDK, or any
  ``oct.mcp.executor`` / ``oct.mcp.tools`` module (no cycles).
- :meth:`SafetyGate.check` never raises for valid input.
- The confirmation request string always starts with the sentinel
  ``[oct-mcp requires_confirmation]`` so callers can detect it via
  simple prefix matching.

Function Documentation

◆ _dbg()

None oct.mcp.safety._dbg ( * args,
** kwargs )
protected

Definition at line 75 of file safety.py.

Here is the caller graph for this function:

◆ _format_confirmation_request()

str oct.mcp.safety._format_confirmation_request ( str tool_name,
ToolSpec spec,
dict args )
protected 
Return the structured confirmation-required response string.

The string always starts with :data:`HITL_SENTINEL` so callers can
detect it with a prefix check.  The body describes the tool, its
risk, and the args that would be applied.

Parameters
----------
tool_name
    MCP tool name (e.g. ``"oct_format"``).
spec
    The :class:`~oct.mcp.policy.ToolSpec` for this tool.
args
    Validated args dict (``model.model_dump()``).  Shown in the
    confirmation request so the user can review what will happen.

Definition at line 141 of file safety.py.

Variable Documentation

◆ _TOOL_RISK_DESCRIPTIONS

dict oct.mcp.safety._TOOL_RISK_DESCRIPTIONS
protected
Initial value:
1= {
2 "oct_format": "auto-fixes Python formatting in project files",
3 "oct_docs": "generates or removes documentation artifacts",
4 "oct_export_source": "writes consolidated source-code export files",
5 "oct_new": "creates a new Python source file",
6 "oct_scaffold": "creates a new Option C project directory tree",
7 "oct_clean": "removes _source_code-*, _skeleton_code-*, and __pycache__ directories",
8 "oct_install_hooks": "installs pre-commit hooks configuration",
9 "oct_git_commit": "commits staged changes to the git history",
10 "oct_git_hooks_install":"installs git pre-commit hooks",
11 "oct_git_init": "initialises or enhances the git repository configuration",
12 "oct_git_changelog": "writes CHANGELOG.md from commit history",
13}

Definition at line 88 of file safety.py.

◆ HITL_SENTINEL

str oct.mcp.safety.HITL_SENTINEL = "[oct-mcp requires_confirmation]"

Definition at line 85 of file safety.py.