bareagent-cli 0.1.0__py3-none-any.whl

bareagent/memory/token_tracker.py

@@ -0,0 +1,262 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+# Built-in prices for the project's default Claude models, in USD per million
+# tokens (input, output). DEFAULT_PRICES is a fallback only — prices drift, so
+# the authoritative source is the user's [cost.prices] config, which overrides
+# and extends these. Prefix-matched (startswith) so dated model ids such as
+# "claude-opus-4-8-20251101" still resolve to the family price.
+#
+# NOTE: prices are reference values as of 2026-06 and MAY CHANGE; override them
+# via [cost.prices] in config.toml / config.local.toml to keep them accurate.
+DEFAULT_PRICES: dict[str, tuple[float, float]] = {
+    "claude-opus-4": (15.0, 75.0),
+    "claude-sonnet-4": (3.0, 15.0),
+    "claude-haiku-4": (1.0, 5.0),
+}
+
+# Prompt-cache price multipliers relative to a model's base *input* price,
+# keyed by model-family prefix (longest-prefix matched like DEFAULT_PRICES):
+# ``(read_multiplier, write_multiplier)``.
+#   - Anthropic: read 0.1x, write 1.25x (5m TTL; 1h's 2x is approximated as
+#     1.25x — see PRD Out of Scope, estimate-only).
+#   - OpenAI: cached input billed ~0.5x, no separate write premium.
+#   - DeepSeek: cache hits ~0.1x, no separate write premium.
+# Unknown models fall back to the Anthropic-like default (0.1, 1.25); cache
+# tokens are only ever populated for providers covered here, so the fallback is
+# a conservative estimate, never load-bearing.
+DEFAULT_CACHE_MULTIPLIERS: dict[str, tuple[float, float]] = {
+    "claude": (0.1, 1.25),
+    "gpt": (0.5, 0.0),
+    "o1": (0.5, 0.0),
+    "o3": (0.5, 0.0),
+    "o4": (0.5, 0.0),
+    "deepseek": (0.1, 0.0),
+}
+_FALLBACK_CACHE_MULTIPLIERS: tuple[float, float] = (0.1, 1.25)
+
+# Built-in prices are expressed per *million* tokens; convert to per-token.
+_PER_MILLION = 1_000_000
+
+
+def resolve_cache_multipliers(model: str) -> tuple[float, float]:
+    """Resolve ``(read_mult, write_mult)`` cache price multipliers for *model*.
+
+    Longest-prefix match against :data:`DEFAULT_CACHE_MULTIPLIERS`, falling back
+    to an Anthropic-like default when the family is unknown.
+    """
+    prefix = _longest_prefix_match(model, DEFAULT_CACHE_MULTIPLIERS.keys())
+    if prefix is not None:
+        return DEFAULT_CACHE_MULTIPLIERS[prefix]
+    return _FALLBACK_CACHE_MULTIPLIERS
+
+
+def resolve_price(
+    model: str,
+    prices: dict[str, dict[str, float]] | None,
+) -> tuple[float, float] | None:
+    """Resolve (input, output) price per million tokens for *model*.
+
+    Lookup order:
+    1. User-configured ``prices`` — exact match wins, then longest prefix match.
+    2. Built-in :data:`DEFAULT_PRICES` — longest prefix match.
+
+    Returns ``None`` when no price is known (the caller shows token counts only,
+    never a fabricated cost).
+    """
+    if prices:
+        exact = prices.get(model)
+        if exact is not None:
+            resolved = _coerce_price_entry(exact)
+            if resolved is not None:
+                return resolved
+        prefix_match = _longest_prefix_match(model, prices.keys())
+        if prefix_match is not None:
+            resolved = _coerce_price_entry(prices[prefix_match])
+            if resolved is not None:
+                return resolved
+
+    builtin_prefix = _longest_prefix_match(model, DEFAULT_PRICES.keys())
+    if builtin_prefix is not None:
+        return DEFAULT_PRICES[builtin_prefix]
+    return None
+
+
+def _longest_prefix_match(model: str, keys: Any) -> str | None:
+    """Return the longest key in *keys* that is a prefix of *model*."""
+    best: str | None = None
+    for key in keys:
+        if model.startswith(key) and (best is None or len(key) > len(best)):
+            best = key
+    return best
+
+
+def _coerce_price_entry(entry: dict[str, float]) -> tuple[float, float] | None:
+    """Coerce a ``{input, output}`` config dict into an (input, output) tuple."""
+    if not isinstance(entry, dict):
+        return None
+    try:
+        return float(entry["input"]), float(entry["output"])
+    except (KeyError, TypeError, ValueError):
+        return None
+
+
+@dataclass(slots=True)
+class _ModelUsage:
+    input_tokens: int = 0
+    output_tokens: int = 0
+    cache_read_tokens: int = 0
+    cache_write_tokens: int = 0
+    call_count: int = 0
+
+
+@dataclass(slots=True)
+class TokenTracker:
+    """Process-level accumulator for LLM token usage during a session.
+
+    Records ``input_tokens`` / ``output_tokens`` from each :class:`LLMResponse`
+    plus a per-model breakdown. Pure logic with no I/O so it is unit-testable in
+    isolation. Reset on session boundaries (``/new`` / ``/clear`` / ``/resume``)
+    but not on in-session compaction (``/compact``).
+    """
+
+    total_input: int = 0
+    total_output: int = 0
+    total_cache_read: int = 0
+    total_cache_write: int = 0
+    call_count: int = 0
+    per_model: dict[str, _ModelUsage] = field(default_factory=dict)
+
+    @property
+    def total_tokens(self) -> int:
+        return self.total_input + self.total_output + self.total_cache_read + self.total_cache_write
+
+    def record(self, response: Any, model: str) -> None:
+        """Accumulate one LLM response's token usage under *model*.
+
+        Reads only the normalized usage fields off the response so it never
+        couples to a specific provider's wire shape. ``input_tokens`` is the
+        full-price remainder; cache read/write are additive and non-overlapping
+        (see ``LLMResponse``), so summing all four gives the true prompt size.
+        """
+        input_tokens = int(getattr(response, "input_tokens", 0) or 0)
+        output_tokens = int(getattr(response, "output_tokens", 0) or 0)
+        cache_read = int(getattr(response, "cache_read_input_tokens", 0) or 0)
+        cache_write = int(getattr(response, "cache_creation_input_tokens", 0) or 0)
+
+        self.total_input += input_tokens
+        self.total_output += output_tokens
+        self.total_cache_read += cache_read
+        self.total_cache_write += cache_write
+        self.call_count += 1
+
+        usage = self.per_model.get(model)
+        if usage is None:
+            usage = _ModelUsage()
+            self.per_model[model] = usage
+        usage.input_tokens += input_tokens
+        usage.output_tokens += output_tokens
+        usage.cache_read_tokens += cache_read
+        usage.cache_write_tokens += cache_write
+        usage.call_count += 1
+
+    def reset(self) -> None:
+        """Clear all accumulated usage (session boundary)."""
+        self.total_input = 0
+        self.total_output = 0
+        self.total_cache_read = 0
+        self.total_cache_write = 0
+        self.call_count = 0
+        self.per_model.clear()
+
+    def estimate_cost(
+        self,
+        prices: dict[str, dict[str, float]] | None,
+    ) -> float | None:
+        """Estimate total cost in USD across all priced models.
+
+        Models without a known price are skipped (their tokens still count, but
+        contribute no dollars). Returns ``None`` only when *no* recorded model
+        has a price, so the caller can suppress the ``$`` line entirely rather
+        than print ``$0.00``.
+        """
+        total = 0.0
+        any_priced = False
+        for model, usage in self.per_model.items():
+            price = resolve_price(model, prices)
+            if price is None:
+                continue
+            any_priced = True
+            input_price, output_price = price
+            read_mult, write_mult = resolve_cache_multipliers(model)
+            total += usage.input_tokens / _PER_MILLION * input_price
+            total += usage.output_tokens / _PER_MILLION * output_price
+            total += usage.cache_read_tokens / _PER_MILLION * input_price * read_mult
+            total += usage.cache_write_tokens / _PER_MILLION * input_price * write_mult
+        return total if any_priced else None
+
+    def summary(self, prices: dict[str, dict[str, float]] | None) -> str:
+        """Render a human-readable usage summary for the ``/cost`` command.
+
+        Always shows token counts (total input/output/total + call_count +
+        per-model breakdown). Priced models show their ``$`` estimate inline;
+        unpriced models are tagged ``(no price)``. A total cost line is added
+        only when at least one model is priced.
+        """
+        lines = [
+            "Token usage (this session):",
+            f"  Input:  {self.total_input:,} tokens",
+            f"  Output: {self.total_output:,} tokens",
+        ]
+        # Only surface the cache line when caching actually happened, so
+        # non-cached sessions keep the original compact output.
+        if self.total_cache_read or self.total_cache_write:
+            lines.append(
+                f"  Cache:  {self.total_cache_read:,} read / "
+                f"{self.total_cache_write:,} write tokens"
+            )
+        lines.extend(
+            [
+                f"  Total:  {self.total_tokens:,} tokens",
+                f"  Calls:  {self.call_count}",
+            ]
+        )
+
+        if self.per_model:
+            lines.append("  By model:")
+            for model in sorted(self.per_model):
+                usage = self.per_model[model]
+                price = resolve_price(model, prices)
+                if price is None:
+                    cost_label = " (no price)"
+                else:
+                    input_price, output_price = price
+                    read_mult, write_mult = resolve_cache_multipliers(model)
+                    model_cost = (
+                        usage.input_tokens / _PER_MILLION * input_price
+                        + usage.output_tokens / _PER_MILLION * output_price
+                        + usage.cache_read_tokens / _PER_MILLION * input_price * read_mult
+                        + usage.cache_write_tokens / _PER_MILLION * input_price * write_mult
+                    )
+                    cost_label = f" — ${model_cost:.4f}"
+                cache_label = ""
+                if usage.cache_read_tokens or usage.cache_write_tokens:
+                    cache_label = (
+                        f", {usage.cache_read_tokens:,} cache-read / "
+                        f"{usage.cache_write_tokens:,} cache-write"
+                    )
+                lines.append(
+                    f"    {model}: "
+                    f"{usage.input_tokens:,} in / {usage.output_tokens:,} out"
+                    f"{cache_label} "
+                    f"({usage.call_count} calls){cost_label}"
+                )
+
+        total_cost = self.estimate_cost(prices)
+        if total_cost is not None:
+            lines.append(f"  Estimated cost: ${total_cost:.4f}")
+            lines.append("  (prices are estimates; override via [cost.prices] in config)")
+
+        return "\n".join(lines)

bareagent/memory/transcript.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+_SAVE_TIMESTAMP_FORMAT = "%Y-%m-%dT%H-%M-%S-%f"
+_TIMESTAMP_FORMATS = (
+    _SAVE_TIMESTAMP_FORMAT,
+    "%Y-%m-%dT%H-%M-%S",
+)
+
+
+@dataclass(slots=True)
+class _TranscriptEntry:
+    session_id: str
+    timestamp: datetime
+    path: Path
+
+
+class TranscriptManager:
+    def __init__(self, transcript_dir: str | Path = ".transcripts") -> None:
+        self.transcript_dir = Path(transcript_dir)
+        self.transcript_dir.mkdir(parents=True, exist_ok=True)
+
+    def save(self, messages: list[dict[str, Any]], session_id: str) -> Path:
+        timestamp = datetime.now().strftime(_SAVE_TIMESTAMP_FORMAT)
+        path = self.transcript_dir / f"{session_id}_{timestamp}.jsonl"
+        with path.open("w", encoding="utf-8") as file:
+            for message in messages:
+                file.write(json.dumps(message, ensure_ascii=False))
+                file.write("\n")
+        return path
+
+    def load(self, session_id: str) -> list[dict[str, Any]]:
+        entry = self._get_session_entry(session_id)
+        with entry.path.open("r", encoding="utf-8") as file:
+            return [json.loads(line) for line in file if line.strip()]
+
+    def list_sessions(self) -> list[str]:
+        latest_by_session: dict[str, datetime] = {}
+        for entry in self._iter_entries():
+            latest_by_session[entry.session_id] = max(
+                entry.timestamp,
+                latest_by_session.get(entry.session_id, datetime.min),
+            )
+        return [
+            session_id
+            for session_id, _ in sorted(
+                latest_by_session.items(),
+                key=lambda item: item[1],
+                reverse=True,
+            )
+        ]
+
+    def get_latest_session(self) -> str | None:
+        entries = self._iter_entries()
+        if not entries:
+            return None
+        return max(entries, key=lambda entry: entry.timestamp).session_id
+
+    def resume(self, session_id: str | None = None) -> list[dict[str, Any]]:
+        target_session = session_id or self.get_latest_session()
+        if target_session is None:
+            raise FileNotFoundError("No saved transcripts found.")
+        return self.load(target_session)
+
+    def _get_session_entry(self, session_id: str) -> _TranscriptEntry:
+        entries = [
+            entry for entry in self._iter_entries() if entry.session_id == session_id
+        ]
+        if not entries:
+            raise FileNotFoundError(f"No transcript found for session: {session_id}")
+        return max(entries, key=lambda entry: entry.timestamp)
+
+    def _iter_entries(self) -> list[_TranscriptEntry]:
+        entries: list[_TranscriptEntry] = []
+        for path in self.transcript_dir.glob("*.jsonl"):
+            entry = self._parse_entry(path)
+            if entry is not None:
+                entries.append(entry)
+        return entries
+
+    def _parse_entry(self, path: Path) -> _TranscriptEntry | None:
+        stem = path.stem
+        if "_" not in stem:
+            return None
+        session_id, raw_timestamp = stem.rsplit("_", 1)
+        timestamp: datetime | None = None
+        for fmt in _TIMESTAMP_FORMATS:
+            try:
+                timestamp = datetime.strptime(raw_timestamp, fmt)
+                break
+            except ValueError:
+                continue
+        if timestamp is None:
+            return None
+        return _TranscriptEntry(session_id=session_id, timestamp=timestamp, path=path)

bareagent/permission/__init__.py

@@ -0,0 +1 @@
+"""Permission control modules for BareAgent."""

bareagent/permission/guard.py

@@ -0,0 +1,329 @@
+from __future__ import annotations
+
+import json
+import re
+import sys
+from collections.abc import Callable
+from enum import Enum
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from bareagent.planning.agent_types import AgentType
+
+
+class PermissionMode(Enum):
+    DEFAULT = "default"
+    AUTO = "auto"
+    PLAN = "plan"
+    BYPASS = "bypass"
+
+
+_SHELLS = "bash|sh|zsh|dash|ksh|fish"
+
+_MCP_TOOL_PREFIX = "mcp__"
+# Preview limits for MCP ask prompts. MCP args are JSON, not shell text, and
+# servers can produce arbitrarily large strings (file blobs, long URLs). Cap
+# top-level string values so a single field can't flood the terminal.
+_MCP_PREVIEW_FIELD_LIMIT = 256
+
+
+def _is_mcp_tool(tool_name: str) -> bool:
+    """Return True if ``tool_name`` follows the ``mcp__<server>__<tool>`` namespace."""
+    return tool_name.startswith(_MCP_TOOL_PREFIX)
+
+
+class PermissionGuard:
+    SAFE_TOOLS = {
+        "read_file",
+        "glob",
+        "grep",
+        "todo_read",
+        "todo_write",
+        "load_skill",
+        "task_list",
+        "task_get",
+        "team_list",
+        "web_fetch",
+        "web_search",
+        # Memory is sandboxed to its own directory (never user code) and is
+        # agent bookkeeping; prompting on every recall/save would be noise.
+        # Read-only isolation for sub-agents is handled at the AgentType layer
+        # (memory_writable), not here.
+        "memory",
+        # skill_create writes only to the generated-skills pending sandbox and
+        # is exposed only inside the isolated reflection call (never the main
+        # tool set / sub-agents), so prompting would be noise.
+        "skill_create",
+        # goal_verdict only records the evaluator's judgement into an in-memory
+        # sink (no workspace side effects) and is exposed only inside the
+        # isolated goal-evaluator call (never the main tool set / sub-agents),
+        # so prompting would be noise.
+        "goal_verdict",
+        # exit_plan_mode is the *only* way out of PLAN mode; it MUST be allowed
+        # while in PLAN (a non-SAFE tool is blocked there). Its own action is the
+        # approval prompt, so a separate permission confirm would be redundant.
+        # It is a main-loop-only tool (never in the global set / sub-agents).
+        "exit_plan_mode",
+    }
+    AUTO_SAFE_PATTERNS = [
+        re.compile(r"^(ls|cat|head|tail|wc|echo|pwd|date|which|type)\b"),
+        re.compile(r"^git\s+(status|log|diff|branch|show)\b"),
+        re.compile(r"^(pytest|python\s+-m\s+pytest|ruff|mypy)\b"),
+        re.compile(r"^npm\s+(test|run\s+lint|run\s+test)\b"),
+    ]
+    DANGEROUS_PATTERNS = [
+        re.compile(r"(^|\s)rm\s+-[rR]f?\b"),
+        re.compile(r"git\s+push\s+--force\b"),
+        re.compile(r"git\s+reset\s+--hard\b"),
+        re.compile(r"DROP\s+TABLE\b", re.IGNORECASE),
+        re.compile(r"DELETE\s+FROM\b", re.IGNORECASE),
+        # shell wrapper bypass
+        re.compile(rf"(^|\s)({_SHELLS})\s+-c\b"),
+        # absolute-path rm bypass
+        re.compile(r"(^|\s)/(?:usr/)?bin/rm\b"),
+        # env prefix bypass
+        re.compile(r"(^|\s)env\s+"),
+        # pipe-to-shell execution
+        re.compile(rf"curl\b.*\|\s*({_SHELLS})\b"),
+        re.compile(rf"wget\b.*\|\s*({_SHELLS})\b"),
+        # destructive system commands
+        re.compile(r"(^|\s)chmod\s+777\b"),
+        re.compile(r"(^|\s)mkfs\b"),
+        re.compile(r"(^|\s)dd\s+if="),
+        re.compile(r"find\b.*-delete\b"),
+    ]
+
+    def __init__(
+        self,
+        mode: PermissionMode = PermissionMode.DEFAULT,
+        *,
+        fail_closed: bool = False,
+        ask_user_fn: Callable[[Any], bool] | None = None,
+    ) -> None:
+        self.mode = mode
+        self.allow_rules: list[str] = []
+        self.deny_rules: list[str] = []
+        self.fail_closed = fail_closed
+        self._ask_user_fn = ask_user_fn
+
+    def requires_confirm(self, tool_name: str, tool_input: dict[str, Any]) -> bool:
+        if self.mode == PermissionMode.BYPASS:
+            return False
+        normalized_tool = tool_name.strip().lower()
+        rule_subject = permission_rule_subject(normalized_tool, tool_input)
+        # MCP tools carry JSON args (not shell text), so DANGEROUS_PATTERNS
+        # are not applicable. Branch early on mode but still honour the
+        # generic allow/deny prefix rules (handled below via rule_subject).
+        if _is_mcp_tool(normalized_tool):
+            # PLAN mode rejects every MCP tool by policy — MCP servers have
+            # unknown side effects and are not in SAFE_TOOLS. This check runs
+            # before allow_rules so an allowlist in config.toml cannot punch
+            # holes through PLAN.
+            if self.mode == PermissionMode.PLAN:
+                return True
+            if rule_subject and self._match_rules(
+                self.deny_rules,
+                normalized_tool,
+                rule_subject,
+            ):
+                return True
+            if rule_subject and self._match_rules(
+                self.allow_rules,
+                normalized_tool,
+                rule_subject,
+            ):
+                return False
+            if self.mode == PermissionMode.AUTO:
+                return False
+            # DEFAULT: always ask for MCP tools.
+            return True
+        if self.mode == PermissionMode.PLAN:
+            return normalized_tool not in self.SAFE_TOOLS
+        if normalized_tool == "bash":
+            cmd = rule_subject or ""
+            if self._match_rules(self.deny_rules, normalized_tool, cmd):
+                return True
+            if any(pattern.search(cmd) for pattern in self.DANGEROUS_PATTERNS):
+                return True
+            if self._match_rules(self.allow_rules, normalized_tool, cmd):
+                return False
+            if any(pattern.search(cmd) for pattern in self.AUTO_SAFE_PATTERNS):
+                return False
+            if self.mode == PermissionMode.DEFAULT:
+                return True
+            # AUTO mode: not matching any dangerous pattern, allow
+            return False
+
+        if rule_subject and self._match_rules(
+            self.deny_rules,
+            normalized_tool,
+            rule_subject,
+        ):
+            return True
+        if normalized_tool in self.SAFE_TOOLS:
+            return False
+        if normalized_tool in {"edit_file", "task_create", "task_update"}:
+            return False
+        if rule_subject and self._match_rules(
+            self.allow_rules,
+            normalized_tool,
+            rule_subject,
+        ):
+            return False
+        if normalized_tool in {"write_file", "semantic_rename"}:
+            # Write tools: confirm in DEFAULT, auto-approve in AUTO. PLAN was
+            # already rejected above (not in SAFE_TOOLS), BYPASS short-circuited
+            # at the top.
+            return self.mode == PermissionMode.DEFAULT
+        return True
+
+    def is_dangerous(self, tool_name: str, tool_input: dict[str, Any]) -> bool:
+        """Return True if ``tool_name`` + ``tool_input`` match a known dangerous shell pattern.
+
+        DANGEROUS_PATTERNS encode shell-text heuristics (``rm -rf``,
+        ``git push --force``, ``DROP TABLE``...). They are intentionally
+        skipped for MCP tools, whose ``tool_input`` is JSON rather than a
+        shell command — applying shell regexes against JSON would produce
+        false positives without catching anything real.
+        """
+        normalized_tool = tool_name.strip().lower()
+        if _is_mcp_tool(normalized_tool):
+            return False
+        if normalized_tool == "bash":
+            cmd = str(tool_input.get("command", ""))
+            return any(pattern.search(cmd) for pattern in self.DANGEROUS_PATTERNS)
+        return False
+
+    def format_preview(self, tool_name: str, tool_input: dict[str, Any]) -> str:
+        """Return a human-readable JSON preview of ``tool_input`` for ask prompts.
+
+        Top-level string values longer than ``_MCP_PREVIEW_FIELD_LIMIT`` are
+        truncated with a ``... [truncated, N chars]`` suffix so a single huge
+        argument (file blob, long URL) cannot drown the terminal. Nested
+        structures are not recursively truncated — v1 keeps the rule simple.
+        """
+        if not isinstance(tool_input, dict) or not tool_input:
+            return json.dumps(tool_input, ensure_ascii=False, indent=2)
+        prepared: dict[str, Any] = {}
+        for key, value in tool_input.items():
+            if isinstance(value, str) and len(value) > _MCP_PREVIEW_FIELD_LIMIT:
+                prepared[key] = (
+                    value[:_MCP_PREVIEW_FIELD_LIMIT] + f"... [truncated, {len(value)} chars]"
+                )
+            else:
+                prepared[key] = value
+        return json.dumps(prepared, ensure_ascii=False, indent=2, default=str)
+
+    def ask_user(self, call: Any) -> bool:
+        if self.fail_closed:
+            return False
+        if self.mode == PermissionMode.PLAN:
+            print(f"Plan mode: {call.name} blocked (read-only)")
+            return False
+        if self._ask_user_fn is not None:
+            return self._ask_user_fn(call)
+        if not sys.stdin.isatty():
+            print(f"Non-interactive environment: {call.name} denied")
+            return False
+        print(f"{call.name}: {json.dumps(call.input, ensure_ascii=False)[:200]}")
+        try:
+            return input("Allow? [y/N] ").strip().lower() == "y"
+        except EOFError:
+            return False
+
+    def _match_rules(self, rules: list[str], tool_name: str, cmd: str) -> bool:
+        normalized_tool = tool_name.strip().lower()
+        for rule in rules:
+            parsed = _parse_prefix_rule(rule)
+            if parsed is None:
+                continue
+            rule_tool, prefix = parsed
+            if rule_tool != normalized_tool:
+                continue
+            if cmd.strip().startswith(prefix):
+                return True
+        return False
+
+    def clone(
+        self, *, mode: PermissionMode | None = None, fail_closed: bool | None = None
+    ) -> PermissionGuard:
+        """Create a copy of this guard with optional overrides."""
+        child = PermissionGuard(
+            mode=mode if mode is not None else self.mode,
+            fail_closed=fail_closed if fail_closed is not None else self.fail_closed,
+            ask_user_fn=self._ask_user_fn,
+        )
+        child.allow_rules = list(self.allow_rules)
+        child.deny_rules = list(self.deny_rules)
+        return child
+
+    def for_subagent(
+        self,
+        agent_type: AgentType,
+        *,
+        background: bool = False,
+    ) -> PermissionGuard:
+        """Clone the guard for child-agent execution."""
+        resolved_mode = (
+            agent_type.permission_mode if agent_type.permission_mode is not None else self.mode
+        )
+        return self.clone(
+            mode=resolved_mode,
+            fail_closed=self.fail_closed or background or resolved_mode == PermissionMode.PLAN,
+        )
+
+
+def _parse_prefix_rule(rule: str) -> tuple[str, str] | None:
+    match = re.fullmatch(
+        r"\s*([A-Za-z_][A-Za-z0-9_]*)\((prefix|prefix_json):([\s\S]+)\)\s*",
+        rule,
+    )
+    if match is None:
+        return None
+    tool_name = match.group(1).strip().lower()
+    rule_kind = match.group(2)
+    raw_prefix = match.group(3)
+    if rule_kind == "prefix_json":
+        try:
+            parsed_prefix = json.loads(raw_prefix)
+        except json.JSONDecodeError:
+            return None
+        if not isinstance(parsed_prefix, str):
+            return None
+        return tool_name, parsed_prefix
+    prefix = raw_prefix.rstrip("*").strip()
+    return tool_name, prefix
+
+
+def permission_rule_subject(tool_name: str, tool_input: dict[str, Any]) -> str | None:
+    normalized_tool = tool_name.strip().lower()
+    if normalized_tool == "bash":
+        command = str(tool_input.get("command", "")).strip()
+        return command or None
+
+    for key in ("file_path", "path", "name", "to_agent", "task_id", "skill_name"):
+        value = tool_input.get(key)
+        if not isinstance(value, str):
+            continue
+        subject = value.strip()
+        if subject:
+            return subject
+
+    if "task" in tool_input:
+        task = str(tool_input.get("task", "")).strip()
+        if task:
+            return task
+
+    if not tool_input:
+        return None
+
+    try:
+        serialized = json.dumps(
+            tool_input,
+            ensure_ascii=False,
+            sort_keys=True,
+            default=str,
+        )
+    except (TypeError, ValueError):
+        serialized = str(tool_input).strip()
+    return serialized or None