claude-code - 💡(How to fix) Fix [DOCS] Background session docs omit `$CLAUDE_JOB_DIR` temp-file behavior

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/agent-view

Section/Topic

"Where state is stored" and background session temp-file behavior.

Current Documentation

The Agent View docs currently say:

Every background session has a short ID you can use from the shell. The ID is printed when you start a session with claude --bg, and each session's ID is its directory name under ~/.claude/jobs/.

The same page lists stored session state:

~/.claude/jobs/<id>/state.json | Per-session state shown in agent view

The environment variables reference documents CLAUDE_CODE_TMPDIR:

Override the temp directory used for internal temp files. Claude Code appends /claude-{uid}/ (Unix) or /claude/ (Windows) to this path.

No page documents $CLAUDE_JOB_DIR.

What's Wrong or Missing?

A. $CLAUDE_JOB_DIR is mentioned in the v2.1.153 changelog but absent from reference docs

The release notes say background sessions writing temp files to $CLAUDE_JOB_DIR no longer trigger a "sensitive file" permission prompt. Users who see this variable in logs, hooks, shell commands, or changelog entries have no reference explaining what it points to or whether it is safe for temporary files.

B. The relationship between job directories and temp files is unclear

Agent View documents ~/.claude/jobs/<id>/state.json, and env-vars documents CLAUDE_CODE_TMPDIR, but neither explains whether background sessions set a per-job directory environment variable, when it should be used instead of the global temp directory, or how Claude Code treats files created there.

C. Permission behavior is not stated

Because the fix is about avoiding a "sensitive file" permission prompt, users need a short note that files created under the background session job directory are part of Claude Code's own background-session state/temp area and should not be treated like arbitrary sensitive project files.

Suggested Improvement

Add a note in Agent View's "Where state is stored" section:

Background session processes set CLAUDE_JOB_DIR to the per-session job directory under the Claude Code config directory. Claude Code may use this directory for session-scoped state and temporary files. Files written there by Claude Code background-session internals should not trigger sensitive-project-file prompts.

If $CLAUDE_JOB_DIR is intentionally public for hooks or user scripts, also add it to env-vars.md. If it is internal-only, state that it is internal and should not be relied on by user scripts.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 3 pages affected

Version context: Claude Code v2.1.153 changelog entry: "Fixed background sessions writing temp files to $CLAUDE_JOB_DIR triggering a "sensitive file" permission prompt."