Class ScopedSearchAction

__Scoped_Search — scope-aware universal search for AI agents.

Enforces the calling agent's SearchScopeAccess setting and restricts the requested scope against the agent's MJ: AI Agent Search Scopes rows (Phase IN 'AgentInvoked','Both'). Delegates the actual search to SearchEngine.Search() with ScopeIDs: [resolvedScopeID].

Agent identity is resolved from (in order):

1. The explicit AgentID input parameter (most common — passed by the agent executor).
2. params.Context?.AgentID (when the agent executor stamps context).
3. params.Context?.agentID (lowercased variant used in some execution paths).

Enforcement rules (Section 5 of plans/search-scopes-rag-plus.md):

• SearchScopeAccess='None' → rejects with ACCESS_DENIED.
• SearchScopeAccess='Assigned':
  • If ScopeID supplied: must match one of the agent's active AgentInvoked/Both rows.
  • If omitted: uses the agent's IsDefault=1 row (falling back to lowest Priority).
  • If the agent has no such rows: rejects with NO_DEFAULT_SCOPE.
• SearchScopeAccess='All':
  • If ScopeID supplied: used as-is.
  • If omitted: uses the Global scope.

Multi-tenant SearchContext (per-call): Two optional inputs assemble a SearchContext that is threaded into SearchParams.SearchContext. The engine renders the values into every scope-level Nunjucks template (MetadataFilter, ExtraFilter, UserSearchString, FolderPath) at search time — so one scope definition serves many tenants.

• PrimaryScopeRecordID (string) — primary tenant key (e.g. OrganizationID). Available in templates as {{ context.PrimaryScopeRecordID }}.
• SecondaryScopes (JSON string) — flat object of additional dimensions. Each value must be string | number | boolean | string[]. Available in templates as {{ context.SecondaryScopes.<key> }}. Incompatible value types are dropped with a log; malformed JSON falls back to undefined rather than failing the call.

SearchContext is included only when at least one of the two inputs is provided — omitting both preserves the original "no per-call tenant filter" behavior. See guides/SEARCH_SCOPES_AND_RAG_GUIDE.md §10 for the full multi-tenant model and template-rendering details.