Description

[Bug] Primary agents lack identity awareness when user switches agents - cannot determine which agent is active

Description

When switching between primary agents in OpenCode (via Tab key or agent selector), the newly activated agent has no awareness of its own identity. This causes the agent to:

1. Confuse itself with other agents being discussed
2. Fail to maintain proper role boundaries
3. Respond from the wrong perspective

According to OpenCode agent documentation, users can "switch between agents during a session" and agents are defined with configurations including mode: "primary" or mode: "subagent". However, when a primary agent is activated, it cannot determine:

• Which agent configuration is currently active
• Whether it is the subject being discussed or the one analyzing
• What agent the user was previously interacting with
• Its own name, config path, or role in the workspace

Steps to Reproduce

1. Create a custom primary agent in .opencode/agent/custom-agent.md:

   ---
   description: Custom agent with specific behavior
   mode: primary
   ---
   # Custom Agent Instructions
   [specific instructions]

2. Start a conversation with the custom agent (via agent selector or @ mention)

3. Have the custom agent perform some tasks

4. Switch to a built-in agent using Tab key or Ctrl+P → Select Agent (e.g., switch to build agent)

5. Ask the build agent: "Why did the custom agent do X?"

Expected Behavior:
Build agent analyzes the custom agent's behavior objectively as a separate entity, referencing .opencode/agent/custom-agent.md.

Actual Behavior:
Build agent responds AS IF it is the custom agent, attempting to self-correct rather than analyze.

Example

[User is talking to custom-agent]
User: "Do task A"
Custom Agent: [performs task, exhibits some behavior]

[User switches to build agent via agent selector]
User: "You are the build agent, not the custom agent. Why did that agent skip step X?"

Build Agent: "You're absolutely right - I skipped that step..." ❌

What should happen:

Build Agent: "I'm the build agent. Looking at the custom-agent configuration at 
.opencode/agent/custom-agent.md, the agent likely skipped that step because..." ✅

Root Cause

Agents receive no metadata about their identity or role despite having rich configuration options in their frontmatter (description, mode, model, tools, permissions, temperature, prompt).

Per the OpenCode documentation:

• Agents are defined in ~/.config/opencode/agent/ (global) or .opencode/agent/ (project-specific)
• Agents have two modes: mode: "primary" (user switches between them) or mode: "subagent" (invoked by other agents)
• Users switch between primary agents using Tab key or the agent selector

However, when a primary agent is activated, the agent system provides:

// Current agent context (missing identity info)
{
  instructions: "composite prompt from multiple sources",
  tools: [...],
  // ❌ MISSING:
  // agent_name: "build",
  // agent_mode: "primary",
  // agent_config: ".opencode/agent/build.md",
  // agent_description: "Build system agent",
  // session_context: { previous_agent: "custom-agent", ... }
}

The agent receives its instructions but has no awareness of:

• Which .md file those instructions came from
• Whether it's a primary agent or subagent
• Its configured description or other frontmatter metadata
• That the user just switched from another agent

Impact

Severity: High - Breaks multi-agent workflows with primary agents

1. Role confusion: Agent cannot distinguish "I am X agent" vs "User is discussing Y agent"
2. No meta-analysis capability: Cannot debug or analyze other agent behavior
3. Context loss on switch: No awareness that user switched agents (via Tab key)
4. Ambiguous instructions: Cannot determine which instructions apply to current role
5. Frontmatter metadata unused: Agent config has description and mode but agent can't access them

This particularly affects the documented primary agent workflow:

• User creates specialized primary agents for different roles (code-reviewer, build, test, documentation)
• User switches between them during development using Tab key
• Agents lose context and confuse their identities
• The intended multi-agent collaboration pattern breaks down

Proposed Solution

Solution 1: Inject Agent Identity into System Prompt

Prepend to agent instructions (leveraging existing frontmatter):

# AGENT IDENTITY CONTEXT

**You are currently operating as:** build
**Your configuration file:** .opencode/agent/build.md
**Your mode:** primary (user can switch to you via Tab key)
**Your description:** "Build system agent" (from frontmatter)

**Other primary agents in workspace:** plan, code-review, custom-agent
**Previous agent in session:** custom-agent (switched at 2026-01-09 10:30:00)

When the user refers to "the agent" or "the custom agent", they are referring to 
a DIFFERENT agent (not you). Analyze that agent's behavior objectively.

This approach:

• Uses existing frontmatter metadata (description, mode)
• Provides agent name and config path
• Shows agent switching context
• Clarifies workspace agent topology

Solution 2: Add Agent Context Metadata to Session

Provide structured identity data (aligning with existing agent config):

interface AgentContext {
  current: {
    name: string;                           // "build" | "plan" | "custom-agent"
    config_path: string;                    // ".opencode/agent/build.md"
    mode: "primary" | "subagent" | "all";  // From frontmatter
    description: string;                    // From frontmatter 'description'
    is_builtin: boolean;                    // true for build/plan/general/explore
    model?: string;                         // From frontmatter if specified
    temperature?: number;                   // From frontmatter if specified
  };
  
  session: {
    previous_agent?: string;   // Agent user was using before switch
    switch_timestamp?: number; // When Tab key was pressed
    switch_method?: "tab_key" | "selector" | "mention"; // How agent was invoked
    session_id: string;
  };
  
  workspace: {
    available_agents: {
      name: string;
      mode: "primary" | "subagent" | "all";
      description: string;
    }[];
    default_agent: string;
  };
}

This approach:

• Mirrors existing frontmatter structure
• Distinguishes builtin vs custom agents
• Tracks agent switching behavior
• Provides workspace topology

Solution 3: Agent Introspection Tool

Add tool for agents to query their identity:

{
  name: "get_agent_context",
  description: "Query information about current agent identity and session",
  parameters: {},
  returns: AgentContext
}

Related Issues

• [Security Bug] Subagent permissions not enforced - configured restrictions ignored #7474 - Subagent permissions not enforced (agents don't maintain identity boundaries)
• [FEATURE]: Add per-agent filesystem boundaries (allow/deny paths) + optional run-as user for bash #5529 - Per-agent filesystem boundaries (agents lack identity-based restrictions)

Environment

• OpenCode Version: v1.0.200+
• Using custom agents defined in .opencode/agent/
• Switching between agents via agent selector
• OS: Linux

Use Cases Affected

This bug severely impacts:

1. Custom agent development - Cannot create agents that analyze other agents
2. Multi-agent workflows - Confusion when switching between specialized agents
3. Debugging agent behavior - Cannot meta-analyze why an agent behaved a certain way
4. Role-specific agents - Agents with distinct responsibilities get confused about their role
5. Educational/tutoring applications - Teaching agents that need to maintain boundaries

Additional Context

The agent system needs clear identity boundaries to function correctly in multi-agent environments. Without identity awareness, agents cannot maintain proper separation of concerns when users switch between different agent configurations.

This bug specifically affects the documented primary agent workflow:

• Per OpenCode docs: "You can switch between agents during a session"
• Primary agents are designed to be user-switchable via Tab key
• Agent frontmatter supports description and mode to define agent identity
• However, agents have no runtime access to this identity information

This is distinct from subagent issues:

• Issue [Security Bug] Subagent permissions not enforced - configured restrictions ignored #7474 addresses subagent permissions (parent-child hierarchy)
• Issue [FEATURE]: Add per-agent filesystem boundaries (allow/deny paths) + optional run-as user for bash #5529 addresses per-agent filesystem boundaries
• This issue addresses primary agent identity awareness when user switches via Tab key

The bug prevents the intended multi-agent collaboration pattern documented in OpenCode where users create specialized primary agents and switch between them during development.

Report generated with Opencode + Claude Sonnet 4.5

OpenCode version

1.1.8