nsaspy/prolog-rlm
1
0
Fork 0
Code Issues 83 Pull requests 10 Projects Releases Packages Wiki Activity Actions

[RESEARCH] Experts as native direct-mode tools (verified analysis) #334

Open
nsaspy wants to merge 0 commits from research/expert-direct-tool-projection into main
pull from: research/expert-direct-tool-projection
merge into: nsaspy:main
Conversation 0 Commits - Files changed -
nsaspy commented 2026-09-02 21:24:51 +00:00
Owner
Copy link

Research record

docs/research/expert-direct-tool-projection.md — ADADR research slice (human-gated). Research approval pending; no design or implementation work is authorized by this PR. Tracking issue: lost-rob0t/prolog-rlm#353.

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 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.
  • 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_* 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; 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.

Verification

  • prolog-verify check passed (workspace evidence recorded in .prolog/)
  • swipl -q -s test/check_runtime.pl green (SWI 10.0.2)
  • git diff --check clean
## Research record `docs/research/expert-direct-tool-projection.md` — ADADR research slice (human-gated). **Research approval pending; no design or implementation work is authorized by this PR.** Tracking issue: lost-rob0t/prolog-rlm#353. ## 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 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. - 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_*` 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; 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. ## Verification - `prolog-verify check` passed (workspace evidence recorded in `.prolog/`) - `swipl -q -s test/check_runtime.pl` green (SWI 10.0.2) - `git diff --check` clean
research: experts as native direct-mode tools (verified analysis)
Some checks failed
CI / Deterministic unit and load checks (pull_request) Has been cancelled
Details
CI / REAL OpenRouter integration (pull_request) Has been cancelled
Details
Nix flake / Flake package and clean runtime load (pull_request) Has been cancelled
Details
Clean SWI pack install / Install and load copied pack (pull_request) Has been cancelled
Details
Paid OpenRouter / Pinned paid OpenRouter integration (pull_request) Has been cancelled
Details
Tree-sitter FFI / Direct SWI-Prolog Tree-sitter FFI (pull_request) Has been cancelled
Details
59f2a72f0d 
Verified code facts (direct-mode native catalog families, registry tool
contract, effect isolation, nested charge-back precedents), web-verified
prior art (OpenAI Agent.as_tool, MCP sampling, Claude Code bounded nesting,
LangChain deepagents limit-propagation counterexample), gap analysis G1-G5,
and options for projecting expert capabilities into direct mode as
model-invocable native tools without new authority surfaces.

Research approval gate pending; design work not authorized by this commit.
research: convert record to canonical org template (RLM-RESEARCH-353)
Some checks failed
CI / Deterministic unit and load checks (pull_request) Has been cancelled
Details
CI / REAL OpenRouter integration (pull_request) Has been cancelled
Details
Nix flake / Flake package and clean runtime load (pull_request) Has been cancelled
Details
Clean SWI pack install / Install and load copied pack (pull_request) Has been cancelled
Details
Paid OpenRouter / Pinned paid OpenRouter integration (pull_request) Has been cancelled
Details
Tree-sitter FFI / Direct SWI-Prolog Tree-sitter FFI (pull_request) Has been cancelled
Details
5a6e89c4c0 
Rejected review feedback: research records use the canonical
docs/research-record-template.org format with the
prolog-rlm.research-approval.v1 header block, not prose markdown.

approval_base_commit pins main @ 39b278589d; approval_base_blob pins this
record's content blob. Approval state remains PENDING/NONE - approval
signals live only in the header block.
research: answer operator note on effect batching (open question 5)
Some checks failed
CI / Deterministic unit and load checks (pull_request) Has been cancelled
Details
CI / REAL OpenRouter integration (pull_request) Has been cancelled
Details
Nix flake / Flake package and clean runtime load (pull_request) Has been cancelled
Details
Clean SWI pack install / Install and load copied pack (pull_request) Has been cancelled
Details
Paid OpenRouter / Pinned paid OpenRouter integration (pull_request) Has been cancelled
Details
Tree-sitter FFI / Direct SWI-Prolog Tree-sitter FFI (pull_request) Failing after 40s
Details
ca29ec1c26 
Preserve the operator note and record the evidence-based response: effects
are supported on the tool path; effectful_batch_unsupported forbids only
multi-call batches containing an effectful sibling, because sequential
non-atomic execution plus run-abort failure semantics cannot offer safe
retry for a set of admitted effect intents. Design-phase relaxation is a
live option with explicit new invariants.
Some checks failed
CI / Deterministic unit and load checks (pull_request) Has been cancelled
Details
CI / REAL OpenRouter integration (pull_request) Has been cancelled
Details
Nix flake / Flake package and clean runtime load (pull_request) Has been cancelled
Details
Clean SWI pack install / Install and load copied pack (pull_request) Has been cancelled
Details
Paid OpenRouter / Pinned paid OpenRouter integration (pull_request) Has been cancelled
Details
Tree-sitter FFI / Direct SWI-Prolog Tree-sitter FFI (pull_request) Failing after 40s
Details
This pull request is broken due to missing fork information.
View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u origin research/expert-direct-tool-projection:research/expert-direct-tool-projection
git switch research/expert-direct-tool-projection

Merge

Merge the changes and update on Forgejo.

Warning: The "Autodetect manual merge" setting is not enabled for this repository, you will have to mark this pull request as manually merged afterwards.

git switch main
git merge --no-ff research/expert-direct-tool-projection
git switch research/expert-direct-tool-projection
git rebase main
git switch main
git merge --ff-only research/expert-direct-tool-projection
git switch research/expert-direct-tool-projection
git rebase main
git switch main
git merge --no-ff research/expert-direct-tool-projection
git switch main
git merge --squash research/expert-direct-tool-projection
git switch main
git merge --ff-only research/expert-direct-tool-projection
git switch main
git merge research/expert-direct-tool-projection
git push origin main
Sign in to join this conversation.
Reviewers
No reviewers
Labels
Clear labels   
bug
Something isn't working

  
documentation
Improvements or additions to documentation

  
duplicate
This issue or pull request already exists

  
enhancement
New feature or request

  
good first issue
Good for newcomers

  
help wanted
Extra attention is needed

  
invalid
This doesn't seem right

  
question
Further information is requested

  
wontfix
This will not be worked on

No labels
bug
documentation
duplicate
enhancement
good first issue
help wanted
invalid
question
wontfix
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
nsaspy/prolog-rlm!334
No description provided.