tier2_session_grant.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oc_chat/core/tier2_session_grant.py
 
"""
Session-long Tier-2 grant for python scripts under the work directory (SHELL-02).
 
Purpose
-------
A Tier-2 ``run_command`` is authorised by an out-of-band human ``y``, and that
``y`` covers ONE exact command string ONCE (``shell.human_confirmed_command``).
An agent iterating on a probe script it just wrote therefore raises the same
prompt on every run. The operator, as the M8.1 lock authority, ruled on
2026-09-04 for a DIRECTORY-scoped, session-long grant and explicitly AGAINST a
path-bound one: the agent authors the file it runs, so a path grant is a grant on
any content, and agents rename probe files anyway.
 
Stated plainly, as the operator accepted it: for the rest of the session the
agent can run any Python it writes under ONE directory without a keystroke. Under
``permissive`` that sits beside the already-accepted in-process residual; it is
refused outright under ``guarded``/``isolated``. Everything in this module exists
to keep that reach exactly that wide, visible, and revocable.
 
What a grant does NOT do
------------------------
It never becomes authority of its own. A grant-satisfied call is re-dispatched
under :func:`oc_chat.tools.shell.human_confirmed_command` exactly as an approved
``y`` is, so the ContextVar exact-string contract stays the single authorisation
seam. This module only decides whether the human is ASKED.
 
Responsibilities
----------------
- :func:`active_session_grant` / :func:`grant_work_dir_for_session` /
  :func:`revoke_session_grants` — the process-lifetime grant state.
- :func:`resolve_work_dir` — the grantable directory for a sandbox root
  (``<sandbox_root>/<project_tree.work_dir>``, resolved strictly).
- :func:`session_grant_satisfies` — whether an ACTIVE grant covers this argv.
- :func:`grantable_work_dir` — the directory a grant WOULD cover for this argv,
  i.e. whether the prompt may offer the third key at all.
 
Contracts
---------
- The grant is a resolved DIRECTORY, never a path and never a pattern. It is
  stored resolved and compared with ``Path.relative_to`` on resolved paths, so a
  symlink or junction pointing out of the directory is not covered.
- A command qualifies only when ALL hold: ``argv[0]`` is python/python3/py;
  ``argv[1]`` is a path (never an option) resolving strictly to a regular ``.py``
  file inside the granted directory; the granted directory is still inside the
  effective sandbox root; and the resolved risk profile is ``permissive``.
  Trailing tokens are the script's own argv and add no reach.
- The TTY precondition (§P2) is enforced by the CALLER: the react-loop relay
  fails closed on a missing TTY before it ever consults this module.
- State is process-lifetime and is NEVER persisted to disk or session metadata;
  a fresh process starts with no grant. It is cleared at both seams where F67's
  ``reset_session_trust`` is called.
 
Dependencies
------------
- oc_diagnostics (structured debug logging via _dbg)
- oc_chat.core.risk_profile (lazy; the permissive-only rule)
- oc_chat.core.settings (lazy; the ``work_dir`` name)
- oc_chat.tools._sandbox (lazy; the sandbox containment check)
 
Diagnostics
-----------
Domain: OC_CHAT.CORE
Levels:
    L1 — never (a grant is an operator decision, not a fault)
    L2 — grant / revoke lifecycle events
    L3 — per-decision detail
    L4 — deep tracing
"""
from __future__ import annotations
 
from collections.abc import Sequence
from pathlib import Path
 
from oc_diagnostics import _dbg
 
#: The interpreter basenames a grant may cover. ``pytest``/``oct``/``pip`` are
#: Tier-2 too and are deliberately absent: the grant covers code the agent WROTE
#: in the granted directory, not arbitrary tooling.
PYTHON_PROGRAMS: frozenset[str] = frozenset({"python", "python3", "py"})
 
#: Fallback when settings cannot be read; matches ``DEFAULT_SETTINGS``.
DEFAULT_WORK_DIR = "_work"
 
#: The directory granted for this process, or ``None``. Never persisted.
_SESSION_GRANT_DIR: Path | None = None
 
 
def active_session_grant() -> "Path | None":
    """The resolved directory granted for this session, or ``None``."""
    return _SESSION_GRANT_DIR
 
 
def grant_work_dir_for_session(resolved_dir: Path) -> None:
    """Grant python-on-*resolved_dir* for the rest of this session.
 
    *resolved_dir* must already be resolved and validated by the caller (the
    react-loop offers the third key only for a directory :func:`resolve_work_dir`
    produced), so this is a bare assignment plus its lifecycle diagnostic.
    """
    func = "grant_work_dir_for_session"
    global _SESSION_GRANT_DIR
    _SESSION_GRANT_DIR = resolved_dir
    _dbg("OC_CHAT.CORE", func,
         f"session Tier-2 python grant ACTIVE on {resolved_dir} — scripts there run "
         f"without a keystroke until /grants revoke or the session ends", 2, override=True)
 
 
def revoke_session_grants() -> None:
    """Drop any active grant (``/grants revoke``, and both session-reset seams).
 
    The state is cleared BEFORE the diagnostic, never after: ``_dbg`` raises under
    warnings-as-errors if diagnostics are not initialised yet, and a grant that
    survived its own revocation because a log line failed would be exactly the
    kind of silent authority this module exists to prevent.
    """
    func = "revoke_session_grants"
    global _SESSION_GRANT_DIR
    revoked, _SESSION_GRANT_DIR = _SESSION_GRANT_DIR, None
    if revoked is not None:
        _dbg("OC_CHAT.CORE", func,
             f"session Tier-2 python grant REVOKED (was {revoked})", 2, override=True)
 
 
def _work_dir_name() -> str:
    """The configured scratch-directory name (``project_tree.work_dir``)."""
    func = "_work_dir_name"
    try:
        from oc_chat.core.settings import runtime_settings
        name = str(runtime_settings().project_tree.get("work_dir") or "").strip()
    except Exception as exc:                          # pragma: no cover - defensive
        # EXTERNAL_ERROR (L2): settings are operator data; an unreadable file must
        # narrow the grant to the documented default, never widen it.
        _dbg("OC_CHAT.CORE", func,
             f"EXTERNAL_ERROR: settings unreadable ({exc}); using {DEFAULT_WORK_DIR!r}", 2)
        return DEFAULT_WORK_DIR
    return name or DEFAULT_WORK_DIR
 
 
def resolve_work_dir(sandbox_root: "str | Path") -> "Path | None":
    """The grantable directory under *sandbox_root*, or ``None``.
 
    ``<sandbox_root>/<project_tree.work_dir>`` resolved with ``strict=True`` and
    checked with :func:`~oc_chat.tools._sandbox.require_inside_sandbox`. Returns
    ``None`` when it does not exist, is not a directory, or resolves outside the
    sandbox — in which case the third prompt key is never offered.
    """
    func = "resolve_work_dir"
    from oc_chat.tools._sandbox import SandboxViolation, require_inside_sandbox
 
    root = Path(sandbox_root)
    try:
        candidate = (root / _work_dir_name()).resolve(strict=True)
    except (OSError, RuntimeError, ValueError) as exc:
        _dbg("OC_CHAT.CORE", func, f"no grantable work dir under {root}: {exc}", 3)
        return None
    if not candidate.is_dir():
        _dbg("OC_CHAT.CORE", func, f"work dir is not a directory: {candidate}", 3)
        return None
    try:
        return require_inside_sandbox(candidate, root)
    except SandboxViolation as exc:
        _dbg("OC_CHAT.CORE", func, f"work dir outside the sandbox: {exc}", 3)
        return None
 
 
def _python_program(arg0: str) -> bool:
    """True when *arg0*'s basename is a python interpreter (``.exe`` stripped)."""
    name = Path(arg0).name.lower()
    if name.endswith(".exe"):
        name = name[:-4]
    return name in PYTHON_PROGRAMS
 
 
def _resolved_script(arg: str, sandbox_root: "str | Path") -> "Path | None":
    """*arg* resolved strictly to a regular ``.py`` file, or ``None``.
 
    An OPTION (anything starting with ``-``) is never a script: ``-c`` and ``-m``
    are the two shapes that would turn a directory grant into arbitrary code
    execution, so they are rejected on their leading dash rather than by name.
    A relative path is joined to *sandbox_root*, which is the cwd
    :func:`~oc_chat.tools.shell.run_command` executes in.
    """
    if not arg or arg.startswith("-"):
        return None
    candidate = Path(arg)
    if not candidate.is_absolute():
        candidate = Path(sandbox_root) / candidate
    try:
        resolved = candidate.resolve(strict=True)
    except (OSError, RuntimeError, ValueError):
        return None                                   # missing / unresolvable
    if resolved.suffix.lower() != ".py" or not resolved.is_file():
        return None
    return resolved
 
 
def _qualifies(argv: "Sequence[str]", sandbox_root: "str | Path",
               grant_dir: "Path | None") -> bool:
    """Whether *argv* is ``python <script inside grant_dir>`` under ``permissive``.
 
    The single predicate behind both :func:`session_grant_satisfies` (with the
    ACTIVE grant) and :func:`grantable_work_dir` (with the candidate directory),
    so what a grant would cover and what it does cover cannot drift apart.
    """
    func = "_qualifies"
    if grant_dir is None or len(argv) < 2 or not _python_program(argv[0]):
        return False
 
    from oc_chat.core.risk_profile import resolve_risk_profile
    if resolve_risk_profile() != "permissive":
        _dbg("OC_CHAT.CORE", func, "not permissive — session grants are not consulted", 3)
        return False
 
    # The grant is pinned to the sandbox it was taken in: a later `/sandbox set`
    # leaves the granted directory outside the new root, and it stops applying.
    from oc_chat.tools._sandbox import SandboxViolation, require_inside_sandbox
    try:
        require_inside_sandbox(grant_dir, Path(sandbox_root))
    except SandboxViolation:
        _dbg("OC_CHAT.CORE", func, f"granted dir {grant_dir} is outside the active sandbox", 3)
        return False
 
    script = _resolved_script(argv[1], sandbox_root)
    if script is None:
        return False
    try:
        script.relative_to(grant_dir)
    except ValueError:
        _dbg("OC_CHAT.CORE", func, f"{script} resolves outside {grant_dir}", 3)
        return False
    return True
 
 
def session_grant_satisfies(argv: "Sequence[str]", sandbox_root: "str | Path") -> bool:
    """True when the ACTIVE grant covers *argv* (§P2).
 
    Trailing tokens after the script path are the script's own argv and are not
    examined: the agent authored the script, so its arguments add no reach.
    """
    func = "session_grant_satisfies"
    satisfied = _qualifies(argv, sandbox_root, _SESSION_GRANT_DIR)
    if satisfied:
        _dbg("OC_CHAT.CORE", func,
             f"session grant satisfies {list(argv)[:2]} under {_SESSION_GRANT_DIR}", 3)
    return satisfied
 
 
def grantable_work_dir(argv: "Sequence[str]", sandbox_root: "str | Path") -> "Path | None":
    """The directory the third prompt key would grant for *argv*, or ``None``.
 
    Returns a directory ONLY when *argv* would qualify under a grant on it, so
    the prompt gains its third key exactly when pressing it would help.
    """
    candidate = resolve_work_dir(sandbox_root)
    return candidate if _qualifies(argv, sandbox_root, candidate) else None
 
 
__all__ = [
    "PYTHON_PROGRAMS",
    "DEFAULT_WORK_DIR",
    "active_session_grant",
    "grant_work_dir_for_session",
    "revoke_session_grants",
    "resolve_work_dir",
    "session_grant_satisfies",
    "grantable_work_dir",
]