Feature: per-invocation effort parameter + runtime session-config introspection for skills

Feature request: per-invocation effort parameter + runtime session-config introspection for skills

Summary

Two related capability gaps surfaced while building a Claude Code skill that orchestrates 8 specialized sub-agents (via the Agent tool) for code review. The skill aims to lock in a consistent quality bar across all contributors who run it, but it can only pin sub-agent model per invocation — not effort, not context-window variant, not parent-session config. This means a contributor running the skill on a downgraded session silently produces a lower-quality review than intended, with no mechanical way to detect or surface the drop.

This is related to (and would close on) the already-open #43083 ("Feature: configurable reasoning effort level for subagents"), but extends scope to two adjacent runtime introspection needs.

Gap 1: Per-invocation effort parameter on the Agent tool

Already requested in #43083 — re-citing here for completeness.

Current: subagent frontmatter accepts effort (per docs/sub-agents § Supported frontmatter fields), but the Agent tool's per-invocation parameter surface only exposes subagent_type, prompt, description, model. So a skill can pin model: "opus" per invocation but cannot pin effort.

Impact: when a skill spawns N parallel sub-agents that must all run at MAX effort regardless of parent session config, the only options today are:

• (a) Set effort in each plugin sub-agent's frontmatter (impossible if the plugin is owned by a third party)
• (b) Rely on parent-session inheritance (silently degrades if parent is at default)
• (c) Prompt the user at skill entry to confirm parent effort is MAX (what we currently do, see Gap 3 below)

Asked-for: add effort to the Agent tool's invocation parameters, mirroring the resolution order documented for model: env var → per-invocation → frontmatter → parent session.

Gap 2: Runtime API for plugin registration

A skill that depends on specialized subagents from plugins (feature-dev:*, pr-review-toolkit:*) currently has no way to verify those subagent types are registered before invoking them. The workaround is post-hoc error-catching: call Agent(subagent_type: "X"), catch the resulting Agent type 'X' not found. Available agents: [list] error, parse the list. This works (the tool errors cleanly — verified via probe), but it requires actually attempting an invocation to discover the gap.

Asked-for: a runtime query (env var, tool, or process.env-accessible value) that exposes the list of currently-registered subagent types. Equivalent of /agents output in machine-readable form. Would let skills do pre-launch availability gates instead of post-hoc detection.

Gap 3: Runtime introspection of active session model + effort

A skill's quality is bounded by the parent session's actual model + reasoning effort, but the skill has no way to read those values at runtime. Today the only mitigation is a precondition AskUserQuestion asking the user to self-report their session config — which is fragile (the user can mis-click, especially on a 3-option prompt where Option 1 is "everything is fine" and a tired user might pick it by default).

Asked-for: read-only access to the active session's model + effort tier, via env vars (e.g., CLAUDE_CODE_ACTIVE_MODEL, CLAUDE_CODE_ACTIVE_EFFORT) OR a small introspection tool (e.g., SessionInfo()). Equivalent of the values shown in the session's startup header, but accessible from within a tool-using skill body.

Use case

A multi-agent code review skill that orchestrates ~36 Opus invocations per session. The skill encodes "must run on Opus 4.7 + MAX effort + specific plugins" as a quality contract. Today, the only enforcement is documentation + a user-self-report prompt. With Gaps 1-3 closed:

• The skill would pin effort: max on every Agent invocation (Gap 1).
• It would pre-launch verify all specialized plugins are present (Gap 2).
• It would read the parent session's actual config and either auto-proceed or hard-halt based on match (Gap 3).

Today's workaround pattern (which is operational but bounded) is documented in code.claude.com/docs/en/sub-agents compatibility notes; a sample skill that implements all three workarounds is happy to share if helpful for design context.

Priority

Medium. The workarounds (model pin, post-hoc error-catching, user-confirmation prompt) cover the most common cases. Closing these gaps would primarily benefit:

• Teams running multi-agent orchestration skills at scale
• Skills designed to be portable across teams with varying session-config discipline
• CI/non-interactive contexts where AskUserQuestion is unavailable

Acknowledgement

Built on / cross-references: #43083. Happy to refine the spec or split into smaller issues if that's preferred.