Merge remote-tracking branch 'upstream/dev' into feat/ui-revamp

surfsense_backend/app/agents/multi_agent_chat/subagents/builtins/deliverables/agent.py

@@ -1,55 +1,44 @@
-"""`deliverables` route: ``SubAgent`` spec for deepagents."""
+"""``deliverables`` route: ``SurfSenseSubagentSpec`` builder for deepagents.
+
+Tools self-gate inside their bodies via :func:`request_approval`; the
+empty :data:`tools.index.RULESET` is layered into a per-subagent
+:class:`PermissionMiddleware` for uniformity.
+"""
 
 from __future__ import annotations
 
-from collections.abc import Sequence
 from typing import Any
 
-from deepagents import SubAgent
 from langchain_core.language_models import BaseChatModel
+from langchain_core.tools import BaseTool
 
-from app.agents.multi_agent_chat.subagents.shared.md_file_reader import (
-    read_md_file,
-)
-from app.agents.multi_agent_chat.subagents.shared.permissions import (
-    ToolsPermissions,
-    merge_tools_permissions,
-    middleware_gated_interrupt_on,
-)
-from app.agents.multi_agent_chat.subagents.shared.subagent_builder import (
-    pack_subagent,
-)
+from app.agents.multi_agent_chat.subagents.shared.md_file_reader import read_md_file
+from app.agents.multi_agent_chat.subagents.shared.spec import SurfSenseSubagentSpec
+from app.agents.multi_agent_chat.subagents.shared.subagent_builder import pack_subagent
 
-from .tools.index import load_tools
-
-NAME = "deliverables"
+from .tools.index import NAME, RULESET, load_tools
 
 
 def build_subagent(
     *,
     dependencies: dict[str, Any],
     model: BaseChatModel | None = None,
-    extra_middleware: Sequence[Any] | None = None,
-    extra_tools_bucket: ToolsPermissions | None = None,
-) -> SubAgent:
-    buckets = load_tools(dependencies=dependencies)
-    merged_tools_bucket = merge_tools_permissions(buckets, extra_tools_bucket)
-    tools = [
-        row["tool"]
-        for row in (*merged_tools_bucket["allow"], *merged_tools_bucket["ask"])
-        if row.get("tool") is not None
-    ]
-    interrupt_on = middleware_gated_interrupt_on(merged_tools_bucket)
-    description = read_md_file(__package__, "description").strip()
-    if not description:
-        description = "Handles deliverables tasks for this workspace."
+    middleware_stack: dict[str, Any] | None = None,
+    mcp_tools: list[BaseTool] | None = None,
+) -> SurfSenseSubagentSpec:
+    tools = [*load_tools(dependencies=dependencies), *(mcp_tools or [])]
+    description = (
+        read_md_file(__package__, "description").strip()
+        or "Handles deliverables tasks for this workspace."
+    )
     system_prompt = read_md_file(__package__, "system_prompt").strip()
     return pack_subagent(
         name=NAME,
         description=description,
         system_prompt=system_prompt,
         tools=tools,
-        interrupt_on=interrupt_on,
+        ruleset=RULESET,
+        dependencies=dependencies,
         model=model,
-        extra_middleware=extra_middleware,
+        middleware_stack=middleware_stack,
     )

surfsense_backend/app/agents/multi_agent_chat/subagents/builtins/deliverables/description.md

@@ -1 +1,2 @@
-Use for deliverables and shareable artifacts: generated reports, podcasts, video presentations, resumes, and images—not for routine lookups or single small edits elsewhere.
+Specialist for producing long-form deliverables: reports, podcasts, video presentations, resumes, and generated images.
+Use proactively when the user wants one of these artifacts produced.

surfsense_backend/app/agents/multi_agent_chat/subagents/builtins/deliverables/tools/index.py

@@ -1,10 +1,15 @@
+"""``deliverables`` native tools and (empty) permission ruleset.
+
+Tools self-gate via :func:`request_approval` in their bodies.
+"""
+
 from __future__ import annotations
 
 from typing import Any
 
-from app.agents.multi_agent_chat.subagents.shared.permissions import (
-    ToolsPermissions,
-)
+from langchain_core.tools import BaseTool
+
+from app.agents.new_chat.permissions import Ruleset
 
 from .generate_image import create_generate_image_tool
 from .podcast import create_generate_podcast_tool
@@ -12,43 +17,39 @@ from .report import create_generate_report_tool
 from .resume import create_generate_resume_tool
 from .video_presentation import create_generate_video_presentation_tool
 
+NAME = "deliverables"
+
+RULESET = Ruleset(origin=NAME, rules=[])
+
 
 def load_tools(
     *, dependencies: dict[str, Any] | None = None, **kwargs: Any
-) -> ToolsPermissions:
-    resolved_dependencies = {**(dependencies or {}), **kwargs}
-    podcast = create_generate_podcast_tool(
-        search_space_id=resolved_dependencies["search_space_id"],
-        db_session=resolved_dependencies["db_session"],
-        thread_id=resolved_dependencies["thread_id"],
-    )
-    video = create_generate_video_presentation_tool(
-        search_space_id=resolved_dependencies["search_space_id"],
-        db_session=resolved_dependencies["db_session"],
-        thread_id=resolved_dependencies["thread_id"],
-    )
-    report = create_generate_report_tool(
-        search_space_id=resolved_dependencies["search_space_id"],
-        thread_id=resolved_dependencies["thread_id"],
-        connector_service=resolved_dependencies.get("connector_service"),
-        available_connectors=resolved_dependencies.get("available_connectors"),
-        available_document_types=resolved_dependencies.get("available_document_types"),
-    )
-    resume = create_generate_resume_tool(
-        search_space_id=resolved_dependencies["search_space_id"],
-        thread_id=resolved_dependencies["thread_id"],
-    )
-    image = create_generate_image_tool(
-        search_space_id=resolved_dependencies["search_space_id"],
-        db_session=resolved_dependencies["db_session"],
-    )
-    return {
-        "allow": [
-            {"name": getattr(podcast, "name", "") or "", "tool": podcast},
-            {"name": getattr(video, "name", "") or "", "tool": video},
-            {"name": getattr(report, "name", "") or "", "tool": report},
-            {"name": getattr(resume, "name", "") or "", "tool": resume},
-            {"name": getattr(image, "name", "") or "", "tool": image},
-        ],
-        "ask": [],
-    }
+) -> list[BaseTool]:
+    d = {**(dependencies or {}), **kwargs}
+    return [
+        create_generate_podcast_tool(
+            search_space_id=d["search_space_id"],
+            db_session=d["db_session"],
+            thread_id=d["thread_id"],
+        ),
+        create_generate_video_presentation_tool(
+            search_space_id=d["search_space_id"],
+            db_session=d["db_session"],
+            thread_id=d["thread_id"],
+        ),
+        create_generate_report_tool(
+            search_space_id=d["search_space_id"],
+            thread_id=d["thread_id"],
+            connector_service=d.get("connector_service"),
+            available_connectors=d.get("available_connectors"),
+            available_document_types=d.get("available_document_types"),
+        ),
+        create_generate_resume_tool(
+            search_space_id=d["search_space_id"],
+            thread_id=d["thread_id"],
+        ),
+        create_generate_image_tool(
+            search_space_id=d["search_space_id"],
+            db_session=d["db_session"],
+        ),
+    ]

surfsense_backend/app/agents/multi_agent_chat/subagents/builtins/general_purpose/agent.py

@@ -1,105 +0,0 @@
-"""General-purpose subagent for the multi-agent main agent."""
-
-from __future__ import annotations
-
-from collections.abc import Sequence
-from typing import Any, cast
-
-from deepagents import SubAgent
-from deepagents.middleware.patch_tool_calls import PatchToolCallsMiddleware
-from deepagents.middleware.subagents import GENERAL_PURPOSE_SUBAGENT
-from langchain_anthropic.middleware import AnthropicPromptCachingMiddleware
-from langchain_core.language_models import BaseChatModel
-from langchain_core.tools import BaseTool
-
-from app.agents.multi_agent_chat.middleware.shared.anthropic_cache import (
-    build_anthropic_cache_mw,
-)
-from app.agents.multi_agent_chat.middleware.shared.compaction import (
-    build_compaction_mw,
-)
-from app.agents.multi_agent_chat.middleware.shared.file_intent import (
-    build_file_intent_mw,
-)
-from app.agents.multi_agent_chat.middleware.shared.filesystem import (
-    build_filesystem_mw,
-)
-from app.agents.multi_agent_chat.middleware.shared.patch_tool_calls import (
-    build_patch_tool_calls_mw,
-)
-from app.agents.multi_agent_chat.middleware.shared.permissions import (
-    PermissionContext,
-)
-from app.agents.multi_agent_chat.middleware.shared.resilience import (
-    ResilienceBundle,
-)
-from app.agents.multi_agent_chat.middleware.shared.todos import build_todos_mw
-from app.agents.new_chat.filesystem_selection import FilesystemMode
-from app.agents.new_chat.middleware import MemoryInjectionMiddleware
-
-NAME = "general-purpose"
-
-
-def build_subagent(
-    *,
-    llm: BaseChatModel,
-    tools: Sequence[BaseTool],
-    backend_resolver: Any,
-    filesystem_mode: FilesystemMode,
-    search_space_id: int,
-    user_id: str | None,
-    thread_id: int | None,
-    permissions: PermissionContext,
-    resilience: ResilienceBundle,
-    memory_mw: MemoryInjectionMiddleware,
-) -> SubAgent:
-    """Deny + resilience inserts encapsulated here so the orchestrator never mutates the list."""
-    middleware: list[Any] = [
-        build_todos_mw(),
-        memory_mw,
-        build_file_intent_mw(llm),
-        build_filesystem_mw(
-            backend_resolver=backend_resolver,
-            filesystem_mode=filesystem_mode,
-            search_space_id=search_space_id,
-            user_id=user_id,
-            thread_id=thread_id,
-        ),
-        build_compaction_mw(llm),
-        build_patch_tool_calls_mw(),
-        build_anthropic_cache_mw(),
-    ]
-
-    if permissions.subagent_deny_mw is not None:
-        patch_idx = next(
-            (
-                i
-                for i, m in enumerate(middleware)
-                if isinstance(m, PatchToolCallsMiddleware)
-            ),
-            len(middleware),
-        )
-        middleware.insert(patch_idx, permissions.subagent_deny_mw)
-
-    resilience_mws = resilience.as_list()
-    if resilience_mws:
-        cache_idx = next(
-            (
-                i
-                for i, m in enumerate(middleware)
-                if isinstance(m, AnthropicPromptCachingMiddleware)
-            ),
-            len(middleware),
-        )
-        for offset, mw in enumerate(resilience_mws):
-            middleware.insert(cache_idx + offset, mw)
-
-    spec: dict[str, Any] = {
-        **GENERAL_PURPOSE_SUBAGENT,
-        "model": llm,
-        "tools": tools,
-        "middleware": middleware,
-    }
-    if permissions.general_purpose_interrupt_on:
-        spec["interrupt_on"] = permissions.general_purpose_interrupt_on
-    return cast(SubAgent, spec)

surfsense_backend/app/agents/multi_agent_chat/subagents/builtins/knowledge_base/agent.py

@@ -0,0 +1,92 @@
+"""``knowledge_base`` route: full and read-only ``SurfSenseSubagentSpec`` builders.
+
+KB owns its destructive-FS approval ruleset (:data:`KB_RULESET`); rules
+are layered into KB's :class:`PermissionMiddleware` (built inside
+``build_kb_middleware``). One emitter, one wire format, one source of truth.
+"""
+
+from __future__ import annotations
+
+from typing import Any, cast
+
+from deepagents import SubAgent
+from langchain_core.language_models import BaseChatModel
+from langchain_core.tools import BaseTool
+
+from app.agents.multi_agent_chat.subagents.shared.spec import SurfSenseSubagentSpec
+from app.agents.new_chat.filesystem_selection import FilesystemMode
+from app.agents.new_chat.permissions import Rule, Ruleset
+
+from .middleware_stack import build_kb_middleware
+from .prompts import load_description, load_readonly_system_prompt, load_system_prompt
+from .tools.index import DESTRUCTIVE_FS_OPS
+
+NAME = "knowledge_base"
+READONLY_NAME = "knowledge_base_readonly"
+
+KB_RULESET = Ruleset(
+    origin=NAME,
+    rules=[Rule(permission=op, pattern="*", action="ask") for op in DESTRUCTIVE_FS_OPS],
+)
+
+_KB_READONLY_RULESET = Ruleset(origin=READONLY_NAME, rules=[])
+
+
+def build_subagent(
+    *,
+    dependencies: dict[str, Any],
+    model: BaseChatModel | None = None,
+    middleware_stack: dict[str, Any] | None = None,
+    mcp_tools: list[BaseTool] | None = None,
+) -> SurfSenseSubagentSpec:
+    del mcp_tools
+    llm = model if model is not None else dependencies["llm"]
+    filesystem_mode: FilesystemMode = dependencies["filesystem_mode"]
+    spec = cast(
+        SubAgent,
+        {
+            "name": NAME,
+            "description": load_description(),
+            "system_prompt": load_system_prompt(filesystem_mode),
+            "model": llm,
+            "tools": [],
+            "middleware": build_kb_middleware(
+                llm=llm,
+                dependencies=dependencies,
+                middleware_stack=middleware_stack,
+                read_only=False,
+                subagent_name=NAME,
+                ruleset=KB_RULESET,
+            ),
+        },
+    )
+    return SurfSenseSubagentSpec(spec=spec, ruleset=KB_RULESET)
+
+
+def build_readonly_subagent(
+    *,
+    dependencies: dict[str, Any],
+    model: BaseChatModel | None = None,
+    middleware_stack: dict[str, Any] | None = None,
+) -> SurfSenseSubagentSpec:
+    llm = model if model is not None else dependencies["llm"]
+    filesystem_mode: FilesystemMode = dependencies["filesystem_mode"]
+    spec = cast(
+        SubAgent,
+        {
+            "name": READONLY_NAME,
+            "description": "Read-only knowledge_base specialist (invoked via ask_knowledge_base).",
+            "system_prompt": load_readonly_system_prompt(filesystem_mode),
+            "model": llm,
+            "tools": [],
+            "middleware": build_kb_middleware(
+                llm=llm,
+                dependencies=dependencies,
+                middleware_stack=middleware_stack,
+                read_only=True,
+                subagent_name=READONLY_NAME,
+                ruleset=None,
+            ),
+        },
+    )
+    return SurfSenseSubagentSpec(spec=spec, ruleset=_KB_READONLY_RULESET)

surfsense_backend/app/agents/multi_agent_chat/subagents/builtins/knowledge_base/ask_knowledge_base_tool.py

@@ -0,0 +1,80 @@
+"""Wrap the read-only knowledge_base runnable as the ``ask_knowledge_base`` tool."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from langchain.tools import BaseTool, ToolRuntime
+from langchain_core.messages import HumanMessage, ToolMessage
+from langchain_core.runnables import Runnable
+from langchain_core.tools import StructuredTool
+from langgraph.types import Command
+
+from app.agents.multi_agent_chat.middleware.main_agent.checkpointed_subagent_middleware.config import (
+    subagent_invoke_config,
+)
+from app.agents.multi_agent_chat.middleware.main_agent.checkpointed_subagent_middleware.constants import (
+    EXCLUDED_STATE_KEYS,
+)
+
+from .prompts import load_readonly_description
+
+TOOL_NAME = "ask_knowledge_base"
+
+
+def _forward_state(runtime: ToolRuntime, query: str) -> dict:
+    forwarded = {k: v for k, v in runtime.state.items() if k not in EXCLUDED_STATE_KEYS}
+    forwarded["messages"] = [HumanMessage(content=query)]
+    return forwarded
+
+
+def _wrap_result(result: dict, tool_call_id: str) -> Command:
+    messages = result.get("messages") or []
+    if not messages:
+        raise ValueError(
+            "knowledge_base_readonly returned an empty 'messages' list; "
+            "expected at least one assistant message."
+        )
+    last_text = (getattr(messages[-1], "text", None) or "").rstrip()
+    return Command(
+        update={"messages": [ToolMessage(last_text, tool_call_id=tool_call_id)]}
+    )
+
+
+def build_ask_knowledge_base_tool(kb_readonly_runnable: Runnable) -> BaseTool:
+    def ask_knowledge_base(
+        query: Annotated[
+            str,
+            "Full question for the workspace specialist. Include all path hints, "
+            "filters, and constraints the specialist needs to answer.",
+        ],
+        runtime: ToolRuntime,
+    ) -> str | Command:
+        if not runtime.tool_call_id:
+            raise ValueError("Tool call ID is required for ask_knowledge_base")
+        sub_state = _forward_state(runtime, query)
+        sub_config = subagent_invoke_config(runtime)
+        result = kb_readonly_runnable.invoke(sub_state, config=sub_config)
+        return _wrap_result(result, runtime.tool_call_id)
+
+    async def aask_knowledge_base(
+        query: Annotated[
+            str,
+            "Full question for the workspace specialist. Include all path hints, "
+            "filters, and constraints the specialist needs to answer.",
+        ],
+        runtime: ToolRuntime,
+    ) -> str | Command:
+        if not runtime.tool_call_id:
+            raise ValueError("Tool call ID is required for ask_knowledge_base")
+        sub_state = _forward_state(runtime, query)
+        sub_config = subagent_invoke_config(runtime)
+        result = await kb_readonly_runnable.ainvoke(sub_state, config=sub_config)
+        return _wrap_result(result, runtime.tool_call_id)
+
+    return StructuredTool.from_function(
+        name=TOOL_NAME,
+        func=ask_knowledge_base,
+        coroutine=aask_knowledge_base,
+        description=load_readonly_description(),
+    )

surfsense_backend/app/agents/multi_agent_chat/subagents/builtins/knowledge_base/description.md

@@ -0,0 +1,2 @@
+Specialist for the user's workspace (documents and folders).
+Use proactively when the user wants to create, read, edit, search, organise, or remove a document or folder.

surfsense_backend/app/agents/multi_agent_chat/subagents/builtins/knowledge_base/description_readonly.md

@@ -0,0 +1,5 @@
+Read-only specialist for the user's workspace (documents and folders). Use to find, read, search, or quote a document or folder when your task needs workspace context — instead of asking the user or guessing.
+
+Pass your full question as one string. The specialist runs in isolation: it cannot see this thread, so include any path hints, filters, or constraints it needs.
+
+The specialist returns plain prose with absolute paths.

surfsense_backend/app/agents/multi_agent_chat/subagents/builtins/knowledge_base/middleware_stack.py

@@ -0,0 +1,117 @@
+"""Middleware list shared by the full and read-only knowledge_base compiles.
+
+The KB-owned :class:`PermissionMiddleware` slot is what enforces
+"ask before destructive FS op" for KB tools.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from langchain_core.language_models import BaseChatModel
+
+from app.agents.multi_agent_chat.middleware.shared.anthropic_cache import (
+    build_anthropic_cache_mw,
+)
+from app.agents.multi_agent_chat.middleware.shared.compaction import (
+    build_compaction_mw,
+)
+from app.agents.multi_agent_chat.middleware.shared.filesystem import (
+    build_filesystem_mw,
+)
+from app.agents.multi_agent_chat.middleware.shared.kb_context_projection import (
+    build_kb_context_projection_mw,
+)
+from app.agents.multi_agent_chat.middleware.shared.patch_tool_calls import (
+    build_patch_tool_calls_mw,
+)
+from app.agents.multi_agent_chat.middleware.shared.permissions import (
+    build_permission_mw,
+)
+from app.agents.new_chat.feature_flags import AgentFeatureFlags
+from app.agents.new_chat.filesystem_selection import FilesystemMode
+from app.agents.new_chat.permissions import Ruleset
+
+
+def _kb_user_allowlist(
+    dependencies: dict[str, Any], subagent_name: str
+) -> Ruleset | None:
+    """Return the user's persisted allow-rules for ``subagent_name`` if any.
+
+    KB does not currently expose an "Always Allow" UI surface (the FE
+    button is MCP-only today), but the wiring is symmetrical with the
+    connector subagents so that adding KB trust later is a one-line
+    backend change.
+    """
+    by_subagent = dependencies.get("user_allowlist_by_subagent") or {}
+    user_allowlist = by_subagent.get(subagent_name)
+    if isinstance(user_allowlist, Ruleset) and user_allowlist.rules:
+        return user_allowlist
+    return None
+
+
+def build_kb_middleware(
+    *,
+    llm: BaseChatModel,
+    dependencies: dict[str, Any],
+    middleware_stack: dict[str, Any] | None,
+    read_only: bool,
+    subagent_name: str,
+    ruleset: Ruleset | None = None,
+) -> list[Any]:
+    """Compose the KB subagent's middleware list.
+
+    Args:
+        subagent_name: Identity of the subagent being built (e.g.
+            ``"knowledge_base"``, ``"knowledge_base_readonly"``). Used to
+            look up the user's persistent allow-list bucket in
+            ``dependencies["user_allowlist_by_subagent"]``.
+        ruleset: The KB-owned permission ruleset (typically the
+            destructive-FS ``ask`` rules). When provided, a dedicated
+            :class:`PermissionMiddleware` is appended so KB enforces
+            approval at the rule layer. The user's persistent allow-list
+            for ``subagent_name`` is layered after ``ruleset`` so user
+            ``allow`` rules override coded ``ask`` rules via
+            last-match-wins.
+    """
+    mws = middleware_stack or {}
+    filesystem_mode: FilesystemMode = dependencies["filesystem_mode"]
+    flags: AgentFeatureFlags | None = dependencies.get("flags")
+    resilience_mws = [
+        m
+        for m in (
+            mws.get("retry"),
+            mws.get("fallback"),
+            mws.get("model_call_limit"),
+            mws.get("tool_call_limit"),
+        )
+        if m is not None
+    ]
+    permission_mw = None
+    if ruleset is not None and flags is not None:
+        rulesets: list[Ruleset] = [ruleset]
+        user_allowlist = _kb_user_allowlist(dependencies, subagent_name)
+        if user_allowlist is not None:
+            rulesets.append(user_allowlist)
+        permission_mw = build_permission_mw(
+            flags=flags,
+            subagent_rulesets=rulesets,
+            trusted_tool_saver=dependencies.get("trusted_tool_saver"),
+        )
+    return [
+        mws["todos"],
+        build_kb_context_projection_mw(),
+        build_filesystem_mw(
+            backend_resolver=dependencies["backend_resolver"],
+            filesystem_mode=filesystem_mode,
+            search_space_id=dependencies["search_space_id"],
+            user_id=dependencies.get("user_id"),
+            thread_id=dependencies.get("thread_id"),
+            read_only=read_only,
+        ),
+        build_compaction_mw(llm),
+        build_patch_tool_calls_mw(),
+        *([permission_mw] if permission_mw is not None else []),
+        *resilience_mws,
+        build_anthropic_cache_mw(),
+    ]

surfsense_backend/app/agents/multi_agent_chat/subagents/builtins/knowledge_base/prompts.py

@@ -0,0 +1,34 @@
+"""Prompt loaders for the knowledge_base subagent."""
+
+from __future__ import annotations
+
+from app.agents.multi_agent_chat.subagents.shared.md_file_reader import read_md_file
+from app.agents.new_chat.filesystem_selection import FilesystemMode
+
+
+def load_system_prompt(filesystem_mode: FilesystemMode) -> str:
+    stem = (
+        "system_prompt_cloud"
+        if filesystem_mode == FilesystemMode.CLOUD
+        else "system_prompt_desktop"
+    )
+    return read_md_file(__package__, stem).strip()
+
+
+def load_readonly_system_prompt(filesystem_mode: FilesystemMode) -> str:
+    stem = (
+        "system_prompt_readonly_cloud"
+        if filesystem_mode == FilesystemMode.CLOUD
+        else "system_prompt_readonly_desktop"
+    )
+    return read_md_file(__package__, stem).strip()
+
+
+def load_description() -> str:
+    return read_md_file(__package__, "description").strip() or (
+        "Handles knowledge-base reads, writes, edits, and organisation."
+    )
+
+
+def load_readonly_description() -> str:
+    return read_md_file(__package__, "description_readonly").strip()

surfsense_backend/app/agents/multi_agent_chat/subagents/builtins/knowledge_base/system_prompt_cloud.md

@@ -0,0 +1,122 @@
+You are the SurfSense knowledge base specialist for the user's `/documents/` workspace.
+
+## Required inputs
+
+**Resolve paths from the supervisor's task text before asking.**
+
+- If the supervisor already provided a precise path (e.g. `/documents/notes/2026-05-11.md`), use it directly — skip the lookup steps below.
+- Otherwise, most requests reference documents by description (`"my meeting notes from last week"`, `"the design doc"`). Resolve them yourself:
+  1. Consult `<priority_documents>` — it's a hint about top-K likely matches, not a directive. Skip when the ranked entries don't fit the task.
+  2. Walk `<workspace_tree>` for descriptive folder/filename matches.
+  3. Use the `glob` tool for filename patterns the tree didn't surface, and the `grep` tool when the description points at *content* rather than a name.
+  4. Only return `status=blocked` with `missing_fields=["path"]` when the description is genuinely ambiguous after a thorough lookup.
+
+For writes (where you choose the path yourself):
+
+- **Discover the user's existing conventions before inventing a path.** Scan `<workspace_tree>` for folders that already hold similar content (e.g. an existing `/documents/meetings/` with dated standup notes, or `/documents/projects/<name>/`). When a convention exists, follow it. Use `ls`, `glob`, or `grep` to look closer when the tree is truncated.
+- Only choose a brand-new path when no relevant convention exists. Prefer a clear folder hierarchy with a descriptive filename.
+- Use the `temp_` prefix only for scratch content you do **not** want persisted.
+- Prefer the `edit_file` tool over rewriting an entire document.
+
+## Interpreting tool results
+
+The FS tools return free-form text rather than structured fields:
+
+- **Success** — a confirmation message that names the path (e.g. `"Updated file /documents/foo.md"`, `"Successfully replaced 2 instance(s) of the string in '/documents/foo.md'"`) or the file's content (for reads).
+- **Failure** — text starting with `"Error: "` followed by a cause (e.g. `"Error: File '/documents/x.md' not found"`).
+- **HITL declined** — a runtime-supplied rejection message in place of the tool's output.
+
+Map outcomes to your `status`:
+
+- Clean success message or content returned → `status=success`.
+- `"Error: …not found"` → `status=blocked` with `next_step="Document '<description>' was not found. Ask the user to confirm or provide more detail."`.
+- Any other `"Error: …"` → `status=error` and relay the tool's message verbatim as `next_step`.
+- HITL rejection → `status=blocked` with `next_step="User declined this filesystem action. Do not retry."`.
+
+You construct the structured `evidence` fields from your own knowledge of what you called and what you observed — the tools do not return them. Never report values you did not actually see.
+
+## Examples
+
+**Example 1 — happy path write (path discovered from existing convention):**
+
+- *Supervisor task:* `"Save these meeting notes to my KB: <notes>"`
+- *You:* scan `<workspace_tree>` and spot `/documents/meetings/` already holding files like `2026-05-04-standup.md` and `2026-04-27-standup.md` — the user's convention is dated meeting notes under that folder. → `write_file("/documents/meetings/2026-05-11-meeting.md", content)` → success.
+- *Output:*
+
+  ```json
+  {
+    "status": "success",
+    "action_summary": "Created /documents/meetings/2026-05-11-meeting.md.",
+    "evidence": {
+      "operation": "write_file",
+      "path": "/documents/meetings/2026-05-11-meeting.md",
+      "matched_candidates": null,
+      "content_excerpt": null,
+      "chunk_ids": null
+    },
+    "next_step": null,
+    "missing_fields": null,
+    "assumptions": ["Followed the existing /documents/meetings/<YYYY-MM-DD>-<slug>.md convention from <workspace_tree>"]
+  }
+  ```
+
+**Example 2 — edit by inference:**
+
+- *Supervisor task:* `"Add a bullet about the new feature flag to my Q2 roadmap"`
+- *You:* search for the roadmap doc — check `<priority_documents>` and `<workspace_tree>` first; if neither surfaces it, widen with the `glob` tool (try filename patterns the user's language suggests) or the `grep` tool (search by content). Suppose `<priority_documents>` hits `/documents/planning/q2-roadmap.md` → `read_file("/documents/planning/q2-roadmap.md")` → `edit_file("/documents/planning/q2-roadmap.md", old, new)` → success.
+- *Output:* `status=success`, evidence includes path and the inserted snippet.
+
+**Example 3 — blocked, multiple candidates:**
+
+- *Supervisor task:* `"Update the design doc."`
+- *You:* `<workspace_tree>` shows several plausible design docs and the task gives no further hint. Do not pick arbitrarily.
+- *Output:*
+
+  ```json
+  {
+    "status": "blocked",
+    "action_summary": "Multiple design docs exist; cannot pick without more detail.",
+    "evidence": {
+      "operation": null,
+      "path": null,
+      "matched_candidates": [
+        { "id": "/documents/design/payment-flow.md", "label": "Payment Flow" },
+        { "id": "/documents/design/auth-rework.md", "label": "Auth Rework" }
+      ],
+      "content_excerpt": null,
+      "chunk_ids": null
+    },
+    "next_step": "Ask the user which design doc to update.",
+    "missing_fields": ["path"],
+    "assumptions": null
+  }
+  ```
+
+## Output contract
+
+Return **only** one JSON object (no markdown or prose outside it):
+
+```json
+{
+  "status": "success" | "partial" | "blocked" | "error",
+  "action_summary": string,
+  "evidence": {
+    "operation": "write_file" | "edit_file" | "read_file" | "ls" | "glob" | "grep" | "mkdir" | "move_file" | "rm" | "rmdir" | "list_tree" | null,
+    "path": string | null,
+    "matched_candidates": [ { "id": string, "label": string } ] | null,
+    "content_excerpt": string | null,
+    "chunk_ids": string[] | null
+  },
+  "next_step": string | null,
+  "missing_fields": string[] | null,
+  "assumptions": string[] | null
+}
+```
+
+Rules:
+
+- `status=success` → `next_step=null`, `missing_fields=null`.
+- `status=partial|blocked|error` → `next_step` must be non-null.
+- `status=blocked` due to missing required inputs → `missing_fields` must be non-null.
+
+Infer before you call; map every tool outcome faithfully.

surfsense_backend/app/agents/multi_agent_chat/subagents/builtins/knowledge_base/system_prompt_desktop.md

@@ -0,0 +1,122 @@
+You are the SurfSense workspace specialist for the user's local folders.
+
+## Required inputs
+
+**Resolve paths from the supervisor's task text before asking.**
+
+- If the supervisor already provided a precise path (e.g. `/notes/2026-05-11.md`), use it directly — skip the lookup steps below.
+- Otherwise, most requests reference files by description (`"my meeting notes from last week"`, `"the design doc"`). Resolve them yourself:
+  1. If you do not know which mounts exist, call `ls('/')` first.
+  2. Walk likely folders with the `ls` and `list_tree` tools.
+  3. Use the `glob` tool for filename patterns; use the `grep` tool when the description points at *content* rather than a name.
+  4. `<priority_documents>` lists top-K cloud-ingested docs, not local files — consult it only when the task spans both worlds (e.g. drafting a local note from a Notion source). Skip otherwise.
+  5. Only return `status=blocked` with `missing_fields=["path"]` when the description is genuinely ambiguous after a thorough lookup.
+
+For writes (where you choose the path yourself):
+
+- **Discover the user's existing conventions before inventing a path.** Inspect the relevant mount's folder layout via `ls` / `list_tree` and look for folders that already hold similar content (e.g. an existing `/notes/meetings/` with dated standup files, or `/projects/<name>/`). When a convention exists, follow it.
+- Only choose a brand-new path when no relevant convention exists. Prefer a clear folder hierarchy with a descriptive filename.
+- Prefer the `edit_file` tool over rewriting an entire file.
+
+## Interpreting tool results
+
+The FS tools return free-form text rather than structured fields:
+
+- **Success** — a confirmation message that names the path (e.g. `"Updated file /notes/foo.md"`, `"Successfully replaced 2 instance(s) of the string in '/notes/foo.md'"`) or the file's content (for reads).
+- **Failure** — text starting with `"Error: "` followed by a cause (e.g. `"Error: File '/notes/x.md' not found"`).
+- **HITL declined** — a runtime-supplied rejection message in place of the tool's output.
+
+Map outcomes to your `status`:
+
+- Clean success message or content returned → `status=success`.
+- `"Error: …not found"` → `status=blocked` with `next_step="File '<description>' was not found. Ask the user to confirm or provide more detail."`.
+- Any other `"Error: …"` → `status=error` and relay the tool's message verbatim as `next_step`.
+- HITL rejection → `status=blocked` with `next_step="User declined this filesystem action. Do not retry."`.
+
+You construct the structured `evidence` fields from your own knowledge of what you called and what you observed — the tools do not return them. `chunk_ids` apply only to `<priority_documents>` hits; for local-file operations leave them `null`. Never report values you did not actually see.
+
+## Examples
+
+**Example 1 — happy path write (path discovered from existing convention):**
+
+- *Supervisor task:* `"Save these meeting notes to my notes folder: <notes>"`
+- *You:* `ls('/')` reveals a `/notes` mount → `list_tree('/notes')` shows `/notes/meetings/` already holds dated files like `2026-05-04-standup.md` and `2026-04-27-standup.md` — the user's convention is dated meeting notes under that folder. → `write_file("/notes/meetings/2026-05-11-meeting.md", content)` → success.
+- *Output:*
+
+  ```json
+  {
+    "status": "success",
+    "action_summary": "Created /notes/meetings/2026-05-11-meeting.md.",
+    "evidence": {
+      "operation": "write_file",
+      "path": "/notes/meetings/2026-05-11-meeting.md",
+      "matched_candidates": null,
+      "content_excerpt": null,
+      "chunk_ids": null
+    },
+    "next_step": null,
+    "missing_fields": null,
+    "assumptions": ["Followed the existing /notes/meetings/<YYYY-MM-DD>-<slug>.md convention discovered via list_tree"]
+  }
+  ```
+
+**Example 2 — edit by inference:**
+
+- *Supervisor task:* `"Add a bullet about the new feature flag to my Q2 roadmap"`
+- *You:* search for the roadmap file — `ls('/')` then `glob` for filename patterns; if nothing surfaces, `grep` for content. Suppose `glob` finds `/projects/planning/q2-roadmap.md` → `read_file("/projects/planning/q2-roadmap.md")` → `edit_file("/projects/planning/q2-roadmap.md", old, new)` → success.
+- *Output:* `status=success`, evidence includes path and the inserted snippet.
+
+**Example 3 — blocked, multiple candidates:**
+
+- *Supervisor task:* `"Update the design doc."`
+- *You:* `glob('**/design*')` returns several plausible design files and the task gives no further hint. Do not pick arbitrarily.
+- *Output:*
+
+  ```json
+  {
+    "status": "blocked",
+    "action_summary": "Multiple design docs exist; cannot pick without more detail.",
+    "evidence": {
+      "operation": null,
+      "path": null,
+      "matched_candidates": [
+        { "id": "/projects/web/design/payment-flow.md", "label": "Payment Flow" },
+        { "id": "/projects/web/design/auth-rework.md", "label": "Auth Rework" }
+      ],
+      "content_excerpt": null,
+      "chunk_ids": null
+    },
+    "next_step": "Ask the user which design doc to update.",
+    "missing_fields": ["path"],
+    "assumptions": null
+  }
+  ```
+
+## Output contract
+
+Return **only** one JSON object (no markdown or prose outside it):
+
+```json
+{
+  "status": "success" | "partial" | "blocked" | "error",
+  "action_summary": string,
+  "evidence": {
+    "operation": "write_file" | "edit_file" | "read_file" | "ls" | "glob" | "grep" | "mkdir" | "move_file" | "rm" | "rmdir" | "list_tree" | null,
+    "path": string | null,
+    "matched_candidates": [ { "id": string, "label": string } ] | null,
+    "content_excerpt": string | null,
+    "chunk_ids": string[] | null
+  },
+  "next_step": string | null,
+  "missing_fields": string[] | null,
+  "assumptions": string[] | null
+}
+```
+
+Rules:
+
+- `status=success` → `next_step=null`, `missing_fields=null`.
+- `status=partial|blocked|error` → `next_step` must be non-null.
+- `status=blocked` due to missing required inputs → `missing_fields` must be non-null.
+
+Infer before you call; map every tool outcome faithfully.

surfsense_backend/app/agents/multi_agent_chat/subagents/builtins/knowledge_base/system_prompt_readonly_cloud.md

@@ -0,0 +1,29 @@
+You are the **read-only** SurfSense Knowledge Base specialist for `/documents/`.
+
+You answer workspace questions for another agent. The end user does **not** see your reply directly — be terse, cite paths, no greetings or apologies.
+
+## Resolving paths
+
+The caller's question often references documents by description (`"my meeting notes from last week"`, `"the design doc"`). Resolve them yourself:
+
+1. Consult `<priority_documents>` — a hint about top-K likely matches, not a directive. Skip when the ranked entries don't fit.
+2. Walk `<workspace_tree>` for descriptive folder/filename matches.
+3. Use `glob` for filename patterns the tree didn't surface, and `grep` when the description points at *content* rather than a name.
+
+If a precise path was already given, use it directly — skip the lookup.
+
+## Interpreting tool results
+
+- **Success** — file content (for `read_file`) or a listing (for `ls` / `glob` / `grep` / `list_tree`).
+- **Failure** — text starting with `"Error: "` followed by a cause (e.g. `"Error: File '/documents/x.md' not found"`). Relay the cause to the caller verbatim.
+
+Never report values you did not actually see.
+
+## Return contract
+
+Reply in plain prose:
+
+- One short paragraph or a bullet list, whichever fits.
+- Cite every claim with an absolute path under `/documents/`.
+- If the workspace does not contain the requested information, say so explicitly. Do not fabricate paths or content.
+- If the question is genuinely ambiguous after a thorough lookup, list the candidates with their paths and stop.

surfsense_backend/app/agents/multi_agent_chat/subagents/builtins/knowledge_base/system_prompt_readonly_desktop.md

@@ -0,0 +1,30 @@
+You are the **read-only** SurfSense workspace specialist for the user's local folders.
+
+You answer workspace questions for another agent. The end user does **not** see your reply directly — be terse, cite paths, no greetings or apologies.
+
+## Resolving paths
+
+The caller's question often references files by description (`"my meeting notes from last week"`, `"the design doc"`). Resolve them yourself:
+
+1. If you do not know which mounts exist, call `ls('/')` first.
+2. Walk likely folders with the `ls` and `list_tree` tools.
+3. Use `glob` for filename patterns; use `grep` when the description points at *content* rather than a name.
+4. `<priority_documents>` lists top-K cloud-ingested docs, not local files — consult it only when the task spans both worlds (e.g. drafting a local note from a Notion source). Skip otherwise.
+
+If a precise path was already given, use it directly — skip the lookup.
+
+## Interpreting tool results
+
+- **Success** — file content (for `read_file`) or a listing (for `ls` / `glob` / `grep` / `list_tree`).
+- **Failure** — text starting with `"Error: "` followed by a cause (e.g. `"Error: File '/notes/x.md' not found"`). Relay the cause to the caller verbatim.
+
+Never report values you did not actually see.
+
+## Return contract
+
+Reply in plain prose:
+
+- One short paragraph or a bullet list, whichever fits.
+- Cite every claim with an absolute path.
+- If the workspace does not contain the requested information, say so explicitly. Do not fabricate paths or content.
+- If the question is genuinely ambiguous after a thorough lookup, list the candidates with their paths and stop.

surfsense_backend/app/agents/multi_agent_chat/subagents/builtins/knowledge_base/tools/__init__.py

@@ -0,0 +1 @@
+"""Route-local tool permissions for the ``knowledge_base`` subagent."""

surfsense_backend/app/agents/multi_agent_chat/subagents/builtins/knowledge_base/tools/index.py

@@ -0,0 +1,20 @@
+"""Route-local FS tool permissions.
+
+The KB subagent's actual ``BaseTool`` instances are provided at runtime by
+``SurfSenseFilesystemMiddleware`` (mounted in ``agent.py``). This module
+only carries the *names* of destructive ops so the agent can convert them
+into permission rules — see :data:`KB_RULESET` in ``agent.py``.
+"""
+
+from __future__ import annotations
+
+DESTRUCTIVE_FS_OPS: tuple[str, ...] = (
+    "rm",
+    "rmdir",
+    "move_file",
+    "edit_file",
+    "write_file",
+)
+
+
+__all__ = ["DESTRUCTIVE_FS_OPS"]

surfsense_backend/app/agents/multi_agent_chat/subagents/builtins/memory/agent.py

@@ -1,55 +1,39 @@
-"""`memory` route: ``SubAgent`` spec for deepagents."""
+"""``memory`` route: ``SurfSenseSubagentSpec`` builder for deepagents."""
 
 from __future__ import annotations
 
-from collections.abc import Sequence
 from typing import Any
 
-from deepagents import SubAgent
 from langchain_core.language_models import BaseChatModel
+from langchain_core.tools import BaseTool
 
-from app.agents.multi_agent_chat.subagents.shared.md_file_reader import (
-    read_md_file,
-)
-from app.agents.multi_agent_chat.subagents.shared.permissions import (
-    ToolsPermissions,
-    merge_tools_permissions,
-    middleware_gated_interrupt_on,
-)
-from app.agents.multi_agent_chat.subagents.shared.subagent_builder import (
-    pack_subagent,
-)
+from app.agents.multi_agent_chat.subagents.shared.md_file_reader import read_md_file
+from app.agents.multi_agent_chat.subagents.shared.spec import SurfSenseSubagentSpec
+from app.agents.multi_agent_chat.subagents.shared.subagent_builder import pack_subagent
 
-from .tools.index import load_tools
-
-NAME = "memory"
+from .tools.index import NAME, RULESET, load_tools
 
 
 def build_subagent(
     *,
     dependencies: dict[str, Any],
     model: BaseChatModel | None = None,
-    extra_middleware: Sequence[Any] | None = None,
-    extra_tools_bucket: ToolsPermissions | None = None,
-) -> SubAgent:
-    buckets = load_tools(dependencies=dependencies)
-    merged_tools_bucket = merge_tools_permissions(buckets, extra_tools_bucket)
-    tools = [
-        row["tool"]
-        for row in (*merged_tools_bucket["allow"], *merged_tools_bucket["ask"])
-        if row.get("tool") is not None
-    ]
-    interrupt_on = middleware_gated_interrupt_on(merged_tools_bucket)
-    description = read_md_file(__package__, "description").strip()
-    if not description:
-        description = "Handles memory tasks for this workspace."
+    middleware_stack: dict[str, Any] | None = None,
+    mcp_tools: list[BaseTool] | None = None,
+) -> SurfSenseSubagentSpec:
+    tools = [*load_tools(dependencies=dependencies), *(mcp_tools or [])]
+    description = (
+        read_md_file(__package__, "description").strip()
+        or "Handles memory tasks for this workspace."
+    )
     system_prompt = read_md_file(__package__, "system_prompt").strip()
     return pack_subagent(
         name=NAME,
         description=description,
         system_prompt=system_prompt,
         tools=tools,
-        interrupt_on=interrupt_on,
+        ruleset=RULESET,
+        dependencies=dependencies,
         model=model,
-        extra_middleware=extra_middleware,
+        middleware_stack=middleware_stack,
     )

surfsense_backend/app/agents/multi_agent_chat/subagents/builtins/memory/description.md

@@ -1 +1,2 @@
-Use for storing durable user memory (private team variant selected at runtime).
+Specialist for durable user memory.
+Use whenever a task requires storing or retrieving information that should persist across conversations.

surfsense_backend/app/agents/multi_agent_chat/subagents/builtins/memory/tools/index.py

@@ -1,32 +1,37 @@
+"""``memory`` native tools and (empty) permission ruleset."""
+
 from __future__ import annotations
 
 from typing import Any
 
-from app.agents.multi_agent_chat.subagents.shared.permissions import (
-    ToolsPermissions,
-)
+from langchain_core.tools import BaseTool
+
+from app.agents.new_chat.permissions import Ruleset
 from app.db import ChatVisibility
 
 from .update_memory import create_update_memory_tool, create_update_team_memory_tool
 
+NAME = "memory"
+
+RULESET = Ruleset(origin=NAME, rules=[])
+
 
 def load_tools(
     *, dependencies: dict[str, Any] | None = None, **kwargs: Any
-) -> ToolsPermissions:
-    resolved_dependencies = {**(dependencies or {}), **kwargs}
-    if resolved_dependencies.get("thread_visibility") == ChatVisibility.SEARCH_SPACE:
-        mem = create_update_team_memory_tool(
-            search_space_id=resolved_dependencies["search_space_id"],
-            db_session=resolved_dependencies["db_session"],
-            llm=resolved_dependencies.get("llm"),
+) -> list[BaseTool]:
+    d = {**(dependencies or {}), **kwargs}
+    if d.get("thread_visibility") == ChatVisibility.SEARCH_SPACE:
+        return [
+            create_update_team_memory_tool(
+                search_space_id=d["search_space_id"],
+                db_session=d["db_session"],
+                llm=d.get("llm"),
+            )
+        ]
+    return [
+        create_update_memory_tool(
+            user_id=d["user_id"],
+            db_session=d["db_session"],
+            llm=d.get("llm"),
         )
-        return {
-            "allow": [{"name": getattr(mem, "name", "") or "", "tool": mem}],
-            "ask": [],
-        }
-    mem = create_update_memory_tool(
-        user_id=resolved_dependencies["user_id"],
-        db_session=resolved_dependencies["db_session"],
-        llm=resolved_dependencies.get("llm"),
-    )
-    return {"allow": [{"name": getattr(mem, "name", "") or "", "tool": mem}], "ask": []}
+    ]

surfsense_backend/app/agents/multi_agent_chat/subagents/builtins/research/agent.py

@@ -1,55 +1,39 @@
-"""`research` route: ``SubAgent`` spec for deepagents."""
+"""``research`` route: ``SurfSenseSubagentSpec`` builder for deepagents."""
 
 from __future__ import annotations
 
-from collections.abc import Sequence
 from typing import Any
 
-from deepagents import SubAgent
 from langchain_core.language_models import BaseChatModel
+from langchain_core.tools import BaseTool
 
-from app.agents.multi_agent_chat.subagents.shared.md_file_reader import (
-    read_md_file,
-)
-from app.agents.multi_agent_chat.subagents.shared.permissions import (
-    ToolsPermissions,
-    merge_tools_permissions,
-    middleware_gated_interrupt_on,
-)
-from app.agents.multi_agent_chat.subagents.shared.subagent_builder import (
-    pack_subagent,
-)
+from app.agents.multi_agent_chat.subagents.shared.md_file_reader import read_md_file
+from app.agents.multi_agent_chat.subagents.shared.spec import SurfSenseSubagentSpec
+from app.agents.multi_agent_chat.subagents.shared.subagent_builder import pack_subagent
 
-from .tools.index import load_tools
-
-NAME = "research"
+from .tools.index import NAME, RULESET, load_tools
 
 
 def build_subagent(
     *,
     dependencies: dict[str, Any],
     model: BaseChatModel | None = None,
-    extra_middleware: Sequence[Any] | None = None,
-    extra_tools_bucket: ToolsPermissions | None = None,
-) -> SubAgent:
-    buckets = load_tools(dependencies=dependencies)
-    merged_tools_bucket = merge_tools_permissions(buckets, extra_tools_bucket)
-    tools = [
-        row["tool"]
-        for row in (*merged_tools_bucket["allow"], *merged_tools_bucket["ask"])
-        if row.get("tool") is not None
-    ]
-    interrupt_on = middleware_gated_interrupt_on(merged_tools_bucket)
-    description = read_md_file(__package__, "description").strip()
-    if not description:
-        description = "Handles research tasks for this workspace."
+    middleware_stack: dict[str, Any] | None = None,
+    mcp_tools: list[BaseTool] | None = None,
+) -> SurfSenseSubagentSpec:
+    tools = [*load_tools(dependencies=dependencies), *(mcp_tools or [])]
+    description = (
+        read_md_file(__package__, "description").strip()
+        or "Handles research tasks for this workspace."
+    )
     system_prompt = read_md_file(__package__, "system_prompt").strip()
     return pack_subagent(
         name=NAME,
         description=description,
         system_prompt=system_prompt,
         tools=tools,
-        interrupt_on=interrupt_on,
+        ruleset=RULESET,
+        dependencies=dependencies,
         model=model,
-        extra_middleware=extra_middleware,
+        middleware_stack=middleware_stack,
     )

surfsense_backend/app/agents/multi_agent_chat/subagents/builtins/research/description.md

@@ -1 +1,2 @@
-Use for external research: find sources on the web, extract evidence, and answer documentation questions.
+Specialist for external research.
+Use whenever a task requires finding sources on the web and extracting evidence to answer documentation questions.

surfsense_backend/app/agents/multi_agent_chat/subagents/builtins/research/tools/index.py

@@ -1,35 +1,31 @@
+"""``research`` native tools and (empty) permission ruleset."""
+
 from __future__ import annotations
 
 from typing import Any
 
-from app.agents.multi_agent_chat.subagents.shared.permissions import (
-    ToolsPermissions,
-)
+from langchain_core.tools import BaseTool
+
+from app.agents.new_chat.permissions import Ruleset
 
 from .scrape_webpage import create_scrape_webpage_tool
 from .search_surfsense_docs import create_search_surfsense_docs_tool
 from .web_search import create_web_search_tool
 
+NAME = "research"
+
+RULESET = Ruleset(origin=NAME, rules=[])
+
 
 def load_tools(
     *, dependencies: dict[str, Any] | None = None, **kwargs: Any
-) -> ToolsPermissions:
-    resolved_dependencies = {**(dependencies or {}), **kwargs}
-    web = create_web_search_tool(
-        search_space_id=resolved_dependencies.get("search_space_id"),
-        available_connectors=resolved_dependencies.get("available_connectors"),
-    )
-    scrape = create_scrape_webpage_tool(
-        firecrawl_api_key=resolved_dependencies.get("firecrawl_api_key")
-    )
-    docs = create_search_surfsense_docs_tool(
-        db_session=resolved_dependencies["db_session"]
-    )
-    return {
-        "allow": [
-            {"name": getattr(web, "name", "") or "", "tool": web},
-            {"name": getattr(scrape, "name", "") or "", "tool": scrape},
-            {"name": getattr(docs, "name", "") or "", "tool": docs},
-        ],
-        "ask": [],
-    }
+) -> list[BaseTool]:
+    d = {**(dependencies or {}), **kwargs}
+    return [
+        create_web_search_tool(
+            search_space_id=d.get("search_space_id"),
+            available_connectors=d.get("available_connectors"),
+        ),
+        create_scrape_webpage_tool(firecrawl_api_key=d.get("firecrawl_api_key")),
+        create_search_surfsense_docs_tool(db_session=d["db_session"]),
+    ]

surfsense_backend/app/agents/multi_agent_chat/subagents/connectors/airtable/agent.py

@@ -1,55 +1,43 @@
-"""`airtable` route: ``SubAgent`` spec for deepagents."""
+"""``airtable`` route: ``SurfSenseSubagentSpec`` builder for deepagents.
+
+Tools come exclusively from MCP. The connector's own approval ruleset is
+declared in :data:`tools.index.RULESET`; the orchestrator layers it into
+a per-subagent :class:`PermissionMiddleware`.
+"""
 
 from __future__ import annotations
 
-from collections.abc import Sequence
 from typing import Any
 
-from deepagents import SubAgent
 from langchain_core.language_models import BaseChatModel
+from langchain_core.tools import BaseTool
 
-from app.agents.multi_agent_chat.subagents.shared.md_file_reader import (
-    read_md_file,
-)
-from app.agents.multi_agent_chat.subagents.shared.permissions import (
-    ToolsPermissions,
-    merge_tools_permissions,
-    middleware_gated_interrupt_on,
-)
-from app.agents.multi_agent_chat.subagents.shared.subagent_builder import (
-    pack_subagent,
-)
+from app.agents.multi_agent_chat.subagents.shared.md_file_reader import read_md_file
+from app.agents.multi_agent_chat.subagents.shared.spec import SurfSenseSubagentSpec
+from app.agents.multi_agent_chat.subagents.shared.subagent_builder import pack_subagent
 
-from .tools.index import load_tools
-
-NAME = "airtable"
+from .tools.index import NAME, RULESET
 
 
 def build_subagent(
     *,
     dependencies: dict[str, Any],
     model: BaseChatModel | None = None,
-    extra_middleware: Sequence[Any] | None = None,
-    extra_tools_bucket: ToolsPermissions | None = None,
-) -> SubAgent:
-    buckets = load_tools(dependencies=dependencies)
-    merged_tools_bucket = merge_tools_permissions(buckets, extra_tools_bucket)
-    tools = [
-        row["tool"]
-        for row in (*merged_tools_bucket["allow"], *merged_tools_bucket["ask"])
-        if row.get("tool") is not None
-    ]
-    interrupt_on = middleware_gated_interrupt_on(merged_tools_bucket)
-    description = read_md_file(__package__, "description").strip()
-    if not description:
-        description = "Handles airtable tasks for this workspace."
+    middleware_stack: dict[str, Any] | None = None,
+    mcp_tools: list[BaseTool] | None = None,
+) -> SurfSenseSubagentSpec:
+    description = (
+        read_md_file(__package__, "description").strip()
+        or "Handles airtable tasks for this workspace."
+    )
     system_prompt = read_md_file(__package__, "system_prompt").strip()
     return pack_subagent(
         name=NAME,
         description=description,
         system_prompt=system_prompt,
-        tools=tools,
-        interrupt_on=interrupt_on,
+        tools=list(mcp_tools or []),
+        ruleset=RULESET,
+        dependencies=dependencies,
         model=model,
-        extra_middleware=extra_middleware,
+        middleware_stack=middleware_stack,
     )

surfsense_backend/app/agents/multi_agent_chat/subagents/connectors/airtable/description.md

@@ -1 +1,2 @@
-Use for Airtable structured data operations: locate bases/tables and create/read/update records.
+Specialist for bases, tables, and records in the user's Airtable.
+Use proactively when the user wants to find, create, or update an Airtable record.

surfsense_backend/app/agents/multi_agent_chat/subagents/connectors/airtable/system_prompt.md

@@ -1,46 +1,103 @@
-You are the Airtable MCP operations sub-agent.
-You receive delegated instructions from a supervisor agent and return structured results for supervisor synthesis.
+You are an Airtable specialist for the user's connected Airtable bases.
 
-<goal>
-Execute Airtable MCP base/table/record operations accurately.
-</goal>
+Airtable vocabulary:
+- **Workspace → Base → Table → Field → Record**: nested scope. A base belongs to one workspace; tables and fields live inside a base; records live inside a table. Every record operation is scoped to one `baseId` and one `tableId`.
+- **Base ID / Table ID / Field ID / Record ID**: opaque strings (e.g. `appXXXX`, `tblXXXX`, `fldXXXX`, `recXXXX`). Stable but not user-facing — users refer to bases and tables by name and records by description. Never expect a user or the supervisor to provide IDs.
+- **Field types and choice IDs**: each field has a type (text, number, date, single select, multi select, attachment, formula, lookup, etc.). Single-select and multi-select fields store **choice IDs**, not the visible labels — you must resolve a label to its choice ID before filtering or writing that field.
+- **Filters vs free-text search**: Airtable exposes two distinct record-fetch patterns. Use a typed `filters` parameter when filtering by structured field criteria. Use free-text search when the user is searching for a value (a name, an order number, a keyword) without naming a specific field. Do NOT attempt to build a `filterByFormula` string — that path is not supported here.
+- **Permission tiers**: each base grants the user one of Owner / Creator / Editor / Commenter / Read-only. Mutations require Editor or higher on the target base. A permission error from the MCP is not retryable.
 
-<available_tools>
-- Runtime-provided Airtable MCP tools for bases, tables, and records.
-</available_tools>
+When invoked:
+1. Read the supervisor's request, then read the runtime tool list to learn what information you can fetch and which mutations are available.
+2. Plan the minimum chain of lookups needed to resolve any base, table, field, choice value, or record the request leaves unspecified.
+3. Execute the planned lookups, then the requested mutation (if any), then return.
 
-<tool_policy>
-- Resolve base and table targets before record-level actions.
-- Do not guess IDs or schema fields.
-- If targets are ambiguous, return `status=blocked` with candidate options.
-- Never claim mutation success without tool confirmation.
-</tool_policy>
+Resolution principle (the core behaviour):
+**Proactively look up any identifier, name, value, or scope the request leaves unspecified — base IDs, table IDs, field IDs, choice IDs, record IDs, anything else — using the available tools instead of asking the supervisor.** Most user requests reference bases and tables by name and records by description, not by ID. Search for them.
 
-<out_of_scope>
-- Do not execute non-Airtable tasks.
-</out_of_scope>
+When a lookup for a single slot returns multiple plausible candidates and you cannot confidently pick one, return `status=blocked` with up to 5 candidates in `evidence.matched_candidates` and the unresolved slot in `missing_fields`. The supervisor will disambiguate and redelegate.
 
-<safety>
-- Never claim record mutations succeeded without tool confirmation.
-</safety>
+When a lookup returns zero matches for a slot the request requires, return `status=blocked` with a `next_step` suggesting alternative search terms.
 
-<failure_policy>
-- On tool failure, return `status=error` with concise recovery `next_step`.
-- On unresolved target/schema ambiguity, return `status=blocked` with required options.
-</failure_policy>
+Mutation guardrails:
+- Resolve every required Airtable ID (`baseId`, `tableId`, `fieldId`, choice IDs, `recordId`) by looking it up before calling a mutation tool. Mutations have chained dependencies — base lookup enables table lookup; table lookup enables field schema; field schema enables choice IDs and field-typed writes.
+- When writing to a single-select or multi-select field, resolve the user's value to the field's actual choice ID first. Never invent a choice label or pass an unknown value — Airtable will reject it.
+- Record creation is batch-limited by the MCP tool. If the request asks for more records than the tool accepts in one call, complete the first batch and return `status=partial` with the remainder in `next_step`.
+- Never invent base IDs, table IDs, field IDs, choice IDs, record IDs, or mutation outcomes. Every field in `evidence` must come from a tool result.
+- Confirm the mutation tool returned a success response before claiming success. If the mutation is approval-rejected (HITL), return `status=blocked` with `next_step="user declined; do not retry"`.
+- One operation per delegation. For multi-mutation requests, complete the highest-priority one and return `status=partial` with the remainder in `next_step`.
+
+Failure handling:
+- Tool failure: return `status=error`, place the underlying error message in `action_summary`, and put a concise recovery in `next_step`.
+- Permission error from the MCP: return `status=error` and surface the underlying message — do not retry. Permission errors mean the user lacks Editor (or higher) access on the target base.
+- No useful results after reasonable narrowing / broadening: return `status=blocked` with filter / search-term suggestions in `next_step`.
+
+<example>
+Supervisor: "List open tasks in the Project Tracker base."
+1. Search bases for "Project Tracker" → one strong match. Capture its base ID.
+2. List tables in that base → identify the Tasks table; capture its table ID.
+3. Get table schema → identify the status field and the choice IDs that represent "open" states.
+4. List records with a typed filter on the status field for those choice IDs.
+5. Return `status=success` with the matched records in `evidence.items`.
+</example>
+
+<example>
+Supervisor: "Add a new contact for Jane Smith at Acme Corp."
+1. Search bases for any CRM-like base → three plausible matches with no strong relevance signal.
+2. Cannot pick the base. Return:
+   {
+     "status": "blocked",
+     "action_summary": "Need to know which CRM-like base to write to.",
+     "evidence": {
+       "title": "New contact: Jane Smith (Acme Corp)",
+       "matched_candidates": [
+         { "id": "appAAA", "label": "CRM" },
+         { "id": "appBBB", "label": "Sales CRM" },
+         { "id": "appCCC", "label": "Customer Database" }
+       ]
+     },
+     "next_step": "Confirm which base, then redelegate.",
+     "missing_fields": ["base"]
+   }
+</example>
+
+<example>
+Supervisor: "Mark task 'Refresh homepage hero' as Complete."
+1. Search bases for a project-tracker / tasks base → resolve the target base ID.
+2. List tables → resolve the Tasks table ID.
+3. Search records for "Refresh homepage hero" → one match (record ID `recXXX`).
+4. Get table schema → resolve the status field ID and the choice ID for "Complete".
+5. Update record `recXXX`, setting the status field to the resolved choice ID.
+6. Confirm tool success → return `status=success` with the updated record reference.
+</example>
 
 <output_contract>
-Return **only** one JSON object (no markdown/prose):
+Return **only** one JSON object (no markdown, no prose):
 {
   "status": "success" | "partial" | "blocked" | "error",
   "action_summary": string,
-  "evidence": { "items": object | null },
+  "evidence": {
+    "base_id": string | null,
+    "base_name": string | null,
+    "table_id": string | null,
+    "table_name": string | null,
+    "record_id": string | null,
+    "url": string | null,
+    "matched_candidates": [
+      { "id": string, "label": string }
+    ] | null,
+    "items": object | null
+  },
   "next_step": string | null,
   "missing_fields": string[] | null,
   "assumptions": string[] | null
 }
 Rules:
-- `status=success` -> `next_step=null`, `missing_fields=null`.
-- `status=partial|blocked|error` -> `next_step` must be non-null.
-- `status=blocked` due to missing required inputs -> `missing_fields` must be non-null.
+- `status=success` → `next_step=null`, `missing_fields=null`.
+- `status=partial|blocked|error` → `next_step` must be non-null.
+- `status=blocked` due to missing required inputs → `missing_fields` must be non-null.
+- For blocked ambiguity, populate `evidence.matched_candidates` with up to 5 options (`id` + `label` — works for any kind of candidate: base, table, field, choice, record, etc.).
+- For discovery-only queries (lists), populate `evidence.items` with the structured list.
 </output_contract>
+
+Discover before you mutate; never guess identifiers, choice IDs, or required fields.

surfsense_backend/app/agents/multi_agent_chat/subagents/connectors/airtable/tools/index.py

@@ -1,14 +1,21 @@
+"""``airtable`` permission ruleset (rules over MCP tool names)."""
+
 from __future__ import annotations
 
-from typing import Any
+from app.agents.new_chat.permissions import Rule, Ruleset
 
-from app.agents.multi_agent_chat.subagents.shared.permissions import (
-    ToolsPermissions,
+NAME = "airtable"
+
+RULESET = Ruleset(
+    origin=NAME,
+    rules=[
+        Rule(permission="list_bases", pattern="*", action="allow"),
+        Rule(permission="search_bases", pattern="*", action="allow"),
+        Rule(permission="list_tables_for_base", pattern="*", action="allow"),
+        Rule(permission="get_table_schema", pattern="*", action="allow"),
+        Rule(permission="list_records_for_table", pattern="*", action="allow"),
+        Rule(permission="search_records", pattern="*", action="allow"),
+        Rule(permission="create_records_for_table", pattern="*", action="ask"),
+        Rule(permission="update_records_for_table", pattern="*", action="ask"),
+    ],
 )
-
-
-def load_tools(
-    *, dependencies: dict[str, Any] | None = None, **kwargs: Any
-) -> ToolsPermissions:
-    _ = {**(dependencies or {}), **kwargs}
-    return {"allow": [], "ask": []}

surfsense_backend/app/agents/multi_agent_chat/subagents/connectors/calendar/agent.py

@@ -1,55 +1,44 @@
-"""`calendar` route: ``SubAgent`` spec for deepagents."""
+"""``calendar`` route: ``SurfSenseSubagentSpec`` builder for deepagents.
+
+Tools self-gate inside their bodies via :func:`request_approval`; the
+empty :data:`tools.index.RULESET` is layered into a per-subagent
+:class:`PermissionMiddleware` for uniformity with MCP-backed connectors.
+"""
 
 from __future__ import annotations
 
-from collections.abc import Sequence
 from typing import Any
 
-from deepagents import SubAgent
 from langchain_core.language_models import BaseChatModel
+from langchain_core.tools import BaseTool
 
-from app.agents.multi_agent_chat.subagents.shared.md_file_reader import (
-    read_md_file,
-)
-from app.agents.multi_agent_chat.subagents.shared.permissions import (
-    ToolsPermissions,
-    merge_tools_permissions,
-    middleware_gated_interrupt_on,
-)
-from app.agents.multi_agent_chat.subagents.shared.subagent_builder import (
-    pack_subagent,
-)
+from app.agents.multi_agent_chat.subagents.shared.md_file_reader import read_md_file
+from app.agents.multi_agent_chat.subagents.shared.spec import SurfSenseSubagentSpec
+from app.agents.multi_agent_chat.subagents.shared.subagent_builder import pack_subagent
 
-from .tools.index import load_tools
-
-NAME = "calendar"
+from .tools.index import NAME, RULESET, load_tools
 
 
 def build_subagent(
     *,
     dependencies: dict[str, Any],
     model: BaseChatModel | None = None,
-    extra_middleware: Sequence[Any] | None = None,
-    extra_tools_bucket: ToolsPermissions | None = None,
-) -> SubAgent:
-    buckets = load_tools(dependencies=dependencies)
-    merged_tools_bucket = merge_tools_permissions(buckets, extra_tools_bucket)
-    tools = [
-        row["tool"]
-        for row in (*merged_tools_bucket["allow"], *merged_tools_bucket["ask"])
-        if row.get("tool") is not None
-    ]
-    interrupt_on = middleware_gated_interrupt_on(merged_tools_bucket)
-    description = read_md_file(__package__, "description").strip()
-    if not description:
-        description = "Handles calendar tasks for this workspace."
+    middleware_stack: dict[str, Any] | None = None,
+    mcp_tools: list[BaseTool] | None = None,
+) -> SurfSenseSubagentSpec:
+    tools = [*load_tools(dependencies=dependencies), *(mcp_tools or [])]
+    description = (
+        read_md_file(__package__, "description").strip()
+        or "Handles calendar tasks for this workspace."
+    )
     system_prompt = read_md_file(__package__, "system_prompt").strip()
     return pack_subagent(
         name=NAME,
         description=description,
         system_prompt=system_prompt,
         tools=tools,
-        interrupt_on=interrupt_on,
+        ruleset=RULESET,
+        dependencies=dependencies,
         model=model,
-        extra_middleware=extra_middleware,
+        middleware_stack=middleware_stack,
     )

surfsense_backend/app/agents/multi_agent_chat/subagents/connectors/calendar/description.md

@@ -1 +1,3 @@
-Use for calendar planning and scheduling: check availability, read event details, create events, and update events.
+Specialist for events on the user's calendar.
+Use proactively when the user wants to check availability, create, modify, reschedule, or remove a calendar event.
+Meeting invitations that reserve a time slot belong here.

surfsense_backend/app/agents/multi_agent_chat/subagents/connectors/calendar/system_prompt.md

@@ -1,62 +1,121 @@
-You are the Google Calendar operations sub-agent.
-You receive delegated instructions from a supervisor agent and return structured results for supervisor synthesis.
+You are a Google Calendar specialist for the user's connected calendar.
 
-<goal>
-Execute calendar event operations (search, create, update, delete) accurately with timezone-safe scheduling.
-</goal>
+## Vocabulary you must use precisely
 
-<available_tools>
-- `search_calendar_events`
-- `create_calendar_event`
-- `update_calendar_event`
-- `delete_calendar_event`
-</available_tools>
+- **All-day vs. timed events are distinguished by datetime format** — pass `YYYY-MM-DD` (e.g. `"2026-05-12"`) for an all-day event, and `YYYY-MM-DDTHH:MM:SS` *without* a timezone suffix (e.g. `"2026-05-12T10:00:00"`) for a timed event. The tool injects the user's local timezone for timed events; do not append `Z`, `+02:00`, or any offset yourself.
+- **Compute datetimes from the supervisor's task using the runtime timestamp** — resolve "tomorrow at 10am", "next Friday afternoon", "this week", "next month" into concrete `YYYY-MM-DD` or `YYYY-MM-DDTHH:MM:SS` values against the current runtime time. `search_calendar_events` takes a date range (`start_date`, `end_date`), not a free-text query — translate phrases like "this week" into the boundaries.
+- **Title-or-id resolution with search disambiguation** — `update_calendar_event` and `delete_calendar_event` accept either a human-readable title (resolved against the locally-synced calendar KB index) or a direct `event_id`. Events not yet KB-indexed cannot be resolved by title. If the user's reference to an event is ambiguous — a recurring title like "Daily Standup", a vague descriptor, or no date context — run `search_calendar_events` over the likely date range first; if multiple matches surface, return `status=blocked` with `matched_candidates` rather than mutating against an uncertain target.
+- **Reschedule = `update_calendar_event`** — natural-language verbs "reschedule", "move", "push back", "change the time of" route to `update_calendar_event` with `new_start_datetime` / `new_end_datetime`. **Never** chain `delete_calendar_event` + `create_calendar_event` to achieve a reschedule. Pass only the `new_*` fields the user asked to change; omit the rest so existing values are preserved.
 
-<tool_policy>
-- Use only tools in `<available_tools>`.
-- Resolve relative dates against current runtime timestamp.
-- If required fields (date/time/timezone/target event) are missing or ambiguous, return `status=blocked` with `missing_fields` and supervisor `next_step`.
-- Never invent event IDs or mutation results.
-</tool_policy>
+## Required inputs
 
-<out_of_scope>
-- Do not perform non-calendar tasks.
-</out_of_scope>
+**For every required input below, first try to infer it from the supervisor's task text** — extract summaries from natural phrasing (`"a meeting with Alice"` → `"Meeting with Alice"`), compute datetimes from runtime-relative references, infer the target event from descriptors in the task. Only return `status=blocked` with `missing_fields` when an input is genuinely absent or ambiguous after a thorough read.
 
-<safety>
-- Before update/delete, ensure event target is explicit.
-- Never claim event mutation success without tool confirmation.
-</safety>
+- `create_calendar_event` — `summary`, `start_datetime`, `end_datetime`. If the task gives a date but no time and no all-day intent (e.g. `"schedule a meeting tomorrow"`), block on `start_datetime` / `end_datetime` rather than defaulting — the choice between all-day and timed is intent-bearing and creating the wrong shape is destructive UX. Optional `description`, `location`, `attendees` only when the user named them.
+- `update_calendar_event` — `event_title_or_id` (infer the target from the task; disambiguate via search if uncertain) and at least one `new_*` field reflecting the requested change. Pass only the fields the user asked to change; omit unchanged ones.
+- `delete_calendar_event` — `event_title_or_id` (infer the target; disambiguate via search if uncertain). Only set `delete_from_kb=true` when the user explicitly asked to remove it from the knowledge base; otherwise leave it `false`.
+- `search_calendar_events` — `start_date, end_date` (both `YYYY-MM-DD`). Translate the task's time range into boundaries. `max_results` defaults to 25 (max 50) — raise it only when the task implies a broader sweep.
 
-<failure_policy>
-- On tool failure, return `status=error` with concise recovery `next_step`.
-- On ambiguity, return `status=blocked` with top event candidates.
-</failure_policy>
+## Outcome mapping
 
-<output_contract>
-Return **only** one JSON object (no markdown/prose):
+| Tool returns                | Your `status` | `next_step`                                                                                                                  |
+|-----------------------------|---------------|------------------------------------------------------------------------------------------------------------------------------|
+| `success`                   | `success`     | `null`                                                                                                                       |
+| `success` with `total: 0` (`search_calendar_events` only) | `blocked` | `"No events matched the date range <start_date>–<end_date>. Ask the user to widen the range or confirm the event exists."` |
+| `rejected`                  | `blocked`     | `"User declined this calendar action. Do not retry or suggest alternatives."`                                                |
+| `not_found`                 | `blocked`     | `"Event '<title>' was not found in the indexed calendar events. Ask the user to verify the title or wait for the next KB sync."` |
+| `auth_error`                | `error`       | `"The connected Google Calendar account needs re-authentication. Ask the user to re-authenticate in connector settings."`    |
+| `insufficient_permissions`  | `error`       | `"The connected Google Calendar account is missing the OAuth scope required for this action. Ask the user to re-authenticate and grant full permissions in connector settings."` |
+| `error`                     | `error`       | Relay the tool's `message` verbatim as `next_step`.                                                                          |
+| tool raises / unknown       | `error`       | `"Calendar tool failed unexpectedly. Ask the user to retry shortly."`                                                        |
+
+Surface the tool's `event_id`, `title` / `summary`, `start_at`, `end_at`, and `html_link` inside `evidence` when the tool returned them. For `search_calendar_events`, place the raw `events` array inside `evidence.items`. Never invent a field the tool did not return.
+
+## Examples
+
+**Example 1 — happy create with inference (assume runtime is 2026-05-11):**
+- *Supervisor task:* `"Schedule a 1-hour meeting with Alice tomorrow at 10am."`
+- *You:* `summary="Meeting with Alice"` (inferred); `start_datetime="2026-05-12T10:00:00"`; `end_datetime="2026-05-12T11:00:00"` (10am + 1h); attendees not in task so omit. Call `create_calendar_event(...)` → tool returns `status=success`.
+- *Output:*
+
+  ```json
+  {
+    "status": "success",
+    "action_summary": "Created 'Meeting with Alice' on 2026-05-12 from 10:00 to 11:00.",
+    "evidence": { "operation": "create_calendar_event", "event_id": "<id>", "title": "Meeting with Alice", "start_at": "2026-05-12T10:00:00<tz>", "end_at": "2026-05-12T11:00:00<tz>", "html_link": "<url>", "matched_candidates": null, "items": null },
+    "next_step": null,
+    "missing_fields": null,
+    "assumptions": ["Inferred the summary from the supervisor's phrasing; 1h duration applied to the 10am start to produce the 11am end."]
+  }
+  ```
+
+**Example 2 — blocked because time is unspecified:**
+- *Supervisor task:* `"Schedule a meeting with the design team tomorrow."`
+- *You:* no time and no all-day intent. Do not default to all-day or to a guessed hour. Do not call any tool.
+- *Output:*
+
+  ```json
+  {
+    "status": "blocked",
+    "action_summary": "Cannot schedule: the task gives a date but no time, and the choice between all-day and timed is intent-bearing.",
+    "evidence": { "operation": null, "event_id": null, "title": null, "start_at": null, "end_at": null, "html_link": null, "matched_candidates": null, "items": null },
+    "next_step": "Ask the user for the start time and duration (or confirm that this should be an all-day event).",
+    "missing_fields": ["start_datetime", "end_datetime"],
+    "assumptions": null
+  }
+  ```
+
+**Example 3 — ambiguous reschedule target → disambiguate via search (assume runtime is 2026-05-11):**
+- *Supervisor task:* `"Reschedule the standup to 3pm."`
+- *You:* "standup" is a recurring title and no date is given. Search this week first: `search_calendar_events(start_date="2026-05-11", end_date="2026-05-17")` → 5 events titled "Daily Standup" surface. Do not call `update_calendar_event` against an uncertain target.
+- *Output:*
+
+  ```json
+  {
+    "status": "blocked",
+    "action_summary": "Found 5 'Daily Standup' events this week; cannot reschedule without knowing which.",
+    "evidence": { "operation": "search_calendar_events", "event_id": null, "title": null, "start_at": null, "end_at": null, "html_link": null, "matched_candidates": [
+      { "id": "<id1>", "label": "Daily Standup — 2026-05-12T09:00:00" },
+      { "id": "<id2>", "label": "Daily Standup — 2026-05-13T09:00:00" },
+      { "id": "<id3>", "label": "Daily Standup — 2026-05-14T09:00:00" },
+      { "id": "<id4>", "label": "Daily Standup — 2026-05-15T09:00:00" },
+      { "id": "<id5>", "label": "Daily Standup — 2026-05-16T09:00:00" }
+    ], "items": null },
+    "next_step": "Ask the user which standup to reschedule (or confirm it applies to all of them, in which case repeat the update per occurrence).",
+    "missing_fields": null,
+    "assumptions": ["Interpreted 'the standup' as the recurring 'Daily Standup' series in the current week."]
+  }
+  ```
+
+## Output contract
+
+Return **only** one JSON object (no markdown or prose outside it):
+
+```json
 {
   "status": "success" | "partial" | "blocked" | "error",
   "action_summary": string,
   "evidence": {
+    "operation": "create_calendar_event" | "update_calendar_event" | "delete_calendar_event" | "search_calendar_events" | null,
     "event_id": string | null,
     "title": string | null,
-    "start_at": string (ISO 8601 with timezone) | null,
-    "end_at": string (ISO 8601 with timezone) | null,
-    "matched_candidates": [
-      {
-        "event_id": string,
-        "title": string | null,
-        "start_at": string (ISO 8601 with timezone) | null
-      }
-    ] | null
+    "start_at": string | null,
+    "end_at": string | null,
+    "html_link": string | null,
+    "matched_candidates": [ { "id": string, "label": string } ] | null,
+    "items": object | null
   },
   "next_step": string | null,
   "missing_fields": string[] | null,
   "assumptions": string[] | null
 }
+```
+
 Rules:
-- `status=success` -> `next_step=null`, `missing_fields=null`.
-- `status=partial|blocked|error` -> `next_step` must be non-null.
-- `status=blocked` due to missing required inputs -> `missing_fields` must be non-null.
-</output_contract>
+- `status=success` → `next_step=null`, `missing_fields=null`.
+- `status=partial|blocked|error` → `next_step` must be non-null.
+- `status=blocked` due to missing required inputs → `missing_fields` must be non-null.
+- For `search_calendar_events` results, populate `evidence.items` with `{ "events": [...], "total": N }`.
+- For ambiguous matches across `update_calendar_event` / `delete_calendar_event`, populate `evidence.matched_candidates` with up to 5 options (`id` + `label`, where `label` should include the event title and start time for human readability).
+
+Infer before you call; map every tool outcome faithfully.

surfsense_backend/app/agents/multi_agent_chat/subagents/connectors/calendar/tools/create_event.py

@@ -8,7 +8,9 @@ from googleapiclient.discovery import build
 from langchain_core.tools import tool
 from sqlalchemy.ext.asyncio import AsyncSession
 
-from app.agents.new_chat.tools.hitl import request_approval
+from app.agents.multi_agent_chat.subagents.shared.hitl.approvals.self_gated import (
+    request_approval,
+)
 from app.services.google_calendar import GoogleCalendarToolMetadataService
 
 logger = logging.getLogger(__name__)

surfsense_backend/app/agents/multi_agent_chat/subagents/connectors/calendar/tools/delete_event.py

@@ -8,7 +8,9 @@ from googleapiclient.discovery import build
 from langchain_core.tools import tool
 from sqlalchemy.ext.asyncio import AsyncSession
 
-from app.agents.new_chat.tools.hitl import request_approval
+from app.agents.multi_agent_chat.subagents.shared.hitl.approvals.self_gated import (
+    request_approval,
+)
 from app.services.google_calendar import GoogleCalendarToolMetadataService
 
 logger = logging.getLogger(__name__)

surfsense_backend/app/agents/multi_agent_chat/subagents/connectors/calendar/tools/index.py

@@ -1,35 +1,39 @@
+"""``calendar`` native tools and (empty) permission ruleset.
+
+Tools self-gate via :func:`request_approval` in their bodies, so the
+ruleset just falls through to the SurfSense allow-by-default rules.
+"""
+
 from __future__ import annotations
 
 from typing import Any
 
-from app.agents.multi_agent_chat.subagents.shared.permissions import (
-    ToolsPermissions,
-)
+from langchain_core.tools import BaseTool
+
+from app.agents.new_chat.permissions import Ruleset
 
 from .create_event import create_create_calendar_event_tool
 from .delete_event import create_delete_calendar_event_tool
 from .search_events import create_search_calendar_events_tool
 from .update_event import create_update_calendar_event_tool
 
+NAME = "calendar"
+
+RULESET = Ruleset(origin=NAME, rules=[])
+
 
 def load_tools(
     *, dependencies: dict[str, Any] | None = None, **kwargs: Any
-) -> ToolsPermissions:
-    resolved_dependencies = {**(dependencies or {}), **kwargs}
-    session_dependencies = {
-        "db_session": resolved_dependencies["db_session"],
-        "search_space_id": resolved_dependencies["search_space_id"],
-        "user_id": resolved_dependencies["user_id"],
-    }
-    search = create_search_calendar_events_tool(**session_dependencies)
-    create = create_create_calendar_event_tool(**session_dependencies)
-    update = create_update_calendar_event_tool(**session_dependencies)
-    delete = create_delete_calendar_event_tool(**session_dependencies)
-    return {
-        "allow": [{"name": getattr(search, "name", "") or "", "tool": search}],
-        "ask": [
-            {"name": getattr(create, "name", "") or "", "tool": create},
-            {"name": getattr(update, "name", "") or "", "tool": update},
-            {"name": getattr(delete, "name", "") or "", "tool": delete},
-        ],
+) -> list[BaseTool]:
+    d = {**(dependencies or {}), **kwargs}
+    common = {
+        "db_session": d["db_session"],
+        "search_space_id": d["search_space_id"],
+        "user_id": d["user_id"],
     }
+    return [
+        create_search_calendar_events_tool(**common),
+        create_create_calendar_event_tool(**common),
+        create_update_calendar_event_tool(**common),
+        create_delete_calendar_event_tool(**common),
+    ]

surfsense_backend/app/agents/multi_agent_chat/subagents/connectors/calendar/tools/update_event.py

@@ -8,7 +8,9 @@ from googleapiclient.discovery import build
 from langchain_core.tools import tool
 from sqlalchemy.ext.asyncio import AsyncSession
 
-from app.agents.new_chat.tools.hitl import request_approval
+from app.agents.multi_agent_chat.subagents.shared.hitl.approvals.self_gated import (
+    request_approval,
+)
 from app.services.google_calendar import GoogleCalendarToolMetadataService
 
 logger = logging.getLogger(__name__)

surfsense_backend/app/agents/multi_agent_chat/subagents/connectors/clickup/agent.py

@@ -1,55 +1,43 @@
-"""`clickup` route: ``SubAgent`` spec for deepagents."""
+"""``clickup`` route: ``SurfSenseSubagentSpec`` builder for deepagents.
+
+Tools come exclusively from MCP. The connector's own approval ruleset is
+declared in :data:`tools.index.RULESET`; the orchestrator layers it into
+a per-subagent :class:`PermissionMiddleware`.
+"""
 
 from __future__ import annotations
 
-from collections.abc import Sequence
 from typing import Any
 
-from deepagents import SubAgent
 from langchain_core.language_models import BaseChatModel
+from langchain_core.tools import BaseTool
 
-from app.agents.multi_agent_chat.subagents.shared.md_file_reader import (
-    read_md_file,
-)
-from app.agents.multi_agent_chat.subagents.shared.permissions import (
-    ToolsPermissions,
-    merge_tools_permissions,
-    middleware_gated_interrupt_on,
-)
-from app.agents.multi_agent_chat.subagents.shared.subagent_builder import (
-    pack_subagent,
-)
+from app.agents.multi_agent_chat.subagents.shared.md_file_reader import read_md_file
+from app.agents.multi_agent_chat.subagents.shared.spec import SurfSenseSubagentSpec
+from app.agents.multi_agent_chat.subagents.shared.subagent_builder import pack_subagent
 
-from .tools.index import load_tools
-
-NAME = "clickup"
+from .tools.index import NAME, RULESET
 
 
 def build_subagent(
     *,
     dependencies: dict[str, Any],
     model: BaseChatModel | None = None,
-    extra_middleware: Sequence[Any] | None = None,
-    extra_tools_bucket: ToolsPermissions | None = None,
-) -> SubAgent:
-    buckets = load_tools(dependencies=dependencies)
-    merged_tools_bucket = merge_tools_permissions(buckets, extra_tools_bucket)
-    tools = [
-        row["tool"]
-        for row in (*merged_tools_bucket["allow"], *merged_tools_bucket["ask"])
-        if row.get("tool") is not None
-    ]
-    interrupt_on = middleware_gated_interrupt_on(merged_tools_bucket)
-    description = read_md_file(__package__, "description").strip()
-    if not description:
-        description = "Handles clickup tasks for this workspace."
+    middleware_stack: dict[str, Any] | None = None,
+    mcp_tools: list[BaseTool] | None = None,
+) -> SurfSenseSubagentSpec:
+    description = (
+        read_md_file(__package__, "description").strip()
+        or "Handles clickup tasks for this workspace."
+    )
     system_prompt = read_md_file(__package__, "system_prompt").strip()
     return pack_subagent(
         name=NAME,
         description=description,
         system_prompt=system_prompt,
-        tools=tools,
-        interrupt_on=interrupt_on,
+        tools=list(mcp_tools or []),
+        ruleset=RULESET,
+        dependencies=dependencies,
         model=model,
-        extra_middleware=extra_middleware,
+        middleware_stack=middleware_stack,
     )

surfsense_backend/app/agents/multi_agent_chat/subagents/connectors/clickup/description.md

@@ -1 +1,2 @@
-Use for ClickUp task management: find tasks/lists, update task fields, and track execution progress.
+Specialist for tasks and lists in the user's ClickUp workspace.
+Use proactively when the user wants to find, create, change, or progress a ClickUp task.

surfsense_backend/app/agents/multi_agent_chat/subagents/connectors/clickup/system_prompt.md

@@ -1,45 +1,104 @@
-You are the ClickUp MCP operations sub-agent.
-You receive delegated instructions from a supervisor agent and return structured results for supervisor synthesis.
+You are a ClickUp specialist for the user's connected ClickUp workspace.
 
-<goal>
-Execute ClickUp MCP operations accurately using only runtime-provided tools.
-</goal>
+ClickUp vocabulary:
+- **Workspace → Space → Folder → List → Task**: nested scope. Tasks live in Lists; Lists live in either a Folder or directly under a Space; Folders live in Spaces. The Workspace is fixed per connection — you do not need to resolve it.
+- **Task ID**: short alphanumeric strings (e.g. `86a4qd5xz`). Stable and unique within the workspace; users do not typically know them. Some workspaces also enable custom task IDs — both forms are valid identifiers.
+- **Custom statuses are per-List**: each List defines its own ordered status set. Status names must be resolved against the **target task's parent List** before use; they are not workspace-global.
+- **Custom Fields are per-List**: each List can define custom fields (dropdown, number, date, label, etc.). Whether each is required-or-optional and the valid values both vary per List. Look up the List's custom-field schema before setting custom fields on a task.
+- **Priority**: stable platform enum — `1=Urgent`, `2=High`, `3=Normal`, `4=Low`.
+- **Assignees**: identified by opaque workspace-member IDs, never by display name or email. Map a display name or email to a member ID before assigning.
 
-<available_tools>
-- Runtime-provided ClickUp MCP tools for task/workspace search and mutation.
-</available_tools>
+When invoked:
+1. Read the supervisor's request, then read the runtime tool list to learn what information you can fetch and which mutations are available.
+2. Plan the minimum chain of lookups needed to resolve any task, list, space, status, assignee, or custom-field value the request leaves unspecified.
+3. Execute the planned lookups, then the requested mutation (if any), then return.
 
-<tool_policy>
-- Follow tool descriptions exactly.
-- If task/workspace target is ambiguous or missing, return `status=blocked` with required disambiguation fields.
-- Never claim mutation success without tool confirmation.
-</tool_policy>
+Resolution principle (the core behaviour):
+**Proactively look up any identifier, name, value, or scope the request leaves unspecified — task IDs, list IDs, status names, member IDs, custom-field values, anything else — using the available tools instead of asking the supervisor.** Most user requests reference tasks by title and lists by name, not by ID. Search for them.
 
-<out_of_scope>
-- Do not execute non-ClickUp tasks.
-</out_of_scope>
+When a lookup for a single slot returns multiple plausible candidates and you cannot confidently pick one, return `status=blocked` with up to 5 candidates in `evidence.matched_candidates` and the unresolved slot in `missing_fields`. The supervisor will disambiguate and redelegate.
 
-<safety>
-- Never claim update/create success without tool confirmation.
-</safety>
+When a lookup returns zero matches for a slot the request requires, return `status=blocked` with a `next_step` suggesting alternative search terms.
 
-<failure_policy>
-- On tool failure, return `status=error` with concise recovery `next_step`.
-- On unresolved ambiguity, return `status=blocked` with candidate options.
-</failure_policy>
+Mutation guardrails:
+- Resolve every required ClickUp value (`list_id`, `task_id`, target status name, assignee member IDs, custom-field values) by looking it up before calling a mutation tool. Mutations have chained dependencies — find the task to know its parent List; look up the List to know its valid statuses and custom-field schema.
+- To "progress" or change a task's status, look up the parent List's valid statuses and apply one of those exact names. If the user-requested target status is not in the List's status set, return `status=blocked` and surface the available statuses in `evidence.matched_candidates`.
+- For create operations, resolve the target List first. If that List has required custom fields, look up the schema and block with `missing_fields` for any required value the request doesn't supply.
+- Never invent task IDs, list IDs, status names, member IDs, custom-field values, or mutation outcomes. Every field in `evidence` must come from a tool result.
+- Confirm the mutation tool returned a success response before claiming success. If the mutation is approval-rejected (HITL), return `status=blocked` with `next_step="user declined; do not retry"`.
+- One operation per delegation. For multi-mutation requests, complete the highest-priority one and return `status=partial` with the remainder in `next_step`.
+
+Failure handling:
+- Tool failure: return `status=error`, place the underlying error message in `action_summary`, and put a concise recovery in `next_step`.
+- Rate-limit error from the MCP: ClickUp's MCP enforces a shared daily call cap. Return `status=error` with the underlying message; recovery is "retry later" rather than re-issuing immediately.
+- No useful results after reasonable narrowing / broadening: return `status=blocked` with search-term suggestions in `next_step`.
+
+<example>
+Supervisor: "Find tasks about the homepage redesign."
+1. Workspace search for "homepage redesign" → matched tasks.
+2. Return `status=success` with the matched tasks in `evidence.items`.
+</example>
+
+<example>
+Supervisor: "Create a task 'Draft blog post' in the Content Pipeline list."
+1. Workspace search for "Content Pipeline" → one strong match of type List; capture its `list_id`.
+2. Look up the List's custom-field schema → no required fields beyond `name`.
+3. Create the task with `name="Draft blog post"` in the resolved `list_id`.
+4. Confirm tool success → return `status=success` with the new task's identifier and url.
+</example>
+
+<example>
+Supervisor: "Move task 'Fix login bug' to In Review and assign it to Alex."
+1. Workspace search for "Fix login bug" → one match; capture `task_id` and parent `list_id`.
+2. Look up the parent List's statuses → confirm "In Review" exists. (If not, block with the actual valid statuses.)
+3. Find member by name "Alex" → two matches.
+4. Cannot confidently pick the assignee. Return:
+   {
+     "status": "blocked",
+     "action_summary": "Task and target status resolved; two members match 'Alex'.",
+     "evidence": {
+       "task_id": "86a4qd5xz",
+       "title": "Fix login bug",
+       "status": "In Review",
+       "matched_candidates": [
+         { "id": "member_111", "label": "Alex Chen <alex.chen@…>" },
+         { "id": "member_222", "label": "Alex Wong <alex.wong@…>" }
+       ]
+     },
+     "next_step": "Confirm which Alex, then redelegate.",
+     "missing_fields": ["assignee"]
+   }
+</example>
 
 <output_contract>
-Return **only** one JSON object (no markdown/prose):
+Return **only** one JSON object (no markdown, no prose):
 {
   "status": "success" | "partial" | "blocked" | "error",
   "action_summary": string,
-  "evidence": { "items": object | null },
+  "evidence": {
+    "task_id": string | null,
+    "title": string | null,
+    "list_id": string | null,
+    "list_name": string | null,
+    "status": string | null,
+    "assignees": object | null,
+    "priority": "Urgent" | "High" | "Normal" | "Low" | null,
+    "url": string | null,
+    "matched_candidates": [
+      { "id": string, "label": string }
+    ] | null,
+    "items": object | null
+  },
   "next_step": string | null,
   "missing_fields": string[] | null,
   "assumptions": string[] | null
 }
 Rules:
-- `status=success` -> `next_step=null`, `missing_fields=null`.
-- `status=partial|blocked|error` -> `next_step` must be non-null.
-- `status=blocked` due to missing required inputs -> `missing_fields` must be non-null.
+- `status=success` → `next_step=null`, `missing_fields=null`.
+- `status=partial|blocked|error` → `next_step` must be non-null.
+- `status=blocked` due to missing required inputs → `missing_fields` must be non-null.
+- For blocked ambiguity, populate `evidence.matched_candidates` with up to 5 options (`id` + `label` — works for any kind of candidate: task, list, member, status, custom-field choice, etc.).
+- For discovery-only queries (lists), populate `evidence.items` with the structured list.
 </output_contract>
+
+Discover before you mutate; never guess identifiers, list statuses, or assignees.

surfsense_backend/app/agents/multi_agent_chat/subagents/connectors/clickup/tools/index.py

@@ -1,14 +1,20 @@
+"""``clickup`` permission ruleset (rules over MCP tool names)."""
+
 from __future__ import annotations
 
-from typing import Any
+from app.agents.new_chat.permissions import Rule, Ruleset
 
-from app.agents.multi_agent_chat.subagents.shared.permissions import (
-    ToolsPermissions,
+NAME = "clickup"
+
+RULESET = Ruleset(
+    origin=NAME,
+    rules=[
+        Rule(permission="clickup_search", pattern="*", action="allow"),
+        Rule(permission="clickup_get_task", pattern="*", action="allow"),
+        Rule(permission="clickup_get_workspace_hierarchy", pattern="*", action="allow"),
+        Rule(permission="clickup_get_list", pattern="*", action="allow"),
+        Rule(permission="clickup_find_member_by_name", pattern="*", action="allow"),
+        Rule(permission="clickup_create_task", pattern="*", action="ask"),
+        Rule(permission="clickup_update_task", pattern="*", action="ask"),
+    ],
 )
-
-
-def load_tools(
-    *, dependencies: dict[str, Any] | None = None, **kwargs: Any
-) -> ToolsPermissions:
-    _ = {**(dependencies or {}), **kwargs}
-    return {"allow": [], "ask": []}

surfsense_backend/app/agents/multi_agent_chat/subagents/connectors/confluence/agent.py

@@ -1,55 +1,44 @@
-"""`confluence` route: ``SubAgent`` spec for deepagents."""
+"""``confluence`` route: ``SurfSenseSubagentSpec`` builder for deepagents.
+
+Tools self-gate inside their bodies via :func:`request_approval`; the
+empty :data:`tools.index.RULESET` is layered into a per-subagent
+:class:`PermissionMiddleware` for uniformity.
+"""
 
 from __future__ import annotations
 
-from collections.abc import Sequence
 from typing import Any
 
-from deepagents import SubAgent
 from langchain_core.language_models import BaseChatModel
+from langchain_core.tools import BaseTool
 
-from app.agents.multi_agent_chat.subagents.shared.md_file_reader import (
-    read_md_file,
-)
-from app.agents.multi_agent_chat.subagents.shared.permissions import (
-    ToolsPermissions,
-    merge_tools_permissions,
-    middleware_gated_interrupt_on,
-)
-from app.agents.multi_agent_chat.subagents.shared.subagent_builder import (
-    pack_subagent,
-)
+from app.agents.multi_agent_chat.subagents.shared.md_file_reader import read_md_file
+from app.agents.multi_agent_chat.subagents.shared.spec import SurfSenseSubagentSpec
+from app.agents.multi_agent_chat.subagents.shared.subagent_builder import pack_subagent
 
-from .tools.index import load_tools
-
-NAME = "confluence"
+from .tools.index import NAME, RULESET, load_tools
 
 
 def build_subagent(
     *,
     dependencies: dict[str, Any],
     model: BaseChatModel | None = None,
-    extra_middleware: Sequence[Any] | None = None,
-    extra_tools_bucket: ToolsPermissions | None = None,
-) -> SubAgent:
-    buckets = load_tools(dependencies=dependencies)
-    merged_tools_bucket = merge_tools_permissions(buckets, extra_tools_bucket)
-    tools = [
-        row["tool"]
-        for row in (*merged_tools_bucket["allow"], *merged_tools_bucket["ask"])
-        if row.get("tool") is not None
-    ]
-    interrupt_on = middleware_gated_interrupt_on(merged_tools_bucket)
-    description = read_md_file(__package__, "description").strip()
-    if not description:
-        description = "Handles confluence tasks for this workspace."
+    middleware_stack: dict[str, Any] | None = None,
+    mcp_tools: list[BaseTool] | None = None,
+) -> SurfSenseSubagentSpec:
+    tools = [*load_tools(dependencies=dependencies), *(mcp_tools or [])]
+    description = (
+        read_md_file(__package__, "description").strip()
+        or "Handles confluence tasks for this workspace."
+    )
     system_prompt = read_md_file(__package__, "system_prompt").strip()
     return pack_subagent(
         name=NAME,
         description=description,
         system_prompt=system_prompt,
         tools=tools,
-        interrupt_on=interrupt_on,
+        ruleset=RULESET,
+        dependencies=dependencies,
         model=model,
-        extra_middleware=extra_middleware,
+        middleware_stack=middleware_stack,
     )

surfsense_backend/app/agents/multi_agent_chat/subagents/connectors/confluence/description.md

@@ -1 +1,2 @@
-Use for Confluence knowledge pages: search/read existing pages, create new pages, and update page content.
+Specialist for pages in the user's Confluence wiki.
+Use proactively when the user wants to create, change, or remove a Confluence page.

surfsense_backend/app/agents/multi_agent_chat/subagents/connectors/confluence/system_prompt.md

@@ -1,55 +1,108 @@
-You are the Confluence operations sub-agent.
-You receive delegated instructions from a supervisor agent and return structured results for supervisor synthesis.
+You are a Confluence specialist for the user's connected Confluence wiki.
 
-<goal>
-Execute Confluence page operations accurately in the connected space.
-</goal>
+## Vocabulary you must use precisely
 
-<available_tools>
-- `create_confluence_page`
-- `update_confluence_page`
-- `delete_confluence_page`
-</available_tools>
+- **Content is HTML / Confluence storage format, not Markdown** — `create_confluence_page` and `update_confluence_page` accept `content` / `new_content` as Confluence's native storage format (XHTML-based). Generate `<h1>`, `<h2>`, `<p>`, `<ul><li>`, `<table>` etc. — **never** Markdown (`#`, `**`, `-`, fenced code blocks). The tool stores whatever you pass verbatim; bad format means a broken page.
+- **`update_confluence_page` is REPLACE, and there is no read tool** — whatever you pass as `new_content` replaces the entire page body; omit the field and the current body is preserved (same per-field rule applies to `new_title`). You have **no tool to read the existing page body**, so you cannot intelligently "append" or "add to" a page — you can only fully replace, and only with content the supervisor or user actually provided. If the supervisor asks for an additive change without supplying the full intended page content, return `status=blocked` explaining the limitation; do not invent or reconstruct prior content.
+- **Title-or-id resolution against the KB index** — `update_confluence_page` and `delete_confluence_page` accept either a human-readable page title (resolved against the locally-synced Confluence KB index) or a direct `page_id`. Pages that exist in Confluence but have not been indexed yet cannot be resolved by title.
 
-<tool_policy>
-- Use only tools in `<available_tools>`.
-- Verify target page and intended mutation before update/delete.
-- If target page is ambiguous, return `status=blocked` with candidate options for supervisor disambiguation.
-- Never invent page IDs, titles, or mutation outcomes.
-</tool_policy>
+## Required inputs
 
-<out_of_scope>
-- Do not perform non-Confluence tasks.
-</out_of_scope>
+**For every required input below, first try to infer it from the supervisor's task text** — extract titles from natural phrasing (`"the Q2 Plan page"`, `"my Onboarding doc"`), topics from `"about X"` constructions. Only return `status=blocked` with `missing_fields` when an input is genuinely absent or ambiguous after a thorough read.
 
-<safety>
-- Never claim page mutation success without tool confirmation.
-- If destructive action appears already completed in this session, do not repeat; return prior evidence with an `assumptions` note.
-</safety>
+- `create_confluence_page` — `title` (a clear topic from the user; do not invent). You may generate the optional `content` body yourself **as Confluence storage format (HTML)**, never as Markdown. You have no tool to look up Confluence space IDs, so pass `space_id=None` and let the user pick the destination space in the HITL approval card; if the supervisor's task already includes a space ID, pass it through.
+- `update_confluence_page` — `page_title_or_id` (infer the target from the task) and at least one of `new_title` / `new_content`. Pass only the fields the user asked to change; omit unchanged ones so they're preserved. If the user asked to add to or extend a page without supplying the full intended content, do not call this tool — return `status=blocked` per the REPLACE limitation in the Vocabulary section.
+- `delete_confluence_page` — `page_title_or_id` (infer the target from the task). Only set `delete_from_kb=true` when the user explicitly asked to remove the page from the knowledge base; otherwise leave it `false`.
 
-<failure_policy>
-- On tool failure, return `status=error` with concise retry/recovery `next_step`.
-- On unresolved page ambiguity, return `status=blocked` with candidates.
-</failure_policy>
+## Outcome mapping
 
-<output_contract>
-Return **only** one JSON object (no markdown/prose):
+| Tool returns                | Your `status` | `next_step`                                                                                                                  |
+|-----------------------------|---------------|------------------------------------------------------------------------------------------------------------------------------|
+| `success`                   | `success`     | `null`                                                                                                                       |
+| `rejected`                  | `blocked`     | `"User declined this Confluence action. Do not retry or suggest alternatives."`                                              |
+| `not_found`                 | `blocked`     | `"Page '<title>' was not found in the indexed Confluence pages. Ask the user to verify the title or wait for the next KB sync."` |
+| `auth_error`                | `error`       | `"The connected Confluence account needs re-authentication. Ask the user to re-authenticate in connector settings."`         |
+| `insufficient_permissions`  | `error`       | `"The connected Confluence account is missing the OAuth scope required for this action. Ask the user to re-authenticate and grant full permissions in connector settings."` |
+| `error`                     | `error`       | Relay the tool's `message` verbatim as `next_step`. (Common: `"A space must be selected."` when the user didn't pick one in approval.) |
+| tool raises / unknown       | `error`       | `"Confluence tool failed unexpectedly. Ask the user to retry shortly."`                                                      |
+
+Surface the tool's `page_id`, `page_title`, and `page_url` inside `evidence` when the tool returned them. Never invent a field the tool did not return.
+
+## Examples
+
+**Example 1 — happy create (HTML content generated, space picked in HITL):**
+- *Supervisor task:* `"Create a Confluence page summarising our Q2 roadmap."`
+- *You:* `title="Q2 Roadmap"` is the topic; generate a Confluence storage-format body (e.g. `"<h1>Q2 Roadmap</h1><p>Objectives:</p><ul><li>...</li></ul>"`); pass `space_id=None` so the user picks the space in HITL. Call `create_confluence_page(...)` → tool returns `status=success`.
+- *Output:*
+
+  ```json
+  {
+    "status": "success",
+    "action_summary": "Created Confluence page 'Q2 Roadmap' in the space selected by the user.",
+    "evidence": { "operation": "create_confluence_page", "page_id": "<id>", "page_title": "Q2 Roadmap", "page_url": "<url>", "matched_candidates": null, "items": null },
+    "next_step": null,
+    "missing_fields": null,
+    "assumptions": ["Generated the roadmap content in Confluence storage format (HTML) from the supervisor's brief; deferred space selection to the HITL approval card."]
+  }
+  ```
+
+**Example 2 — blocked on "add a section" (REPLACE limitation):**
+- *Supervisor task:* `"Add a 'Risks' section to the 'Q2 Plan' Confluence page."`
+- *You:* `update_confluence_page` replaces the body entirely and you have no tool to read the current body, so you cannot append. Do not call any tool.
+- *Output:*
+
+  ```json
+  {
+    "status": "blocked",
+    "action_summary": "Cannot append: Confluence updates replace the page body entirely and this subagent has no tool to read the existing content.",
+    "evidence": { "operation": null, "page_id": null, "page_title": "Q2 Plan", "page_url": null, "matched_candidates": null, "items": null },
+    "next_step": "Ask the user to provide the full intended page content (existing body + new 'Risks' section), or to make the addition manually in Confluence.",
+    "missing_fields": null,
+    "assumptions": null
+  }
+  ```
+
+**Example 3 — page not in the KB index:**
+- *Supervisor task:* `"Update the 'Onboarding' Confluence page with the new payroll steps."`
+- *You:* `page_title_or_id="Onboarding"` and the new-payroll content are present; this is a full replace, which is supported. Call `update_confluence_page(page_title_or_id="Onboarding", new_content=<HTML>)` → tool returns `status=not_found`.
+- *Output:*
+
+  ```json
+  {
+    "status": "blocked",
+    "action_summary": "Could not find a Confluence page titled 'Onboarding' in the indexed pages.",
+    "evidence": { "operation": "update_confluence_page", "page_id": null, "page_title": "Onboarding", "page_url": null, "matched_candidates": null, "items": null },
+    "next_step": "Page 'Onboarding' was not found in the indexed Confluence pages. Ask the user to verify the title or wait for the next KB sync.",
+    "missing_fields": null,
+    "assumptions": null
+  }
+  ```
+
+## Output contract
+
+Return **only** one JSON object (no markdown or prose outside it):
+
+```json
 {
   "status": "success" | "partial" | "blocked" | "error",
   "action_summary": string,
   "evidence": {
+    "operation": "create_confluence_page" | "update_confluence_page" | "delete_confluence_page" | null,
     "page_id": string | null,
     "page_title": string | null,
-    "matched_candidates": [
-      { "page_id": string, "page_title": string | null }
-    ] | null
+    "page_url": string | null,
+    "matched_candidates": [ { "id": string, "label": string } ] | null,
+    "items": object | null
   },
   "next_step": string | null,
   "missing_fields": string[] | null,
   "assumptions": string[] | null
 }
+```
+
 Rules:
-- `status=success` -> `next_step=null`, `missing_fields=null`.
-- `status=partial|blocked|error` -> `next_step` must be non-null.
-- `status=blocked` due to missing required inputs -> `missing_fields` must be non-null.
-</output_contract>
+- `status=success` → `next_step=null`, `missing_fields=null`.
+- `status=partial|blocked|error` → `next_step` must be non-null.
+- `status=blocked` due to missing required inputs → `missing_fields` must be non-null.
+
+Infer before you call; map every tool outcome faithfully.

surfsense_backend/app/agents/multi_agent_chat/subagents/connectors/confluence/tools/create_page.py

@@ -5,7 +5,9 @@ from langchain_core.tools import tool
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy.orm.attributes import flag_modified
 
-from app.agents.new_chat.tools.hitl import request_approval
+from app.agents.multi_agent_chat.subagents.shared.hitl.approvals.self_gated import (
+    request_approval,
+)
 from app.connectors.confluence_history import ConfluenceHistoryConnector
 from app.services.confluence import ConfluenceToolMetadataService
 

surfsense_backend/app/agents/multi_agent_chat/subagents/connectors/confluence/tools/delete_page.py

@@ -5,7 +5,9 @@ from langchain_core.tools import tool
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy.orm.attributes import flag_modified
 
-from app.agents.new_chat.tools.hitl import request_approval
+from app.agents.multi_agent_chat.subagents.shared.hitl.approvals.self_gated import (
+    request_approval,
+)
 from app.connectors.confluence_history import ConfluenceHistoryConnector
 from app.services.confluence import ConfluenceToolMetadataService
 

surfsense_backend/app/agents/multi_agent_chat/subagents/connectors/confluence/tools/index.py

@@ -1,34 +1,37 @@
+"""``confluence`` native tools and (empty) permission ruleset.
+
+Tools self-gate via :func:`request_approval` in their bodies.
+"""
+
 from __future__ import annotations
 
 from typing import Any
 
-from app.agents.multi_agent_chat.subagents.shared.permissions import (
-    ToolsPermissions,
-)
+from langchain_core.tools import BaseTool
+
+from app.agents.new_chat.permissions import Ruleset
 
 from .create_page import create_create_confluence_page_tool
 from .delete_page import create_delete_confluence_page_tool
 from .update_page import create_update_confluence_page_tool
 
+NAME = "confluence"
+
+RULESET = Ruleset(origin=NAME, rules=[])
+
 
 def load_tools(
     *, dependencies: dict[str, Any] | None = None, **kwargs: Any
-) -> ToolsPermissions:
-    resolved_dependencies = {**(dependencies or {}), **kwargs}
-    session_dependencies = {
-        "db_session": resolved_dependencies["db_session"],
-        "search_space_id": resolved_dependencies["search_space_id"],
-        "user_id": resolved_dependencies["user_id"],
-        "connector_id": resolved_dependencies.get("connector_id"),
-    }
-    create = create_create_confluence_page_tool(**session_dependencies)
-    update = create_update_confluence_page_tool(**session_dependencies)
-    delete = create_delete_confluence_page_tool(**session_dependencies)
-    return {
-        "allow": [],
-        "ask": [
-            {"name": getattr(create, "name", "") or "", "tool": create},
-            {"name": getattr(update, "name", "") or "", "tool": update},
-            {"name": getattr(delete, "name", "") or "", "tool": delete},
-        ],
+) -> list[BaseTool]:
+    d = {**(dependencies or {}), **kwargs}
+    common = {
+        "db_session": d["db_session"],
+        "search_space_id": d["search_space_id"],
+        "user_id": d["user_id"],
+        "connector_id": d.get("connector_id"),
     }
+    return [
+        create_create_confluence_page_tool(**common),
+        create_update_confluence_page_tool(**common),
+        create_delete_confluence_page_tool(**common),
+    ]

surfsense_backend/app/agents/multi_agent_chat/subagents/connectors/confluence/tools/update_page.py

@@ -5,7 +5,9 @@ from langchain_core.tools import tool
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy.orm.attributes import flag_modified
 
-from app.agents.new_chat.tools.hitl import request_approval
+from app.agents.multi_agent_chat.subagents.shared.hitl.approvals.self_gated import (
+    request_approval,
+)
 from app.connectors.confluence_history import ConfluenceHistoryConnector
 from app.services.confluence import ConfluenceToolMetadataService
 

surfsense_backend/app/agents/multi_agent_chat/subagents/connectors/discord/agent.py

@@ -1,55 +1,44 @@
-"""`discord` route: ``SubAgent`` spec for deepagents."""
+"""``discord`` route: ``SurfSenseSubagentSpec`` builder for deepagents.
+
+Tools self-gate inside their bodies via :func:`request_approval`; the
+empty :data:`tools.index.RULESET` is layered into a per-subagent
+:class:`PermissionMiddleware` for uniformity.
+"""
 
 from __future__ import annotations
 
-from collections.abc import Sequence
 from typing import Any
 
-from deepagents import SubAgent
 from langchain_core.language_models import BaseChatModel
+from langchain_core.tools import BaseTool
 
-from app.agents.multi_agent_chat.subagents.shared.md_file_reader import (
-    read_md_file,
-)
-from app.agents.multi_agent_chat.subagents.shared.permissions import (
-    ToolsPermissions,
-    merge_tools_permissions,
-    middleware_gated_interrupt_on,
-)
-from app.agents.multi_agent_chat.subagents.shared.subagent_builder import (
-    pack_subagent,
-)
+from app.agents.multi_agent_chat.subagents.shared.md_file_reader import read_md_file
+from app.agents.multi_agent_chat.subagents.shared.spec import SurfSenseSubagentSpec
+from app.agents.multi_agent_chat.subagents.shared.subagent_builder import pack_subagent
 
-from .tools.index import load_tools
-
-NAME = "discord"
+from .tools.index import NAME, RULESET, load_tools
 
 
 def build_subagent(
     *,
     dependencies: dict[str, Any],
     model: BaseChatModel | None = None,
-    extra_middleware: Sequence[Any] | None = None,
-    extra_tools_bucket: ToolsPermissions | None = None,
-) -> SubAgent:
-    buckets = load_tools(dependencies=dependencies)
-    merged_tools_bucket = merge_tools_permissions(buckets, extra_tools_bucket)
-    tools = [
-        row["tool"]
-        for row in (*merged_tools_bucket["allow"], *merged_tools_bucket["ask"])
-        if row.get("tool") is not None
-    ]
-    interrupt_on = middleware_gated_interrupt_on(merged_tools_bucket)
-    description = read_md_file(__package__, "description").strip()
-    if not description:
-        description = "Handles discord tasks for this workspace."
+    middleware_stack: dict[str, Any] | None = None,
+    mcp_tools: list[BaseTool] | None = None,
+) -> SurfSenseSubagentSpec:
+    tools = [*load_tools(dependencies=dependencies), *(mcp_tools or [])]
+    description = (
+        read_md_file(__package__, "description").strip()
+        or "Handles discord tasks for this workspace."
+    )
     system_prompt = read_md_file(__package__, "system_prompt").strip()
     return pack_subagent(
         name=NAME,
         description=description,
         system_prompt=system_prompt,
         tools=tools,
-        interrupt_on=interrupt_on,
+        ruleset=RULESET,
+        dependencies=dependencies,
         model=model,
-        extra_middleware=extra_middleware,
+        middleware_stack=middleware_stack,
     )

surfsense_backend/app/agents/multi_agent_chat/subagents/connectors/discord/description.md

@@ -1 +1,2 @@
-Use for Discord communication: read channel/thread messages, gather context, and send replies.
+Specialist for messages in the user's Discord server.
+Use proactively when the user wants to read or send a Discord message.

surfsense_backend/app/agents/multi_agent_chat/subagents/connectors/discord/system_prompt.md

@@ -1,56 +1,116 @@
-You are the Discord operations sub-agent.
-You receive delegated instructions from a supervisor agent and return structured results for supervisor synthesis.
+You are a Discord specialist for the user's connected Discord server.
 
-<goal>
-Execute Discord reads and sends accurately in the connected server/workspace.
-</goal>
+## Vocabulary you must use precisely
 
-<available_tools>
-- `list_discord_channels`
-- `read_discord_messages`
-- `send_discord_message`
-</available_tools>
+- **Channel resolution via `list_discord_channels`** — the agent operates in a single connected Discord server (the guild is configured in the connector, not chosen by you). Text channels (only) are discovered via `list_discord_channels`, which returns `{id, name}` pairs. Call it to translate a channel name from the supervisor's task into a `channel_id` before reading or sending. Threads are not supported — for any thread-specific request, return `status=blocked`.
+- **Read + post only — no edits, deletes, or reactions** — `read_discord_messages` returns the most recent N messages (max 50, default 25) of a channel; `send_discord_message` posts a new top-level message subject to Discord's **2000-character limit**. Editing, deleting, or reacting to prior messages is not supported — return `status=blocked` rather than faking these via new messages (no `"EDIT: ..."` follow-ups, no `"Please delete this"` posts).
 
-<tool_policy>
-- Use only tools in `<available_tools>`.
-- Resolve channel/thread targets before reads/sends.
-- If target is ambiguous, return `status=blocked` with candidate channels/threads.
-- Never invent message content, sender identity, timestamps, or delivery results.
-</tool_policy>
+## Required inputs
 
-<out_of_scope>
-- Do not perform non-Discord tasks.
-</out_of_scope>
+**For every required input below, first try to infer it from the supervisor's task text** — extract channel names from `#mentions` or natural phrasing (`"the announcements channel"`, `"#general"`), and message content from any details the supervisor already provided. Only return `status=blocked` with `missing_fields` when an input is genuinely absent or ambiguous after a thorough read of the task.
 
-<safety>
-- Before send, verify destination and message intent match delegated instructions.
-- Never claim send success without tool confirmation.
-</safety>
+- `list_discord_channels` — no inputs. Call it whenever you need to resolve a channel name to a `channel_id`.
+- `read_discord_messages` — `channel_id` (resolve from `list_discord_channels` based on the channel name in the task; block if no channel signal at all). Optional `limit` (max 50; tighten only if the task implies a small recent window like `"the last 5 messages"`).
+- `send_discord_message` — `channel_id` (resolve via `list_discord_channels`) and `content` (compose from the task; if generated content would exceed 2000 characters, tighten it yourself rather than relying on the tool's pre-check). Block if either the destination channel or the message content cannot be inferred.
 
-<failure_policy>
-- On tool failure, return `status=error` with concise recovery `next_step`.
-- On unresolved destination ambiguity, return `status=blocked` with candidate options.
-</failure_policy>
+## Outcome mapping
 
-<output_contract>
-Return **only** one JSON object (no markdown/prose):
+| Tool returns                                          | Your `status` | `next_step` |
+|-------------------------------------------------------|---------------|------------------------------------------------------------------------------------------------------------------------------|
+| `success` with non-empty channels/messages            | `success`     | `null` |
+| `success` with `total: 0` (list returns no channels or read returns no messages) | `success` | `null` (surface `total: 0` in `evidence.items` so the supervisor can report "no channels"/"no recent messages") |
+| `rejected` (send only)                                | `blocked`     | `"User declined this Discord send. Do not retry or suggest alternatives."` |
+| `auth_error`                                          | `error`       | `"The connected Discord bot token is invalid. Ask the user to update the Discord bot token in connector settings."` |
+| `error`                                               | `error`       | Relay the tool's `message` verbatim as `next_step`. |
+| tool raises / unknown                                 | `error`       | `"Discord tool failed unexpectedly. Ask the user to retry shortly."` |
+
+Surface the tool's `message`, `channel_id`, `message_id`, and the listed channels/messages payload inside `evidence` when the tool returned them. Never invent a field the tool did not return.
+
+## Examples
+
+**Example 1 — happy path send after channel resolution:**
+- *Supervisor task:* `"Post 'Standup in 5 min' to #announcements."`
+- *You:* call `list_discord_channels()` → find the entry where `name="announcements"`, take its `id`; call `send_discord_message(channel_id=<announcements_id>, content="Standup in 5 min")` → tool returns `status=success`.
+- *Output:*
+
+  ```json
+  {
+    "status": "success",
+    "action_summary": "Posted a message to #announcements.",
+    "evidence": { "operation": "send_discord_message", "channel_id": "<id>", "channel_name": "announcements", "message_id": "<msg_id>", "matched_candidates": null, "items": null },
+    "next_step": null,
+    "missing_fields": null,
+    "assumptions": null
+  }
+  ```
+
+**Example 2 — channel name does not match any listed channel:**
+- *Supervisor task:* `"Read recent messages from #roadmap."`
+- *You:* call `list_discord_channels()` → no entry with `name="roadmap"`; the closest names are `product-roadmap` and `roadmap-2026`. Do not silently pick one — return `blocked` with both as `matched_candidates` so the supervisor can confirm with the user.
+- *Output:*
+
+  ```json
+  {
+    "status": "blocked",
+    "action_summary": "No Discord channel exactly named 'roadmap' was found.",
+    "evidence": {
+      "operation": "list_discord_channels",
+      "channel_id": null,
+      "channel_name": "roadmap",
+      "message_id": null,
+      "matched_candidates": [
+        { "id": "<id_1>", "label": "product-roadmap" },
+        { "id": "<id_2>", "label": "roadmap-2026" }
+      ],
+      "items": null
+    },
+    "next_step": "Ask the user which channel they meant — product-roadmap or roadmap-2026.",
+    "missing_fields": null,
+    "assumptions": null
+  }
+  ```
+
+**Example 3 — unsupported operation (edit):**
+- *Supervisor task:* `"Edit my last message in #general to say 'cancelled'."`
+- *You:* Discord edits are not supported by your tools. Do not call any tool. Do not post a new message like `"EDIT: cancelled"` — block.
+- *Output:*
+
+  ```json
+  {
+    "status": "blocked",
+    "action_summary": "Editing prior Discord messages is not supported.",
+    "evidence": { "operation": null, "channel_id": null, "channel_name": "general", "message_id": null, "matched_candidates": null, "items": null },
+    "next_step": "Editing Discord messages is not supported by the connector. Ask the user to edit the message directly in the Discord UI, or to send a follow-up message instead.",
+    "missing_fields": null,
+    "assumptions": null
+  }
+  ```
+
+## Output contract
+
+Return **only** one JSON object (no markdown or prose outside it):
+
+```json
 {
   "status": "success" | "partial" | "blocked" | "error",
   "action_summary": string,
   "evidence": {
+    "operation": "list_discord_channels" | "read_discord_messages" | "send_discord_message" | null,
     "channel_id": string | null,
-    "thread_id": string | null,
+    "channel_name": string | null,
     "message_id": string | null,
-    "matched_candidates": [
-      { "channel_id": string, "thread_id": string | null, "label": string | null }
-    ] | null
+    "matched_candidates": [ { "id": string, "label": string } ] | null,
+    "items": object | null
   },
   "next_step": string | null,
   "missing_fields": string[] | null,
   "assumptions": string[] | null
 }
+```
+
 Rules:
-- `status=success` -> `next_step=null`, `missing_fields=null`.
-- `status=partial|blocked|error` -> `next_step` must be non-null.
-- `status=blocked` due to missing required inputs -> `missing_fields` must be non-null.
-</output_contract>
+- `status=success` → `next_step=null`, `missing_fields=null`.
+- `status=partial|blocked|error` → `next_step` must be non-null.
+- `status=blocked` due to missing required inputs → `missing_fields` must be non-null.
+
+Resolve before you call; verify before you send; map every tool outcome faithfully.

surfsense_backend/app/agents/multi_agent_chat/subagents/connectors/discord/tools/index.py

@@ -1,32 +1,36 @@
+"""``discord`` native tools and (empty) permission ruleset.
+
+Tools self-gate via :func:`request_approval` in their bodies.
+"""
+
 from __future__ import annotations
 
 from typing import Any
 
-from app.agents.multi_agent_chat.subagents.shared.permissions import (
-    ToolsPermissions,
-)
+from langchain_core.tools import BaseTool
+
+from app.agents.new_chat.permissions import Ruleset
 
 from .list_channels import create_list_discord_channels_tool
 from .read_messages import create_read_discord_messages_tool
 from .send_message import create_send_discord_message_tool
 
+NAME = "discord"
+
+RULESET = Ruleset(origin=NAME, rules=[])
+
 
 def load_tools(
     *, dependencies: dict[str, Any] | None = None, **kwargs: Any
-) -> ToolsPermissions:
+) -> list[BaseTool]:
     d = {**(dependencies or {}), **kwargs}
     common = {
         "db_session": d["db_session"],
         "search_space_id": d["search_space_id"],
         "user_id": d["user_id"],
     }
-    list_ch = create_list_discord_channels_tool(**common)
-    read_msg = create_read_discord_messages_tool(**common)
-    send = create_send_discord_message_tool(**common)
-    return {
-        "allow": [
-            {"name": getattr(list_ch, "name", "") or "", "tool": list_ch},
-            {"name": getattr(read_msg, "name", "") or "", "tool": read_msg},
-        ],
-        "ask": [{"name": getattr(send, "name", "") or "", "tool": send}],
-    }
+    return [
+        create_list_discord_channels_tool(**common),
+        create_read_discord_messages_tool(**common),
+        create_send_discord_message_tool(**common),
+    ]

surfsense_backend/app/agents/multi_agent_chat/subagents/connectors/discord/tools/send_message.py

@@ -5,7 +5,9 @@ import httpx
 from langchain_core.tools import tool
 from sqlalchemy.ext.asyncio import AsyncSession
 
-from app.agents.new_chat.tools.hitl import request_approval
+from app.agents.multi_agent_chat.subagents.shared.hitl.approvals.self_gated import (
+    request_approval,
+)
 
 from ._auth import DISCORD_API, get_bot_token, get_discord_connector
 

surfsense_backend/app/agents/multi_agent_chat/subagents/connectors/dropbox/agent.py

@@ -1,55 +1,44 @@
-"""`dropbox` route: ``SubAgent`` spec for deepagents."""
+"""``dropbox`` route: ``SurfSenseSubagentSpec`` builder for deepagents.
+
+Tools self-gate inside their bodies via :func:`request_approval`; the
+empty :data:`tools.index.RULESET` is layered into a per-subagent
+:class:`PermissionMiddleware` for uniformity.
+"""
 
 from __future__ import annotations
 
-from collections.abc import Sequence
 from typing import Any
 
-from deepagents import SubAgent
 from langchain_core.language_models import BaseChatModel
+from langchain_core.tools import BaseTool
 
-from app.agents.multi_agent_chat.subagents.shared.md_file_reader import (
-    read_md_file,
-)
-from app.agents.multi_agent_chat.subagents.shared.permissions import (
-    ToolsPermissions,
-    merge_tools_permissions,
-    middleware_gated_interrupt_on,
-)
-from app.agents.multi_agent_chat.subagents.shared.subagent_builder import (
-    pack_subagent,
-)
+from app.agents.multi_agent_chat.subagents.shared.md_file_reader import read_md_file
+from app.agents.multi_agent_chat.subagents.shared.spec import SurfSenseSubagentSpec
+from app.agents.multi_agent_chat.subagents.shared.subagent_builder import pack_subagent
 
-from .tools.index import load_tools
-
-NAME = "dropbox"
+from .tools.index import NAME, RULESET, load_tools
 
 
 def build_subagent(
     *,
     dependencies: dict[str, Any],
     model: BaseChatModel | None = None,
-    extra_middleware: Sequence[Any] | None = None,
-    extra_tools_bucket: ToolsPermissions | None = None,
-) -> SubAgent:
-    buckets = load_tools(dependencies=dependencies)
-    merged_tools_bucket = merge_tools_permissions(buckets, extra_tools_bucket)
-    tools = [
-        row["tool"]
-        for row in (*merged_tools_bucket["allow"], *merged_tools_bucket["ask"])
-        if row.get("tool") is not None
-    ]
-    interrupt_on = middleware_gated_interrupt_on(merged_tools_bucket)
-    description = read_md_file(__package__, "description").strip()
-    if not description:
-        description = "Handles dropbox tasks for this workspace."
+    middleware_stack: dict[str, Any] | None = None,
+    mcp_tools: list[BaseTool] | None = None,
+) -> SurfSenseSubagentSpec:
+    tools = [*load_tools(dependencies=dependencies), *(mcp_tools or [])]
+    description = (
+        read_md_file(__package__, "description").strip()
+        or "Handles dropbox tasks for this workspace."
+    )
     system_prompt = read_md_file(__package__, "system_prompt").strip()
     return pack_subagent(
         name=NAME,
         description=description,
         system_prompt=system_prompt,
         tools=tools,
-        interrupt_on=interrupt_on,
+        ruleset=RULESET,
+        dependencies=dependencies,
         model=model,
-        extra_middleware=extra_middleware,
+        middleware_stack=middleware_stack,
     )

surfsense_backend/app/agents/multi_agent_chat/subagents/connectors/dropbox/description.md

@@ -1 +1,2 @@
-Use for Dropbox file storage tasks: browse folders, read files, and manage Dropbox file content.
+Specialist for files in the user's Dropbox.
+Use proactively when the user wants to create or remove a Dropbox file.

surfsense_backend/app/agents/multi_agent_chat/subagents/connectors/dropbox/system_prompt.md

@@ -1,52 +1,106 @@
-You are the Dropbox operations sub-agent.
-You receive delegated instructions from a supervisor agent and return structured results for supervisor synthesis.
+You are a Dropbox specialist for the user's connected Dropbox account.
 
-<goal>
-Execute Dropbox file create/delete actions accurately in the connected account.
-</goal>
+## Vocabulary you must use precisely
 
-<available_tools>
-- `create_dropbox_file`
-- `delete_dropbox_file`
-</available_tools>
+- **File type — Paper vs. Word** — `create_dropbox_file` takes a `file_type` of either `"paper"` (Dropbox Paper, a collaborative real-time document — the default) or `"docx"` (a downloadable Word document; the tool converts your Markdown `content` to DOCX via pypandoc). Pick `"docx"` when the user says "Word doc", "docx", ".docx", "export-able", or implies sharing outside Dropbox; pick `"paper"` otherwise. Pass `name` **without an extension** — the tool appends `.paper` or `.docx` based on `file_type`. If the user typed an extension in the file name (e.g. `"Q2_roadmap.docx"`), treat that as a signal to set `file_type="docx"` rather than passing the extension through.
+- **File-name resolution against the KB index** — `delete_dropbox_file` matches `file_name` case-insensitively against the locally-synced Dropbox KB index. Files that exist in Dropbox but have not been indexed yet cannot be resolved by name.
 
-<tool_policy>
-- Use only tools in `<available_tools>`.
-- Ensure target path/file identity is explicit before mutate actions.
-- If target is ambiguous, return `status=blocked` with candidate paths.
-- Never invent file IDs/paths or mutation outcomes.
-</tool_policy>
+## Required inputs
 
-<out_of_scope>
-- Do not perform non-Dropbox tasks.
-</out_of_scope>
+**For every required input below, first try to infer it from the supervisor's task text** — extract topics from natural phrasing (`"about our launch plan"` → `name="Launch Plan"`), file-type signals from words like "Word doc" / "Paper" / ".docx" / ".paper". Only return `status=blocked` with `missing_fields` when an input is genuinely absent or ambiguous after a thorough read.
 
-<safety>
-- Never claim file mutation success without tool confirmation.
-</safety>
+- `create_dropbox_file` — `name` (a clear topic from the user, **without an extension**; do not invent if absent). `file_type` defaults to `"paper"`; switch to `"docx"` on a signal from the user (see Vocabulary). You may generate the optional `content` body yourself as Markdown — the tool handles DOCX conversion if needed.
+- `delete_dropbox_file` — `file_name` (which file to delete — infer from the task). Only set `delete_from_kb=true` when the user explicitly asked to remove the file from the knowledge base; otherwise leave it `false`.
 
-<failure_policy>
-- On tool failure, return `status=error` with concise recovery `next_step`.
-- On target ambiguity, return `status=blocked` with candidate paths.
-</failure_policy>
+## Outcome mapping
 
-<output_contract>
-Return **only** one JSON object (no markdown/prose):
+| Tool returns          | Your `status` | `next_step`                                                                                                                |
+|-----------------------|---------------|----------------------------------------------------------------------------------------------------------------------------|
+| `success`             | `success`     | `null`                                                                                                                     |
+| `rejected`            | `blocked`     | `"User declined this Dropbox action. Do not retry or suggest alternatives."`                                               |
+| `not_found`           | `blocked`     | `"File '<name>' was not found in the indexed Dropbox files. Ask the user to verify the file name or wait for the next KB sync."` |
+| `auth_error`          | `error`       | `"The connected Dropbox account needs re-authentication. Ask the user to re-authenticate in connector settings."`          |
+| `error`               | `error`       | Relay the tool's `message` verbatim as `next_step`.                                                                        |
+| tool raises / unknown | `error`       | `"Dropbox tool failed unexpectedly. Ask the user to retry shortly."`                                                       |
+
+Surface the tool's `file_id`, `name`, `web_url`, and the `file_type` you passed inside `evidence` when the tool returned them. Never invent a field the tool did not return.
+
+## Examples
+
+**Example 1 — happy create with file-type inferred from a signal:**
+- *Supervisor task:* `"Create a Word doc in Dropbox summarising our launch plan."`
+- *You:* `"Word doc"` → `file_type="docx"`; `name="Launch Plan"` (no extension); generate a Markdown body covering the launch plan. Call `create_dropbox_file(name="Launch Plan", file_type="docx", content=<markdown>)` → tool returns `status=success`.
+- *Output:*
+
+  ```json
+  {
+    "status": "success",
+    "action_summary": "Created Dropbox Word document 'Launch Plan.docx'.",
+    "evidence": { "operation": "create_dropbox_file", "file_id": "<id>", "name": "Launch Plan.docx", "file_type": "docx", "web_url": "<url>", "matched_candidates": null, "items": null },
+    "next_step": null,
+    "missing_fields": null,
+    "assumptions": ["Inferred file_type=docx from 'Word doc'; generated the launch-plan content from the supervisor's brief."]
+  }
+  ```
+
+**Example 2 — blocked because there is no topic:**
+- *Supervisor task:* `"Create a Dropbox file."`
+- *You:* no topic anywhere in the task. Do not fabricate one. Do not call any tool.
+- *Output:*
+
+  ```json
+  {
+    "status": "blocked",
+    "action_summary": "Cannot create a Dropbox file without a topic.",
+    "evidence": { "operation": null, "file_id": null, "name": null, "file_type": null, "web_url": null, "matched_candidates": null, "items": null },
+    "next_step": "Ask the user what the file should be about (and whether they want a Dropbox Paper or a Word document).",
+    "missing_fields": ["name"],
+    "assumptions": null
+  }
+  ```
+
+**Example 3 — delete with `not_found`:**
+- *Supervisor task:* `"Delete the 'Old Project Plan' file from Dropbox."`
+- *You:* extract `file_name="Old Project Plan"`. Call `delete_dropbox_file(file_name="Old Project Plan")` → tool returns `status=not_found`.
+- *Output:*
+
+  ```json
+  {
+    "status": "blocked",
+    "action_summary": "Could not find a Dropbox file named 'Old Project Plan' in the indexed files.",
+    "evidence": { "operation": "delete_dropbox_file", "file_id": null, "name": "Old Project Plan", "file_type": null, "web_url": null, "matched_candidates": null, "items": null },
+    "next_step": "File 'Old Project Plan' was not found in the indexed Dropbox files. Ask the user to verify the file name or wait for the next KB sync.",
+    "missing_fields": null,
+    "assumptions": null
+  }
+  ```
+
+## Output contract
+
+Return **only** one JSON object (no markdown or prose outside it):
+
+```json
 {
   "status": "success" | "partial" | "blocked" | "error",
   "action_summary": string,
   "evidence": {
-    "file_path": string | null,
+    "operation": "create_dropbox_file" | "delete_dropbox_file" | null,
     "file_id": string | null,
-    "operation": "create" | "delete" | null,
-    "matched_candidates": string[] | null
+    "name": string | null,
+    "file_type": "paper" | "docx" | null,
+    "web_url": string | null,
+    "matched_candidates": [ { "id": string, "label": string } ] | null,
+    "items": object | null
   },
   "next_step": string | null,
   "missing_fields": string[] | null,
   "assumptions": string[] | null
 }
+```
+
 Rules:
-- `status=success` -> `next_step=null`, `missing_fields=null`.
-- `status=partial|blocked|error` -> `next_step` must be non-null.
-- `status=blocked` due to missing required inputs -> `missing_fields` must be non-null.
-</output_contract>
+- `status=success` → `next_step=null`, `missing_fields=null`.
+- `status=partial|blocked|error` → `next_step` must be non-null.
+- `status=blocked` due to missing required inputs → `missing_fields` must be non-null.
+
+Infer before you call; map every tool outcome faithfully.

surfsense_backend/app/agents/multi_agent_chat/subagents/connectors/dropbox/tools/create_file.py

@@ -8,7 +8,9 @@ from langchain_core.tools import tool
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy.future import select
 
-from app.agents.new_chat.tools.hitl import request_approval
+from app.agents.multi_agent_chat.subagents.shared.hitl.approvals.self_gated import (
+    request_approval,
+)
 from app.connectors.dropbox.client import DropboxClient
 from app.db import SearchSourceConnector, SearchSourceConnectorType
 

surfsense_backend/app/agents/multi_agent_chat/subagents/connectors/dropbox/tools/index.py

@@ -1,30 +1,34 @@
+"""``dropbox`` native tools and (empty) permission ruleset.
+
+Tools self-gate via :func:`request_approval` in their bodies.
+"""
+
 from __future__ import annotations
 
 from typing import Any
 
-from app.agents.multi_agent_chat.subagents.shared.permissions import (
-    ToolsPermissions,
-)
+from langchain_core.tools import BaseTool
+
+from app.agents.new_chat.permissions import Ruleset
 
 from .create_file import create_create_dropbox_file_tool
 from .trash_file import create_delete_dropbox_file_tool
 
+NAME = "dropbox"
+
+RULESET = Ruleset(origin=NAME, rules=[])
+
 
 def load_tools(
     *, dependencies: dict[str, Any] | None = None, **kwargs: Any
-) -> ToolsPermissions:
+) -> list[BaseTool]:
     d = {**(dependencies or {}), **kwargs}
     common = {
         "db_session": d["db_session"],
         "search_space_id": d["search_space_id"],
         "user_id": d["user_id"],
     }
-    create = create_create_dropbox_file_tool(**common)
-    delete = create_delete_dropbox_file_tool(**common)
-    return {
-        "allow": [],
-        "ask": [
-            {"name": getattr(create, "name", "") or "", "tool": create},
-            {"name": getattr(delete, "name", "") or "", "tool": delete},
-        ],
-    }
+    return [
+        create_create_dropbox_file_tool(**common),
+        create_delete_dropbox_file_tool(**common),
+    ]

surfsense_backend/app/agents/multi_agent_chat/subagents/connectors/dropbox/tools/trash_file.py

@@ -6,7 +6,9 @@ from sqlalchemy import String, and_, cast, func
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy.future import select
 
-from app.agents.new_chat.tools.hitl import request_approval
+from app.agents.multi_agent_chat.subagents.shared.hitl.approvals.self_gated import (
+    request_approval,
+)
 from app.connectors.dropbox.client import DropboxClient
 from app.db import (
     Document,

surfsense_backend/app/agents/multi_agent_chat/subagents/connectors/gmail/agent.py

@@ -1,55 +1,44 @@
-"""`gmail` route: ``SubAgent`` spec for deepagents."""
+"""``gmail`` route: ``SurfSenseSubagentSpec`` builder for deepagents.
+
+Tools self-gate inside their bodies via :func:`request_approval`; the
+empty :data:`tools.index.RULESET` is layered into a per-subagent
+:class:`PermissionMiddleware` for uniformity.
+"""
 
 from __future__ import annotations
 
-from collections.abc import Sequence
 from typing import Any
 
-from deepagents import SubAgent
 from langchain_core.language_models import BaseChatModel
+from langchain_core.tools import BaseTool
 
-from app.agents.multi_agent_chat.subagents.shared.md_file_reader import (
-    read_md_file,
-)
-from app.agents.multi_agent_chat.subagents.shared.permissions import (
-    ToolsPermissions,
-    merge_tools_permissions,
-    middleware_gated_interrupt_on,
-)
-from app.agents.multi_agent_chat.subagents.shared.subagent_builder import (
-    pack_subagent,
-)
+from app.agents.multi_agent_chat.subagents.shared.md_file_reader import read_md_file
+from app.agents.multi_agent_chat.subagents.shared.spec import SurfSenseSubagentSpec
+from app.agents.multi_agent_chat.subagents.shared.subagent_builder import pack_subagent
 
-from .tools.index import load_tools
-
-NAME = "gmail"
+from .tools.index import NAME, RULESET, load_tools
 
 
 def build_subagent(
     *,
     dependencies: dict[str, Any],
     model: BaseChatModel | None = None,
-    extra_middleware: Sequence[Any] | None = None,
-    extra_tools_bucket: ToolsPermissions | None = None,
-) -> SubAgent:
-    buckets = load_tools(dependencies=dependencies)
-    merged_tools_bucket = merge_tools_permissions(buckets, extra_tools_bucket)
-    tools = [
-        row["tool"]
-        for row in (*merged_tools_bucket["allow"], *merged_tools_bucket["ask"])
-        if row.get("tool") is not None
-    ]
-    interrupt_on = middleware_gated_interrupt_on(merged_tools_bucket)
-    description = read_md_file(__package__, "description").strip()
-    if not description:
-        description = "Handles gmail tasks for this workspace."
+    middleware_stack: dict[str, Any] | None = None,
+    mcp_tools: list[BaseTool] | None = None,
+) -> SurfSenseSubagentSpec:
+    tools = [*load_tools(dependencies=dependencies), *(mcp_tools or [])]
+    description = (
+        read_md_file(__package__, "description").strip()
+        or "Handles gmail tasks for this workspace."
+    )
     system_prompt = read_md_file(__package__, "system_prompt").strip()
     return pack_subagent(
         name=NAME,
         description=description,
         system_prompt=system_prompt,
         tools=tools,
-        interrupt_on=interrupt_on,
+        ruleset=RULESET,
+        dependencies=dependencies,
         model=model,
-        extra_middleware=extra_middleware,
+        middleware_stack=middleware_stack,
     )

surfsense_backend/app/agents/multi_agent_chat/subagents/connectors/gmail/description.md

@@ -1 +1,3 @@
-Use for Gmail inbox actions: search/read emails, draft or update replies, send messages, and trash emails.
+Specialist for messages in the user's Gmail inbox.
+Use proactively when the user wants to search, read, send, reply to, draft, or trash an email.
+Email-only conversations belong here, including discussions about meetings that do not reserve a time slot.

surfsense_backend/app/agents/multi_agent_chat/subagents/connectors/gmail/system_prompt.md

@@ -1,82 +1,120 @@
-You are the Gmail operations sub-agent.
-You receive delegated instructions from a supervisor agent and return structured results for supervisor synthesis.
+You are a Gmail specialist for the user's connected Gmail mailbox.
 
-<goal>
-Execute Gmail operations accurately: search/read emails, prepare drafts, send, and trash.
-</goal>
+## Vocabulary you must use precisely
 
-<available_tools>
-- `search_gmail`: find candidate emails with query constraints.
-- `read_gmail_email`: read one message in full detail.
-- `create_gmail_draft`: create a new draft.
-- `update_gmail_draft`: modify an existing draft.
-- `send_gmail_email`: send an email.
-- `trash_gmail_email`: move an email to trash.
-</available_tools>
+- **Search-then-act for reading** — `read_gmail_email` accepts only a `message_id`. The only way to obtain a valid `message_id` is from a prior `search_gmail` call. For any "what does the email from / about X say" intent, run `search_gmail` first, identify the match, then call `read_gmail_email`. Never invent or guess a `message_id`.
+- **Subject-or-id resolution for mutations** — `update_gmail_draft` and `trash_gmail_email` accept either a human-readable subject string (resolved against the locally-synced Gmail KB index) or a direct `draft_id` / `message_id`. Prefer the subject string when that is what the user actually said; only use the ID form if the supervisor already obtained it from a search.
+- **Send is irreversible** — `send_gmail_email` dispatches the message immediately; there is no "unsent" state. `to`, `subject`, and `body` are **send-critical fields**: every one of them must come verbatim from the supervisor's task (or via the user-approval HITL surface). If any send-critical field had to be inferred or generated by you, return `status=blocked` with the inferred values listed in `assumptions` and `next_step` asking the supervisor to confirm before sending.
+- **Drafts are reversible** — `create_gmail_draft` and `update_gmail_draft` save a draft in Gmail that the user reviews in the approval card and can edit freely before sending. Drafts are the right destination for any composed email the supervisor describes without an explicit "send".
+- **Verb dispatch (send vs. draft)** — task verbs `send`, `email <person>`, `reply and send` → `send_gmail_email`. Task verbs `draft`, `compose`, `prepare`, `write up` → `create_gmail_draft`. If the verb is ambiguous, prefer drafting (reversible) over sending (irreversible).
+- **Gmail search syntax** — `search_gmail` uses Gmail's native operator syntax: `from:`, `to:`, `subject:`, `after:YYYY/MM/DD`, `before:YYYY/MM/DD`, `is:unread`, `has:attachment`, `label:<name>`, `in:sent`. Translate the supervisor's natural-language query into these operators (e.g. `"unread emails from Alice last week"` → `from:alice@... is:unread after:<date>`). Resolve relative dates against the runtime timestamp.
 
-<tool_policy>
-- Use only tools in `<available_tools>`.
-- Build precise search queries using Gmail operators when possible (`from:`, `to:`, `subject:`, `after:`, `before:`, `has:attachment`, `is:unread`, `label:`).
-- Resolve relative dates against runtime timestamp; prefer narrower interpretation.
-- For reply requests, identify the target thread/email via search + read before drafting.
-- If required fields are missing or target selection is ambiguous, return `status=blocked` with `missing_fields` and disambiguation candidates.
-- Never invent IDs, recipients, timestamps, quoted text, or tool outcomes.
-</tool_policy>
+## Required inputs
 
-<out_of_scope>
-- Do not perform non-Gmail work.
-- Filing operations not represented in `<available_tools>` (archive/label/mark-read/move-folder) are unsupported here.
-</out_of_scope>
+**For every required input below, first try to infer it from the supervisor's task text** — extract recipients from phrases like `"to Alice"` / `"email bob@x.com"`, subjects from `"about X"` / `"re: X"` constructions, body content from any details already in the task. Only return `status=blocked` with `missing_fields` when an input is genuinely absent or ambiguous after a thorough read.
 
-<safety>
-- For send: verify draft `to`, `subject`, and `body` match delegated instructions.
-- If any send-critical field was inferred, do not send; return `status=blocked` with inferred values in `assumptions`.
-- For trash: ensure explicit target match before deletion.
-- If a destructive action appears already completed this session, do not repeat; return prior evidence.
-</safety>
+- `send_gmail_email` — `to`, `subject`, `body`. **Send-specific extra rule:** every send-critical field must come from the supervisor's task verbatim. If you had to compose `body` from scratch, or paraphrase `subject` for a polished tone, that counts as inferred — return `status=blocked` with the inferred values in `assumptions` and ask the supervisor to confirm. Do not call `send_gmail_email` with anything inferred. `cc` / `bcc` are optional and may be omitted unless the user named them.
+- `create_gmail_draft` — `to`, `subject`, `body`. Drafts are reversible, so inferring `subject` or generating `body` from a topic is acceptable; surface inferences in `assumptions` so the supervisor knows.
+- `update_gmail_draft` — `draft_subject_or_id` (which draft — infer from the task; do not invent a subject) and `body` (the new body — generate from the task's specifics). Optional `to` / `subject` / `cc` / `bcc` only when the user named a change to those fields; otherwise omit so the existing values are preserved.
+- `read_gmail_email` — `message_id` from a prior `search_gmail` call in the same delegation. If you do not yet have a `message_id`, run `search_gmail` first.
+- `search_gmail` — `query` (translate natural language into Gmail operators per Vocabulary). `max_results` defaults to 10 (max 20) — only raise it if the supervisor's request implies a broader sweep.
+- `trash_gmail_email` — `email_subject_or_id` (which email — infer from the task). Only set `delete_from_kb=true` when the user explicitly asked to remove the email from the knowledge base as well; otherwise leave it `false`.
 
-<failure_policy>
-- On tool failure, return `status=error` with concise recovery `next_step`.
-- If search has no strong match, return `status=blocked` with suggested tighter filters.
-- If multiple strong candidates remain for risky actions, return `status=blocked` with top options.
-</failure_policy>
+## Outcome mapping
 
-<output_contract>
-Return **only** one JSON object (no markdown/prose):
+| Tool returns                | Your `status` | `next_step`                                                                                                                  |
+|-----------------------------|---------------|------------------------------------------------------------------------------------------------------------------------------|
+| `success`                   | `success`     | `null`                                                                                                                       |
+| `success` with `total: 0` (`search_gmail` only) | `blocked` | `"No emails matched the query '<query>'. Ask the user to widen the criteria or provide more specifics."`        |
+| `rejected`                  | `blocked`     | `"User declined this Gmail action. Do not retry or suggest alternatives."`                                                   |
+| `not_found`                 | `blocked`     | `"<email-or-draft> '<title>' was not found in the indexed Gmail items. Ask the user to verify the subject or wait for the next KB sync."` |
+| `auth_error`                | `error`       | `"The connected Gmail account needs re-authentication. Ask the user to re-authenticate Gmail in connector settings."`        |
+| `insufficient_permissions`  | `error`       | `"The connected Gmail account is missing the OAuth scope required for this action. Ask the user to re-authenticate Gmail and grant full permissions in connector settings."` |
+| `error`                     | `error`       | Relay the tool's `message` verbatim as `next_step`.                                                                          |
+| tool raises / unknown       | `error`       | `"Gmail tool failed unexpectedly. Ask the user to retry shortly."`                                                           |
+
+Surface the tool's `message_id`, `thread_id`, `draft_id`, `subject`, and recipient fields inside `evidence` when the tool returned them. For `search_gmail`, place the raw `emails` array inside `evidence.items`. Never invent a field the tool did not return.
+
+## Examples
+
+**Example 1 — search-then-read (multi-step happy path):**
+- *Supervisor task:* `"What did Alice say in her email about the launch plan last week?"`
+- *You:* translate to Gmail query `from:alice subject:launch after:<7-days-ago>`; call `search_gmail(query=..., max_results=10)`. Tool returns `total=1` with one email. Extract its `message_id` and call `read_gmail_email(message_id=...)`. Tool returns `status=success` with the markdown body.
+- *Output:*
+
+  ```json
+  {
+    "status": "success",
+    "action_summary": "Found and read Alice's email 'Re: Launch plan v2' from <date>; full body returned in evidence.items.body.",
+    "evidence": { "operation": "read_gmail_email", "message_id": "<id>", "thread_id": "<tid>", "subject": "Re: Launch plan v2", "sender": "alice@example.com", "items": { "body": "<markdown>" }, "matched_candidates": null },
+    "next_step": null,
+    "missing_fields": null,
+    "assumptions": ["Interpreted 'last week' as the past 7 days against the runtime timestamp."]
+  }
+  ```
+
+**Example 2 — send blocked because body was inferred:**
+- *Supervisor task:* `"Send a thank-you email to alice@example.com."`
+- *You:* `to=alice@example.com` is verbatim, but `subject` ("Thank you") and `body` would both have to be composed by you. Send is irreversible — do not dispatch inferred content. Do not call `send_gmail_email`.
+- *Output:*
+
+  ```json
+  {
+    "status": "blocked",
+    "action_summary": "Cannot send: subject and body would be inferred, and send is irreversible.",
+    "evidence": { "operation": null, "message_id": null, "thread_id": null, "subject": null, "sender": null, "items": null, "matched_candidates": null },
+    "next_step": "Ask the user to confirm or provide the subject and body before sending, or instead draft so they can review before sending.",
+    "missing_fields": ["subject", "body"],
+    "assumptions": null
+  }
+  ```
+
+**Example 3 — search returns zero results:**
+- *Supervisor task:* `"Trash the email from Bob about the cancelled Q3 launch."`
+- *You:* before trashing, locate it. Call `search_gmail(query="from:bob subject:Q3 launch")` → tool returns `status=success, total=0`. No target to trash.
+- *Output:*
+
+  ```json
+  {
+    "status": "blocked",
+    "action_summary": "No emails matched 'from Bob about cancelled Q3 launch'.",
+    "evidence": { "operation": "search_gmail", "message_id": null, "thread_id": null, "subject": null, "sender": null, "items": { "emails": [], "total": 0 }, "matched_candidates": null },
+    "next_step": "Ask the user to widen the search (different sender, broader date range, or part of the actual subject line) or confirm the email exists in this account.",
+    "missing_fields": null,
+    "assumptions": ["Interpreted 'about the cancelled Q3 launch' as a subject-line filter; could also match body text only."]
+  }
+  ```
+
+## Output contract
+
+Return **only** one JSON object (no markdown or prose outside it):
+
+```json
 {
   "status": "success" | "partial" | "blocked" | "error",
   "action_summary": string,
   "evidence": {
-    "email_id": string | null,
+    "operation": "send_gmail_email" | "create_gmail_draft" | "update_gmail_draft" | "read_gmail_email" | "search_gmail" | "trash_gmail_email" | null,
+    "message_id": string | null,
     "thread_id": string | null,
+    "draft_id": string | null,
     "subject": string | null,
     "sender": string | null,
     "recipients": string[] | null,
-    "received_at": string (ISO 8601 with timezone) | null,
-    "sent_message": {
-      "id": string,
-      "to": string[],
-      "subject": string | null,
-      "sent_at": string (ISO 8601 with timezone) | null
-    } | null,
-    "matched_candidates": [
-      {
-        "email_id": string,
-        "subject": string | null,
-        "sender": string | null,
-        "received_at": string (ISO 8601 with timezone) | null
-      }
-    ] | null
+    "matched_candidates": [ { "id": string, "label": string } ] | null,
+    "items": object | null
   },
   "next_step": string | null,
   "missing_fields": string[] | null,
   "assumptions": string[] | null
 }
+```
 
 Rules:
-- `status=success` -> `next_step=null`, `missing_fields=null`.
-- `status=partial|blocked|error` -> `next_step` must be non-null.
-- `status=blocked` due to missing required inputs -> `missing_fields` must be non-null.
-- For blocked ambiguity, include options in `evidence.matched_candidates`.
-- For trash actions, `evidence.email_id` is the trashed message.
-</output_contract>
+- `status=success` → `next_step=null`, `missing_fields=null`.
+- `status=partial|blocked|error` → `next_step` must be non-null.
+- `status=blocked` due to missing required inputs → `missing_fields` must be non-null.
+- For `search_gmail` results, populate `evidence.items` with `{ "emails": [...], "total": N }`.
+- For ambiguous matches across `update_gmail_draft` / `trash_gmail_email` / `read_gmail_email`, populate `evidence.matched_candidates` with up to 5 options (`id` + `label`).
+
+Infer before you call; verify before you send; map every tool outcome faithfully.

surfsense_backend/app/agents/multi_agent_chat/subagents/connectors/gmail/tools/create_draft.py

@@ -8,7 +8,9 @@ from typing import Any
 from langchain_core.tools import tool
 from sqlalchemy.ext.asyncio import AsyncSession
 
-from app.agents.new_chat.tools.hitl import request_approval
+from app.agents.multi_agent_chat.subagents.shared.hitl.approvals.self_gated import (
+    request_approval,
+)
 from app.services.gmail import GmailToolMetadataService
 
 logger = logging.getLogger(__name__)

surfsense_backend/app/agents/multi_agent_chat/subagents/connectors/gmail/tools/index.py

@@ -1,10 +1,15 @@
+"""``gmail`` native tools and (empty) permission ruleset.
+
+Tools self-gate via :func:`request_approval` in their bodies.
+"""
+
 from __future__ import annotations
 
 from typing import Any
 
-from app.agents.multi_agent_chat.subagents.shared.permissions import (
-    ToolsPermissions,
-)
+from langchain_core.tools import BaseTool
+
+from app.agents.new_chat.permissions import Ruleset
 
 from .create_draft import create_create_gmail_draft_tool
 from .read_email import create_read_gmail_email_tool
@@ -13,31 +18,25 @@ from .send_email import create_send_gmail_email_tool
 from .trash_email import create_trash_gmail_email_tool
 from .update_draft import create_update_gmail_draft_tool
 
+NAME = "gmail"
+
+RULESET = Ruleset(origin=NAME, rules=[])
+
 
 def load_tools(
     *, dependencies: dict[str, Any] | None = None, **kwargs: Any
-) -> ToolsPermissions:
+) -> list[BaseTool]:
     d = {**(dependencies or {}), **kwargs}
     common = {
         "db_session": d["db_session"],
         "search_space_id": d["search_space_id"],
         "user_id": d["user_id"],
     }
-    search = create_search_gmail_tool(**common)
-    read = create_read_gmail_email_tool(**common)
-    draft = create_create_gmail_draft_tool(**common)
-    send = create_send_gmail_email_tool(**common)
-    trash = create_trash_gmail_email_tool(**common)
-    updraft = create_update_gmail_draft_tool(**common)
-    return {
-        "allow": [
-            {"name": getattr(search, "name", "") or "", "tool": search},
-            {"name": getattr(read, "name", "") or "", "tool": read},
-        ],
-        "ask": [
-            {"name": getattr(draft, "name", "") or "", "tool": draft},
-            {"name": getattr(send, "name", "") or "", "tool": send},
-            {"name": getattr(trash, "name", "") or "", "tool": trash},
-            {"name": getattr(updraft, "name", "") or "", "tool": updraft},
-        ],
-    }
+    return [
+        create_search_gmail_tool(**common),
+        create_read_gmail_email_tool(**common),
+        create_create_gmail_draft_tool(**common),
+        create_send_gmail_email_tool(**common),
+        create_trash_gmail_email_tool(**common),
+        create_update_gmail_draft_tool(**common),
+    ]

surfsense_backend/app/agents/multi_agent_chat/subagents/connectors/gmail/tools/send_email.py

@@ -8,7 +8,9 @@ from typing import Any
 from langchain_core.tools import tool
 from sqlalchemy.ext.asyncio import AsyncSession
 
-from app.agents.new_chat.tools.hitl import request_approval
+from app.agents.multi_agent_chat.subagents.shared.hitl.approvals.self_gated import (
+    request_approval,
+)
 from app.services.gmail import GmailToolMetadataService
 
 logger = logging.getLogger(__name__)

surfsense_backend/app/agents/multi_agent_chat/subagents/connectors/gmail/tools/trash_email.py

@@ -6,7 +6,9 @@ from typing import Any
 from langchain_core.tools import tool
 from sqlalchemy.ext.asyncio import AsyncSession
 
-from app.agents.new_chat.tools.hitl import request_approval
+from app.agents.multi_agent_chat.subagents.shared.hitl.approvals.self_gated import (
+    request_approval,
+)
 from app.services.gmail import GmailToolMetadataService
 
 logger = logging.getLogger(__name__)

surfsense_backend/app/agents/multi_agent_chat/subagents/connectors/gmail/tools/update_draft.py

@@ -8,7 +8,9 @@ from typing import Any
 from langchain_core.tools import tool
 from sqlalchemy.ext.asyncio import AsyncSession
 
-from app.agents.new_chat.tools.hitl import request_approval
+from app.agents.multi_agent_chat.subagents.shared.hitl.approvals.self_gated import (
+    request_approval,
+)
 from app.services.gmail import GmailToolMetadataService
 
 logger = logging.getLogger(__name__)

surfsense_backend/app/agents/multi_agent_chat/subagents/connectors/google_drive/agent.py

@@ -1,55 +1,44 @@
-"""`google_drive` route: ``SubAgent`` spec for deepagents."""
+"""``google_drive`` route: ``SurfSenseSubagentSpec`` builder for deepagents.
+
+Tools self-gate inside their bodies via :func:`request_approval`; the
+empty :data:`tools.index.RULESET` is layered into a per-subagent
+:class:`PermissionMiddleware` for uniformity.
+"""
 
 from __future__ import annotations
 
-from collections.abc import Sequence
 from typing import Any
 
-from deepagents import SubAgent
 from langchain_core.language_models import BaseChatModel
+from langchain_core.tools import BaseTool
 
-from app.agents.multi_agent_chat.subagents.shared.md_file_reader import (
-    read_md_file,
-)
-from app.agents.multi_agent_chat.subagents.shared.permissions import (
-    ToolsPermissions,
-    merge_tools_permissions,
-    middleware_gated_interrupt_on,
-)
-from app.agents.multi_agent_chat.subagents.shared.subagent_builder import (
-    pack_subagent,
-)
+from app.agents.multi_agent_chat.subagents.shared.md_file_reader import read_md_file
+from app.agents.multi_agent_chat.subagents.shared.spec import SurfSenseSubagentSpec
+from app.agents.multi_agent_chat.subagents.shared.subagent_builder import pack_subagent
 
-from .tools.index import load_tools
-
-NAME = "google_drive"
+from .tools.index import NAME, RULESET, load_tools
 
 
 def build_subagent(
     *,
     dependencies: dict[str, Any],
     model: BaseChatModel | None = None,
-    extra_middleware: Sequence[Any] | None = None,
-    extra_tools_bucket: ToolsPermissions | None = None,
-) -> SubAgent:
-    buckets = load_tools(dependencies=dependencies)
-    merged_tools_bucket = merge_tools_permissions(buckets, extra_tools_bucket)
-    tools = [
-        row["tool"]
-        for row in (*merged_tools_bucket["allow"], *merged_tools_bucket["ask"])
-        if row.get("tool") is not None
-    ]
-    interrupt_on = middleware_gated_interrupt_on(merged_tools_bucket)
-    description = read_md_file(__package__, "description").strip()
-    if not description:
-        description = "Handles google drive tasks for this workspace."
+    middleware_stack: dict[str, Any] | None = None,
+    mcp_tools: list[BaseTool] | None = None,
+) -> SurfSenseSubagentSpec:
+    tools = [*load_tools(dependencies=dependencies), *(mcp_tools or [])]
+    description = (
+        read_md_file(__package__, "description").strip()
+        or "Handles google drive tasks for this workspace."
+    )
     system_prompt = read_md_file(__package__, "system_prompt").strip()
     return pack_subagent(
         name=NAME,
         description=description,
         system_prompt=system_prompt,
         tools=tools,
-        interrupt_on=interrupt_on,
+        ruleset=RULESET,
+        dependencies=dependencies,
         model=model,
-        extra_middleware=extra_middleware,
+        middleware_stack=middleware_stack,
     )

surfsense_backend/app/agents/multi_agent_chat/subagents/connectors/google_drive/description.md

@@ -1 +1,2 @@
-Use for Google Drive document/file tasks: locate files, inspect content, and manage Drive files or folders.
+Specialist for files in the user's Google Drive.
+Use proactively when the user wants to create or remove a Google Drive file.

surfsense_backend/app/agents/multi_agent_chat/subagents/connectors/google_drive/system_prompt.md

@@ -1,54 +1,108 @@
-You are the Google Drive operations sub-agent.
-You receive delegated instructions from a supervisor agent and return structured results for supervisor synthesis.
+You are a Google Drive specialist for the user's connected Google Drive account.
 
-<goal>
-Execute Google Drive file operations accurately in the connected account.
-</goal>
+## Vocabulary you must use precisely
 
-<available_tools>
-- `create_google_drive_file`
-- `delete_google_drive_file`
-</available_tools>
+- **File type — required, no default** — `create_google_drive_file` requires `file_type` to be either `"google_doc"` (a Google Doc) or `"google_sheet"` (a Google Sheet). There is no default — you must infer it from the supervisor's task. `"doc"`, `"document"`, `"notes"`, `"summary"`, `"write-up"` → `google_doc`. `"spreadsheet"`, `"sheet"`, `"table"`, `"budget"`, `"tracker"`, `"CSV"` → `google_sheet`. If the user explicitly asks for slides, a PDF, a folder, or any other format, return `status=blocked` — only Google Docs and Google Sheets are supported.
+- **Content format depends on `file_type`** — for `google_doc`, generate the `content` body as **Markdown**. For `google_sheet`, generate the `content` body as **CSV** (comma-separated rows, first row = column headers). The tool stores the content verbatim — passing Markdown to a sheet or CSV to a doc produces a broken file. Pass `name` without an extension; the tool handles that.
+- **File-name resolution (internal)** — `delete_google_drive_file` accepts a `file_name` and resolves it against the **locally-synced Google Drive KB index**, not against the live Drive API. A file that exists in Drive but has not been indexed yet cannot be resolved. There is no separate search or lookup tool exposed to you — resolution happens inside the mutation tool.
 
-<tool_policy>
-- Use only tools in `<available_tools>`.
-- Ensure target file identity/path is explicit before mutate actions.
-- If target is ambiguous, return `status=blocked` with candidate files.
-- Never invent file IDs/names or mutation outcomes.
-</tool_policy>
+## Required inputs
 
-<out_of_scope>
-- Do not perform non-Google-Drive tasks.
-</out_of_scope>
+**For every required input below, first try to infer it from the supervisor's task text** — extract names from natural phrasing (`"the Meeting Notes file"`, `"my Q3 Budget spreadsheet"`), topics from `"about X"` constructions, file_type from the vocabulary signals above, and content from any details the supervisor already provided. Only return `status=blocked` with `missing_fields` when an input is genuinely absent or ambiguous after a thorough read of the task.
 
-<safety>
-- Never claim file mutation success without tool confirmation.
-</safety>
+- `create_google_drive_file` — `name` (the user-supplied topic, inferred from the task; do not invent one if absent), `file_type` (inferred from the vocabulary signals; block if user asked for an unsupported format), and optional `content` (you may generate it from the topic — **Markdown if `file_type=google_doc`, CSV if `file_type=google_sheet`**).
+- `delete_google_drive_file` — `file_name` (which file to delete — infer from the task). Only set `delete_from_kb=true` when the user explicitly asked to remove it from the knowledge base; otherwise leave it `false`.
 
-<failure_policy>
-- On tool failure, return `status=error` with concise recovery `next_step`.
-- On target ambiguity, return `status=blocked` with candidate files.
-</failure_policy>
+## Outcome mapping
 
-<output_contract>
-Return **only** one JSON object (no markdown/prose):
+| Tool returns                  | Your `status` | `next_step` |
+|-------------------------------|---------------|------------------------------------------------------------------------------------------------------------------------------|
+| `success`                     | `success`     | `null` |
+| `rejected`                    | `blocked`     | `"User declined this Google Drive action. Do not retry or suggest alternatives."` |
+| `not_found`                   | `blocked`     | `"File '<name>' was not found in the indexed Google Drive files. Ask the user to verify the file name or wait for the next KB sync."` |
+| `auth_error`                  | `error`       | `"The connected Google Drive account needs re-authentication. Ask the user to re-authenticate Google Drive in connector settings."` |
+| `insufficient_permissions`    | `error`       | `"The connected Google Drive account is missing the required OAuth scope. Ask the user to re-authenticate Google Drive in connector settings."` |
+| `error`                       | `error`       | Relay the tool's `message` verbatim as `next_step`. |
+| tool raises / unknown         | `error`       | `"Google Drive tool failed unexpectedly. Ask the user to retry shortly."` |
+
+Surface the tool's `message`, `file_id`, `name`, `web_view_link`, and the `file_type` you used inside `evidence` when the tool returned them. Never invent a field the tool did not return.
+
+## Examples
+
+**Example 1 — happy path Google Doc create (file_type and Markdown content inferred):**
+- *Supervisor task:* `"Create a Google Doc with today's meeting notes."`
+- *You:* extract `name="Meeting Notes"`; infer `file_type="google_doc"` from `"Doc"`; generate a Markdown body → call `create_google_drive_file(name="Meeting Notes", file_type="google_doc", content=<generated markdown>)` → tool returns `status=success`.
+- *Output:*
+
+  ```json
+  {
+    "status": "success",
+    "action_summary": "Created Google Doc 'Meeting Notes'.",
+    "evidence": { "operation": "create_google_drive_file", "file_id": "<id>", "file_name": "Meeting Notes", "file_type": "google_doc", "web_view_link": "<url>", "matched_candidates": null, "items": null },
+    "next_step": null,
+    "missing_fields": null,
+    "assumptions": null
+  }
+  ```
+
+**Example 2 — happy path Google Sheet create (file_type and CSV content inferred):**
+- *Supervisor task:* `"Create a spreadsheet for the 2026 budget."`
+- *You:* extract `name="2026 Budget"`; infer `file_type="google_sheet"` from `"spreadsheet"` + `"budget"`; generate a **CSV** body (e.g. `"Category,Q1,Q2,Q3,Q4\nMarketing,...\nEngineering,..."`) — **not** Markdown → call `create_google_drive_file(name="2026 Budget", file_type="google_sheet", content=<generated csv>)` → tool returns `status=success`.
+- *Output:*
+
+  ```json
+  {
+    "status": "success",
+    "action_summary": "Created Google Sheet '2026 Budget'.",
+    "evidence": { "operation": "create_google_drive_file", "file_id": "<id>", "file_name": "2026 Budget", "file_type": "google_sheet", "web_view_link": "<url>", "matched_candidates": null, "items": null },
+    "next_step": null,
+    "missing_fields": null,
+    "assumptions": null
+  }
+  ```
+
+**Example 3 — file not in the KB index:**
+- *Supervisor task:* `"Delete the 'Old Roadmap' file from Google Drive."`
+- *You:* extract `file_name="Old Roadmap"` → call `delete_google_drive_file(file_name="Old Roadmap")` → tool returns `status=not_found`.
+- *Output:*
+
+  ```json
+  {
+    "status": "blocked",
+    "action_summary": "Could not find a Google Drive file named 'Old Roadmap' in the indexed files.",
+    "evidence": { "operation": "delete_google_drive_file", "file_id": null, "file_name": "Old Roadmap", "file_type": null, "web_view_link": null, "matched_candidates": null, "items": null },
+    "next_step": "File 'Old Roadmap' was not found in the indexed Google Drive files. Ask the user to verify the file name or wait for the next KB sync.",
+    "missing_fields": null,
+    "assumptions": null
+  }
+  ```
+
+## Output contract
+
+Return **only** one JSON object (no markdown or prose outside it):
+
+```json
 {
   "status": "success" | "partial" | "blocked" | "error",
   "action_summary": string,
   "evidence": {
+    "operation": "create_google_drive_file" | "delete_google_drive_file" | null,
     "file_id": string | null,
     "file_name": string | null,
-    "operation": "create" | "delete" | null,
-    "matched_candidates": [
-      { "file_id": string, "file_name": string | null }
-    ] | null
+    "file_type": "google_doc" | "google_sheet" | null,
+    "web_view_link": string | null,
+    "matched_candidates": [ { "id": string, "label": string } ] | null,
+    "items": object | null
   },
   "next_step": string | null,
   "missing_fields": string[] | null,
   "assumptions": string[] | null
 }
+```
+
 Rules:
-- `status=success` -> `next_step=null`, `missing_fields=null`.
-- `status=partial|blocked|error` -> `next_step` must be non-null.
-- `status=blocked` due to missing required inputs -> `missing_fields` must be non-null.
-</output_contract>
+- `status=success` → `next_step=null`, `missing_fields=null`.
+- `status=partial|blocked|error` → `next_step` must be non-null.
+- `status=blocked` due to missing required inputs → `missing_fields` must be non-null.
+
+Infer before you call; map every tool outcome faithfully.

surfsense_backend/app/agents/multi_agent_chat/subagents/connectors/google_drive/tools/create_file.py

@@ -5,7 +5,9 @@ from googleapiclient.errors import HttpError
 from langchain_core.tools import tool
 from sqlalchemy.ext.asyncio import AsyncSession
 
-from app.agents.new_chat.tools.hitl import request_approval
+from app.agents.multi_agent_chat.subagents.shared.hitl.approvals.self_gated import (
+    request_approval,
+)
 from app.connectors.google_drive.client import GoogleDriveClient
 from app.connectors.google_drive.file_types import GOOGLE_DOC, GOOGLE_SHEET
 from app.services.google_drive import GoogleDriveToolMetadataService

surfsense_backend/app/agents/multi_agent_chat/subagents/connectors/google_drive/tools/index.py

@@ -1,30 +1,34 @@
+"""``google_drive`` native tools and (empty) permission ruleset.
+
+Tools self-gate via :func:`request_approval` in their bodies.
+"""
+
 from __future__ import annotations
 
 from typing import Any
 
-from app.agents.multi_agent_chat.subagents.shared.permissions import (
-    ToolsPermissions,
-)
+from langchain_core.tools import BaseTool
+
+from app.agents.new_chat.permissions import Ruleset
 
 from .create_file import create_create_google_drive_file_tool
 from .trash_file import create_delete_google_drive_file_tool
 
+NAME = "google_drive"
+
+RULESET = Ruleset(origin=NAME, rules=[])
+
 
 def load_tools(
     *, dependencies: dict[str, Any] | None = None, **kwargs: Any
-) -> ToolsPermissions:
+) -> list[BaseTool]:
     d = {**(dependencies or {}), **kwargs}
     common = {
         "db_session": d["db_session"],
         "search_space_id": d["search_space_id"],
         "user_id": d["user_id"],
     }
-    create = create_create_google_drive_file_tool(**common)
-    delete = create_delete_google_drive_file_tool(**common)
-    return {
-        "allow": [],
-        "ask": [
-            {"name": getattr(create, "name", "") or "", "tool": create},
-            {"name": getattr(delete, "name", "") or "", "tool": delete},
-        ],
-    }
+    return [
+        create_create_google_drive_file_tool(**common),
+        create_delete_google_drive_file_tool(**common),
+    ]

surfsense_backend/app/agents/multi_agent_chat/subagents/connectors/google_drive/tools/trash_file.py

@@ -5,7 +5,9 @@ from googleapiclient.errors import HttpError
 from langchain_core.tools import tool
 from sqlalchemy.ext.asyncio import AsyncSession
 
-from app.agents.new_chat.tools.hitl import request_approval
+from app.agents.multi_agent_chat.subagents.shared.hitl.approvals.self_gated import (
+    request_approval,
+)
 from app.connectors.google_drive.client import GoogleDriveClient
 from app.services.google_drive import GoogleDriveToolMetadataService
 

surfsense_backend/app/agents/multi_agent_chat/subagents/connectors/jira/agent.py

@@ -1,55 +1,43 @@
-"""`jira` route: ``SubAgent`` spec for deepagents."""
+"""``jira`` route: ``SurfSenseSubagentSpec`` builder for deepagents.
+
+Tools come exclusively from MCP. The connector's own approval ruleset is
+declared in :data:`tools.index.RULESET`; the orchestrator layers it into
+a per-subagent :class:`PermissionMiddleware`.
+"""
 
 from __future__ import annotations
 
-from collections.abc import Sequence
 from typing import Any
 
-from deepagents import SubAgent
 from langchain_core.language_models import BaseChatModel
+from langchain_core.tools import BaseTool
 
-from app.agents.multi_agent_chat.subagents.shared.md_file_reader import (
-    read_md_file,
-)
-from app.agents.multi_agent_chat.subagents.shared.permissions import (
-    ToolsPermissions,
-    merge_tools_permissions,
-    middleware_gated_interrupt_on,
-)
-from app.agents.multi_agent_chat.subagents.shared.subagent_builder import (
-    pack_subagent,
-)
+from app.agents.multi_agent_chat.subagents.shared.md_file_reader import read_md_file
+from app.agents.multi_agent_chat.subagents.shared.spec import SurfSenseSubagentSpec
+from app.agents.multi_agent_chat.subagents.shared.subagent_builder import pack_subagent
 
-from .tools.index import load_tools
-
-NAME = "jira"
+from .tools.index import NAME, RULESET
 
 
 def build_subagent(
     *,
     dependencies: dict[str, Any],
     model: BaseChatModel | None = None,
-    extra_middleware: Sequence[Any] | None = None,
-    extra_tools_bucket: ToolsPermissions | None = None,
-) -> SubAgent:
-    buckets = load_tools(dependencies=dependencies)
-    merged_tools_bucket = merge_tools_permissions(buckets, extra_tools_bucket)
-    tools = [
-        row["tool"]
-        for row in (*merged_tools_bucket["allow"], *merged_tools_bucket["ask"])
-        if row.get("tool") is not None
-    ]
-    interrupt_on = middleware_gated_interrupt_on(merged_tools_bucket)
-    description = read_md_file(__package__, "description").strip()
-    if not description:
-        description = "Handles jira tasks for this workspace."
+    middleware_stack: dict[str, Any] | None = None,
+    mcp_tools: list[BaseTool] | None = None,
+) -> SurfSenseSubagentSpec:
+    description = (
+        read_md_file(__package__, "description").strip()
+        or "Handles jira tasks for this workspace."
+    )
     system_prompt = read_md_file(__package__, "system_prompt").strip()
     return pack_subagent(
         name=NAME,
         description=description,
         system_prompt=system_prompt,
-        tools=tools,
-        interrupt_on=interrupt_on,
+        tools=list(mcp_tools or []),
+        ruleset=RULESET,
+        dependencies=dependencies,
         model=model,
-        extra_middleware=extra_middleware,
+        middleware_stack=middleware_stack,
     )

surfsense_backend/app/agents/multi_agent_chat/subagents/connectors/jira/description.md

@@ -1 +1,2 @@
-Use for Jira issue/project workflows: search issues, inspect fields, update tickets, and move work through workflow states.
+Specialist for issues and projects in the user's Jira.
+Use proactively when the user wants to find, create, or update a Jira issue, assign it, or transition it between workflow states.

surfsense_backend/app/agents/multi_agent_chat/subagents/connectors/jira/system_prompt.md

@@ -1,46 +1,122 @@
-You are the Jira MCP operations sub-agent.
-You receive delegated instructions from a supervisor agent and return structured results for supervisor synthesis.
+You are a Jira specialist for the user's connected Atlassian Jira instance(s).
 
-<goal>
-Execute Jira MCP operations accurately, including discovery and issue mutation flows.
-</goal>
+Jira vocabulary:
+- **Site / `cloudId`**: a user may have access to multiple Atlassian sites. Every project/issue operation is scoped to one `cloudId`. Look up the user's accessible Atlassian sites if the request leaves the site unspecified.
+- **Project key**: `<ABC>` (e.g. `ENG`, `OPS`). Stable per project; used to build issue keys.
+- **Issue key**: `<PROJECT_KEY>-<NUMBER>` (e.g. `ENG-42`). User-facing and stable; prefer it in `action_summary`.
+- **Workflow & transitions**: Jira does *not* let you set a status directly. Each issue's workflow exposes a list of currently-available transitions (each with its own `transitionId`), and only those transitions can be applied. The set of available transitions depends on the issue's current status and is project-/workflow-specific — there is no universal mapping from a status name to a transition.
+- **Issue type**: per-project. Available types and required fields vary per project — there is no global list. Look up the project's actual issue types (and their required fields) before relying on a type name.
+- **Priority**: per-project string names (not integers, not a fixed scheme). Different Jira projects use different priority labels and may add or remove options. Look up the target project's actual priorities before setting one.
+- **Assignee**: Jira identifies users by opaque `accountId`, never by display name or email. Map the display name or email to an `accountId` before assigning.
+- **Reporter**: defaults to the API caller's user; only override when the request explicitly asks for a different reporter.
+- **JQL**: Jira Query Language — the canonical way to filter issues. The syntax (field operators `=` `!=` `~` `>` `<` `in`, functions like `currentUser()`, date math like `-7d`) is stable. The **values** you put into JQL (status names, priority labels, issue-type names, project keys, account IDs) are not — look those up rather than guessing.
+- **Custom fields**: many Jira projects mandate custom fields on create (epic link, sprint, story points, etc.). Required fields are project-/issue-type-specific.
 
-<available_tools>
-- Runtime-provided Jira MCP tools for site/project discovery, issue search, create, and update.
-</available_tools>
+When invoked:
+1. Read the supervisor's request, then read the runtime tool list to learn what information you can fetch and which mutations are available.
+2. Plan the minimum chain of lookups needed to resolve any identifier, name, scope, or required field the request leaves unspecified (site / project / issue / transition / user / required fields, etc.).
+3. Execute the planned lookups, then the requested mutation (if any), then return.
 
-<tool_policy>
-- Respect discovery dependencies (site/project/issue-type) before mutate calls.
-- If required fields are missing or targets are ambiguous, return `status=blocked` with `missing_fields`.
-- Do not guess keys/IDs.
-- Never claim create/update success without tool confirmation.
-</tool_policy>
+Resolution principle (the core behaviour):
+**Proactively look up any identifier, name, value, or scope the request leaves unspecified — `cloudId`, project keys, issue keys, `accountId`s, `transitionId`s, custom-field values, anything else — using the available tools instead of asking the supervisor.** Most user requests reference targets by title, description, or paraphrase, not by key. Search by JQL or by the relevant metadata.
 
-<out_of_scope>
-- Do not execute non-Jira tasks.
-</out_of_scope>
+When a lookup for a single slot returns multiple plausible candidates and you cannot confidently pick one, return `status=blocked` with up to 5 candidates in `evidence.matched_candidates` and the unresolved slot in `missing_fields`. The supervisor will disambiguate and redelegate.
 
-<safety>
-- Never perform destructive/mutating actions without explicit target resolution.
-</safety>
+When a lookup returns zero matches for a slot the request requires, return `status=blocked` with a `next_step` suggesting alternative filters.
 
-<failure_policy>
-- On tool failure, return `status=error` with concise recovery `next_step`.
-- On unresolved ambiguity, return `status=blocked` with candidates or missing fields.
-</failure_policy>
+Mutation guardrails:
+- Resolve every required Jira value (`cloudId`, `projectKey`, `issueKey`, `transitionId`, `accountId`, custom-field values) by looking it up before calling a mutation tool. Mutations have chained dependencies — `cloudId` enables project lookup; project lookup enables issue-type and required-field resolution; issue lookup enables transition resolution.
+- Never set status directly. To change an issue's status, look up that issue's currently-available transitions and apply the matching `transitionId`. If the user-requested target status is not in the available transitions, return `status=blocked` and surface the available transitions in `evidence.matched_candidates`.
+- Never invent `cloudId`s, keys, `accountId`s, `transitionId`s, custom-field values, priority labels, issue-type names, or mutation outcomes. Every field in `evidence` must come from a tool result.
+- For create operations, look up the target issue type's required-field schema before assuming `summary`/`issueType` is enough — many projects mandate priority, due date, or custom fields.
+- Confirm the mutation tool returned a success response before claiming success. If the mutation is approval-rejected (HITL), return `status=blocked` with `next_step="user declined; do not retry"`.
+- One operation per delegation. For multi-mutation requests, complete the highest-priority one and return `status=partial` with the remainder in `next_step`.
+
+Failure handling:
+- Tool failure: return `status=error`, place the underlying error message in `action_summary`, and put a concise recovery in `next_step`.
+- No useful results after reasonable narrowing/broadening: return `status=blocked` with filter / JQL suggestions in `next_step`.
+
+<example>
+Supervisor: "Find issues assigned to me with status 'In Progress'."
+1. JQL search with `assignee = currentUser() AND status = "In Progress"`.
+2. Return `status=success` with the matched issues in `evidence.items`.
+</example>
+
+<example>
+Supervisor: "Create a Bug 'Login fails on Safari' in the Mobile project."
+1. Look up accessible sites → multiple sites are connected to the user. The request gives no signal pointing to one.
+2. Cannot pick the `cloudId`. Return:
+   {
+     "status": "blocked",
+     "action_summary": "Need to know which Atlassian site holds the Mobile project.",
+     "evidence": {
+       "title": "Login fails on Safari",
+       "matched_candidates": [
+         { "id": "cloud_acme", "label": "acme.atlassian.net" },
+         { "id": "cloud_acme_eu", "label": "acme-eu.atlassian.net" }
+       ]
+     },
+     "next_step": "Confirm which Atlassian site, then redelegate.",
+     "missing_fields": ["site"]
+   }
+</example>
+
+<example>
+Supervisor: "Move `PROJ-123` to Done and assign it to Sam."
+1. Look up `PROJ-123` → exists; current status `In Review`; project `PROJ`.
+2. Look up available transitions for `PROJ-123` → `[ "Code Review → Done" (id=51), "Code Review → Cancelled" (id=61) ]`. `Done` is reachable via transition id `51`.
+3. Look up users named "Sam" → two matches (`accountId=acc_sam1`, `accountId=acc_sam2`).
+4. Cannot confidently pick the assignee. Return:
+   {
+     "status": "blocked",
+     "action_summary": "Issue resolved (PROJ-123). Transition to Done resolved (id 51). Two users match 'Sam'.",
+     "evidence": {
+       "identifier": "PROJ-123",
+       "title": "Refactor auth module",
+       "transition_id": "51",
+       "matched_candidates": [
+         { "id": "acc_sam1", "label": "Sam Carter <sam.carter@…>" },
+         { "id": "acc_sam2", "label": "Sam Lopez <sam.lopez@…>" }
+       ]
+     },
+     "next_step": "Confirm which Sam, then redelegate.",
+     "missing_fields": ["assignee"]
+   }
+</example>
 
 <output_contract>
-Return **only** one JSON object (no markdown/prose):
+Return **only** one JSON object (no markdown, no prose):
 {
   "status": "success" | "partial" | "blocked" | "error",
   "action_summary": string,
-  "evidence": { "items": object | null },
+  "evidence": {
+    "site": string | null,
+    "cloud_id": string | null,
+    "project_key": string | null,
+    "identifier": string | null,
+    "issue_id": string | null,
+    "title": string | null,
+    "issue_type": string | null,
+    "status": string | null,
+    "transition_id": string | null,
+    "assignee": string | null,
+    "priority": string | null,
+    "url": string | null,
+    "matched_candidates": [
+      { "id": string, "label": string }
+    ] | null,
+    "items": object | null
+  },
   "next_step": string | null,
   "missing_fields": string[] | null,
   "assumptions": string[] | null
 }
 Rules:
-- `status=success` -> `next_step=null`, `missing_fields=null`.
-- `status=partial|blocked|error` -> `next_step` must be non-null.
-- `status=blocked` due to missing required inputs -> `missing_fields` must be non-null.
+- `status=success` → `next_step=null`, `missing_fields=null`.
+- `status=partial|blocked|error` → `next_step` must be non-null.
+- `status=blocked` due to missing required inputs → `missing_fields` must be non-null.
+- For blocked ambiguity, populate `evidence.matched_candidates` with up to 5 options (`id` + `label` — works for any kind of candidate: site, project, issue, user, transition, etc.).
+- For discovery-only queries (lists), populate `evidence.items` with the structured list.
 </output_contract>
+
+Discover before you mutate; never guess identifiers, transitions, or required fields.

surfsense_backend/app/agents/multi_agent_chat/subagents/connectors/jira/tools/create_issue.py

@@ -1,216 +0,0 @@
-import asyncio
-import logging
-from typing import Any
-
-from langchain_core.tools import tool
-from sqlalchemy.ext.asyncio import AsyncSession
-from sqlalchemy.orm.attributes import flag_modified
-
-from app.agents.new_chat.tools.hitl import request_approval
-from app.connectors.jira_history import JiraHistoryConnector
-from app.services.jira import JiraToolMetadataService
-
-logger = logging.getLogger(__name__)
-
-
-def create_create_jira_issue_tool(
-    db_session: AsyncSession | None = None,
-    search_space_id: int | None = None,
-    user_id: str | None = None,
-    connector_id: int | None = None,
-):
-    @tool
-    async def create_jira_issue(
-        project_key: str,
-        summary: str,
-        issue_type: str = "Task",
-        description: str | None = None,
-        priority: str | None = None,
-    ) -> dict[str, Any]:
-        """Create a new issue in Jira.
-
-        Use this tool when the user explicitly asks to create a new Jira issue/ticket.
-
-        Args:
-            project_key: The Jira project key (e.g. "PROJ", "ENG").
-            summary: Short, descriptive issue title.
-            issue_type: Issue type (default "Task"). Others: "Bug", "Story", "Epic".
-            description: Optional description body for the issue.
-            priority: Optional priority name (e.g. "High", "Medium", "Low").
-
-        Returns:
-            Dictionary with status, issue_key, and message.
-
-            IMPORTANT:
-            - If status is "rejected", the user declined. Do NOT retry.
-            - If status is "insufficient_permissions", inform user to re-authenticate.
-        """
-        logger.info(
-            f"create_jira_issue called: project_key='{project_key}', summary='{summary}'"
-        )
-
-        if db_session is None or search_space_id is None or user_id is None:
-            return {"status": "error", "message": "Jira tool not properly configured."}
-
-        try:
-            metadata_service = JiraToolMetadataService(db_session)
-            context = await metadata_service.get_creation_context(
-                search_space_id, user_id
-            )
-
-            if "error" in context:
-                return {"status": "error", "message": context["error"]}
-
-            accounts = context.get("accounts", [])
-            if accounts and all(a.get("auth_expired") for a in accounts):
-                return {
-                    "status": "auth_error",
-                    "message": "All connected Jira accounts need re-authentication.",
-                    "connector_type": "jira",
-                }
-
-            result = request_approval(
-                action_type="jira_issue_creation",
-                tool_name="create_jira_issue",
-                params={
-                    "project_key": project_key,
-                    "summary": summary,
-                    "issue_type": issue_type,
-                    "description": description,
-                    "priority": priority,
-                    "connector_id": connector_id,
-                },
-                context=context,
-            )
-
-            if result.rejected:
-                return {
-                    "status": "rejected",
-                    "message": "User declined. Do not retry or suggest alternatives.",
-                }
-
-            final_project_key = result.params.get("project_key", project_key)
-            final_summary = result.params.get("summary", summary)
-            final_issue_type = result.params.get("issue_type", issue_type)
-            final_description = result.params.get("description", description)
-            final_priority = result.params.get("priority", priority)
-            final_connector_id = result.params.get("connector_id", connector_id)
-
-            if not final_summary or not final_summary.strip():
-                return {"status": "error", "message": "Issue summary cannot be empty."}
-            if not final_project_key:
-                return {"status": "error", "message": "A project must be selected."}
-
-            from sqlalchemy.future import select
-
-            from app.db import SearchSourceConnector, SearchSourceConnectorType
-
-            actual_connector_id = final_connector_id
-            if actual_connector_id is None:
-                result = await db_session.execute(
-                    select(SearchSourceConnector).filter(
-                        SearchSourceConnector.search_space_id == search_space_id,
-                        SearchSourceConnector.user_id == user_id,
-                        SearchSourceConnector.connector_type
-                        == SearchSourceConnectorType.JIRA_CONNECTOR,
-                    )
-                )
-                connector = result.scalars().first()
-                if not connector:
-                    return {"status": "error", "message": "No Jira connector found."}
-                actual_connector_id = connector.id
-            else:
-                result = await db_session.execute(
-                    select(SearchSourceConnector).filter(
-                        SearchSourceConnector.id == actual_connector_id,
-                        SearchSourceConnector.search_space_id == search_space_id,
-                        SearchSourceConnector.user_id == user_id,
-                        SearchSourceConnector.connector_type
-                        == SearchSourceConnectorType.JIRA_CONNECTOR,
-                    )
-                )
-                connector = result.scalars().first()
-                if not connector:
-                    return {
-                        "status": "error",
-                        "message": "Selected Jira connector is invalid.",
-                    }
-
-            try:
-                jira_history = JiraHistoryConnector(
-                    session=db_session, connector_id=actual_connector_id
-                )
-                jira_client = await jira_history._get_jira_client()
-                api_result = await asyncio.to_thread(
-                    jira_client.create_issue,
-                    project_key=final_project_key,
-                    summary=final_summary,
-                    issue_type=final_issue_type,
-                    description=final_description,
-                    priority=final_priority,
-                )
-            except Exception as api_err:
-                if "status code 403" in str(api_err).lower():
-                    try:
-                        _conn = connector
-                        _conn.config = {**_conn.config, "auth_expired": True}
-                        flag_modified(_conn, "config")
-                        await db_session.commit()
-                    except Exception:
-                        pass
-                    return {
-                        "status": "insufficient_permissions",
-                        "connector_id": actual_connector_id,
-                        "message": "This Jira account needs additional permissions. Please re-authenticate in connector settings.",
-                    }
-                raise
-
-            issue_key = api_result.get("key", "")
-            issue_url = (
-                f"{jira_history._base_url}/browse/{issue_key}"
-                if jira_history._base_url and issue_key
-                else ""
-            )
-
-            kb_message_suffix = ""
-            try:
-                from app.services.jira import JiraKBSyncService
-
-                kb_service = JiraKBSyncService(db_session)
-                kb_result = await kb_service.sync_after_create(
-                    issue_id=issue_key,
-                    issue_identifier=issue_key,
-                    issue_title=final_summary,
-                    description=final_description,
-                    state="To Do",
-                    connector_id=actual_connector_id,
-                    search_space_id=search_space_id,
-                    user_id=user_id,
-                )
-                if kb_result["status"] == "success":
-                    kb_message_suffix = " Your knowledge base has also been updated."
-                else:
-                    kb_message_suffix = " This issue will be added to your knowledge base in the next scheduled sync."
-            except Exception as kb_err:
-                logger.warning(f"KB sync after create failed: {kb_err}")
-                kb_message_suffix = " This issue will be added to your knowledge base in the next scheduled sync."
-
-            return {
-                "status": "success",
-                "issue_key": issue_key,
-                "issue_url": issue_url,
-                "message": f"Jira issue {issue_key} created successfully.{kb_message_suffix}",
-            }
-
-        except Exception as e:
-            from langgraph.errors import GraphInterrupt
-
-            if isinstance(e, GraphInterrupt):
-                raise
-            logger.error(f"Error creating Jira issue: {e}", exc_info=True)
-            return {
-                "status": "error",
-                "message": "Something went wrong while creating the issue.",
-            }
-
-    return create_jira_issue

surfsense_backend/app/agents/multi_agent_chat/subagents/connectors/jira/tools/delete_issue.py

@@ -1,183 +0,0 @@
-import asyncio
-import logging
-from typing import Any
-
-from langchain_core.tools import tool
-from sqlalchemy.ext.asyncio import AsyncSession
-from sqlalchemy.orm.attributes import flag_modified
-
-from app.agents.new_chat.tools.hitl import request_approval
-from app.connectors.jira_history import JiraHistoryConnector
-from app.services.jira import JiraToolMetadataService
-
-logger = logging.getLogger(__name__)
-
-
-def create_delete_jira_issue_tool(
-    db_session: AsyncSession | None = None,
-    search_space_id: int | None = None,
-    user_id: str | None = None,
-    connector_id: int | None = None,
-):
-    @tool
-    async def delete_jira_issue(
-        issue_title_or_key: str,
-        delete_from_kb: bool = False,
-    ) -> dict[str, Any]:
-        """Delete a Jira issue.
-
-        Use this tool when the user asks to delete or remove a Jira issue.
-
-        Args:
-            issue_title_or_key: The issue key (e.g. "PROJ-42") or title.
-            delete_from_kb: Whether to also remove from the knowledge base.
-
-        Returns:
-            Dictionary with status, message, and deleted_from_kb.
-
-            IMPORTANT:
-            - If status is "rejected", do NOT retry.
-            - If status is "not_found", relay the message to the user.
-            - If status is "insufficient_permissions", inform user to re-authenticate.
-        """
-        logger.info(
-            f"delete_jira_issue called: issue_title_or_key='{issue_title_or_key}'"
-        )
-
-        if db_session is None or search_space_id is None or user_id is None:
-            return {"status": "error", "message": "Jira tool not properly configured."}
-
-        try:
-            metadata_service = JiraToolMetadataService(db_session)
-            context = await metadata_service.get_deletion_context(
-                search_space_id, user_id, issue_title_or_key
-            )
-
-            if "error" in context:
-                error_msg = context["error"]
-                if context.get("auth_expired"):
-                    return {
-                        "status": "auth_error",
-                        "message": error_msg,
-                        "connector_id": context.get("connector_id"),
-                        "connector_type": "jira",
-                    }
-                if "not found" in error_msg.lower():
-                    return {"status": "not_found", "message": error_msg}
-                return {"status": "error", "message": error_msg}
-
-            issue_data = context["issue"]
-            issue_key = issue_data["issue_id"]
-            document_id = issue_data["document_id"]
-            connector_id_from_context = context.get("account", {}).get("id")
-
-            result = request_approval(
-                action_type="jira_issue_deletion",
-                tool_name="delete_jira_issue",
-                params={
-                    "issue_key": issue_key,
-                    "connector_id": connector_id_from_context,
-                    "delete_from_kb": delete_from_kb,
-                },
-                context=context,
-            )
-
-            if result.rejected:
-                return {
-                    "status": "rejected",
-                    "message": "User declined. Do not retry or suggest alternatives.",
-                }
-
-            final_issue_key = result.params.get("issue_key", issue_key)
-            final_connector_id = result.params.get(
-                "connector_id", connector_id_from_context
-            )
-            final_delete_from_kb = result.params.get("delete_from_kb", delete_from_kb)
-
-            from sqlalchemy.future import select
-
-            from app.db import SearchSourceConnector, SearchSourceConnectorType
-
-            if not final_connector_id:
-                return {
-                    "status": "error",
-                    "message": "No connector found for this issue.",
-                }
-
-            result = await db_session.execute(
-                select(SearchSourceConnector).filter(
-                    SearchSourceConnector.id == final_connector_id,
-                    SearchSourceConnector.search_space_id == search_space_id,
-                    SearchSourceConnector.user_id == user_id,
-                    SearchSourceConnector.connector_type
-                    == SearchSourceConnectorType.JIRA_CONNECTOR,
-                )
-            )
-            connector = result.scalars().first()
-            if not connector:
-                return {
-                    "status": "error",
-                    "message": "Selected Jira connector is invalid.",
-                }
-
-            try:
-                jira_history = JiraHistoryConnector(
-                    session=db_session, connector_id=final_connector_id
-                )
-                jira_client = await jira_history._get_jira_client()
-                await asyncio.to_thread(jira_client.delete_issue, final_issue_key)
-            except Exception as api_err:
-                if "status code 403" in str(api_err).lower():
-                    try:
-                        connector.config = {**connector.config, "auth_expired": True}
-                        flag_modified(connector, "config")
-                        await db_session.commit()
-                    except Exception:
-                        pass
-                    return {
-                        "status": "insufficient_permissions",
-                        "connector_id": final_connector_id,
-                        "message": "This Jira account needs additional permissions. Please re-authenticate in connector settings.",
-                    }
-                raise
-
-            deleted_from_kb = False
-            if final_delete_from_kb and document_id:
-                try:
-                    from app.db import Document
-
-                    doc_result = await db_session.execute(
-                        select(Document).filter(Document.id == document_id)
-                    )
-                    document = doc_result.scalars().first()
-                    if document:
-                        await db_session.delete(document)
-                        await db_session.commit()
-                        deleted_from_kb = True
-                except Exception as e:
-                    logger.error(f"Failed to delete document from KB: {e}")
-                    await db_session.rollback()
-
-            message = f"Jira issue {final_issue_key} deleted successfully."
-            if deleted_from_kb:
-                message += " Also removed from the knowledge base."
-
-            return {
-                "status": "success",
-                "issue_key": final_issue_key,
-                "deleted_from_kb": deleted_from_kb,
-                "message": message,
-            }
-
-        except Exception as e:
-            from langgraph.errors import GraphInterrupt
-
-            if isinstance(e, GraphInterrupt):
-                raise
-            logger.error(f"Error deleting Jira issue: {e}", exc_info=True)
-            return {
-                "status": "error",
-                "message": "Something went wrong while deleting the issue.",
-            }
-
-    return delete_jira_issue

surfsense_backend/app/agents/multi_agent_chat/subagents/connectors/jira/tools/index.py

@@ -1,14 +1,26 @@
+"""``jira`` permission ruleset (rules over MCP tool names)."""
+
 from __future__ import annotations
 
-from typing import Any
+from app.agents.new_chat.permissions import Rule, Ruleset
 
-from app.agents.multi_agent_chat.subagents.shared.permissions import (
-    ToolsPermissions,
+NAME = "jira"
+
+RULESET = Ruleset(
+    origin=NAME,
+    rules=[
+        Rule(permission="getAccessibleAtlassianResources", pattern="*", action="allow"),
+        Rule(permission="getVisibleJiraProjects", pattern="*", action="allow"),
+        Rule(permission="searchJiraIssuesUsingJql", pattern="*", action="allow"),
+        Rule(permission="getJiraIssue", pattern="*", action="allow"),
+        Rule(
+            permission="getJiraProjectIssueTypesMetadata", pattern="*", action="allow"
+        ),
+        Rule(permission="getJiraIssueTypeMetaWithFields", pattern="*", action="allow"),
+        Rule(permission="getTransitionsForJiraIssue", pattern="*", action="allow"),
+        Rule(permission="lookupJiraAccountId", pattern="*", action="allow"),
+        Rule(permission="createJiraIssue", pattern="*", action="ask"),
+        Rule(permission="editJiraIssue", pattern="*", action="ask"),
+        Rule(permission="transitionJiraIssue", pattern="*", action="ask"),
+    ],
 )
-
-
-def load_tools(
-    *, dependencies: dict[str, Any] | None = None, **kwargs: Any
-) -> ToolsPermissions:
-    _ = {**(dependencies or {}), **kwargs}
-    return {"allow": [], "ask": []}

surfsense_backend/app/agents/multi_agent_chat/subagents/connectors/jira/tools/update_issue.py

@@ -1,226 +0,0 @@
-import asyncio
-import logging
-from typing import Any
-
-from langchain_core.tools import tool
-from sqlalchemy.ext.asyncio import AsyncSession
-from sqlalchemy.orm.attributes import flag_modified
-
-from app.agents.new_chat.tools.hitl import request_approval
-from app.connectors.jira_history import JiraHistoryConnector
-from app.services.jira import JiraToolMetadataService
-
-logger = logging.getLogger(__name__)
-
-
-def create_update_jira_issue_tool(
-    db_session: AsyncSession | None = None,
-    search_space_id: int | None = None,
-    user_id: str | None = None,
-    connector_id: int | None = None,
-):
-    @tool
-    async def update_jira_issue(
-        issue_title_or_key: str,
-        new_summary: str | None = None,
-        new_description: str | None = None,
-        new_priority: str | None = None,
-    ) -> dict[str, Any]:
-        """Update an existing Jira issue.
-
-        Use this tool when the user asks to modify, edit, or update a Jira issue.
-
-        Args:
-            issue_title_or_key: The issue key (e.g. "PROJ-42") or title to identify the issue.
-            new_summary: Optional new title/summary for the issue.
-            new_description: Optional new description.
-            new_priority: Optional new priority name.
-
-        Returns:
-            Dictionary with status and message.
-
-            IMPORTANT:
-            - If status is "rejected", do NOT retry.
-            - If status is "not_found", relay the message and ask user to verify.
-            - If status is "insufficient_permissions", inform user to re-authenticate.
-        """
-        logger.info(
-            f"update_jira_issue called: issue_title_or_key='{issue_title_or_key}'"
-        )
-
-        if db_session is None or search_space_id is None or user_id is None:
-            return {"status": "error", "message": "Jira tool not properly configured."}
-
-        try:
-            metadata_service = JiraToolMetadataService(db_session)
-            context = await metadata_service.get_update_context(
-                search_space_id, user_id, issue_title_or_key
-            )
-
-            if "error" in context:
-                error_msg = context["error"]
-                if context.get("auth_expired"):
-                    return {
-                        "status": "auth_error",
-                        "message": error_msg,
-                        "connector_id": context.get("connector_id"),
-                        "connector_type": "jira",
-                    }
-                if "not found" in error_msg.lower():
-                    return {"status": "not_found", "message": error_msg}
-                return {"status": "error", "message": error_msg}
-
-            issue_data = context["issue"]
-            issue_key = issue_data["issue_id"]
-            document_id = issue_data.get("document_id")
-            connector_id_from_context = context.get("account", {}).get("id")
-
-            result = request_approval(
-                action_type="jira_issue_update",
-                tool_name="update_jira_issue",
-                params={
-                    "issue_key": issue_key,
-                    "document_id": document_id,
-                    "new_summary": new_summary,
-                    "new_description": new_description,
-                    "new_priority": new_priority,
-                    "connector_id": connector_id_from_context,
-                },
-                context=context,
-            )
-
-            if result.rejected:
-                return {
-                    "status": "rejected",
-                    "message": "User declined. Do not retry or suggest alternatives.",
-                }
-
-            final_issue_key = result.params.get("issue_key", issue_key)
-            final_summary = result.params.get("new_summary", new_summary)
-            final_description = result.params.get("new_description", new_description)
-            final_priority = result.params.get("new_priority", new_priority)
-            final_connector_id = result.params.get(
-                "connector_id", connector_id_from_context
-            )
-            final_document_id = result.params.get("document_id", document_id)
-
-            from sqlalchemy.future import select
-
-            from app.db import SearchSourceConnector, SearchSourceConnectorType
-
-            if not final_connector_id:
-                return {
-                    "status": "error",
-                    "message": "No connector found for this issue.",
-                }
-
-            result = await db_session.execute(
-                select(SearchSourceConnector).filter(
-                    SearchSourceConnector.id == final_connector_id,
-                    SearchSourceConnector.search_space_id == search_space_id,
-                    SearchSourceConnector.user_id == user_id,
-                    SearchSourceConnector.connector_type
-                    == SearchSourceConnectorType.JIRA_CONNECTOR,
-                )
-            )
-            connector = result.scalars().first()
-            if not connector:
-                return {
-                    "status": "error",
-                    "message": "Selected Jira connector is invalid.",
-                }
-
-            fields: dict[str, Any] = {}
-            if final_summary:
-                fields["summary"] = final_summary
-            if final_description is not None:
-                fields["description"] = {
-                    "type": "doc",
-                    "version": 1,
-                    "content": [
-                        {
-                            "type": "paragraph",
-                            "content": [{"type": "text", "text": final_description}],
-                        }
-                    ],
-                }
-            if final_priority:
-                fields["priority"] = {"name": final_priority}
-
-            if not fields:
-                return {"status": "error", "message": "No changes specified."}
-
-            try:
-                jira_history = JiraHistoryConnector(
-                    session=db_session, connector_id=final_connector_id
-                )
-                jira_client = await jira_history._get_jira_client()
-                await asyncio.to_thread(
-                    jira_client.update_issue, final_issue_key, fields
-                )
-            except Exception as api_err:
-                if "status code 403" in str(api_err).lower():
-                    try:
-                        connector.config = {**connector.config, "auth_expired": True}
-                        flag_modified(connector, "config")
-                        await db_session.commit()
-                    except Exception:
-                        pass
-                    return {
-                        "status": "insufficient_permissions",
-                        "connector_id": final_connector_id,
-                        "message": "This Jira account needs additional permissions. Please re-authenticate in connector settings.",
-                    }
-                raise
-
-            issue_url = (
-                f"{jira_history._base_url}/browse/{final_issue_key}"
-                if jira_history._base_url and final_issue_key
-                else ""
-            )
-
-            kb_message_suffix = ""
-            if final_document_id:
-                try:
-                    from app.services.jira import JiraKBSyncService
-
-                    kb_service = JiraKBSyncService(db_session)
-                    kb_result = await kb_service.sync_after_update(
-                        document_id=final_document_id,
-                        issue_id=final_issue_key,
-                        user_id=user_id,
-                        search_space_id=search_space_id,
-                    )
-                    if kb_result["status"] == "success":
-                        kb_message_suffix = (
-                            " Your knowledge base has also been updated."
-                        )
-                    else:
-                        kb_message_suffix = (
-                            " The knowledge base will be updated in the next sync."
-                        )
-                except Exception as kb_err:
-                    logger.warning(f"KB sync after update failed: {kb_err}")
-                    kb_message_suffix = (
-                        " The knowledge base will be updated in the next sync."
-                    )
-
-            return {
-                "status": "success",
-                "issue_key": final_issue_key,
-                "issue_url": issue_url,
-                "message": f"Jira issue {final_issue_key} updated successfully.{kb_message_suffix}",
-            }
-
-        except Exception as e:
-            from langgraph.errors import GraphInterrupt
-
-            if isinstance(e, GraphInterrupt):
-                raise
-            logger.error(f"Error updating Jira issue: {e}", exc_info=True)
-            return {
-                "status": "error",
-                "message": "Something went wrong while updating the issue.",
-            }
-
-    return update_jira_issue

surfsense_backend/app/agents/multi_agent_chat/subagents/connectors/linear/agent.py

@@ -1,55 +1,43 @@
-"""`linear` route: ``SubAgent`` spec for deepagents."""
+"""``linear`` route: ``SurfSenseSubagentSpec`` builder for deepagents.
+
+Tools come exclusively from MCP. The connector's own approval ruleset is
+declared in :data:`tools.index.RULESET`; the orchestrator layers it into
+a per-subagent :class:`PermissionMiddleware`.
+"""
 
 from __future__ import annotations
 
-from collections.abc import Sequence
 from typing import Any
 
-from deepagents import SubAgent
 from langchain_core.language_models import BaseChatModel
+from langchain_core.tools import BaseTool
 
-from app.agents.multi_agent_chat.subagents.shared.md_file_reader import (
-    read_md_file,
-)
-from app.agents.multi_agent_chat.subagents.shared.permissions import (
-    ToolsPermissions,
-    merge_tools_permissions,
-    middleware_gated_interrupt_on,
-)
-from app.agents.multi_agent_chat.subagents.shared.subagent_builder import (
-    pack_subagent,
-)
+from app.agents.multi_agent_chat.subagents.shared.md_file_reader import read_md_file
+from app.agents.multi_agent_chat.subagents.shared.spec import SurfSenseSubagentSpec
+from app.agents.multi_agent_chat.subagents.shared.subagent_builder import pack_subagent
 
-from .tools.index import load_tools
-
-NAME = "linear"
+from .tools.index import NAME, RULESET
 
 
 def build_subagent(
     *,
     dependencies: dict[str, Any],
     model: BaseChatModel | None = None,
-    extra_middleware: Sequence[Any] | None = None,
-    extra_tools_bucket: ToolsPermissions | None = None,
-) -> SubAgent:
-    buckets = load_tools(dependencies=dependencies)
-    merged_tools_bucket = merge_tools_permissions(buckets, extra_tools_bucket)
-    tools = [
-        row["tool"]
-        for row in (*merged_tools_bucket["allow"], *merged_tools_bucket["ask"])
-        if row.get("tool") is not None
-    ]
-    interrupt_on = middleware_gated_interrupt_on(merged_tools_bucket)
-    description = read_md_file(__package__, "description").strip()
-    if not description:
-        description = "Handles linear tasks for this workspace."
+    middleware_stack: dict[str, Any] | None = None,
+    mcp_tools: list[BaseTool] | None = None,
+) -> SurfSenseSubagentSpec:
+    description = (
+        read_md_file(__package__, "description").strip()
+        or "Handles linear tasks for this workspace."
+    )
     system_prompt = read_md_file(__package__, "system_prompt").strip()
     return pack_subagent(
         name=NAME,
         description=description,
         system_prompt=system_prompt,
-        tools=tools,
-        interrupt_on=interrupt_on,
+        tools=list(mcp_tools or []),
+        ruleset=RULESET,
+        dependencies=dependencies,
         model=model,
-        extra_middleware=extra_middleware,
+        middleware_stack=middleware_stack,
     )

surfsense_backend/app/agents/multi_agent_chat/subagents/connectors/linear/description.md

@@ -1 +1,2 @@
-Use for Linear issue/project work: find/create issues, update status/assignees, review project progress, and inspect cycles.
+Specialist for issues, projects, and cycles in the user's Linear workspace.
+Use proactively when the user wants to find, create, triage, assign, or close a Linear issue, or inspect a cycle.

surfsense_backend/app/agents/multi_agent_chat/subagents/connectors/linear/system_prompt.md

@@ -1,45 +1,112 @@
-You are the Linear MCP operations sub-agent.
-You receive delegated instructions from a supervisor agent and return structured results for supervisor synthesis.
+You are a Linear specialist for the user's connected Linear workspace.
 
-<goal>
-Execute Linear MCP operations accurately using only available runtime tools.
-</goal>
+Linear vocabulary:
+- **Issue identifier**: `<TEAM_KEY>-<NUMBER>` (e.g. `ENG-42`). User-facing and stable; prefer it in `action_summary`.
+- **Workflow states** are per-team and customizable — names, ordering, and which states exist all vary. State names must be resolved against the target team's actual workflow before use; do not assume a standard set.
+- **Default state on create**: when creating an issue without an explicit state, Linear routes it to the team's configured default state. Set an explicit state only when the request requires overriding the default.
+- **Priority**: `0=No priority`, `1=Urgent`, `2=High`, `3=Medium`, `4=Low`.
+- **Cycle**: a time-boxed iteration. Cycles advance by date in Linear and cannot be advanced via tool calls — they are read-only from this subagent's perspective.
 
-<available_tools>
-- Runtime-provided Linear MCP tools for issues/projects/teams/workflows.
-</available_tools>
+When invoked:
+1. Read the supervisor's request and the runtime tool list. Identify which tools cover discovery (list/get/search) and which cover mutation, by reading their descriptions.
+2. Plan the minimum chain of discovery calls needed to resolve any identifier, name, or scope the request leaves unspecified (target item, team, state, assignee, labels, project, etc.).
+3. Execute the planned discovery, then the requested mutation (if any), then return.
 
-<tool_policy>
-- Follow tool descriptions exactly; do not assume unsupported endpoints.
-- If required identifiers or context are missing, return `status=blocked` with `missing_fields` and supervisor `next_step`.
-- Never invent IDs, statuses, or mutation outcomes.
-</tool_policy>
+Resolution principle (the core behaviour):
+**Proactively look up any identifier, name, value, or scope the request leaves unspecified — target identifiers, user IDs, state IDs, label IDs, project scope, anything else — using the available tools instead of asking the supervisor.** Most user requests reference targets by title, description, or paraphrase, not by identifier. Search for them.
 
-<out_of_scope>
-- Do not execute non-Linear tasks.
-</out_of_scope>
+When discovery for a single slot returns multiple plausible candidates and you cannot confidently pick one, return `status=blocked` with up to 5 candidates in `evidence.matched_candidates` and the unresolved slot in `missing_fields`. The supervisor will disambiguate and redelegate.
 
-<safety>
-- Never claim mutation success without tool confirmation.
-</safety>
+When discovery returns zero matches for a slot the request requires, return `status=blocked` with a `next_step` suggesting alternative filters.
 
-<failure_policy>
-- On tool failure, return `status=error` with concise recovery `next_step`.
-- On unresolved ambiguity, return `status=blocked` with candidates.
-</failure_policy>
+Mutation guardrails:
+- Resolve every required Linear ID via discovery before calling a mutation tool. Mutations may have dependencies (state names are scoped to a team, so the team must be known first) — chain discovery calls as needed.
+- Never invent IDs, identifiers, state names, assignees, labels, or mutation outcomes. Every field in `evidence` must come from a tool result.
+- Confirm the mutation tool returned a success response before claiming success. If the mutation is approval-rejected (HITL), return `status=blocked` with `next_step="user declined; do not retry"`.
+- One operation per delegation. For multi-mutation requests, complete the highest-priority one and return `status=partial` with the remainder in `next_step`.
+
+Failure handling:
+- Tool failure: return `status=error`, place the underlying error message in `action_summary`, and put a concise recovery in `next_step`.
+- No useful results after reasonable narrowing/broadening: return `status=blocked` with filter suggestions in `next_step`.
+
+<example>
+Supervisor: "Find issues assigned to me with priority Urgent."
+1. Discovery: list issues with filters `{assignee: "me", priority: 1}`.
+2. Return `status=success` with the matched issues in `evidence.items`.
+</example>
+
+<example>
+Supervisor: "Create an issue 'Customers can't reset their password'."
+1. Discovery: team lookup → multiple teams exist in the workspace; the request gives no signal pointing to one.
+2. Priority was not specified, but priority is optional (Linear defaults to "No priority") — do not block on it. State is also optional (Linear applies the team's default state).
+3. Cannot pick the team. Return:
+   {
+     "status": "blocked",
+     "action_summary": "Need to know which team the new issue belongs to.",
+     "evidence": {
+       "title": "Customers can't reset their password",
+       "matched_candidates": [
+         { "id": "team_be", "label": "Backend (BE)" },
+         { "id": "team_fe", "label": "Frontend (FE)" },
+         { "id": "team_mob", "label": "Mobile (MOB)" }
+       ]
+     },
+     "next_step": "Confirm which team owns this issue, then redelegate.",
+     "missing_fields": ["team"]
+   }
+</example>
+
+<example>
+Supervisor: "Triage the login bug and assign it to Alex."
+1. Discovery: search issues for text "login bug" → one strong match, `ENG-42 — "Fix login bug on Safari"`. Capture its team_id.
+2. Discovery: workflow-state lookup for that team → find the `Triage` state id.
+3. Discovery: user lookup for "Alex" → two matches (alex.chen@…, alex.wong@…).
+4. Cannot confidently pick the assignee. Return:
+   {
+     "status": "blocked",
+     "action_summary": "Issue resolved (ENG-42). State resolved (Triage). Two users match 'Alex'.",
+     "evidence": {
+       "identifier": "ENG-42",
+       "title": "Fix login bug on Safari",
+       "matched_candidates": [
+         { "id": "user_xyz", "label": "Alex Chen <alex.chen@…>" },
+         { "id": "user_abc", "label": "Alex Wong <alex.wong@…>" }
+       ]
+     },
+     "next_step": "Confirm which Alex, then redelegate.",
+     "missing_fields": ["assignee"]
+   }
+</example>
 
 <output_contract>
-Return **only** one JSON object (no markdown/prose):
+Return **only** one JSON object (no markdown, no prose):
 {
   "status": "success" | "partial" | "blocked" | "error",
   "action_summary": string,
-  "evidence": { "items": object | null },
+  "evidence": {
+    "identifier": string | null,
+    "issue_id": string | null,
+    "title": string | null,
+    "state": string | null,
+    "assignee": string | null,
+    "priority": "No priority" | "Urgent" | "High" | "Medium" | "Low" | null,
+    "team_key": string | null,
+    "url": string | null,
+    "matched_candidates": [
+      { "id": string, "label": string }
+    ] | null,
+    "items": object | null
+  },
   "next_step": string | null,
   "missing_fields": string[] | null,
   "assumptions": string[] | null
 }
 Rules:
-- `status=success` -> `next_step=null`, `missing_fields=null`.
-- `status=partial|blocked|error` -> `next_step` must be non-null.
-- `status=blocked` due to missing required inputs -> `missing_fields` must be non-null.
+- `status=success` → `next_step=null`, `missing_fields=null`.
+- `status=partial|blocked|error` → `next_step` must be non-null.
+- `status=blocked` due to missing required inputs → `missing_fields` must be non-null.
+- For blocked ambiguity, populate `evidence.matched_candidates` with up to 5 options (`id` + `label` — works for any kind of candidate: issue, user, project, state, etc.).
+- For discovery-only queries (lists), populate `evidence.items` with the structured list.
 </output_contract>
+
+Discover before you mutate; never guess identifiers.

surfsense_backend/app/agents/multi_agent_chat/subagents/connectors/linear/tools/index.py

@@ -1,14 +1,31 @@
+"""``linear`` permission ruleset (rules over MCP tool names)."""
+
 from __future__ import annotations
 
-from typing import Any
+from app.agents.new_chat.permissions import Rule, Ruleset
 
-from app.agents.multi_agent_chat.subagents.shared.permissions import (
-    ToolsPermissions,
+NAME = "linear"
+
+RULESET = Ruleset(
+    origin=NAME,
+    rules=[
+        Rule(permission="list_issues", pattern="*", action="allow"),
+        Rule(permission="get_issue", pattern="*", action="allow"),
+        Rule(permission="list_my_issues", pattern="*", action="allow"),
+        Rule(permission="list_issue_statuses", pattern="*", action="allow"),
+        Rule(permission="list_issue_labels", pattern="*", action="allow"),
+        Rule(permission="list_comments", pattern="*", action="allow"),
+        Rule(permission="list_users", pattern="*", action="allow"),
+        Rule(permission="get_user", pattern="*", action="allow"),
+        Rule(permission="list_teams", pattern="*", action="allow"),
+        Rule(permission="get_team", pattern="*", action="allow"),
+        Rule(permission="list_projects", pattern="*", action="allow"),
+        Rule(permission="get_project", pattern="*", action="allow"),
+        Rule(permission="list_project_labels", pattern="*", action="allow"),
+        Rule(permission="list_cycles", pattern="*", action="allow"),
+        Rule(permission="list_documents", pattern="*", action="allow"),
+        Rule(permission="get_document", pattern="*", action="allow"),
+        Rule(permission="search_documentation", pattern="*", action="allow"),
+        Rule(permission="save_issue", pattern="*", action="ask"),
+    ],
 )
-
-
-def load_tools(
-    *, dependencies: dict[str, Any] | None = None, **kwargs: Any
-) -> ToolsPermissions:
-    _ = {**(dependencies or {}), **kwargs}
-    return {"allow": [], "ask": []}

surfsense_backend/app/agents/multi_agent_chat/subagents/connectors/linear/tools/update_issue.py

@@ -1,318 +0,0 @@
-import logging
-from typing import Any
-
-from langchain_core.tools import tool
-from sqlalchemy.ext.asyncio import AsyncSession
-
-from app.agents.new_chat.tools.hitl import request_approval
-from app.connectors.linear_connector import LinearAPIError, LinearConnector
-from app.services.linear import LinearKBSyncService, LinearToolMetadataService
-
-logger = logging.getLogger(__name__)
-
-
-def create_update_linear_issue_tool(
-    db_session: AsyncSession | None = None,
-    search_space_id: int | None = None,
-    user_id: str | None = None,
-    connector_id: int | None = None,
-):
-    """
-    Factory function to create the update_linear_issue tool.
-
-    Args:
-        db_session: Database session for accessing the Linear connector
-        search_space_id: Search space ID to find the Linear connector
-        user_id: User ID for fetching user-specific context
-        connector_id: Optional specific connector ID (if known)
-
-    Returns:
-        Configured update_linear_issue tool
-    """
-
-    @tool
-    async def update_linear_issue(
-        issue_ref: str,
-        new_title: str | None = None,
-        new_description: str | None = None,
-        new_state_name: str | None = None,
-        new_assignee_email: str | None = None,
-        new_priority: int | None = None,
-        new_label_names: list[str] | None = None,
-    ) -> dict[str, Any]:
-        """Update an existing Linear issue that has been indexed in the knowledge base.
-
-        Use this tool when the user asks to modify, change, or update a Linear issue —
-        for example, changing its status, reassigning it, updating its title or description,
-        adjusting its priority, or changing its labels.
-
-        Only issues already indexed in the knowledge base can be updated.
-
-        Args:
-            issue_ref: The issue to update. Can be the issue title (e.g. "Fix login bug"),
-                       the identifier (e.g. "ENG-42"), or the full document title
-                       (e.g. "ENG-42: Fix login bug"). Matched case-insensitively.
-            new_title: New title for the issue (optional).
-            new_description: New markdown body for the issue (optional).
-            new_state_name: New workflow state name (e.g. "In Progress", "Done").
-                            Matched case-insensitively against the team's states.
-            new_assignee_email: Email address of the new assignee.
-                                Matched case-insensitively against the team's members.
-            new_priority: New priority (0 = No Priority, 1 = Urgent, 2 = High,
-                          3 = Medium, 4 = Low).
-            new_label_names: New set of label names to apply.
-                             Matched case-insensitively against the team's labels.
-                             Unrecognised names are silently skipped.
-
-        Returns:
-            Dictionary with:
-            - status: "success", "rejected", "not_found", or "error"
-            - identifier: Human-readable ID like "ENG-42" (if success)
-            - url: URL to the updated issue (if success)
-            - message: Result message
-
-            IMPORTANT:
-            - If status is "rejected", the user explicitly declined the action.
-              Respond with a brief acknowledgment (e.g., "Understood, I didn't update the issue.")
-              and move on. Do NOT ask for alternatives or troubleshoot.
-            - If status is "not_found", inform the user conversationally using the exact message
-              provided. Do NOT treat this as an error. Simply relay the message and ask the user
-              to verify the issue title or identifier, or check if it has been indexed.
-
-        Examples:
-            - "Mark the 'Fix login bug' issue as done"
-            - "Assign ENG-42 to john@company.com"
-            - "Change the priority of 'Payment timeout' to urgent"
-        """
-        logger.info(f"update_linear_issue called: issue_ref='{issue_ref}'")
-
-        if db_session is None or search_space_id is None or user_id is None:
-            logger.error(
-                "Linear tool not properly configured - missing required parameters"
-            )
-            return {
-                "status": "error",
-                "message": "Linear tool not properly configured. Please contact support.",
-            }
-
-        try:
-            metadata_service = LinearToolMetadataService(db_session)
-            context = await metadata_service.get_update_context(
-                search_space_id, user_id, issue_ref
-            )
-
-            if "error" in context:
-                error_msg = context["error"]
-                if context.get("auth_expired"):
-                    logger.warning(f"Auth expired for update context: {error_msg}")
-                    return {
-                        "status": "auth_error",
-                        "message": error_msg,
-                        "connector_id": context.get("connector_id"),
-                        "connector_type": "linear",
-                    }
-                if "not found" in error_msg.lower():
-                    logger.warning(f"Issue not found: {error_msg}")
-                    return {"status": "not_found", "message": error_msg}
-                else:
-                    logger.error(f"Failed to fetch update context: {error_msg}")
-                    return {"status": "error", "message": error_msg}
-
-            issue_id = context["issue"]["id"]
-            document_id = context["issue"]["document_id"]
-            connector_id_from_context = context.get("workspace", {}).get("id")
-
-            team = context.get("team", {})
-            new_state_id = _resolve_state(team, new_state_name)
-            new_assignee_id = _resolve_assignee(team, new_assignee_email)
-            new_label_ids = _resolve_labels(team, new_label_names)
-
-            logger.info(
-                f"Requesting approval for updating Linear issue: '{issue_ref}' (id={issue_id})"
-            )
-            result = request_approval(
-                action_type="linear_issue_update",
-                tool_name="update_linear_issue",
-                params={
-                    "issue_id": issue_id,
-                    "document_id": document_id,
-                    "new_title": new_title,
-                    "new_description": new_description,
-                    "new_state_id": new_state_id,
-                    "new_assignee_id": new_assignee_id,
-                    "new_priority": new_priority,
-                    "new_label_ids": new_label_ids,
-                    "connector_id": connector_id_from_context,
-                },
-                context=context,
-            )
-
-            if result.rejected:
-                logger.info("Linear issue update rejected by user")
-                return {
-                    "status": "rejected",
-                    "message": "User declined. Do not retry or suggest alternatives.",
-                }
-
-            final_issue_id = result.params.get("issue_id", issue_id)
-            final_document_id = result.params.get("document_id", document_id)
-            final_new_title = result.params.get("new_title", new_title)
-            final_new_description = result.params.get(
-                "new_description", new_description
-            )
-            final_new_state_id = result.params.get("new_state_id", new_state_id)
-            final_new_assignee_id = result.params.get(
-                "new_assignee_id", new_assignee_id
-            )
-            final_new_priority = result.params.get("new_priority", new_priority)
-            final_new_label_ids: list[str] | None = result.params.get(
-                "new_label_ids", new_label_ids
-            )
-            final_connector_id = result.params.get(
-                "connector_id", connector_id_from_context
-            )
-
-            if not final_connector_id:
-                logger.error("No connector found for this issue")
-                return {
-                    "status": "error",
-                    "message": "No connector found for this issue.",
-                }
-
-            from sqlalchemy.future import select
-
-            from app.db import SearchSourceConnector, SearchSourceConnectorType
-
-            result = await db_session.execute(
-                select(SearchSourceConnector).filter(
-                    SearchSourceConnector.id == final_connector_id,
-                    SearchSourceConnector.search_space_id == search_space_id,
-                    SearchSourceConnector.user_id == user_id,
-                    SearchSourceConnector.connector_type
-                    == SearchSourceConnectorType.LINEAR_CONNECTOR,
-                )
-            )
-            connector = result.scalars().first()
-            if not connector:
-                logger.error(
-                    f"Invalid connector_id={final_connector_id} for search_space_id={search_space_id}"
-                )
-                return {
-                    "status": "error",
-                    "message": "Selected Linear connector is invalid or has been disconnected.",
-                }
-            logger.info(f"Validated Linear connector: id={final_connector_id}")
-
-            logger.info(
-                f"Updating Linear issue with final params: issue_id={final_issue_id}"
-            )
-            linear_client = LinearConnector(
-                session=db_session, connector_id=final_connector_id
-            )
-            updated_issue = await linear_client.update_issue(
-                issue_id=final_issue_id,
-                title=final_new_title,
-                description=final_new_description,
-                state_id=final_new_state_id,
-                assignee_id=final_new_assignee_id,
-                priority=final_new_priority,
-                label_ids=final_new_label_ids,
-            )
-
-            if updated_issue.get("status") == "error":
-                logger.error(
-                    f"Failed to update Linear issue: {updated_issue.get('message')}"
-                )
-                return {
-                    "status": "error",
-                    "message": updated_issue.get("message"),
-                }
-
-            logger.info(
-                f"update_issue result: {updated_issue.get('identifier')} - {updated_issue.get('title')}"
-            )
-
-            if final_document_id is not None:
-                logger.info(
-                    f"Updating knowledge base for document {final_document_id}..."
-                )
-                kb_service = LinearKBSyncService(db_session)
-                kb_result = await kb_service.sync_after_update(
-                    document_id=final_document_id,
-                    issue_id=final_issue_id,
-                    user_id=user_id,
-                    search_space_id=search_space_id,
-                )
-                if kb_result["status"] == "success":
-                    logger.info(
-                        f"Knowledge base successfully updated for issue {final_issue_id}"
-                    )
-                    kb_message = " Your knowledge base has also been updated."
-                elif kb_result["status"] == "not_indexed":
-                    kb_message = " This issue will be added to your knowledge base in the next scheduled sync."
-                else:
-                    logger.warning(
-                        f"KB update failed for issue {final_issue_id}: {kb_result.get('message')}"
-                    )
-                    kb_message = " Your knowledge base will be updated in the next scheduled sync."
-            else:
-                kb_message = ""
-
-            identifier = updated_issue.get("identifier")
-            default_msg = f"Issue {identifier} updated successfully."
-            return {
-                "status": "success",
-                "identifier": identifier,
-                "url": updated_issue.get("url"),
-                "message": f"{updated_issue.get('message', default_msg)}{kb_message}",
-            }
-
-        except Exception as e:
-            from langgraph.errors import GraphInterrupt
-
-            if isinstance(e, GraphInterrupt):
-                raise
-
-            logger.error(f"Error updating Linear issue: {e}", exc_info=True)
-            if isinstance(e, ValueError | LinearAPIError):
-                message = str(e)
-            else:
-                message = (
-                    "Something went wrong while updating the issue. Please try again."
-                )
-            return {"status": "error", "message": message}
-
-    return update_linear_issue
-
-
-def _resolve_state(team: dict, state_name: str | None) -> str | None:
-    if not state_name:
-        return None
-    name_lower = state_name.lower()
-    for state in team.get("states", []):
-        if state.get("name", "").lower() == name_lower:
-            return state["id"]
-    return None
-
-
-def _resolve_assignee(team: dict, assignee_email: str | None) -> str | None:
-    if not assignee_email:
-        return None
-    email_lower = assignee_email.lower()
-    for member in team.get("members", []):
-        if member.get("email", "").lower() == email_lower:
-            return member["id"]
-    return None
-
-
-def _resolve_labels(team: dict, label_names: list[str] | None) -> list[str] | None:
-    if label_names is None:
-        return None
-    if not label_names:
-        return []
-    name_set = {n.lower() for n in label_names}
-    return [
-        label["id"]
-        for label in team.get("labels", [])
-        if label.get("name", "").lower() in name_set
-    ]

surfsense_backend/app/agents/multi_agent_chat/subagents/connectors/luma/agent.py

@@ -1,55 +1,44 @@
-"""`luma` route: ``SubAgent`` spec for deepagents."""
+"""``luma`` route: ``SurfSenseSubagentSpec`` builder for deepagents.
+
+Tools self-gate inside their bodies via :func:`request_approval`; the
+empty :data:`tools.index.RULESET` is layered into a per-subagent
+:class:`PermissionMiddleware` for uniformity.
+"""
 
 from __future__ import annotations
 
-from collections.abc import Sequence
 from typing import Any
 
-from deepagents import SubAgent
 from langchain_core.language_models import BaseChatModel
+from langchain_core.tools import BaseTool
 
-from app.agents.multi_agent_chat.subagents.shared.md_file_reader import (
-    read_md_file,
-)
-from app.agents.multi_agent_chat.subagents.shared.permissions import (
-    ToolsPermissions,
-    merge_tools_permissions,
-    middleware_gated_interrupt_on,
-)
-from app.agents.multi_agent_chat.subagents.shared.subagent_builder import (
-    pack_subagent,
-)
+from app.agents.multi_agent_chat.subagents.shared.md_file_reader import read_md_file
+from app.agents.multi_agent_chat.subagents.shared.spec import SurfSenseSubagentSpec
+from app.agents.multi_agent_chat.subagents.shared.subagent_builder import pack_subagent
 
-from .tools.index import load_tools
-
-NAME = "luma"
+from .tools.index import NAME, RULESET, load_tools
 
 
 def build_subagent(
     *,
     dependencies: dict[str, Any],
     model: BaseChatModel | None = None,
-    extra_middleware: Sequence[Any] | None = None,
-    extra_tools_bucket: ToolsPermissions | None = None,
-) -> SubAgent:
-    buckets = load_tools(dependencies=dependencies)
-    merged_tools_bucket = merge_tools_permissions(buckets, extra_tools_bucket)
-    tools = [
-        row["tool"]
-        for row in (*merged_tools_bucket["allow"], *merged_tools_bucket["ask"])
-        if row.get("tool") is not None
-    ]
-    interrupt_on = middleware_gated_interrupt_on(merged_tools_bucket)
-    description = read_md_file(__package__, "description").strip()
-    if not description:
-        description = "Handles luma tasks for this workspace."
+    middleware_stack: dict[str, Any] | None = None,
+    mcp_tools: list[BaseTool] | None = None,
+) -> SurfSenseSubagentSpec:
+    tools = [*load_tools(dependencies=dependencies), *(mcp_tools or [])]
+    description = (
+        read_md_file(__package__, "description").strip()
+        or "Handles luma tasks for this workspace."
+    )
     system_prompt = read_md_file(__package__, "system_prompt").strip()
     return pack_subagent(
         name=NAME,
         description=description,
         system_prompt=system_prompt,
         tools=tools,
-        interrupt_on=interrupt_on,
+        ruleset=RULESET,
+        dependencies=dependencies,
         model=model,
-        extra_middleware=extra_middleware,
+        middleware_stack=middleware_stack,
     )

surfsense_backend/app/agents/multi_agent_chat/subagents/connectors/luma/description.md

@@ -1 +1,2 @@
-Use for Luma event operations: list events, inspect event details, and create new events.
+Specialist for events in the user's Luma account.
+Use proactively when the user wants to find, view, or create a Luma event.

surfsense_backend/app/agents/multi_agent_chat/subagents/connectors/luma/system_prompt.md

@@ -1,55 +1,109 @@
-You are the Luma operations sub-agent.
-You receive delegated instructions from a supervisor agent and return structured results for supervisor synthesis.
+You are a Luma specialist for the user's connected Luma account.
 
-<goal>
-Execute Luma event listing, reads, and creation accurately.
-</goal>
+## Vocabulary you must use precisely
 
-<available_tools>
-- `list_luma_events`
-- `read_luma_event`
-- `create_luma_event`
-</available_tools>
+- **Event resolution via `list_luma_events`** — events in the connected account are discovered via `list_luma_events` (live Luma API). Call it to translate an event name or date in the supervisor's task into an `event_id` before reading. There is no KB index and no name-based lookup inside `read_luma_event`, so you cannot pass a title to it — you must resolve the id from the list first.
+- **Create datetime format — naive ISO 8601 + separate `timezone` field** — `create_luma_event` takes `start_at` / `end_at` as **naive** ISO timestamps without an offset (e.g. `"2026-05-01T18:00:00"`) **and** `timezone` as a separate argument (default `"UTC"`, e.g. `"America/New_York"`, `"Europe/Paris"`). Compute both from the supervisor's task using the runtime timestamp for any relative phrasing (`"next Friday"`, `"in 2 weeks"`). Never embed a timezone offset inside `start_at` / `end_at`.
+- **Read + create only — no update, delete, or RSVP** — `list_luma_events` and `read_luma_event` are read-only and `create_luma_event` is the only mutation. If the supervisor asks to reschedule, modify, cancel, delete, or RSVP to an event, return `status=blocked` — these operations are not supported by the connector.
 
-<tool_policy>
-- Use only tools in `<available_tools>`.
-- Resolve relative dates against runtime timestamp.
-- If required event fields are missing, return `status=blocked` with `missing_fields`.
-- Never invent event IDs/times or creation outcomes.
-</tool_policy>
+## Required inputs
 
-<out_of_scope>
-- Do not perform non-Luma tasks.
-</out_of_scope>
+**For every required input below, first try to infer it from the supervisor's task text** — extract event names from natural phrasing (`"the Founders Mixer"`, `"'Q3 Demo Day'"`), dates and times from relative or absolute phrasing (use the runtime timestamp for `"next Friday"`, `"in 2 weeks"`), timezone from location signals (`"in NYC"` → `"America/New_York"`), and description content from any details the supervisor already provided. Only return `status=blocked` with `missing_fields` when an input is genuinely absent or ambiguous after a thorough read of the task.
 
-<safety>
-- Never claim event creation success without tool confirmation.
-</safety>
+- `list_luma_events` — no inputs. Call it whenever you need to resolve an event name or date to an `event_id`. Optional `max_results` (max 50; tighten only when the task implies a small window).
+- `read_luma_event` — `event_id` (resolve via `list_luma_events` based on the event name or date signal in the task; block if no event signal at all).
+- `create_luma_event` — `name` (event title inferred from the task; do not invent one if absent), `start_at` and `end_at` (naive ISO 8601 without offset, computed from the task using the runtime timestamp; if the user gave only a start and a duration, compute `end_at` from them). Optional `description` (you may generate it from the task) and `timezone` (set from location signals; otherwise leave the default `"UTC"`). Block if the event title, start time, or duration/end time cannot be inferred.
 
-<failure_policy>
-- On tool failure, return `status=error` with concise recovery `next_step`.
-- On missing required fields, return `status=blocked` with `missing_fields`.
-</failure_policy>
+## Outcome mapping
 
-<output_contract>
-Return **only** one JSON object (no markdown/prose):
+| Tool returns                                       | Your `status` | `next_step` |
+|----------------------------------------------------|---------------|------------------------------------------------------------------------------------------------------------------------------|
+| `success` with non-empty events / event details    | `success`     | `null` |
+| `success` with `total: 0` (list returns no events) | `success`     | `null` (surface `total: 0` in `evidence.items` so the supervisor can report "no upcoming events") |
+| `rejected` (create only)                           | `blocked`     | `"User declined this Luma event creation. Do not retry or suggest alternatives."` |
+| `not_found` (read only)                            | `blocked`     | `"Event '<event_id>' was not found in Luma. Ask the user to verify or re-list events."` |
+| `auth_error`                                       | `error`       | `"The connected Luma API key is invalid. Ask the user to update the Luma API key in connector settings."` |
+| `error`                                            | `error`       | Relay the tool's `message` verbatim as `next_step` (this covers Luma Plus 403s and other API errors). |
+| tool raises / unknown                              | `error`       | `"Luma tool failed unexpectedly. Ask the user to retry shortly."` |
+
+Surface the tool's `message`, `event_id`, `name`, `start_at`, and `url` inside `evidence` when the tool returned them. Never invent a field the tool did not return.
+
+## Examples
+
+**Example 1 — happy path create (datetime and timezone inferred from task):**
+- *Supervisor task:* `"Create a Luma event 'Q3 Demo Day' on May 1 2026 from 6 PM to 8 PM in New York time."`
+- *You:* extract `name="Q3 Demo Day"`; compute naive ISO `start_at="2026-05-01T18:00:00"` and `end_at="2026-05-01T20:00:00"` (no offset embedded); set `timezone="America/New_York"` from `"in New York time"` → call `create_luma_event(name="Q3 Demo Day", start_at="2026-05-01T18:00:00", end_at="2026-05-01T20:00:00", timezone="America/New_York")` → tool returns `status=success`.
+- *Output:*
+
+  ```json
+  {
+    "status": "success",
+    "action_summary": "Created Luma event 'Q3 Demo Day' on May 1 2026, 6 PM–8 PM (America/New_York).",
+    "evidence": { "operation": "create_luma_event", "event_id": "<id>", "event_name": "Q3 Demo Day", "start_at": "2026-05-01T18:00:00", "url": null, "matched_candidates": null, "items": null },
+    "next_step": null,
+    "missing_fields": null,
+    "assumptions": null
+  }
+  ```
+
+**Example 2 — list → read by name:**
+- *Supervisor task:* `"Show me the details of the 'Founders Mixer' event."`
+- *You:* call `list_luma_events()` → find the entry where `name="Founders Mixer"`, take its `event_id`; call `read_luma_event(event_id=<founders_mixer_id>)` → tool returns `status=success` with the full event payload.
+- *Output:*
+
+  ```json
+  {
+    "status": "success",
+    "action_summary": "Retrieved details for Luma event 'Founders Mixer'.",
+    "evidence": { "operation": "read_luma_event", "event_id": "<id>", "event_name": "Founders Mixer", "start_at": "<iso>", "url": "<url>", "matched_candidates": null, "items": { "description": "<...>", "location_name": "<...>", "meeting_url": "<...>" } },
+    "next_step": null,
+    "missing_fields": null,
+    "assumptions": null
+  }
+  ```
+
+**Example 3 — unsupported operation (reschedule):**
+- *Supervisor task:* `"Reschedule the 'Founders Mixer' to next Friday."`
+- *You:* Luma updates are not supported by your tools. Do not call any tool. Do not work around by creating a new event with the same name — block.
+- *Output:*
+
+  ```json
+  {
+    "status": "blocked",
+    "action_summary": "Rescheduling Luma events is not supported.",
+    "evidence": { "operation": null, "event_id": null, "event_name": "Founders Mixer", "start_at": null, "url": null, "matched_candidates": null, "items": null },
+    "next_step": "Updating Luma events is not supported by the connector. Ask the user to reschedule the event directly in the Luma UI.",
+    "missing_fields": null,
+    "assumptions": null
+  }
+  ```
+
+## Output contract
+
+Return **only** one JSON object (no markdown or prose outside it):
+
+```json
 {
   "status": "success" | "partial" | "blocked" | "error",
   "action_summary": string,
   "evidence": {
+    "operation": "list_luma_events" | "read_luma_event" | "create_luma_event" | null,
     "event_id": string | null,
-    "title": string | null,
-    "start_at": string (ISO 8601 with timezone) | null,
-    "matched_candidates": [
-      { "event_id": string, "title": string | null, "start_at": string | null }
-    ] | null
+    "event_name": string | null,
+    "start_at": string | null,
+    "url": string | null,
+    "matched_candidates": [ { "id": string, "label": string } ] | null,
+    "items": object | null
   },
   "next_step": string | null,
   "missing_fields": string[] | null,
   "assumptions": string[] | null
 }
+```
+
 Rules:
-- `status=success` -> `next_step=null`, `missing_fields=null`.
-- `status=partial|blocked|error` -> `next_step` must be non-null.
-- `status=blocked` due to missing required inputs -> `missing_fields` must be non-null.
-</output_contract>
+- `status=success` → `next_step=null`, `missing_fields=null`.
+- `status=partial|blocked|error` → `next_step` must be non-null.
+- `status=blocked` due to missing required inputs → `missing_fields` must be non-null.
+
+Infer before you call; verify before you create; map every tool outcome faithfully.

surfsense_backend/app/agents/multi_agent_chat/subagents/connectors/luma/tools/create_event.py

@@ -5,7 +5,9 @@ import httpx
 from langchain_core.tools import tool
 from sqlalchemy.ext.asyncio import AsyncSession
 
-from app.agents.new_chat.tools.hitl import request_approval
+from app.agents.multi_agent_chat.subagents.shared.hitl.approvals.self_gated import (
+    request_approval,
+)
 
 from ._auth import LUMA_API, get_api_key, get_luma_connector, luma_headers
 

surfsense_backend/app/agents/multi_agent_chat/subagents/connectors/luma/tools/index.py

@@ -1,32 +1,36 @@
+"""``luma`` native tools and (empty) permission ruleset.
+
+Tools self-gate via :func:`request_approval` in their bodies.
+"""
+
 from __future__ import annotations
 
 from typing import Any
 
-from app.agents.multi_agent_chat.subagents.shared.permissions import (
-    ToolsPermissions,
-)
+from langchain_core.tools import BaseTool
+
+from app.agents.new_chat.permissions import Ruleset
 
 from .create_event import create_create_luma_event_tool
 from .list_events import create_list_luma_events_tool
 from .read_event import create_read_luma_event_tool
 
+NAME = "luma"
+
+RULESET = Ruleset(origin=NAME, rules=[])
+
 
 def load_tools(
     *, dependencies: dict[str, Any] | None = None, **kwargs: Any
-) -> ToolsPermissions:
+) -> list[BaseTool]:
     d = {**(dependencies or {}), **kwargs}
     common = {
         "db_session": d["db_session"],
         "search_space_id": d["search_space_id"],
         "user_id": d["user_id"],
     }
-    list_ev = create_list_luma_events_tool(**common)
-    read_ev = create_read_luma_event_tool(**common)
-    create = create_create_luma_event_tool(**common)
-    return {
-        "allow": [
-            {"name": getattr(list_ev, "name", "") or "", "tool": list_ev},
-            {"name": getattr(read_ev, "name", "") or "", "tool": read_ev},
-        ],
-        "ask": [{"name": getattr(create, "name", "") or "", "tool": create}],
-    }
+    return [
+        create_list_luma_events_tool(**common),
+        create_read_luma_event_tool(**common),
+        create_create_luma_event_tool(**common),
+    ]

surfsense_backend/app/agents/multi_agent_chat/subagents/connectors/notion/agent.py

@@ -1,55 +1,44 @@
-"""`notion` route: ``SubAgent`` spec for deepagents."""
+"""``notion`` route: ``SurfSenseSubagentSpec`` builder for deepagents.
+
+Tools self-gate inside their bodies via :func:`request_approval`; the
+empty :data:`tools.index.RULESET` is layered into a per-subagent
+:class:`PermissionMiddleware` for uniformity.
+"""
 
 from __future__ import annotations
 
-from collections.abc import Sequence
 from typing import Any
 
-from deepagents import SubAgent
 from langchain_core.language_models import BaseChatModel
+from langchain_core.tools import BaseTool
 
-from app.agents.multi_agent_chat.subagents.shared.md_file_reader import (
-    read_md_file,
-)
-from app.agents.multi_agent_chat.subagents.shared.permissions import (
-    ToolsPermissions,
-    merge_tools_permissions,
-    middleware_gated_interrupt_on,
-)
-from app.agents.multi_agent_chat.subagents.shared.subagent_builder import (
-    pack_subagent,
-)
+from app.agents.multi_agent_chat.subagents.shared.md_file_reader import read_md_file
+from app.agents.multi_agent_chat.subagents.shared.spec import SurfSenseSubagentSpec
+from app.agents.multi_agent_chat.subagents.shared.subagent_builder import pack_subagent
 
-from .tools.index import load_tools
-
-NAME = "notion"
+from .tools.index import NAME, RULESET, load_tools
 
 
 def build_subagent(
     *,
     dependencies: dict[str, Any],
     model: BaseChatModel | None = None,
-    extra_middleware: Sequence[Any] | None = None,
-    extra_tools_bucket: ToolsPermissions | None = None,
-) -> SubAgent:
-    buckets = load_tools(dependencies=dependencies)
-    merged_tools_bucket = merge_tools_permissions(buckets, extra_tools_bucket)
-    tools = [
-        row["tool"]
-        for row in (*merged_tools_bucket["allow"], *merged_tools_bucket["ask"])
-        if row.get("tool") is not None
-    ]
-    interrupt_on = middleware_gated_interrupt_on(merged_tools_bucket)
-    description = read_md_file(__package__, "description").strip()
-    if not description:
-        description = "Handles notion tasks for this workspace."
+    middleware_stack: dict[str, Any] | None = None,
+    mcp_tools: list[BaseTool] | None = None,
+) -> SurfSenseSubagentSpec:
+    tools = [*load_tools(dependencies=dependencies), *(mcp_tools or [])]
+    description = (
+        read_md_file(__package__, "description").strip()
+        or "Handles notion tasks for this workspace."
+    )
     system_prompt = read_md_file(__package__, "system_prompt").strip()
     return pack_subagent(
         name=NAME,
         description=description,
         system_prompt=system_prompt,
         tools=tools,
-        interrupt_on=interrupt_on,
+        ruleset=RULESET,
+        dependencies=dependencies,
         model=model,
-        extra_middleware=extra_middleware,
+        middleware_stack=middleware_stack,
     )

surfsense_backend/app/agents/multi_agent_chat/subagents/connectors/notion/description.md

@@ -1 +1,2 @@
-Use for Notion workspace pages: create pages, update page content, and delete pages.
+Specialist for pages in the user's Notion workspace.
+Use proactively when the user wants to create, change, archive, or remove a Notion page.

surfsense_backend/app/agents/multi_agent_chat/subagents/connectors/notion/system_prompt.md

@@ -1,56 +1,107 @@
-You are the Notion operations sub-agent.
-You receive delegated instructions from a supervisor agent and return structured results for supervisor synthesis.
+You are a Notion specialist for the user's connected Notion workspace.
 
-<goal>
-Execute Notion page operations accurately in the connected workspace.
-</goal>
+## Vocabulary you must use precisely
 
-<available_tools>
-- `create_notion_page`
-- `update_notion_page`
-- `delete_notion_page`
-</available_tools>
+- **Page resolution (internal)** — `update_notion_page` and `delete_notion_page` accept a `page_title` and resolve it against the **locally-synced Notion KB index**, not against the live Notion API. A page that exists in Notion but has not been indexed yet cannot be resolved. There is no separate "search" or "lookup" tool exposed to you — resolution happens inside the mutation tool.
+- **Update is append-only** — `update_notion_page` appends new content blocks to the page body. It cannot edit, replace, or remove existing content.
+- **Delete is archive** — `delete_notion_page` archives the page (Notion's "trash"); the user can restore it from Notion's UI. With `delete_from_kb=true` the local KB document is also removed; the default is `false`.
 
-<tool_policy>
-- Use only tools in `<available_tools>`.
-- If target page context is unclear, do not ask the user directly; return `status=blocked` with candidate options and supervisor `next_step`.
-- Never invent page IDs, titles, or mutation outcomes.
-</tool_policy>
+## Required inputs
 
-<out_of_scope>
-- Do not perform non-Notion tasks.
-</out_of_scope>
+**For every required input below, first try to infer it from the supervisor's task text** — extract titles from natural phrasing (`"the Weekly Sync page"`, `"my Q1 retro"`), topics from `"about X"` constructions, content from any details the supervisor already provided. Only return `status=blocked` with `missing_fields` when an input is genuinely absent or ambiguous after a thorough read of the task.
 
-<safety>
-- Before update/delete, ensure the target page match is explicit.
-- Never claim mutation success without tool confirmation.
-</safety>
+- `create_notion_page` — `title` (the user-supplied topic, inferred from the task; do not invent one if absent). You may generate the markdown `content` body yourself from that topic.
+- `update_notion_page` — `page_title` (which page to update — infer from the task) and `content` (what to append — infer or generate from the task's specifics).
+- `delete_notion_page` — `page_title` (which page to delete — infer from the task). Only set `delete_from_kb=true` when the user explicitly asked to remove it from the knowledge base; otherwise leave it `false`.
 
-<failure_policy>
-- On tool failure, return `status=error` with concise retry/recovery `next_step`.
-- On ambiguous target, return `status=blocked` with candidate options.
-</failure_policy>
+## Outcome mapping
 
-<output_contract>
-Return **only** one JSON object (no markdown/prose):
+| Tool returns          | Your `status` | `next_step`                                                                                                                  |
+|-----------------------|---------------|------------------------------------------------------------------------------------------------------------------------------|
+| `success`             | `success`     | `null`                                                                                                                       |
+| `rejected`            | `blocked`     | `"User declined this Notion action. Do not retry or suggest alternatives."`                                                  |
+| `not_found`           | `blocked`     | `"Page '<title>' was not found in the indexed Notion pages. Ask the user to verify the title or wait for the next KB sync."` |
+| `auth_error`          | `error`       | `"The connected Notion account needs re-authentication. Ask the user to re-authenticate Notion in connector settings."`      |
+| `error`               | `error`       | Relay the tool's `message` verbatim as `next_step`.                                                                          |
+| tool raises / unknown | `error`       | `"Notion tool failed unexpectedly. Ask the user to retry shortly."`                                                          |
+
+Surface the tool's `message`, `page_id`, `page_title`, and `url` inside `evidence` when the tool returned them. Never invent a field the tool did not return.
+
+## Examples
+
+**Example 1 — happy path create (topic inferred from task):**
+- *Supervisor task:* `"Create a Notion page summarising our Q2 roadmap."`
+- *You:* extract `title="Q2 Roadmap"` from `"about Q2 roadmap"`; generate a markdown body → call `create_notion_page(title="Q2 Roadmap", content=<generated markdown>)` → tool returns `status=success`.
+- *Output:*
+
+  ```json
+  {
+    "status": "success",
+    "action_summary": "Created Notion page 'Q2 Roadmap'.",
+    "evidence": { "operation": "create_notion_page", "page_id": "<id>", "page_title": "Q2 Roadmap", "url": "<url>", "matched_candidates": null, "items": null },
+    "next_step": null,
+    "missing_fields": null,
+    "assumptions": null
+  }
+  ```
+
+**Example 2 — blocked only because nothing is inferable:**
+- *Supervisor task:* `"Create a Notion page."`
+- *You:* no topic anywhere in the task text — no `"about X"`, no quoted phrase, no descriptor. Do not fabricate one. Do not call any tool. (Contrast: `"Create a Notion page about our launch plan"` would yield `title="Launch Plan"` and proceed immediately — block only because the task carries zero topic information.)
+- *Output:*
+
+  ```json
+  {
+    "status": "blocked",
+    "action_summary": "Cannot create a Notion page without a topic.",
+    "evidence": { "operation": null, "page_id": null, "page_title": null, "url": null, "matched_candidates": null, "items": null },
+    "next_step": "Ask the user what the page should be about.",
+    "missing_fields": ["title"],
+    "assumptions": null
+  }
+  ```
+
+**Example 3 — page not in the KB index:**
+- *Supervisor task:* `"Add today's meeting notes to my 'Weekly Sync' Notion page."`
+- *You:* extract `page_title="Weekly Sync"` and meeting-notes content → call `update_notion_page(page_title="Weekly Sync", content=<generated notes>)` → tool returns `status=not_found`.
+- *Output:*
+
+  ```json
+  {
+    "status": "blocked",
+    "action_summary": "Could not find a Notion page titled 'Weekly Sync' in the indexed pages.",
+    "evidence": { "operation": "update_notion_page", "page_id": null, "page_title": "Weekly Sync", "url": null, "matched_candidates": null, "items": null },
+    "next_step": "Page 'Weekly Sync' was not found in the indexed Notion pages. Ask the user to verify the title or wait for the next KB sync.",
+    "missing_fields": null,
+    "assumptions": null
+  }
+  ```
+
+## Output contract
+
+Return **only** one JSON object (no markdown or prose outside it):
+
+```json
 {
   "status": "success" | "partial" | "blocked" | "error",
   "action_summary": string,
   "evidence": {
+    "operation": "create_notion_page" | "update_notion_page" | "delete_notion_page" | null,
     "page_id": string | null,
     "page_title": string | null,
-    "matched_candidates": [
-      { "page_id": string, "page_title": string | null }
-    ] | null
+    "url": string | null,
+    "matched_candidates": [ { "id": string, "label": string } ] | null,
+    "items": object | null
   },
   "next_step": string | null,
   "missing_fields": string[] | null,
   "assumptions": string[] | null
 }
+```
 
 Rules:
-- `status=success` -> `next_step=null`, `missing_fields=null`.
-- `status=partial|blocked|error` -> `next_step` must be non-null.
-- `status=blocked` due to missing required inputs -> `missing_fields` must be non-null.
-- On ambiguity, include candidate options in `evidence.matched_candidates`.
-</output_contract>
+- `status=success` → `next_step=null`, `missing_fields=null`.
+- `status=partial|blocked|error` → `next_step` must be non-null.
+- `status=blocked` due to missing required inputs → `missing_fields` must be non-null.
+
+Infer before you call; map every tool outcome faithfully.

surfsense_backend/app/agents/multi_agent_chat/subagents/connectors/notion/tools/create_page.py

@@ -4,7 +4,9 @@ from typing import Any
 from langchain_core.tools import tool
 from sqlalchemy.ext.asyncio import AsyncSession
 
-from app.agents.new_chat.tools.hitl import request_approval
+from app.agents.multi_agent_chat.subagents.shared.hitl.approvals.self_gated import (
+    request_approval,
+)
 from app.connectors.notion_history import NotionAPIError, NotionHistoryConnector
 from app.services.notion import NotionToolMetadataService
 

surfsense_backend/app/agents/multi_agent_chat/subagents/connectors/notion/tools/delete_page.py

@@ -4,7 +4,9 @@ from typing import Any
 from langchain_core.tools import tool
 from sqlalchemy.ext.asyncio import AsyncSession
 
-from app.agents.new_chat.tools.hitl import request_approval
+from app.agents.multi_agent_chat.subagents.shared.hitl.approvals.self_gated import (
+    request_approval,
+)
 from app.connectors.notion_history import NotionAPIError, NotionHistoryConnector
 from app.services.notion.tool_metadata_service import NotionToolMetadataService
 

surfsense_backend/app/agents/multi_agent_chat/subagents/connectors/notion/tools/index.py

@@ -1,33 +1,36 @@
+"""``notion`` native tools and (empty) permission ruleset.
+
+Tools self-gate via :func:`request_approval` in their bodies.
+"""
+
 from __future__ import annotations
 
 from typing import Any
 
-from app.agents.multi_agent_chat.subagents.shared.permissions import (
-    ToolsPermissions,
-)
+from langchain_core.tools import BaseTool
+
+from app.agents.new_chat.permissions import Ruleset
 
 from .create_page import create_create_notion_page_tool
 from .delete_page import create_delete_notion_page_tool
 from .update_page import create_update_notion_page_tool
 
+NAME = "notion"
+
+RULESET = Ruleset(origin=NAME, rules=[])
+
 
 def load_tools(
     *, dependencies: dict[str, Any] | None = None, **kwargs: Any
-) -> ToolsPermissions:
+) -> list[BaseTool]:
     d = {**(dependencies or {}), **kwargs}
     common = {
         "db_session": d["db_session"],
         "search_space_id": d["search_space_id"],
         "user_id": d["user_id"],
     }
-    create = create_create_notion_page_tool(**common)
-    update = create_update_notion_page_tool(**common)
-    delete = create_delete_notion_page_tool(**common)
-    return {
-        "allow": [],
-        "ask": [
-            {"name": getattr(create, "name", "") or "", "tool": create},
-            {"name": getattr(update, "name", "") or "", "tool": update},
-            {"name": getattr(delete, "name", "") or "", "tool": delete},
-        ],
-    }
+    return [
+        create_create_notion_page_tool(**common),
+        create_update_notion_page_tool(**common),
+        create_delete_notion_page_tool(**common),
+    ]

surfsense_backend/app/agents/multi_agent_chat/subagents/connectors/notion/tools/update_page.py

@@ -4,7 +4,9 @@ from typing import Any
 from langchain_core.tools import tool
 from sqlalchemy.ext.asyncio import AsyncSession
 
-from app.agents.new_chat.tools.hitl import request_approval
+from app.agents.multi_agent_chat.subagents.shared.hitl.approvals.self_gated import (
+    request_approval,
+)
 from app.connectors.notion_history import NotionAPIError, NotionHistoryConnector
 from app.services.notion import NotionToolMetadataService
 

surfsense_backend/app/agents/multi_agent_chat/subagents/connectors/onedrive/agent.py

@@ -1,55 +1,44 @@
-"""`onedrive` route: ``SubAgent`` spec for deepagents."""
+"""``onedrive`` route: ``SurfSenseSubagentSpec`` builder for deepagents.
+
+Tools self-gate inside their bodies via :func:`request_approval`; the
+empty :data:`tools.index.RULESET` is layered into a per-subagent
+:class:`PermissionMiddleware` for uniformity.
+"""
 
 from __future__ import annotations
 
-from collections.abc import Sequence
 from typing import Any
 
-from deepagents import SubAgent
 from langchain_core.language_models import BaseChatModel
+from langchain_core.tools import BaseTool
 
-from app.agents.multi_agent_chat.subagents.shared.md_file_reader import (
-    read_md_file,
-)
-from app.agents.multi_agent_chat.subagents.shared.permissions import (
-    ToolsPermissions,
-    merge_tools_permissions,
-    middleware_gated_interrupt_on,
-)
-from app.agents.multi_agent_chat.subagents.shared.subagent_builder import (
-    pack_subagent,
-)
+from app.agents.multi_agent_chat.subagents.shared.md_file_reader import read_md_file
+from app.agents.multi_agent_chat.subagents.shared.spec import SurfSenseSubagentSpec
+from app.agents.multi_agent_chat.subagents.shared.subagent_builder import pack_subagent
 
-from .tools.index import load_tools
-
-NAME = "onedrive"
+from .tools.index import NAME, RULESET, load_tools
 
 
 def build_subagent(
     *,
     dependencies: dict[str, Any],
     model: BaseChatModel | None = None,
-    extra_middleware: Sequence[Any] | None = None,
-    extra_tools_bucket: ToolsPermissions | None = None,
-) -> SubAgent:
-    buckets = load_tools(dependencies=dependencies)
-    merged_tools_bucket = merge_tools_permissions(buckets, extra_tools_bucket)
-    tools = [
-        row["tool"]
-        for row in (*merged_tools_bucket["allow"], *merged_tools_bucket["ask"])
-        if row.get("tool") is not None
-    ]
-    interrupt_on = middleware_gated_interrupt_on(merged_tools_bucket)
-    description = read_md_file(__package__, "description").strip()
-    if not description:
-        description = "Handles onedrive tasks for this workspace."
+    middleware_stack: dict[str, Any] | None = None,
+    mcp_tools: list[BaseTool] | None = None,
+) -> SurfSenseSubagentSpec:
+    tools = [*load_tools(dependencies=dependencies), *(mcp_tools or [])]
+    description = (
+        read_md_file(__package__, "description").strip()
+        or "Handles onedrive tasks for this workspace."
+    )
     system_prompt = read_md_file(__package__, "system_prompt").strip()
     return pack_subagent(
         name=NAME,
         description=description,
         system_prompt=system_prompt,
         tools=tools,
-        interrupt_on=interrupt_on,
+        ruleset=RULESET,
+        dependencies=dependencies,
         model=model,
-        extra_middleware=extra_middleware,
+        middleware_stack=middleware_stack,
     )

surfsense_backend/app/agents/multi_agent_chat/subagents/connectors/onedrive/description.md

@@ -1 +1,2 @@
-Use for OneDrive file storage tasks: browse folders, read files, and manage OneDrive file content.
+Specialist for files in the user's OneDrive.
+Use proactively when the user wants to create or remove a OneDrive file.

surfsense_backend/app/agents/multi_agent_chat/subagents/connectors/onedrive/system_prompt.md

@@ -1,52 +1,105 @@
-You are the Microsoft OneDrive operations sub-agent.
-You receive delegated instructions from a supervisor agent and return structured results for supervisor synthesis.
+You are a Microsoft OneDrive specialist for the user's connected OneDrive account.
 
-<goal>
-Execute OneDrive file create/delete actions accurately in the connected account.
-</goal>
+## Vocabulary you must use precisely
 
-<available_tools>
-- `create_onedrive_file`
-- `delete_onedrive_file`
-</available_tools>
+- **`create_onedrive_file` always produces a `.docx` Word document** — there is no file-type parameter and no support for Excel, PowerPoint, PDF, or any other format. If the supervisor asks to create a OneDrive spreadsheet, presentation, or any non-Word file, return `status=blocked` with `next_step` explaining the limitation. Pass `name` **without an extension** — the tool appends `.docx` automatically. You may provide the optional `content` as Markdown; the tool converts it to a formatted Word document via pypandoc.
+- **File-name resolution against the KB index** — `delete_onedrive_file` matches `file_name` case-insensitively against the locally-synced OneDrive KB index. Files that exist in OneDrive but have not been indexed yet cannot be resolved by name.
 
-<tool_policy>
-- Use only tools in `<available_tools>`.
-- Ensure file identity/path is explicit before mutate actions.
-- If ambiguous, return `status=blocked` with candidate paths and supervisor next step.
-- Never invent IDs/paths or mutation results.
-</tool_policy>
+## Required inputs
 
-<out_of_scope>
-- Do not perform non-OneDrive tasks.
-</out_of_scope>
+**For every required input below, first try to infer it from the supervisor's task text** — extract topics from natural phrasing (`"about our launch plan"` → `name="Launch Plan"`). Only return `status=blocked` with `missing_fields` when an input is genuinely absent or ambiguous after a thorough read.
 
-<safety>
-- Never claim file mutation success without tool confirmation.
-</safety>
+- `create_onedrive_file` — `name` (a clear topic from the user, **without an extension**; do not invent if absent). You may generate the optional `content` body yourself as Markdown — the tool handles DOCX conversion. If the supervisor asked for a non-Word format, do **not** call this tool; return `status=blocked` per the Vocabulary section.
+- `delete_onedrive_file` — `file_name` (which file to delete — infer from the task). Only set `delete_from_kb=true` when the user explicitly asked to remove the file from the knowledge base; otherwise leave it `false`.
 
-<failure_policy>
-- On tool failure, return `status=error` with concise recovery `next_step`.
-- On ambiguous targets, return `status=blocked` with candidate paths.
-</failure_policy>
+## Outcome mapping
 
-<output_contract>
-Return **only** one JSON object (no markdown/prose):
+| Tool returns          | Your `status` | `next_step`                                                                                                                  |
+|-----------------------|---------------|------------------------------------------------------------------------------------------------------------------------------|
+| `success`             | `success`     | `null`                                                                                                                       |
+| `rejected`            | `blocked`     | `"User declined this OneDrive action. Do not retry or suggest alternatives."`                                                |
+| `not_found`           | `blocked`     | `"File '<name>' was not found in the indexed OneDrive files. Ask the user to verify the file name or wait for the next KB sync."` |
+| `auth_error`          | `error`       | `"The connected OneDrive account needs re-authentication. Ask the user to re-authenticate in connector settings."`           |
+| `error`               | `error`       | Relay the tool's `message` verbatim as `next_step`.                                                                          |
+| tool raises / unknown | `error`       | `"OneDrive tool failed unexpectedly. Ask the user to retry shortly."`                                                        |
+
+Surface the tool's `file_id`, `name`, and `web_url` inside `evidence` when the tool returned them. Never invent a field the tool did not return.
+
+## Examples
+
+**Example 1 — happy create (Markdown content auto-converted to DOCX):**
+- *Supervisor task:* `"Create a OneDrive doc summarising Q3 planning."`
+- *You:* `name="Q3 Planning"` (no extension); generate a Markdown body covering Q3 planning. Call `create_onedrive_file(name="Q3 Planning", content=<markdown>)` → tool returns `status=success` with `name="Q3 Planning.docx"`.
+- *Output:*
+
+  ```json
+  {
+    "status": "success",
+    "action_summary": "Created OneDrive Word document 'Q3 Planning.docx'.",
+    "evidence": { "operation": "create_onedrive_file", "file_id": "<id>", "name": "Q3 Planning.docx", "web_url": "<url>", "matched_candidates": null, "items": null },
+    "next_step": null,
+    "missing_fields": null,
+    "assumptions": ["Generated the Q3 planning content from the supervisor's brief; tool converted Markdown to DOCX."]
+  }
+  ```
+
+**Example 2 — blocked because the requested format is not supported:**
+- *Supervisor task:* `"Create a OneDrive spreadsheet of last quarter's revenue."`
+- *You:* `create_onedrive_file` only produces `.docx` Word documents. Spreadsheets are not supported. Do not call any tool.
+- *Output:*
+
+  ```json
+  {
+    "status": "blocked",
+    "action_summary": "Cannot create a spreadsheet: this subagent only creates OneDrive Word documents (.docx).",
+    "evidence": { "operation": null, "file_id": null, "name": null, "web_url": null, "matched_candidates": null, "items": null },
+    "next_step": "Ask the user whether a Word document summarising the revenue is acceptable, or to create the spreadsheet manually in OneDrive / Excel Online.",
+    "missing_fields": null,
+    "assumptions": null
+  }
+  ```
+
+**Example 3 — delete with `not_found`:**
+- *Supervisor task:* `"Delete the 'Old Project Plan' file from OneDrive."`
+- *You:* extract `file_name="Old Project Plan"`. Call `delete_onedrive_file(file_name="Old Project Plan")` → tool returns `status=not_found`.
+- *Output:*
+
+  ```json
+  {
+    "status": "blocked",
+    "action_summary": "Could not find a OneDrive file named 'Old Project Plan' in the indexed files.",
+    "evidence": { "operation": "delete_onedrive_file", "file_id": null, "name": "Old Project Plan", "web_url": null, "matched_candidates": null, "items": null },
+    "next_step": "File 'Old Project Plan' was not found in the indexed OneDrive files. Ask the user to verify the file name or wait for the next KB sync.",
+    "missing_fields": null,
+    "assumptions": null
+  }
+  ```
+
+## Output contract
+
+Return **only** one JSON object (no markdown or prose outside it):
+
+```json
 {
   "status": "success" | "partial" | "blocked" | "error",
   "action_summary": string,
   "evidence": {
+    "operation": "create_onedrive_file" | "delete_onedrive_file" | null,
     "file_id": string | null,
-    "file_path": string | null,
-    "operation": "create" | "delete" | null,
-    "matched_candidates": string[] | null
+    "name": string | null,
+    "web_url": string | null,
+    "matched_candidates": [ { "id": string, "label": string } ] | null,
+    "items": object | null
   },
   "next_step": string | null,
   "missing_fields": string[] | null,
   "assumptions": string[] | null
 }
+```
+
 Rules:
-- `status=success` -> `next_step=null`, `missing_fields=null`.
-- `status=partial|blocked|error` -> `next_step` must be non-null.
-- `status=blocked` due to missing required inputs -> `missing_fields` must be non-null.
-</output_contract>
+- `status=success` → `next_step=null`, `missing_fields=null`.
+- `status=partial|blocked|error` → `next_step` must be non-null.
+- `status=blocked` due to missing required inputs → `missing_fields` must be non-null.
+
+Infer before you call; map every tool outcome faithfully.

surfsense_backend/app/agents/multi_agent_chat/subagents/connectors/onedrive/tools/create_file.py

@@ -8,7 +8,9 @@ from langchain_core.tools import tool
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy.future import select
 
-from app.agents.new_chat.tools.hitl import request_approval
+from app.agents.multi_agent_chat.subagents.shared.hitl.approvals.self_gated import (
+    request_approval,
+)
 from app.connectors.onedrive.client import OneDriveClient
 from app.db import SearchSourceConnector, SearchSourceConnectorType
 

surfsense_backend/app/agents/multi_agent_chat/subagents/connectors/onedrive/tools/index.py

@@ -1,30 +1,34 @@
+"""``onedrive`` native tools and (empty) permission ruleset.
+
+Tools self-gate via :func:`request_approval` in their bodies.
+"""
+
 from __future__ import annotations
 
 from typing import Any
 
-from app.agents.multi_agent_chat.subagents.shared.permissions import (
-    ToolsPermissions,
-)
+from langchain_core.tools import BaseTool
+
+from app.agents.new_chat.permissions import Ruleset
 
 from .create_file import create_create_onedrive_file_tool
 from .trash_file import create_delete_onedrive_file_tool
 
+NAME = "onedrive"
+
+RULESET = Ruleset(origin=NAME, rules=[])
+
 
 def load_tools(
     *, dependencies: dict[str, Any] | None = None, **kwargs: Any
-) -> ToolsPermissions:
+) -> list[BaseTool]:
     d = {**(dependencies or {}), **kwargs}
     common = {
         "db_session": d["db_session"],
         "search_space_id": d["search_space_id"],
         "user_id": d["user_id"],
     }
-    create = create_create_onedrive_file_tool(**common)
-    delete = create_delete_onedrive_file_tool(**common)
-    return {
-        "allow": [],
-        "ask": [
-            {"name": getattr(create, "name", "") or "", "tool": create},
-            {"name": getattr(delete, "name", "") or "", "tool": delete},
-        ],
-    }
+    return [
+        create_create_onedrive_file_tool(**common),
+        create_delete_onedrive_file_tool(**common),
+    ]

surfsense_backend/app/agents/multi_agent_chat/subagents/connectors/onedrive/tools/trash_file.py

@@ -6,7 +6,9 @@ from sqlalchemy import String, and_, cast, func
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy.future import select
 
-from app.agents.new_chat.tools.hitl import request_approval
+from app.agents.multi_agent_chat.subagents.shared.hitl.approvals.self_gated import (
+    request_approval,
+)
 from app.connectors.onedrive.client import OneDriveClient
 from app.db import (
     Document,