feat(permissions): capability-based permission engine with ADK + LangGraph adapters

CLAUDE.md

@@ -47,7 +47,7 @@ agentic-cli/
 │   │       ├── persistence/  # Checkpointers, stores
 │   │       └── tools/        # LangChain-compatible wrappers
 │   ├── tools/
-│   │   ├── registry.py       # ToolRegistry, @register_tool, ToolCategory, PermissionLevel
+│   │   ├── registry.py       # ToolRegistry, @register_tool, ToolCategory
 │   │   ├── executor.py       # SafePythonExecutor
 │   │   ├── knowledge_tools.py # kb_search, kb_ingest, kb_list, kb_read
 │   │   ├── arxiv_tools.py    # search_arxiv, fetch_arxiv_paper, analyze_arxiv_paper
@@ -62,7 +62,7 @@ agentic-cli/
 │   │   ├── memory_tools.py   # save_memory, search_memory + MemoryStore
 │   │   ├── planning_tools.py # save_plan, get_plan + PlanStore
 │   │   ├── task_tools.py     # save_tasks, get_tasks + TaskStore
-│   │   ├── hitl_tools.py     # request_approval + ApprovalManager, HITLConfig
+│   │   ├── reflection_tools.py # save_reflection + ToolReflectionStore
 │   │   ├── shell/            # 8-layer shell security
 │   │   └── webfetch/         # Fetcher, converter, validator, robots
 │   ├── knowledge_base/
@@ -133,7 +133,8 @@ Workflow:
 
 ### Key Design Patterns
 - **Tool error handling**: All tools return `{"success": bool, ...}` dicts. Never raise `ToolError`.
-- **Tool registration**: Use `@register_tool(category=..., permission_level=..., description=...)` decorator. Tools are auto-discovered via the global `ToolRegistry`.
+- **Tool registration**: Use `@register_tool(category=..., capabilities=..., description=...)` decorator. `capabilities=` is required — pass `EXEMPT` for tools that need no permission check or a list of `Capability(name, target_arg=...)` tuples the engine matches against rules. Tools are auto-discovered via the global `ToolRegistry`.
+- **Permissions**: `workflow/permissions/` holds a framework-independent engine that evaluates declared capabilities against rules from four sources (builtin, user `~/.{app_name}/settings.json`, project `./.{app_name}/settings.json`, in-memory session). ADK + LangGraph gate tool calls via `workflow/adk/permission_plugin.py::PermissionPlugin` and `workflow/langgraph/permission_wrap.py::wrap_tool_for_permission`. See `docs/superpowers/specs/2026-04-18-permissions-system-design.md`.
 - **Service registry**: Tools access services and shared state via `get_service(key)` from `workflow.service_registry`. A single ContextVar holds a `dict[str, Any]` set by the workflow manager during processing. Complex services (KBManager, SandboxManager, MemoryStore) are lazily created; simple state (plan string, task list) lives directly in the registry dict.
 - **Manager detection**: Tools decorated with `@requires("kb_manager")` etc. are scanned by `BaseWorkflowManager._detect_required_managers()` which lazily creates only the needed services.
 - **Atomic writes**: Use `atomic_write_json`/`atomic_write_text` from `persistence/_utils.py` for file persistence.

README.md

@@ -38,7 +38,7 @@ Agentic CLI provides the core infrastructure for building interactive CLI applic
 ├─────────────────────────────┬───────────────────────────────────────┤
 │   GoogleADKWorkflowManager  │     LangGraphWorkflowManager          │
 │   (default)                 │     (optional: langgraph extra)       │
-│   + ConfirmationPlugin      │     + confirmation tool wrapper       │
+│   + PermissionPlugin        │     + wrap_tool_for_permission        │
 │   + LLMLoggingPlugin        │     + native ToolNode                 │
 │   + TaskProgressPlugin      │                                       │
 └─────────────────────────────┴───────────────────────────────────────┘
@@ -145,7 +145,7 @@ manager = GoogleADKWorkflowManager(
 ```
 
 ADK integrations:
-- **ConfirmationPlugin** — intercepts `DANGEROUS` tools and prompts the user for approval
+- **PermissionPlugin** — evaluates each tool's declared capabilities against the permission engine and prompts the user when no rule matches
 - **LLMLoggingPlugin** — structured logging of LLM requests/responses
 - **TaskProgressPlugin** — streams the task checklist into its own thinking box
 
@@ -171,7 +171,7 @@ Features:
 - **Explicit provider support**: Uses `langchain-google-genai` for Gemini (not VertexAI)
 - **Thinking mode**: Native support for Claude and Gemini thinking/reasoning
 - **Retry policies**: Automatic retry with exponential backoff
-- **Confirmation wrapper**: Wraps `DANGEROUS` tools to request HITL approval
+- **Permission wrapper**: Wraps each tool to gate execution through the permission engine
 - **Event streaming**: Real-time workflow events via `WorkflowEvent`
 
 Requires: `pip install agentic-cli[langgraph]`
@@ -186,7 +186,7 @@ Requires: `pip install agentic-cli[langgraph]`
 | State persistence | In-memory | Memory, PostgreSQL, or SQLite |
 | Thinking support | Native (Gemini) | Native (Claude & Gemini) |
 | Retry handling | Built-in | Built-in with backoff |
-| HITL confirmation | ConfirmationPlugin | Tool wrapper |
+| Permission gate | PermissionPlugin | wrap_tool_for_permission |
 | Context trimming | Native | Native |
 
 ### Auto-selection via Settings
@@ -320,11 +320,12 @@ configs = [coordinator, researcher, analyst]
 Tools are regular Python functions with type hints and docstrings. **All tools return `{"success": bool, ...}` dicts** — never raise exceptions.
 
 ```python
-from agentic_cli.tools import register_tool, ToolCategory, PermissionLevel
+from agentic_cli.tools import register_tool, ToolCategory
+from agentic_cli.workflow.permissions import Capability, EXEMPT
 
 @register_tool(
-    category=ToolCategory.DATA,
-    permission_level=PermissionLevel.SAFE,
+    category=ToolCategory.NETWORK,
+    capabilities=[Capability("http.read")],
     description="Search the database for matching records.",
 )
 def search_database(query: str, limit: int = 10) -> dict:
@@ -534,15 +535,9 @@ Each tool keeps at most N reflections (FIFO eviction). Reflections can be inject
 
 #### HITL (Human-in-the-Loop)
 
-Two mechanisms:
+Tool calls are gated by the **permission engine** (`workflow/permissions/`). Each tool declares a list of capabilities (e.g. `filesystem.write(path=...)`); the engine evaluates them against rules from four sources (builtin defaults, user `~/.{app_name}/settings.json`, project `./.{app_name}/settings.json`, in-memory session). When no rule matches, the user is prompted with `Allow once / Allow for session / Allow always (save to project) / Deny`. Always-grants persist into the project settings file so the next run picks them up automatically.
 
-1. **Automatic confirmation for `DANGEROUS` tools** — handled by ADK's `ConfirmationPlugin` and LangGraph's tool wrapper. No code changes needed; just mark the tool `DANGEROUS`.
-2. **Explicit `request_approval` tool** — for domain-level checkpoints:
-
-   ```python
-   from agentic_cli.tools import hitl_tools
-   # request_approval(message, options) -> {"success": True, "choice": "..."}
-   ```
+See `docs/superpowers/specs/2026-04-18-permissions-system-design.md` for the full design.
 
 ## CLI Commands
 
@@ -718,15 +713,24 @@ agentic-cli/
 │   │   ├── adk/
 │   │   │   ├── manager.py                # GoogleADKWorkflowManager
 │   │   │   ├── event_processor.py
-│   │   │   ├── plugins.py                # ConfirmationPlugin, LLMLoggingPlugin
+│   │   │   ├── plugins.py                # LLMLoggingPlugin
+│   │   │   ├── permission_plugin.py      # PermissionPlugin (capability gating)
 │   │   │   └── task_progress_plugin.py
-│   │   └── langgraph/
-│   │       ├── manager.py                # LangGraphWorkflowManager
-│   │       ├── graph_builder.py
-│   │       ├── state.py
-│   │       └── persistence/              # Checkpointers and stores
+│   │   ├── langgraph/
+│   │   │   ├── manager.py                # LangGraphWorkflowManager
+│   │   │   ├── graph_builder.py
+│   │   │   ├── permission_wrap.py        # wrap_tool_for_permission
+│   │   │   ├── state.py
+│   │   │   └── persistence/              # Checkpointers and stores
+│   │   └── permissions/                  # Framework-independent permission engine
+│   │       ├── capabilities.py           # Capability, ResolvedCapability, EXEMPT
+│   │       ├── rules.py                  # Rule, Effect, RuleSource, CheckResult, AskScope
+│   │       ├── matchers.py               # Path/URL/Shell/StringGlob matchers
+│   │       ├── store.py                  # PermissionContext, BUILTIN_RULES, JSON load/save
+│   │       ├── prompt.py                 # build_request + parse_response
+│   │       └── engine.py                 # PermissionEngine
 │   ├── tools/
-│   │   ├── registry.py           # ToolRegistry, ToolCategory, PermissionLevel
+│   │   ├── registry.py           # ToolRegistry, ToolCategory, register_tool
 │   │   ├── factories.py          # Backend-aware tool factories
 │   │   ├── executor.py           # SafePythonExecutor
 │   │   ├── arxiv_tools.py        # search_arxiv, fetch_arxiv_paper, ingest_arxiv_paper
@@ -744,7 +748,6 @@ agentic-cli/
 │   │   ├── pdf_utils.py          # PDF text extraction helpers
 │   │   ├── memory_tools.py       # save/search/update/delete + MemoryStore
 │   │   ├── reflection_tools.py   # save_reflection + ToolReflectionStore
-│   │   ├── hitl_tools.py         # request_approval
 │   │   ├── _core/                # Shared planning/task logic
 │   │   │   ├── planning.py
 │   │   │   └── tasks.py

src/agentic_cli/tools/__init__.py

@@ -10,7 +10,6 @@
 
 Framework Tools:
     - memory_tools: Working and long-term memory tools
-    - hitl_tools: Human-in-the-loop approval tools
     - web_search: Web search with pluggable backends (Tavily, Brave)
 
 For resilience patterns, use tenacity, pybreaker, aiolimiter directly.
@@ -48,7 +47,6 @@
 from agentic_cli.tools.webfetch_tool import web_fetch
 from agentic_cli.tools.registry import (
     ToolCategory,
-    PermissionLevel,
     ToolDefinition,
     ToolRegistry,
     get_registry,
@@ -61,7 +59,6 @@
 __all__ = [
     # Registry classes
     "ToolCategory",
-    "PermissionLevel",
     "ToolDefinition",
     "ToolRegistry",
     "get_registry",
@@ -103,7 +100,6 @@
     "ask_clarification",
     # Framework tool modules (lazy loaded)
     "memory_tools",
-    "hitl_tools",
     "sandbox_tools",
     "reflection_tools",
 ]
@@ -112,7 +108,6 @@
 # Lazy loading for framework tool modules
 _lazy_tool_modules = {
     "memory_tools": "agentic_cli.tools.memory_tools",
-    "hitl_tools": "agentic_cli.tools.hitl_tools",
     "sandbox_tools": "agentic_cli.tools.sandbox",
     "reflection_tools": "agentic_cli.tools.reflection_tools",
 }

src/agentic_cli/tools/adk/state_tools.py

@@ -13,8 +13,11 @@
 
 from agentic_cli.tools._core.planning import summarize_checkboxes
 from agentic_cli.tools._core.tasks import validate_tasks, normalize_tasks, filter_tasks
+from agentic_cli.tools.registry import ToolCategory, register_tool
+from agentic_cli.workflow.permissions import EXEMPT
 
 
+@register_tool(capabilities=EXEMPT, category=ToolCategory.PLANNING)
 def save_plan(content: str, tool_context: ToolContext) -> dict[str, Any]:
     """Save or update the execution plan as markdown with checkboxes.
 
@@ -33,6 +36,7 @@ def save_plan(content: str, tool_context: ToolContext) -> dict[str, Any]:
     return {"success": True, "message": message}
 
 
+@register_tool(capabilities=EXEMPT, category=ToolCategory.PLANNING)
 def get_plan(tool_context: ToolContext) -> dict[str, Any]:
     """Retrieve the current execution plan.
 
@@ -47,6 +51,7 @@ def get_plan(tool_context: ToolContext) -> dict[str, Any]:
     return {"success": True, "content": plan}
 
 
+@register_tool(capabilities=EXEMPT, category=ToolCategory.PLANNING)
 def save_tasks(
     tasks: list[dict[str, Any]], tool_context: ToolContext
 ) -> dict[str, Any]:
@@ -86,6 +91,7 @@ def save_tasks(
     }
 
 
+@register_tool(capabilities=EXEMPT, category=ToolCategory.PLANNING)
 def get_tasks(
     status: str = "",
     priority: str = "",

src/agentic_cli/tools/arxiv_tools.py

@@ -20,8 +20,8 @@
 from agentic_cli.tools.registry import (
     register_tool,
     ToolCategory,
-    PermissionLevel,
 )
+from agentic_cli.workflow.permissions import Capability
 from agentic_cli.workflow.service_registry import (
     ARXIV_SOURCE,
     KB_MANAGER,
@@ -122,7 +122,8 @@ async def _fetch_arxiv_paper_with_source(source, arxiv_id: str) -> dict[str, Any
 
 @register_tool(
     category=ToolCategory.KNOWLEDGE,
-    permission_level=PermissionLevel.SAFE,
+
+    capabilities=[Capability("http.read")],
     description="Search arXiv for academic papers by query, category, or date range. Use this to find research papers on a topic.",
 )
 def search_arxiv(
@@ -170,7 +171,8 @@ def search_arxiv(
 
 @register_tool(
     category=ToolCategory.KNOWLEDGE,
-    permission_level=PermissionLevel.SAFE,
+
+    capabilities=[Capability("http.read")],
     description="Fetch metadata for a specific arXiv paper by ID or URL. Returns title, authors, abstract, categories, and PDF URL.",
 )
 async def fetch_arxiv_paper(
@@ -296,7 +298,8 @@ async def _ingest_arxiv_paper_with_services(
 
 @register_tool(
     category=ToolCategory.KNOWLEDGE,
-    permission_level=PermissionLevel.SAFE,
+
+    capabilities=[Capability("http.read"), Capability("kb.write")],
     description="Download an arXiv paper's PDF, extract text, and ingest it into the knowledge base. Use this to add a specific arXiv paper to long-term storage so it can be searched later.",
 )
 async def ingest_arxiv_paper(

src/agentic_cli/tools/execution_tools.py

@@ -9,13 +9,13 @@
 from agentic_cli.tools.registry import (
     register_tool,
     ToolCategory,
-    PermissionLevel,
 )
+from agentic_cli.workflow.permissions import Capability
 
 
 @register_tool(
     category=ToolCategory.EXECUTION,
-    permission_level=PermissionLevel.DANGEROUS,
+    capabilities=[Capability("python.exec")],
     description="Stateless Python scratchpad for quick calculations, formula checks, and mathematical reasoning. Each call starts fresh — no state persists. Only whitelisted modules (math, numpy, pandas, json, etc.) are available. Use sandbox_execute instead for stateful work.",
 )
 def execute_python(

src/agentic_cli/tools/file_read.py

@@ -3,8 +3,6 @@
 Provides safe, read-only tools for file system access:
 - read_file: Read file contents with optional offset/limit
 - diff_compare: Compare two text sources
-
-All tools in this module have PermissionLevel.SAFE.
 """
 
 import difflib
@@ -13,14 +11,14 @@
 
 from agentic_cli.tools.registry import (
     ToolCategory,
-    PermissionLevel,
     register_tool,
 )
+from agentic_cli.workflow.permissions import Capability
 
 
 @register_tool(
     category=ToolCategory.READ,
-    permission_level=PermissionLevel.SAFE,
+    capabilities=[Capability("filesystem.read", target_arg="path")],
     description="Read the contents of a file at the given path. Use this to examine source code, config files, or any text file. For finding files by name pattern use glob instead; for searching file contents use grep.",
 )
 def read_file(
@@ -110,7 +108,7 @@ def read_file(
 
 @register_tool(
     category=ToolCategory.READ,
-    permission_level=PermissionLevel.SAFE,
+    capabilities=[Capability("filesystem.read", target_arg="source_a"), Capability("filesystem.read", target_arg="source_b")],
     description="Compare two text sources (files or strings) and show differences. Use this to see what changed between two versions of content.",
 )
 def diff_compare(

src/agentic_cli/tools/file_write.py

@@ -4,7 +4,6 @@
 - write_file: Write content to a file (creates or overwrites)
 - edit_file: Replace text in a file (sed-like operation)
 
-All tools in this module have PermissionLevel.CAUTION.
 Delete, move, and copy operations should use the shell tool.
 """
 
@@ -15,14 +14,14 @@
 from agentic_cli.file_utils import atomic_write_text
 from agentic_cli.tools.registry import (
     ToolCategory,
-    PermissionLevel,
     register_tool,
 )
+from agentic_cli.workflow.permissions import Capability
 
 
 @register_tool(
     category=ToolCategory.WRITE,
-    permission_level=PermissionLevel.CAUTION,
+    capabilities=[Capability("filesystem.write", target_arg="path")],
     description="Write content to a file (creates or overwrites). Use this to create new files or replace entire file contents. For partial modifications use edit_file instead.",
 )
 def write_file(
@@ -87,7 +86,7 @@ def write_file(
 
 @register_tool(
     category=ToolCategory.WRITE,
-    permission_level=PermissionLevel.CAUTION,
+    capabilities=[Capability("filesystem.read", target_arg="path"), Capability("filesystem.write", target_arg="path")],
     description="Replace specific text in an existing file. Use this for targeted edits (find-and-replace). For creating or fully rewriting files use write_file instead.",
 )
 def edit_file(

src/agentic_cli/tools/glob_tool.py

@@ -2,8 +2,6 @@
 
 Provides file discovery using glob patterns:
 - glob: Find files matching a pattern (also serves as directory listing)
-
-This is a read-only tool with PermissionLevel.SAFE.
 """
 
 import os
@@ -13,14 +11,14 @@
 
 from agentic_cli.tools.registry import (
     ToolCategory,
-    PermissionLevel,
     register_tool,
 )
+from agentic_cli.workflow.permissions import Capability
 
 
 @register_tool(
     category=ToolCategory.READ,
-    permission_level=PermissionLevel.SAFE,
+    capabilities=[Capability("filesystem.read", target_arg="path")],
     description="Find files by name pattern (e.g. '**/*.py'). Use this to discover files in a directory tree. For searching inside file contents, use grep instead.",
 )
 def glob(
@@ -137,7 +135,7 @@ def glob(
 
 @register_tool(
     category=ToolCategory.READ,
-    permission_level=PermissionLevel.SAFE,
+    capabilities=[Capability("filesystem.read", target_arg="path")],
     description="List directory contents organized by type (directories first, then files). Use this when you need a structured overview of a directory; for pattern-based file search use glob.",
 )
 def list_dir(

src/agentic_cli/tools/grep_tool.py

@@ -2,8 +2,6 @@
 
 Provides pattern-based content search across files:
 - grep: Search for patterns in files (ripgrep-like interface)
-
-This is a read-only tool with PermissionLevel.SAFE.
 """
 
 import functools
@@ -14,14 +12,14 @@
 
 from agentic_cli.tools.registry import (
     ToolCategory,
-    PermissionLevel,
     register_tool,
 )
+from agentic_cli.workflow.permissions import Capability
 
 
 @register_tool(
     category=ToolCategory.READ,
-    permission_level=PermissionLevel.SAFE,
+    capabilities=[Capability("filesystem.read", target_arg="path")],
     description="Search for text patterns inside file contents (regex or literal). Use this to find code references, function definitions, or any text across files. For finding files by name, use glob instead.",
 )
 def grep(