claude-smart 0.2.46 → 0.2.47

package/plugin/vendor/reflexio/reflexio/server/api.py

@@ -6,7 +6,10 @@ import time
 from collections.abc import Callable
 from concurrent.futures import ThreadPoolExecutor
 from datetime import UTC, datetime
-from typing import Any
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from reflexio.server.extensions import AppContext, CapabilityRegistry
 
 from anyio.to_thread import current_default_thread_limiter
 from fastapi import (
@@ -162,12 +165,6 @@ from reflexio.models.config_schema import (
     SINGLETON_AGENT_SUCCESS_EVALUATION_NAME,
     Config,
 )
-from reflexio.server._auth import (
-    DEFAULT_ORG_ID,
-    default_billing_gate,
-    default_get_caller_type,
-    default_get_org_id,
-)
 from reflexio.server.api_endpoints import (
     account_api,
     health_api,
@@ -175,6 +172,12 @@ from reflexio.server.api_endpoints import (
     publisher_api,
     stall_state_api,
 )
+from reflexio.server.auth import (
+    DEFAULT_ORG_ID,
+    default_billing_gate,
+    default_get_caller_type,
+    default_get_org_id,
+)
 from reflexio.server.cache.reflexio_cache import (
     get_reflexio,
     invalidate_reflexio_cache,
@@ -1845,6 +1848,12 @@ def get_all_profiles(
     limit: int = 100,
     status_filter: str | None = None,
     profile_id: str | None = None,
+    user_id: str | None = None,
+    query: str | None = None,
+    source: str | None = None,
+    profile_time_to_live: str | None = None,
+    start_time: int | None = None,
+    end_time: int | None = None,
     include_tombstones: bool = False,
     org_id: str = Depends(default_get_org_id),
 ) -> GetProfilesViewResponse:
@@ -1854,6 +1863,12 @@ def get_all_profiles(
         limit (int, optional): Maximum number of profiles to return. Defaults to 100.
         status_filter (str, optional): Filter by profile status. Can be "current", "pending", or "archived".
         profile_id (str, optional): Exact profile ID to retrieve.
+        user_id (str, optional): Exact user ID to filter by.
+        query (str, optional): Case-insensitive text filter across visible fields.
+        source (str, optional): Exact profile source to filter by.
+        profile_time_to_live (str, optional): Exact TTL value to filter by.
+        start_time (int, optional): Minimum last-modified epoch seconds.
+        end_time (int, optional): Maximum last-modified epoch seconds.
         include_tombstones (bool, optional): Include merged/superseded rows when
             looking up a specific profile_id.
         org_id (str): Organization ID
@@ -1863,7 +1878,7 @@ def get_all_profiles(
     """
     reflexio = get_reflexio(org_id=org_id)
 
-    if profile_id:
+    if profile_id and include_tombstones:
         storage = reflexio.request_context.storage
         if storage is None:
             return GetProfilesViewResponse(
@@ -1890,7 +1905,17 @@ def get_all_profiles(
     elif status_filter == "archived":
         status_filter_list = [Status.ARCHIVED]
 
-    response = reflexio.get_all_profiles(limit=limit, status_filter=status_filter_list)  # type: ignore[reportArgumentType]
+    response = reflexio.get_all_profiles(
+        limit=limit,
+        status_filter=status_filter_list,  # type: ignore[reportArgumentType]
+        user_id=user_id,
+        profile_id=profile_id,
+        query=query,
+        source=source,
+        profile_time_to_live=profile_time_to_live,
+        start_time=start_time,
+        end_time=end_time,
+    )
     return GetProfilesViewResponse(
         success=response.success,
         user_profiles=[to_profile_view(p) for p in response.user_profiles],
@@ -3302,6 +3327,97 @@ def _add_openapi_security(app: FastAPI) -> None:
     app.openapi = custom_openapi  # type: ignore[method-assign]
 
 
+def _resolve_lifespan_org_id(get_org_id: Callable[..., str] | None) -> str:
+    """Resolve the bootstrap org ID for lifespan schedulers without a request context.
+
+    Args:
+        get_org_id (Callable[..., str] | None): Custom org-ID dependency, or None for
+            the default single-tenant mode.
+
+    Returns:
+        str: The resolved org ID string.
+    """
+    from reflexio.server.auth import default_get_org_id
+
+    if get_org_id is None:
+        return default_get_org_id()
+    try:
+        signature = inspect.signature(get_org_id)
+    except (TypeError, ValueError):
+        return default_get_org_id()
+    if signature.parameters:
+        return default_get_org_id()
+    try:
+        return str(get_org_id())
+    except Exception:
+        logger.exception("Failed to resolve lifespan org_id; using default org")
+        return default_get_org_id()
+
+
+def _wire_capabilities(
+    app: FastAPI,
+    capabilities: "CapabilityRegistry | None",
+    mount_data_plane: bool,
+    additional_routers: list[APIRouter] | None = None,
+) -> None:
+    """Wire capability routers, services, and hooks into the app at construction time.
+
+    No-op when ``capabilities`` is None.
+
+    The deployment role passed to each capability's ``routers(role)`` is
+    sourced from ``capabilities.role`` when set (threaded in by the enterprise
+    composition root via ``build_registry(deployment_role())``).  When
+    ``capabilities.role`` is ``None`` the role falls back to the
+    ``mount_data_plane`` derivation (``"all"`` when True, ``"control-plane"``
+    when False), preserving the existing OSS-only behaviour.
+
+    Args:
+        app (FastAPI): The application instance to wire into.
+        capabilities (CapabilityRegistry | None): Capabilities to install, or None.
+        mount_data_plane (bool): Whether the data-plane role is active.
+        additional_routers (list[APIRouter] | None): Routers already mounted via
+            ``additional_routers``; used to detect and reject double-mounts at boot.
+
+    Raises:
+        ValueError: If a capability's router object is also present in
+            ``additional_routers`` — each router must be mounted exactly once.
+    """
+    if capabilities is None:
+        return
+    from reflexio.server.auth import default_billing_gate
+    from reflexio.server.extensions import HookRegistry
+
+    if capabilities.role is not None:
+        role = capabilities.role
+    else:
+        role = "all" if mount_data_plane else "control-plane"
+    if capabilities.configurator_class is not None:
+        from reflexio.server.services.configurator.configurator import (
+            set_configurator_class,
+        )
+
+        set_configurator_class(capabilities.configurator_class)
+    if capabilities.billing_gate is not None:
+        for line in ("application", "learnings_generated"):
+            app.dependency_overrides[default_billing_gate(line)] = (
+                capabilities.billing_gate(line)
+            )
+    # HookRegistry is a stateless facade: its methods configure process-global
+    # tracer/usage-recorder/retrieval-capture singletons; the object needn't be stored.
+    hooks = HookRegistry()
+    additional = additional_routers or []
+    for cap in capabilities.capabilities:
+        cap.install_services()
+        cap.install_hooks(hooks)
+        for r in cap.routers(role):
+            if any(r is a for a in additional):
+                raise ValueError(
+                    f"router for capability {cap.name!r} is mounted both via the "
+                    f"registry and additional_routers; mount it exactly once"
+                )
+            app.include_router(r)
+
+
 def create_app(
     get_org_id: Callable[..., str] | None = None,
     additional_routers: list[APIRouter] | None = None,
@@ -3310,6 +3426,8 @@ def create_app(
     get_caller_type: Callable[..., str] | None = None,
     get_billing_gate: Callable[[str], Callable[..., None]] | None = None,
     mount_data_plane: bool = True,
+    capabilities: "CapabilityRegistry | None" = None,
+    app_context_factory: "Callable[[], AppContext] | None" = None,
 ) -> FastAPI:
     """Factory to create a FastAPI app.
 
@@ -3337,19 +3455,40 @@ def create_app(
             scheduler, while keeping all other scaffolding (middleware, CORS,
             auth overrides, OpenAPI security, health, ``/meta/version``,
             ``additional_routers``).
+        capabilities: Optional registry of enterprise capabilities. When provided,
+            each capability's routers, services, hooks, and lifecycle methods are
+            wired into the app at construction time. Behavior is unchanged when
+            ``None``.
+        app_context_factory: Optional callable returning the AppContext passed to
+            each capability's on_startup. When None, an empty AppContext() is used
+            (local OSS / tests). Enterprise binds this to supply self_host_org_id /
+            activated computed during its own startup.
 
     Returns:
         Configured FastAPI application.
-    """
+
+    Raises:
+        ValueError: If both ``get_billing_gate`` and ``capabilities.billing_gate``
+            are provided — pass billing_gate through exactly one path.
+    """
+    if (
+        get_billing_gate is not None
+        and capabilities is not None
+        and capabilities.billing_gate is not None
+    ):
+        raise ValueError(
+            "pass billing_gate via either get_billing_gate or capabilities, not both"
+        )
     from collections.abc import AsyncIterator
     from contextlib import asynccontextmanager
 
-    from reflexio.server._auth import (
+    from reflexio.server.api_endpoints.request_context import RequestContext
+    from reflexio.server.auth import (
         default_billing_gate,
         default_get_caller_type,
         default_get_org_id,
     )
-    from reflexio.server.api_endpoints.request_context import RequestContext
+    from reflexio.server.extensions import AppContext
     from reflexio.server.llm.model_defaults import validate_llm_availability
     from reflexio.server.services.extraction.resume_scheduler import (
         maybe_start_resume_scheduler,
@@ -3358,25 +3497,11 @@ def create_app(
         maybe_start_lineage_gc,
     )
 
-    def _lifespan_org_id() -> str:
-        if get_org_id is None:
-            return default_get_org_id()
-        try:
-            signature = inspect.signature(get_org_id)
-        except (TypeError, ValueError):
-            return default_get_org_id()
-        if signature.parameters:
-            return default_get_org_id()
-        try:
-            return str(get_org_id())
-        except Exception:
-            logger.exception("Failed to resolve lifespan org_id; using default org")
-            return default_get_org_id()
-
     @asynccontextmanager
     async def lifespan(app: FastAPI) -> AsyncIterator[None]:  # noqa: ARG001
         scheduler = None
         gc_scheduler = None
+        started_caps: list = []
         if mount_data_plane:
             log_publish_hardware_capacity()
             validate_llm_availability()
@@ -3387,17 +3512,36 @@ def create_app(
             # drives a per-org worker with org-scoped claims, so it is not limited
             # to the bootstrap org. The bootstrap org is only used to read config
             # and to seed cross-org discovery.
+            bootstrap_org_id = _resolve_lifespan_org_id(get_org_id)
             scheduler = maybe_start_resume_scheduler(
                 lambda org_id: RequestContext(org_id=org_id),
-                bootstrap_org_id=_lifespan_org_id(),
+                bootstrap_org_id=bootstrap_org_id,
             )
             gc_scheduler = maybe_start_lineage_gc(
                 lambda org_id: RequestContext(org_id=org_id),
-                bootstrap_org_id=_lifespan_org_id(),
+                bootstrap_org_id=bootstrap_org_id,
             )
         try:
+            if capabilities is not None:
+                ctx = (
+                    app_context_factory()
+                    if app_context_factory is not None
+                    else AppContext()
+                )
+                for cap in capabilities.capabilities:
+                    await cap.on_startup(ctx)
+                    started_caps.append(cap)
             yield
         finally:
+            for cap in reversed(started_caps):
+                try:
+                    await cap.on_shutdown()
+                except Exception:
+                    logger.warning(
+                        "capability %r on_shutdown raised; continuing cleanup",
+                        cap,
+                        exc_info=True,
+                    )
             if scheduler is not None:
                 scheduler.stop()
             if gc_scheduler is not None:
@@ -3507,6 +3651,9 @@ def create_app(
     for router in additional_routers or []:
         app.include_router(router)
 
+    # Wire capability routers, services, and hooks (composition-root only)
+    _wire_capabilities(app, capabilities, mount_data_plane, additional_routers)
+
     # Health/observability endpoint (per-worker metrics for recycling)
     health_api.install(app)
 

package/plugin/vendor/reflexio/reflexio/server/api_endpoints/request_context.py

@@ -1,6 +1,6 @@
 from fastapi import Depends
 
-from reflexio.server._auth import default_get_org_id
+from reflexio.server.auth import default_get_org_id
 from reflexio.server.prompt.prompt_manager import PromptManager
 from reflexio.server.services.configurator.base_configurator import BaseConfigurator
 from reflexio.server.services.configurator.configurator import get_configurator_class

package/plugin/vendor/reflexio/reflexio/server/{_auth.py → auth.py}

@@ -5,6 +5,8 @@ Lives in its own module to avoid an import cycle: api endpoints reference
 :func:`default_get_org_id` (e.g. via FastAPI ``Depends``) and are themselves
 imported by :mod:`reflexio.server.api`. Putting the dependency here keeps the
 import graph acyclic.
+
+Public module path: :mod:`reflexio.server.auth`.
 """
 
 from __future__ import annotations

package/plugin/vendor/reflexio/reflexio/server/extensions.py

@@ -0,0 +1,213 @@
+"""OSS extension primitives: the process-global capability/service registry.
+
+OSS defines these seams; enterprise registers implementations at its composition
+root. OSS never imports reflexio_ext. The service registry is process-global (a
+module dict), mirroring set_configurator_class/get_configurator_class, so it is
+reachable from every RequestContext construction site — HTTP, library
+(lib/_base.py), and background workers — not just app-scoped ones.
+"""
+
+from __future__ import annotations
+
+from abc import ABC
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import ClassVar
+
+from fastapi import APIRouter
+
+from reflexio.server.services.unified_search_service import (
+    RetrievalCaptureHook,
+    configure_retrieval_capture_hook,
+)
+from reflexio.server.tracing import Tracer, configure_tracer
+from reflexio.server.usage_metrics import (
+    UsageEventRecorder,
+    configure_usage_event_recorder,
+)
+
+
+class ServiceKey[T]:
+    """Typed handle into the runtime-service registry.
+
+    Args:
+        name (str): Stable identifier, used in error messages and as the dict key.
+    """
+
+    def __init__(self, name: str) -> None:
+        self.name = name
+
+    def __repr__(self) -> str:
+        return f"ServiceKey({self.name!r})"
+
+
+_services: dict[str, object] = {}
+
+
+def register_service[T](
+    key: ServiceKey[T], value: T, *, override: bool = False
+) -> None:
+    """Register a runtime-service provider under ``key`` (composition root only).
+
+    Args:
+        key (ServiceKey[T]): The typed key.
+        value (T): The provider/value.
+        override (bool): Allow replacing an existing registration. Default False.
+
+    Raises:
+        RuntimeError: If ``key`` is already registered and ``override`` is False.
+    """
+    if not override and key.name in _services:
+        raise RuntimeError(f"service already registered for key {key.name!r}")
+    _services[key.name] = value
+
+
+def get_service[T](key: ServiceKey[T]) -> T | None:
+    """Return the provider for ``key``, or None if unset (optional providers)."""
+    return _services.get(key.name)  # type: ignore[return-value]
+
+
+def require_service[T](key: ServiceKey[T]) -> T:
+    """Return the provider for ``key``, raising if unset (required providers).
+
+    Args:
+        key (ServiceKey[T]): The typed key whose provider to retrieve.
+
+    Returns:
+        T: The registered provider value.
+
+    Raises:
+        LookupError: If no provider is registered for ``key``.
+    """
+    if key.name not in _services:
+        raise LookupError(f"required service not registered for key {key.name!r}")
+    return _services[key.name]  # type: ignore[return-value]
+
+
+def reset_services() -> None:
+    """Clear all registered services. Test-only."""
+    _services.clear()
+
+
+# ---------------------------------------------------------------------------
+# Hook registry, app context, and capability lifecycle primitives
+# ---------------------------------------------------------------------------
+
+
+class HookRegistry:
+    """Facade over OSS process-global hook setters; capabilities install through it."""
+
+    def set_tracer(self, tracer: Tracer | None) -> None:
+        """Install (or clear) the process-global request tracer.
+
+        Args:
+            tracer (Tracer | None): Tracer implementation, or None to disable.
+        """
+        configure_tracer(tracer)
+
+    def set_usage_recorder(self, recorder: UsageEventRecorder | None) -> None:
+        """Install (or clear) the process-global usage-event recorder.
+
+        Args:
+            recorder (UsageEventRecorder | None): Recorder callable, or None to disable.
+        """
+        configure_usage_event_recorder(recorder)
+
+    def set_retrieval_capture(self, hook: RetrievalCaptureHook | None) -> None:
+        """Install (or clear) the process-global retrieval-capture hook.
+
+        Args:
+            hook (RetrievalCaptureHook | None): Hook callable, or None to disable.
+        """
+        configure_retrieval_capture_hook(hook)
+
+
+@dataclass(frozen=True)
+class AppContext:
+    """Inter-step startup data passed to Capability.on_startup.
+
+    Mirrors the values that thread through reflexio_ext lifespan locals
+    (prepare_enterprise_startup output).
+
+    Attributes:
+        self_host_org_id (str | None): Org ID for self-hosted deployments, or None for platform.
+        activated (bool): Whether the enterprise activation check passed.
+    """
+
+    self_host_org_id: str | None = None
+    activated: bool = False
+
+
+class Capability(ABC):
+    """An enterprise feature plugged into the app at its composition root.
+
+    All methods are no-op defaults so the registry can drive every capability
+    through the same phases without hasattr checks. The provider owns this
+    lifecycle shape (ABC); runtime-feature *contracts* are Protocols defined by OSS.
+    """
+
+    name: ClassVar[str]
+
+    def install_services(self) -> None:  # noqa: B027
+        """Register runtime-service providers (process-global). Default: none."""
+
+    def install_hooks(self, hooks: HookRegistry) -> None:  # noqa: B027
+        """Install pipeline hooks (tracer/usage-recorder/retrieval-capture). Default: none.
+
+        Args:
+            hooks (HookRegistry): Registry to install hooks through.
+        """
+
+    def routers(self, role: str) -> list[APIRouter]:  # noqa: ARG002
+        """Return routers to mount for this deployment role. Default: none.
+
+        Args:
+            role (str): Deployment role (e.g. "all", "data-plane").
+
+        Returns:
+            list[APIRouter]: Routers to mount; empty list by default.
+        """
+        return []
+
+    async def on_startup(self, ctx: AppContext) -> None:  # noqa: B027
+        """Start daemons/schedulers. Raising aborts boot (fail-loud). Default: none.
+
+        Args:
+            ctx (AppContext): Startup context produced by prepare_enterprise_startup.
+        """
+
+    async def on_shutdown(self) -> None:  # noqa: B027
+        """Stop what on_startup started. Default: none."""
+
+
+class CapabilityRegistry:
+    """Holds additive capabilities plus the two singular construction-time concerns.
+
+    Args:
+        capabilities (list[Capability]): Capability instances; names must be unique.
+        configurator_class (type | None): Single configurator class, or None.
+        billing_gate (Callable | None): Billing gate factory, or None.
+        role (str | None): Deployment role to thread into ``_wire_capabilities``
+            (e.g. ``"all"``, ``"data-plane"``). When ``None``, ``create_app``
+            derives the role from ``mount_data_plane``.
+
+    Raises:
+        RuntimeError: If two capabilities share the same name.
+    """
+
+    def __init__(
+        self,
+        capabilities: list[Capability],
+        *,
+        configurator_class: type | None = None,
+        billing_gate: Callable[[str], Callable[..., None]] | None = None,
+        role: str | None = None,
+    ) -> None:
+        names = [c.name for c in capabilities]
+        dupes = {n for n in names if names.count(n) > 1}
+        if dupes:
+            raise RuntimeError(f"duplicate capability names: {sorted(dupes)}")
+        self.capabilities = capabilities
+        self.configurator_class = configurator_class
+        self.billing_gate = billing_gate
+        self.role = role

package/plugin/vendor/reflexio/reflexio/server/llm/model_defaults.py

@@ -195,12 +195,12 @@ _PROVIDER_DEFAULTS: dict[str, ProviderDefaults] = {
         extraction_agent="gpt-5.5",
     ),
     "anthropic": ProviderDefaults(
-        generation="claude-sonnet-4-6",
-        evaluation="claude-sonnet-4-6",
+        generation="claude-sonnet-5",
+        evaluation="claude-sonnet-5",
         should_run="claude-haiku-4-5-20251001",
         pre_retrieval="claude-haiku-4-5-20251001",
         embedding=None,
-        extraction_agent="claude-sonnet-4-6",
+        extraction_agent="claude-sonnet-5",
     ),
     "gemini": ProviderDefaults(
         generation="gemini/gemini-3-flash-preview",
@@ -229,7 +229,7 @@ _PROVIDER_DEFAULTS: dict[str, ProviderDefaults] = {
         should_run="minimax/MiniMax-M3",
         pre_retrieval="minimax/MiniMax-M3",
         embedding=None,
-        # Same M2.7 model handles resumable extraction. Surfaced by an
+        # Same M3 model handles resumable extraction. Surfaced by an
         # e2e run on a MiniMax-only VPS where publish printed
         # "No provider in ['minimax'] supports role=extraction_agent"
         # warnings and silently skipped profile creation. Without this,

package/plugin/vendor/reflexio/reflexio/server/llm/providers/claude_code_provider.py

@@ -69,7 +69,7 @@ _CODEX_COMPAT_SCRIPT_NAMES = (
 )
 _CODEX_COMPAT_SCRIPT_NAME_SET = set(_CODEX_COMPAT_SCRIPT_NAMES)
 _DEFAULT_TIMEOUT_SECONDS = 120
-_DEFAULT_CLI_MODEL = "claude-sonnet-4-6"
+_DEFAULT_CLI_MODEL = "claude-sonnet-5"
 
 _TRUTHY_ENV_VALUES = {"1", "true", "yes"}
 _UNSUPPORTED_PARAMS_WARNED: set[str] = set()

package/plugin/vendor/reflexio/reflexio/server/llm/rerank/cross_encoder_reranker.py

@@ -150,7 +150,18 @@ def score_pairs(query: str, docs: list[str]) -> list[float]:
         return []
     model = _get_model()
     pairs = [(query, doc) for doc in docs]
-    raw_scores = model.predict(pairs, show_progress_bar=False)
+    try:
+        from torch import nn
+    except ImportError as e:
+        raise CrossEncoderUnavailableError(
+            "torch is not installed; cannot use the cross-encoder reranker"
+        ) from e
+
+    raw_scores = model.predict(
+        pairs,
+        show_progress_bar=False,
+        activation_fn=nn.Identity(),
+    )
     # ``predict`` returns a numpy array; convert to plain Python floats so
     # the caller can serialise the result without numpy as a dependency.
     return [float(s) for s in raw_scores]

package/plugin/vendor/reflexio/reflexio/server/prompt/prompt_bank/playbook_extraction_context/v4.4.0.prompt.md

@@ -1,7 +1,7 @@
 ---
 active: true
 description: "Context setting prompt for resumable playbook extraction. Every claim must be grounded in the conversation and generalized to a reusable task context; both requirements apply jointly to Correction SOPs and Success Path Recipes."
-changelog: "v4.4.0: deliver the result as a native structured response — output the {{\"playbooks\": [...]}} JSON directly as the final assistant message instead of a finish_extraction tool call; ask_human/attach_pending_info_request remain real intermediate tools, and a plain (no-tool) final turn carrying the JSON is now the valid completion. No output schema change. v4.3.0: expands Correction SOP signals to include avoidable follow-ups, partial delivery, stalled conditional authorization, unverified claims, and incomplete coverage; requires Correction SOPs whenever correction signals are present; adds antecedent-not-reaction trigger guidance. (in-place 2026-06-18: make triggers future-user-query-like retrieval keys.) (in-place 2026-06-15: adds concise retrieve-general/action-specific guidance.) v4.2.3: strengthens strict tool-call discipline so plain-text/no-tool responses are explicitly invalid, including empty extraction outcomes. v4.2.2: replaces output examples with compact tool-call and JSON-shape guidance, while preserving the resumable extraction contract. v4.2.1: negative/avoid guidance cannot contradict the final verified implementation or final evaluation. v4.2.0: adds emergent skill-convention guidance for structuring multi-aspect playbook content as a small set of grouped do/avoid rules (no schema change). v4.1.7: adds resumable extraction guidance, names legacy fallback and malformed-input branches in boundary-change recipes, and avoids a polarity output field. (in-place 2026-05-30: tool-oriented finish_extraction output framing; deprecated and removed blocking_issue.) (in-place 2026-05-30: clarify in the Output Format section that finish_extraction may be preceded by ask_human/attach_pending_info_request; restructure examples into one no-tool example plus a worked ask_human and attach_pending_info_request example; stress that ask_human is rare and reserved for critical missing org-level facts — finish_extraction alone is the norm.) (in-place 2026-05-30: condense the resumable guidance — state finish-required/optional once, replace the duplicated Output Format block with a one-line pointer, and trim example prose.) (in-place 2026-06-03: consolidate and shorten the ask_human condition: ask only for missing shared context needed to know what to do, while still finishing extraction.) (in-place 2026-06-03: frame finish_extraction as the final completion tool and pending-info tools as intermediate.) (in-place 2026-06-03: clarify that empty finish_extraction alone must not replace ask_human when the ask_human condition applies.) (in-place 2026-06-04: clarify ask_human and attach_pending_info_request are alternatives for the same gap, not a sequence.)"
+changelog: "v4.4.0: deliver the result as a native structured response — output the {{\"playbooks\": [...]}} JSON directly as the final assistant message instead of a finish_extraction tool call; ask_human/attach_pending_info_request remain real intermediate tools, and a plain (no-tool) final turn carrying the JSON is now the valid completion. No output schema change. (in-place 2026-06-28: strengthen the ask_human decision boundary for cases where a correction proves a durable shared procedure exists but only avoidance is grounded.) v4.3.0: expands Correction SOP signals to include avoidable follow-ups, partial delivery, stalled conditional authorization, unverified claims, and incomplete coverage; requires Correction SOPs whenever correction signals are present; adds antecedent-not-reaction trigger guidance. (in-place 2026-06-18: make triggers future-user-query-like retrieval keys.) (in-place 2026-06-15: adds concise retrieve-general/action-specific guidance.) v4.2.3: strengthens strict tool-call discipline so plain-text/no-tool responses are explicitly invalid, including empty extraction outcomes. v4.2.2: replaces output examples with compact tool-call and JSON-shape guidance, while preserving the resumable extraction contract. v4.2.1: negative/avoid guidance cannot contradict the final verified implementation or final evaluation. v4.2.0: adds emergent skill-convention guidance for structuring multi-aspect playbook content as a small set of grouped do/avoid rules (no schema change). v4.1.7: adds resumable extraction guidance, names legacy fallback and malformed-input branches in boundary-change recipes, and avoids a polarity output field. (in-place 2026-05-30: tool-oriented finish_extraction output framing; deprecated and removed blocking_issue.) (in-place 2026-05-30: clarify in the Output Format section that finish_extraction may be preceded by ask_human/attach_pending_info_request; restructure examples into one no-tool example plus a worked ask_human and attach_pending_info_request example; stress that ask_human is rare and reserved for critical missing org-level facts — finish_extraction alone is the norm.) (in-place 2026-05-30: condense the resumable guidance — state finish-required/optional once, replace the duplicated Output Format block with a one-line pointer, and trim example prose.) (in-place 2026-06-03: consolidate and shorten the ask_human condition: ask only for missing shared context needed to know what to do, while still finishing extraction.) (in-place 2026-06-03: frame finish_extraction as the final completion tool and pending-info tools as intermediate.) (in-place 2026-06-03: clarify that empty finish_extraction alone must not replace ask_human when the ask_human condition applies.) (in-place 2026-06-04: clarify ask_human and attach_pending_info_request are alternatives for the same gap, not a sequence.)"
 variables:
   - agent_context_prompt
   - extraction_definition_prompt
@@ -26,6 +26,16 @@ Choose exactly one intermediate path per missing fact: use `attach_pending_info_
 
 Do not ask for user-scoped/private facts, context derivable from the trajectory, agent context, tool list, or Prior Knowledge, complete avoidance-only rules, or merely nice-to-have details.
 
+### Ask-human decision boundary
+
+Before finalizing any Correction SOP from a negative correction, run this check:
+
+1. Did the correction merely establish a complete avoidance rule, with no evidence that a shared positive procedure exists? If yes, emit the grounded avoidance rule and do not ask.
+2. Did the correction state or strongly imply that a shared policy, process, approval path, escalation route, canonical target, standard wording, or other durable positive procedure exists, while leaving the actual target/procedure unknown? If yes, the future playbook is incomplete: call `ask_human` (or `attach_pending_info_request` if Prior Knowledge already has the same pending question).
+3. Did the missing detail concern a single user, customer, client, assignment, record, or current factual lookup rather than a reusable agent/org rule? If yes, do not ask; emit only grounded guidance or no playbook.
+
+Phrases like "specific process", "required workflow", "approval path", "special route", "canonical path/target", "standard policy", "standard wording/script", or "do not know the exact name/text" are strong evidence of a shared positive procedure gap when the conversation does not provide the missing procedure. Avoidance-only playbooks are acceptable interim guidance, but they are not a substitute for `ask_human` when the conversation proves that future agents need a missing shared positive action to handle the class of task correctly. The question should ask for the smallest durable missing fact, such as the approved route, required procedure, canonical target, policy threshold, or standard wording.
+
 If an intermediate tool is needed, call exactly one of the two intermediate tools before delivering your final result. Then finalize the current run with any independently valid playbooks now, including avoidance rules; if none are valid without the answer, finalize with `{{"playbooks": []}}`.
 
 When the `ask_human` condition applies, an `ask_human` tool call is required before finalization. Do not replace the question with an empty `{{"playbooks": []}}` final response alone.
@@ -161,6 +171,8 @@ Grounding constrains the *source* of a claim (it must come from the conversation
 
 **When the agent doesn't know what to do:** Describe what to AVOID (the observed mistake) and state the limitation honestly. It is much better to say "do not fabricate order status — admit you cannot look it up" than to invent a specific alternative the agent may not actually have. If the missing "what to do" detail satisfies the `ask_human` condition above, use the tool; otherwise emit only the grounded avoidance rule or no playbook.
 
+If a user correction says there is a specific process, approval path, route, standard, or policy but does not provide it, the extractor does not know enough to produce the durable positive SOP. Do not silently downgrade that case to avoidance-only unless avoidance is the complete reusable lesson; ask for the missing shared procedure and still finalize any grounded interim playbooks.
+
 **Rule of thumb (both checks must pass):**
 1. *Grounded* — if you remove the conversation and only read the `content`, could someone verify every claim by re-reading the conversation? If not, you've hallucinated.
 2. *Generalized* — could a future agent in a similar task context, with no access to this conversation, apply the entry as written? If not, you've overfit — restate the pattern at the level of situation, artifact role, action sequence, verification, and detour.
@@ -175,7 +187,7 @@ For **Correction SOPs**:
 3. Identify the violated implicit expectation
 4. Draft the `trigger` (the problem or situation)
 5. Tautology Check (see above)
-6. Draft `content`: reason through what the agent did wrong and what the user's feedback tells us the agent should do differently. Ground every statement in evidence from the conversation. If the user told the agent what to do, capture that. If the user only told the agent what NOT to do, capture the avoidance. Do not guess what the right action is if the conversation doesn't tell you; use `ask_human` only when the condition above applies.
+6. Draft `content`: reason through what the agent did wrong and what the user's feedback tells us the agent should do differently. Ground every statement in evidence from the conversation. If the user told the agent what to do, capture that. If the user only told the agent what NOT to do, capture the avoidance. If the user indicated that a shared process/policy/route/approval/standard/canonical target exists but did not provide it, call `ask_human` or attach to matching Prior Knowledge before finalizing; the avoidance rule alone does not answer what a future agent should do. Do not guess what the right action is if the conversation doesn't tell you; use `ask_human` only when the condition above applies.
 
 For **Success Path Recipes**:
 1. Identify whether the agent completed the task successfully