[FEATURE] Expose Session Metadata to Claude Agent

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

Summary

Claude Code agents should have programmatic access to their own session metadata (session ID, start time, etc.) during execution without requiring user input.

Problem Statement

Currently, when a Claude agent needs to track or log its own session information (e.g., for session tracking, resumption workflows, or audit trails), the session ID is not accessible programmatically. The agent must ask the user to manually provide the session ID, which:

• Breaks automation workflows
• Creates poor user experience
• Is unnecessary since the system already knows the session ID

Current Behavior

# Agent trying to log session info
session_id = ??? # No way to retrieve this programmatically

# Workarounds (all bad):
# 1. Ask user for session ID manually ❌
# 2. Check environment variables → Not available ❌
# 3. Generate pseudo-ID → Doesn't match actual session ❌

Environment check shows no session metadata:

$ env | grep -i claude
CLAUDE_CODE_ENTRYPOINT=cli
ANTHROPIC_MODEL=anthropic--claude-4.5-sonnet
# No CLAUDE_SESSION_ID or session metadata available

Expected Behavior

Agents should be able to retrieve session metadata automatically.

Proposed Solution

Proposed Solutions

Option 1: Environment Variables (Simplest)

CLAUDE_SESSION_ID=b40a4vc9-585d-470e-b59d-5e878928bw35
CLAUDE_SESSION_START_TIME=2026-03-09T10:00:00Z
CLAUDE_SESSION_WORKING_DIR=/Users/username/project
CLAUDE_SESSION_USER=username

Pros:

• Simple to implement
• Standard pattern (like PWD, USER, etc.)
• Accessible via any language (os.getenv(), process.env, etc.)
• No new tools needed

Alternative Solutions

Option 2: System Tool (More Flexible)

Add a new tool: GetSessionInfo

{
  "name": "GetSessionInfo",
  "description": "Retrieves metadata about the current Claude Code session",
  "returns": {
    "sessionId": "b40a4vc9-585d-470e-b59d-5e878928bw35",
    "startTime": "2026-03-09T10:00:00Z",
    "workingDirectory": "/Users/username/project",
    "userId": "username",
    "modelName": "claude-4.5-sonnet",
    "resumedFrom": null  // or previous session ID if resumed
  }
}

Pros:

• More metadata available
• Structured output
• Extensible for future metadata

Option 3: System Context Injection (Most Seamless)

Include session metadata in the system prompt/context automatically:

<system-context>
  <session-metadata>
    <session-id>b40a4vc9-585d-470e-b59d-5e878928bw35</session-id>
    <start-time>2026-03-09T10:00:00Z</start-time>
    ...
  </session-metadata>
</system-context>

Pros:

• Zero tool calls needed
• Agent always has access
• Most seamless UX

Priority

High - Significant impact on productivity

Feature Category

CLI commands and flags

Use Case Example

Use Cases Enabled

1. Automated Session Tracking

• Agent maintains session logs/history automatically
• No manual user input required

1. Cross-Session References

• "In session X, we implemented Y"
• Build knowledge graphs across sessions

1. Session Resumption Workflows

• Agent can log "resume from session X at timestamp Y"
• Better continuity tracking

1. Audit Trails & Compliance

• Automatic logging of session IDs for compliance
• Traceable decision history

1. Multi-Session Orchestration

• Parent session spawns child sessions
• Track relationships automatically

1. Automated Documentation

• Generate session summaries with proper IDs
• No manual lookup required

Real-World Example

Current (Bad UX):

Agent: I need to log this session. What's the session ID?
User: b40a4vc9-585d-470e-b59d-5e878928bw35
Agent: Thanks, logging now...

With Feature (Good UX):

# Agent automatically logs session
session_id = os.getenv('CLAUDE_SESSION_ID')
# or
session_info = GetSessionInfo()
# Session logged automatically, no user intervention

Impact

• User Experience: Removes friction, enables automation
• Functionality: Unlocks new agent capabilities
• Consistency: Aligns with standard system metadata patterns
• Developer Experience: Easier to build session-aware tools

Priority

Medium-High - This is a quality-of-life improvement that enables better automation and UX, but has workarounds (manual input) currently.

Implementation Complexity

Low - Session ID already exists in the system, just needs to be exposed via environment variable or tool.

Additional Context

Additional Context

• Submitted on: 2026-03-09
• Encountered during: Session tracking automation task
• Session ID (example): b40a4vc9-585d-470e-b59d-5e878928bw35
• Claude Code Version: Latest (as of March 2026)

Suggested Solution (Recommended)

Environment Variable (Option 1) is recommended as the quickest win:

• Low implementation effort
• Standard pattern developers expect
• No new tools to document
• Works across all programming languages

Can be enhanced later with Option 2 (tool) or Option 3 (context) for richer metadata.

---

Submitter Note: This gap was discovered during an automated session logging workflow where the agent needed to track its own session ID but had no programmatic way to retrieve it, forcing manual user input.