claude-code - 💡(How to fix) Fix [BUG] 'claude agents' silently refused from inside any Claude Code session — uninformative error masks the process-tree gate

Preflight Checklist

• I have searched existing issues and this hasn't been reported yet
• This is a single bug report
• I am using the latest version of Claude Code

What's Wrong?

Running claude agents from inside an active Claude Code session — whether via the Bash tool inside a subagent or any nested shell where claude is on the process tree — returns exit 1 with stderr:

'claude agents' is not available in this environment.

The same binary, same auth, same environment variables, invoked from a fresh terminal pane with no claude parent process, opens the agent-view TUI as expected.

The behavior itself appears intentional (preventing nested-session confusion is reasonable), but the error message gives no clue about the gate. I spent ~30 minutes ruling out env-marker scoping, daemon state, auth mode, subscription tier, and binary version before identifying that the gate is parent-process-based.

What Should Happen?

Either:

1. claude agents works from inside an active Claude Code session (perhaps with an indicator that the user is inside session X), or
2. The error message names the gate directly — for example: 'claude agents' cannot be invoked from within an active Claude Code session. Open a new terminal and try again.

Option 2 is an error-string change only, no behavioral shift — the minimal fix that would have saved the diagnostic time.

Error Messages/Logs

$ claude agents
'claude agents' is not available in this environment.
$ echo $?
1

Steps to Reproduce

1. Open a terminal and run claude to start an interactive Claude Code session
2. From inside that session, run claude agents via the Bash tool (or have Claude shell out to a child process and run it there)
3. Observe: stderr 'claude agents' is not available in this environment., exit code 1
4. Open a fresh terminal pane with no claude process anywhere in its ancestry, run claude agents
5. Observe: the agent-view TUI opens normally

Claude Model

Not sure / Multiple models (the gate fires before model selection)

Is this a regression?

I don't know

Claude Code Version

2.1.142 (Claude Code) — also reproduces on 2.1.141

Platform

Anthropic API

Operating System

macOS

Terminal/Shell

Cursor

Additional Information

Diagnostic sequence ruling out alternative gates before identifying the parent-process one:

• Env-marker stripping (env -i HOME=$HOME PATH=$PATH ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY claude agents): same error → not env-scoped
• Daemon state: started a claude --bg session, confirmed daemon alive + worker in ~/.claude/daemon/roster.json + control socket reachable at /tmp/cc-daemon-501/.../control.sock, ran claude agents while session was active: same error → not daemon-gated
• Auth mode: unset ANTHROPIC_API_KEY to force pure-OAuth/subscription auth, ran claude agents: same error, but claude auth status revealed subscriptionType: max (note: this was masked as null when the env API key was set — possibly a separate small UX bug worth filing if confirmed)
• Flag variations: claude agents --cwd <path>, claude agents --setting-sources user: same error → not flag-related
• Direct binary invocation: ~/.local/bin/claude agents bypassing aliases: same error
• Binary version: 2.1.141 and 2.1.142 both reproduce
• Fresh terminal pane outside any Claude session: works ✓ — this is what finally identified the gate

Suggested fix (lightweight): update the error string to name the gate directly. Pseudocode location: wherever claude agents performs its pre-flight environment check, replace the generic error with one that mentions the parent-process constraint and the workaround (run from a fresh terminal).

Related: #19077 ("Sub-agents can't create sub-sub-agents") — same broader subagent/nesting boundary surface, but distinct in scope: that issue is about the Agent tool's nesting depth; this issue is about the claude agents subcommand's parent-process gate.