core/tools: persist soft-confirm grants under session.data

src/plyngent/agent/tools.py

@@ -329,14 +329,14 @@ class ToolRegistry:
         session = self._session_for_grants()
         return session is not None and has_grant(session, name)
 
-    def _record_grant(self, name: str, *, tags: ToolTag) -> None:
+    async def _record_grant(self, name: str, *, tags: ToolTag) -> None:
         if not (tags & ToolTag.TRUSTABLE):
             return
         from plyngent.tools.grants import add_grant
 
         session = self._session_for_grants()
         if session is not None:
-            add_grant(session, name)
+            await add_grant(session, name)
 
     async def _prompt_soft_confirm(
         self,
@@ -352,7 +352,7 @@ class ToolRegistry:
         if inspect.isawaitable(decision):
             decision = await decision
         if decision is True:
-            self._record_grant(name, tags=tags)
+            await self._record_grant(name, tags=tags)
             return None
         if isinstance(decision, str) and decision.strip():
             return f"error: tool {name!r} denied by user confirm ({reason}); user comment: {decision.strip()}"

src/plyngent/tools/context.py

@@ -58,7 +58,8 @@ class SessionState:
     data: PersistentDataView[Any] = field(default_factory=_default_session_data)
     # Live domain object during migration (also under data["todo"] when views bind).
     todo: TodoStack | None = None
-    # Soft-confirm grants: tool_name → True (Phase 1 key is tool name in session).
+    # Soft-confirm grants live map: tool_name → True (Phase 1 key is tool name).
+    # Durable copy lives under data["grants"] (see plyngent.tools.grants).
     grants: dict[str, bool] = field(default_factory=dict)
     extras: dict[str, Any] = field(default_factory=dict)
 
@@ -66,9 +67,11 @@ class SessionState:
         return bool(self.grants.get(tool_name))
 
     def add_grant(self, tool_name: str) -> None:
+        """Update the live map only; prefer :func:`plyngent.tools.grants.add_grant` to persist."""
         self.grants[tool_name] = True
 
     def clear_grants(self) -> None:
+        """Clear the live map; durable view is updated separately when needed."""
         self.grants.clear()
 
 

src/plyngent/tools/grants.py

@@ -1,4 +1,14 @@
-"""Soft-confirm trust grants (session-scoped)."""
+"""Soft-confirm trust grants (session-scoped).
+
+Live map: ``SessionState.grants`` (sync reads for the confirm gate).
+Durable tree: ``session.data["grants"]`` (tool name → bool) via
+:class:`~plyngent.tools.view.PersistentDataView`.
+
+Hosts that resume a session document should call :func:`hydrate_grants`
+after binding :class:`~plyngent.tools.context.SessionState`. Soft-confirm
+approval calls :func:`add_grant`, which updates the live map and commits
+the view.
+"""
 
 from __future__ import annotations
 
@@ -14,12 +24,51 @@ def grant_key(tool_name: str) -> str:
 
 
 def has_grant(session: SessionState, tool_name: str) -> bool:
+    """Return whether *tool_name* is granted in the live session map."""
     return session.has_grant(grant_key(tool_name))
 
 
-def add_grant(session: SessionState, tool_name: str) -> None:
+async def add_grant(session: SessionState, tool_name: str) -> None:
+    """Grant *tool_name* and commit the grants map under ``session.data``."""
     session.add_grant(grant_key(tool_name))
+    await persist_grants(session)
 
 
 def clear_grants(session: SessionState) -> None:
+    """Clear the live grant map (sync; e.g. CLI YOLO off / ``/new``).
+
+    Does not open a view transaction (callers may be outside an event loop).
+    Use :func:`persist_grants` when the durable tree should also clear.
+    """
     session.clear_grants()
+
+
+async def clear_grants_and_persist(session: SessionState) -> None:
+    """Clear live grants and write an empty map to ``session.data``."""
+    session.clear_grants()
+    await persist_grants(session)
+
+
+async def persist_grants(session: SessionState) -> None:
+    """Write the live grants map to ``session.data["grants"]``."""
+    async with session.data as data:
+        data["grants"].store({key: bool(value) for key, value in session.grants.items()})
+
+
+async def hydrate_grants(session: SessionState) -> None:
+    """Load durable grants into the live map (replace)."""
+    from typing import cast
+
+    raw: object | None = None
+    async with session.data as data:
+        try:
+            raw = data["grants"].load()
+        except RuntimeError:
+            raw = None
+    session.grants.clear()
+    if not isinstance(raw, dict):
+        return
+    blob = cast("dict[object, object]", raw)
+    for key_obj, value in blob.items():
+        if value:
+            session.grants[str(key_obj)] = True