odysseus/docs/runtime-decomposition/wave-2-request-authority.md

Wave 2: request authority

Base: d6c3c98c75e03f70c05ebe4058c6fa12e0395f62, branch feature/runtime-request-authority. Discovery and this plan precede production changes. No later runtime waves are included.

Discovered call paths

routes/chat_routes.py parses mode, toggles, workspace, approval decisions and runtime context. User intent can promote Chat to Agent. Owner privileges, global disabled tools, compare/incognito and plan restrictions produce ToolPolicy. Compact/native routes resolve TurnContract; regular/full models can receive the full enabled schema inventory. The route calls _stream_agent_with_execution_bridge and stream_agent_loop. Detached runs retain this generator; reconnecting subscribes to it rather than creating a new invocation. Their stream IDs are distinct from journal IDs.

src/turn_contract.py classifies request families and selected tools, resolves exact safe reads, and filters schema availability. Empty-family routing has a legacy core inventory. Warm tools and editor availability may enlarge offers. Transcription, OCR and tasks have narrow selection; static web retrieval may offer private_browser for fallback. These routing choices are not grants.

src/agent_loop.py selects provider/profile transports, parses native or textual tool blocks, repairs calls, performs deterministic preflights and retries, and calls src/tool_execution.py:execute_tool_block. Compact preview uses src/clean_agent_preview.py but reaches the same dispatcher. The dispatcher checks run security, exact approval, contract membership, disabled tools, ToolPolicy, owner restrictions and bridges before MCP/dynamic/built-in handlers. It forwards policy to dynamic handlers. Legacy loop reconciliation removes disabled names found in a contract's offered inventory. This must not erase a request-authority denial.

Approvals use src/tool_approvals.py. A server record binds tool/content, owner, session, workspace, document id/version/digest, origin run and continuation state. Consume is destructive; claim is one-use. Task/chat scopes bypass an existing run-security gate; they do not define the requested operation classes. Approval continuation executes the sealed action in round zero. Denial exits the route without execution.

Generic app_api forwards both the internal token and the caller's owner to loopback HTTP. Its blocklist does not exclude Chat/skill approval ingress. Matching owner/session/input bindings alone therefore cannot distinguish a model-produced HTTP decision from a user approval. Those existing ingress points need an explicit internal-tool rejection before consuming approval. Internal HTTP skill-test task bodies likewise cannot mint fresh authority. The same origin rule applies to generic Chat HTTP entry: a loopback generated message is not a new trusted user request, even with correct owner attribution. Both Chat entry points use the existing non-persistence switch for these messages and append explicitly untrusted transient context instead. Later referential turns cannot inherit their operation class as prior user intent.

Teacher takeover is queued by the student, then owned by the outer adapter in src/teacher_escalation.py. It invokes a child loop after the student gate closes and forwards policy, contract, workspace and runtime context. The teacher's synthetic user message is model context, not a new authority source.

src/task_scheduler.py:_execute_assistant composes crew/global restrictions and RAG/default shell availability. _run_agent_loop supplies task.prompt or a synthetic override as a user message, with background provider fallback. Exact approval pauses are retired because there is no interactive approver. _execute_action invokes BUILTIN_ACTIONS directly, with a separate admin gate. src/tools/system.py:do_manage_tasks and routes/task/task_routes.py create/edit persisted tasks. No authority snapshot currently survives scheduling.

Detached Bash dispatch launches bg_jobs.launch and returns bg_job_id. src/bg_monitor.py:_run_followup appends an explicitly untrusted result to session context and re-enters the loop. It currently forwards neither the originating authority nor its request restrictions. Skill tests/audits in routes/skills_routes.py also invoke the loop with task/user messages; generated audit context must not manufacture grants.

Question	Current source
Requested operation	User intent classifiers, exact safe-read resolver; ultimately parsed/repaired model tool block
Available capabilities	Registry/MCP inventory, profiles, RAG, TurnContract and request-specific schema filters
Authorized capabilities	Fragmented policy, privileges, run security and approval checks; no independent envelope
Restrictions	Route toggles, owner/global policy, plan/compare/incognito, dispatcher owner/workspace checks
Approval required	Deterministic run-security decision; model output can propose the action but cannot consume approval
Approval input scope	Server-sealed exact tool/content and owner/session/workspace/document binding
Nested state	Explicit policy/contract/workspace/context forwarding and journal lineage; no authority snapshot
Model influence	Tool/input proposals, repairs, recovery choices, generated task/audit prompts; availability currently participates in execution gating

Implementation plan and contract

1. Add immutable ExactOperation, OperationGrant and RequestAuthority in src/agent_runtime/authority.py. Normalize canonical tool identity and JSON inputs (reject duplicate keys/non-finite values); retain exact raw text for Bash/Python, built-in scheduled actions and non-JSON inputs. Grants contain an operation class/tool identity, optional action limits and exact input limits. Authority has its own request id, owner/session/workspace binding, immutable grants and hard denials. It is independent of schema presence, model/profile, stream/journal/receipt IDs.
2. Create authority from trusted request text/history and deterministic policy at the chat route before availability reconciliation. The general loop boundary creates it for other trusted direct callers, without consulting schemas, relevant_tools, forced_tools or model output. Authority family inheritance reads only trusted user history. Tool-history exact reads may narrow an already admitted class, never create a class. Unknown intent grants no execution floor. Neutral interaction/planning controls remain explicit.
3. Keep semantic classification and availability in TurnContract. Resolve authority grants separately from those semantic facts and hard policy. Exact safe reads restrict action/identifiers. Static web fallback authorizes browser reading/navigation, not arbitrary click/evaluate/form operations. Media/task families do not inherit the shell inventory.
4. Bind authority around the whole logical stream, including teacher takeover; forward it explicitly to teacher children and approval records. Children inherit the parent or intersect explicit authority with it. Policy denials union; grants intersect; a child cannot replace the parent scope. Restore the parent on close/error/cancellation. Capture restrictions before legacy offered-tool reconciliation can erase them.
5. Enforce at execute_tool_block, before approvals are claimed or handlers, bridges/MCP/process dispatch begin. Current policy/disabled gates still win. Missing/malformed dispatcher state fails closed. Standalone callers/tests must supply explicit server authority. Journal ownership remains unchanged; denied calls produce no authoritative execution receipt.
6. Existing approvals remain one-use exact claims. Seal the originating authority in the approval digest. Resumption keeps original class limits and current hard restrictions. The approved exact operation may cross its original class boundary only through the consumed, matching server record at that call; it does not mutate authority for subsequent calls. Nested execution cannot use an approval to exceed its parent ceiling. Existing task/chat UI and run-security scope semantics are unchanged. Chat/skill approval ingress rejects validated internal-tool requests before consumption; identity impersonation is not a user approval decision. A shared HTTP factory admits trusted user requests and produces an empty, policy-restricted envelope for known internal-tool Chat/skill requests.
7. Persist a server-only authority snapshot and task-input binding on scheduled records. Direct authenticated task ingress can admit its user-supplied task; task creation inside model execution intersects with parent authority. Scheduler overrides, retries and provider fallbacks reuse that snapshot. Missing/stale snapshots grant no tool authority. Newly seeded server-owned housekeeping jobs receive exact snapshots at their static creation point; existing rows are not retrospectively authorized by their names/actions. Internal tool HTTP task payloads cannot become fresh user requests across an ASGI context boundary. Built-in actions receive an exact admission check. Persist detached-job authority in a separate authority sidecar at dispatch; monitor continuations reuse it and current denials. Do not edit bg_jobs/process containment implementation.
8. Production files: new authority module; routes/chat_routes.py; src/agent_loop.py; src/tool_execution.py; src/teacher_escalation.py; src/tool_approvals.py; core/database.py; routes/task/task_routes.py; src/tools/system.py; src/task_scheduler.py; src/bg_monitor.py; routes/skills_routes.py. Change preview only if direct-entry binding is required by validation. No TurnContract/profile/schema redesign.
9. Shared hotspots: route/loop/dispatch, approvals and task/database integration. One coordinator writes all production files. Keep changes confined to authority creation, forwarding, persistence and admission. Do not modify containment, provenance/effect classification or egress implementation.
10. Focused regressions: available schema/bridge/dynamic handler without grants; model-selected unrelated tool/action; explicit class admission; exact read arguments; narrow transcription/OCR/tasks/browser fallback; hard denials despite offered-tool reconciliation; retry/fallback stability; child and teacher non-widening and restoration; malformed/missing state; exact approval mismatch/replay and continuation scope; scheduled snapshot/input binding and synthetic override; detached followup inheritance; journal denial evidence. Preserve existing policy-forwarding and Ajax assertions.

Validation: new focused tests; existing contract/policy/capability/profile tests; scripts/validate_runtime_wave1.sh; broad affected runtime tests; full pytest; compileall; JS/MJS syntax; diff check and conflict-marker scan. Any production edit after full pytest requires affected tests and full pytest again.

Implemented boundaries and remaining limits

The preview entry also binds authority because it supports direct callers. Research task admission binds the snapshot around the researcher, so nested execution cannot infer grants from generated research context. LAN lookup intent has a narrow host_shell-only admission rule; it adds neither Bash nor Python and does not alter Ajax schemas or profiles.

Scheduled loop entry explicitly forwards the restored workspace as well as the envelope; rebinding the continuation session never drops confinement to the original workspace. Only the actual server Bash launch seals a detached job sidecar. A handler/bridge result claiming a job id cannot create one.

Snapshots are trusted server state, stored in the task database and detached job authority sidecars. Missing, malformed, changed-input, wrong-owner or wrong-session snapshots fail closed. Legacy tasks need a trusted task-input save to obtain a snapshot; legacy detached jobs have no execution grants on followup. No broad backfill, authority-mode UI, containment, effect/egress or receipt/journal redesign is included. Sidecars follow the detached job's server storage trust assumptions; retention/integrity hardening is outside this slice.

Class admission deliberately reuses the deterministic semantic classifiers. Unrecognized intent has only explicit ask_user/update_plan controls. This can deny unsupported phrasing and generated default skill tests/audits; model prompts and tool inventory cannot repair that denial. Existing exact approvals can admit one sealed root operation, never widen subsequent calls or nested authority. They still require the existing armed security context, matching bindings, one-use claim, document checks and current hard restrictions.

Standalone dispatcher test fixtures now supply explicit registry grants to continue exercising their original handler/policy/confinement assertions. New authority tests use the raw dispatcher and prove denial before dispatch.

File ownership and reasons

Production file	Wave 2 change
src/agent_runtime/authority.py	Immutable intent/admission/operation API, trusted factory, intersection/context binding, task/job snapshots
routes/chat_routes.py	Capture authority before availability reconciliation; pass it into execution; guard approval ingress
src/agent_loop.py	Bind logical-invocation authority; capture it in approvals and teacher takeover
src/tool_execution.py	Normalize/check operations before dispatch and approval claims; bind handler context; seal actual detached launch
src/teacher_escalation.py	Explicit child/approval inheritance without synthetic-prompt grants
src/tool_approvals.py	Bind immutable originating authority into exact approval digest
src/clean_agent_preview.py	Bind authority at the supported direct preview entry
core/database.py	Add nullable server-only scheduled snapshot column and additive migration
routes/task/task_routes.py	Seal direct user task inputs; deny fresh grants to internal-tool HTTP payloads
src/tools/system.py	Cap model-created/edited task snapshots by active authority
src/task_scheduler.py	Restore original scope/workspace for loops, admit exact built-ins/research, seal new static defaults
src/bg_monitor.py	Restore original detached-job scope and current hard restrictions
routes/skills_routes.py	Separate explicit user task authority from generated/internal skill prompts; guard approval ingress

Shared hotspots touched: chat routes, agent loop, central dispatcher, preview, teacher escalation, approvals, task CRUD/scheduler/system handlers, database, background monitor and skill entry routes. All production edits have one writer. TurnContract, tool schemas, model profiles, journal/completion foundations, bg_jobs/process containment and effect/egress implementations are untouched.

tests/test_request_authority.py adds the focused authority regressions. tests/runtime_evidence_helpers.py adds explicit standalone server fixture grants. Original assertions are preserved in these adapted fixture suites:

• tests/test_agent_external_tool_schemas.py
• tests/test_ask_user_tool.py
• tests/test_client_tool_routing.py
• tests/test_edit_file.py
• tests/test_execution_bridge.py
• tests/test_external_context_tool_gate.py
• tests/test_image_creation_routing.py
• tests/test_review_regressions.py
• tests/test_runtime_evidence_contract.py
• tests/test_task_cookbook_admin_gate.py
• tests/test_task_scheduler_cancel.py
• tests/test_tool_approvals.py
• tests/test_tool_path_confinement.py
• tests/test_tool_policy.py
• tests/test_turn_contract.py
• tests/test_turn_contract_integration.py
• tests/test_update_plan_tool.py
• tests/test_weather_search_recovery.py
• tests/test_workspace_confine.py

website/configuration-reference.md is regenerated solely to update the chat-route environment-read line number. This document records discovery, the pre-edit plan, implementation boundaries and file ownership. The validation report records final commands/results. No production files in parallel lanes are claimed.