yoi/work-items/open/20260604-234844-feature-api-authority-separation/artifacts/delegation-intent.md

Delegation intent: feature API authority separation

Classification

implementation-ready as a bounded API cleanup/refinement.

This ticket is a prerequisite for ticket-built-in-feature-tools because Ticket tools must be installed as internal built-in feature contributions while Ticket operation authority remains a host-granted backend capability, not arbitrary filesystem write scope.

Intent

Clarify the pod::feature API boundary so internal built-in feature contributions are not confused with external plugin/sandbox authority grants.

The important distinction:

• Contribution declarations (tools, hooks, alerts/notices, service/background descriptors) are what a feature contributes to the host registry.
• Host authority grants are capabilities required for privileged host-mediated operations such as filesystem, network, secrets, Pod management, model notification, state store, or service access.

Internal built-in features should be able to register contributions without implying external plugin approval/sandbox semantics. External plugin authority remains a separate future concern.

Worktree / branch

• worktree: /home/hare/Projects/yoi/.worktree/feature-api-authority-separation
• branch: work/feature-api-authority-separation

Requirements

• Keep the change inside the existing pod::feature layer; do not create a new crate in this ticket.
• Make naming and type boundaries explicit enough that later built-in Ticket tools can request Ticket backend authority without being framed as an external plugin package grant.
• Prefer concrete rename/clarification over compatibility aliases because this is unreleased internal API.
• Distinguish host authority naming from generic contribution naming. Candidate renames if they fit the code:
  • AuthorityRequest -> HostAuthorityRequest
  • AuthorityGrantSet -> HostAuthorityGrantSet
  • AuthorityDenial -> HostAuthorityDenial
  • FeatureDescriptor::requested_authorities -> requested_host_authorities
  • FeatureDescriptor::with_authority -> with_host_authority
  • ToolContribution::required_authorities -> required_host_authorities
  • FeatureInstallReport::granted_authorities -> host_authority_grants
  • FeatureInstallContext::grants() -> host_authority_grants() or equivalent
• Keep contribution declarations as contribution declarations; do not require host authority grants merely to contribute a tool/hook.
• Keep existing built-in Task feature behavior unchanged.
• Keep descriptor-first validation:
  • actual contributed tools/hooks/notifications/etc. must be declared;
  • duplicate tool names remain rejected;
  • missing required host authority still fails feature installation where applicable.
• Update tests/docs/comments to reflect the new distinction.

Non-goals

• Implementing Ticket built-in tools.
• Implementing Ticket backend authority grants beyond the generic host authority naming/model needed here.
• External plugin loading/discovery/package approval.
• WASM/sandbox runtime.
• MCP integration.
• Real human approval/resume protocol.
• Moving feature API to a new crate.
• Changing Hook API behavior.
• Changing Task feature behavior.
• Broad refactors outside pod::feature and direct callers/tests.

Current code map

• crates/pod/src/feature.rs
  • Main feature API, descriptors, contributions, installation, authority request/grant types, tests.
  • Current generic names include AuthorityRequest, AuthorityGrantSet, AuthorityDenial, requested_authorities, granted_authorities, and required_authorities.
  • FeatureRuntimeKind already distinguishes Builtin, LuaProfile, and ExternalPlugin.
  • HostAuthority already names the host-mediated capability concept.
• crates/pod/src/feature/builtin/task/mod.rs
  • Built-in Task feature implementation and contribution example.
  • Must continue to install Task tools/hooks/reminders unchanged.
• crates/pod/src/feature/builtin.rs
  • Built-in feature contribution wiring.
• crates/pod/src/lib.rs
  • Public exports if affected.

Critical risks

• Leaving generic Authority* naming in place makes later Ticket tools read like external plugin/sandbox grants, which is the confusion this ticket is meant to prevent.
• Overcorrecting by making built-in contribution registration depend on host authority grants would make internal features unnecessarily complex.
• Adding compatibility aliases for old names would preserve the ambiguity; avoid unless required by external public API, which should not be the case for this unreleased surface.
• Changing behavior instead of naming/boundary tests could destabilize Task feature installation.

Validation

Run at least:

• cargo test -p pod feature --lib
• cargo test -p pod task --lib
• cargo test -p pod --lib
• cargo test -p llm-worker --lib
• cargo check --workspace --all-targets
• cargo fmt --check
• git diff --check
• ./tickets.sh doctor

Run nix build .#yoi --no-link if feasible.

Completion report

Report:

• worktree path / branch;
• commit hash;
• exact API/type/field renames;
• behavior preserved/changed;
• changed files;
• validation results;
• unresolved risks/follow-ups;
• whether ticket-built-in-feature-tools can proceed afterward.