[RESEARCH] Project expert capabilities into direct mode as model-invocable native tools #346

New issue

Closed

opened 2026-09-04 14:36:20 +00:00 by nsaspy · 2 comments

nsaspy commented

2026-09-04 14:36:20 +00:00

Owner

Research record

docs/research/expert-direct-tool-projection.md on branch
research/expert-direct-tool-projection (head 59f2a72), produced under
human-gated ADADR. Research approval pending — no design work authorized
until the record is approved.

Problem

spec-plan-authority.md §8 defines experts only as plan-internal host
closures; direct mode has no expert surface. Downstream direct-mode consumers
need bounded expert capabilities as model-invocable native tools that the
model may invoke but is never obliged to (availability ≠ authority).

Verified evidence (main @ `39b2785`)

Direct-mode native catalog = three closed binding families
(context / runtime incl. typed_plan_execute / registry); an expert must
land in an existing family, not a fourth one.
Registry tool contract is already expert-shaped: capability must be
tool(Name), effect ∈ read|write|process|network_write, closed schema
vocabulary, per-call limits; advertisement filter and invocation-time
authorize_tool enforcement are independent.
Nested charge-back precedents exist on main (charge_runtime_usage/4,
charge_native_model_execution/3, direct_model_step_budget/3), but are
wired only for runtime ops — a tool handler spawning a nested model
session is unbudgeted today.
No expert_contract/expert_registry/plan_capability_required/2/
reasoning_mode_* exists on main. Doc drift: design doc cites
charge_native_model_execution/2, main defines arity 3.

Prior art (web-verified)

OpenAI Agents SDK Agent.as_tool() (per-nested-run max_turns,
needs_approval, usage aggregation, agent_tool_invocation lineage); MCP
sampling (nested model calls under host budget/approval chokepoint; named
failure modes: injection via callback, runaway recursion, attribution loss);
Claude Code (nesting banned→bounded depth 3; budget cap must halt
already-running nested work; tool_use-id lineage); LangChain deepagents
#1698 (silent limit non-propagation counterexample).

Gaps

G1 expert→tool registration adapter · G2 unbudgeted nested model sessions in
tool handlers · G3 model-boundary rule for expert inner loops · G4 lineage to
outer tool call id · G5 capability narrowing at preflight.

Implied direction (not a decision)

Option A shape — adapter over the existing tool registry; every authority
property the design doc requires of experts is already implemented on the
registry path; the gaps each have an in-repo precedent to reuse.

Non-goals

Plan-side expert registry (S5/S10), mode selection (#335), new
providers/transports/effect classes, a second symbolic-mode expert path.

## Research record `docs/research/expert-direct-tool-projection.md` on branch `research/expert-direct-tool-projection` (head 59f2a72), produced under human-gated ADADR. **Research approval pending — no design work authorized until the record is approved.** ## Problem `spec-plan-authority.md` §8 defines experts only as plan-internal host closures; direct mode has no expert surface. Downstream direct-mode consumers need bounded expert capabilities as model-invocable native tools that the model may invoke but is never obliged to (availability ≠ authority). ## Verified evidence (main @ 39b2785) - Direct-mode native catalog = three closed binding families (context / runtime incl. `typed_plan_execute` / registry); an expert must land in an existing family, not a fourth one. - Registry tool contract is already expert-shaped: capability must be `tool(Name)`, effect ∈ `read|write|process|network_write`, closed schema vocabulary, per-call limits; advertisement filter and invocation-time `authorize_tool` enforcement are independent. - Nested charge-back precedents exist on main (`charge_runtime_usage/4`, `charge_native_model_execution/3`, `direct_model_step_budget/3`), but are wired only for runtime ops — a tool handler spawning a nested model session is unbudgeted today. - No `expert_contract`/`expert_registry`/`plan_capability_required/2`/ `reasoning_mode_*` exists on main. Doc drift: design doc cites `charge_native_model_execution/2`, main defines arity 3. ## Prior art (web-verified) OpenAI Agents SDK `Agent.as_tool()` (per-nested-run `max_turns`, `needs_approval`, usage aggregation, `agent_tool_invocation` lineage); MCP sampling (nested model calls under host budget/approval chokepoint; named failure modes: injection via callback, runaway recursion, attribution loss); Claude Code (nesting banned→bounded depth 3; budget cap must halt already-running nested work; tool_use-id lineage); LangChain deepagents #1698 (silent limit non-propagation counterexample). ## Gaps G1 expert→tool registration adapter · G2 unbudgeted nested model sessions in tool handlers · G3 model-boundary rule for expert inner loops · G4 lineage to outer tool call id · G5 capability narrowing at preflight. ## Implied direction (not a decision) Option A shape — adapter over the existing tool registry; every authority property the design doc requires of experts is already implemented on the registry path; the gaps each have an in-repo precedent to reuse. ## Non-goals Plan-side expert registry (S5/S10), mode selection (#335), new providers/transports/effect classes, a second symbolic-mode expert path.

nsaspy commented

2026-09-04 14:37:09 +00:00

Author

Owner

Research APPROVED by operator (2026-09-02). Canonical record: docs/research/expert-direct-tool-projection.org on git.starintel.actor main (approval PR nsaspy/prolog-rlm#296, header #+approval_state: APPROVED). Resolved OQs: OQ2 turn-cost-aware admission, OQ3 keycard rule, OQ5 single-effectual-call, OQ6 first-class availability events; OQ1 delegated to #354; OQ4 decided at design gate. Design slice (docs/expert-tools.md) is now authorized.

Research APPROVED by operator (2026-09-02). Canonical record: `docs/research/expert-direct-tool-projection.org` on git.starintel.actor main (approval PR nsaspy/prolog-rlm#296, header `#+approval_state: APPROVED`). Resolved OQs: OQ2 turn-cost-aware admission, OQ3 keycard rule, OQ5 single-effectual-call, OQ6 first-class availability events; OQ1 delegated to #354; OQ4 decided at design gate. Design slice (`docs/expert-tools.md`) is now authorized.

nsaspy closed this issue

2026-09-08 01:29:04 +00:00

nsaspy commented

2026-09-08 01:45:03 +00:00

Author

Owner

Superseded at the issue/implementation-contract level by the canonical expert-system epics #376 and #377. Preserve docs/research/expert-direct-tool-projection.org as research input, but do not implement this issue's older framing directly: experts are first-class Prolog capabilities, pure/nested expert invocation is free local computation, direct-mode exposure is an adapter onto the same canonical expert registry, and only an expert's explicit LLM fallback incurs provider token/cost usage. #354 remains valid as independent doc-drift cleanup.

Superseded at the issue/implementation-contract level by the canonical expert-system epics #376 and #377. Preserve `docs/research/expert-direct-tool-projection.org` as research input, but do not implement this issue's older framing directly: experts are first-class Prolog capabilities, pure/nested expert invocation is free local computation, direct-mode exposure is an adapter onto the same canonical expert registry, and only an expert's explicit LLM fallback incurs provider token/cost usage. #354 remains valid as independent doc-drift cleanup.