Agent Identity

OpenCode plugins for agent self-identity and per-message agent attribution.

What it does

This package provides two plugins that improve agent identity awareness in OpenCode sessions:

• AgentSelfIdentityPlugin — Injects a one-liner identity statement (e.g., You are currently operating as the "build" agent.) into the system prompt so the model knows which agent it's operating as. Addresses OpenCode #7492.

• AgentAttributionToolPlugin — Exposes an agent_attribution tool that any agent can call to get per-message attribution for the current session. Returns which agent produced each assistant response and which model was used. Useful for agents that review multi-agent sessions, like a Retrospective agent. Addresses OpenCode #14930.

Installation

Add the plugin to your opencode.json:

{
  "plugin": ["@gotgenes/opencode-agent-identity"]
}

Both plugins are loaded automatically when the package is installed.

How it works

Agent Self-Identity

When a user switches agents mid-session (e.g., Plan → Build → Plan), the newly active agent has no built-in way to know its own name. This plugin uses two hooks with shared, session-scoped state:

1. experimental.chat.messages.transform — Reads the current agent name from the last user message's info.agent field.
2. experimental.chat.system.transform — Appends an identity statement to the system prompt.

State is keyed by session ID so concurrent sessions don't interfere.

Agent Attribution Tool

All agents in a session share one flat conversation history, but MessageV2.toModelMessages() strips the info.agent metadata when converting to the format sent to the LLM. This plugin exposes an agent_attribution tool that retrieves per-message attribution on demand via the OpenCode SDK.

When called, the tool returns a numbered list of every message in the session. User messages show only the role; assistant messages include the agent name and the provider and model that produced the response:

1. user
2. assistant (project-manager) [anthropic/claude-sonnet-4-6]
3. user
4. assistant (product-manager) [anthropic/claude-sonnet-4-6]
5. user
6. assistant (project-manager) [anthropic/claude-sonnet-4-6]

Why a tool instead of inline tags?

An earlier version of this package (v1) injected [agent: X] tags directly into assistant message text in the conversation history. This caused two problems:

1. Identity confusion: When switching agents mid-session, the accumulated tags from the previous agent overwhelmed the system prompt identity, causing the model to identify as the wrong agent.
2. Self-authoring: Models learned the [agent: X] pattern and started generating the tags themselves, creating a feedback loop that reinforced the wrong identity.

The tool-based approach keeps the conversation history clean and lets agents query attribution only when they need it.

Integrating with your agents

To use the attribution tool, mention it in the agent's system prompt. For example, a Retrospective agent that reviews multi-agent sessions could include:

## Multi-agent attribution

This session may involve multiple agents. To determine which agent produced
each response, call the `agent_attribution` tool. It returns a numbered list
of every message in the session. User messages show only the role; assistant
messages include the agent name and the provider and model that produced the
response.

Upgrading

See MIGRATION.md for upgrade guides between major versions.

Development

Prerequisites

• Bun — runtime, package manager, and test runner
• prek — pre-commit hook framework (brew install prek)

Setup

bun install
prek install

Commands

Command	Description
bun run check	TypeScript type checking
bun run lint	Biome linting + formatting check + import sorting
bun run lint:fix	Auto-fix all Biome issues
bun run lint:md	Markdown linting
bun run lint:all	All linting checks
bun run format	Format all files
bun run test	Run tests
bun run test:watch	Run tests in watch mode
bun run build	Build the package

Pre-commit hooks

After running prek install, the following checks run automatically before each commit:

• Trailing whitespace trimming
• End-of-file newline enforcement
• Large file detection
• Markdown linting
• Biome linting and formatting

Related projects

• opencode-model-announcer — Analogous to AgentSelfIdentityPlugin but for model identity: injects the current model name (e.g., anthropic/claude-sonnet-4-6) into the system prompt so the model knows which model it is operating as.

License

MIT