[FEATURE]: Add systemPrompt option to SDK like Claude Agent SDK

[ysm-dev]

Feature hasn't been suggested before.

• I have verified this feature I'm about to request hasn't been suggested before.

Describe the enhancement you want to request

Summary

Add a systemPrompt option to the OpenCode SDK (@opencode-ai/sdk) that allows developers to directly customize or replace the system prompt, similar to how the Claude Agent SDK (@anthropic-ai/claude-agent-sdk) implements this feature.

Background

The Claude Agent SDK provides flexible system prompt customization through the systemPrompt option:

// Option 1: Complete replacement with custom prompt
for await (const message of query({
  prompt: "Help me write code",
  options: {
    systemPrompt: "You are a Python specialist...",
  },
})) {
  console.log(message);
}

// Option 2: Use preset with append
for await (const message of query({
  prompt: "Help me write code",
  options: {
    systemPrompt: {
      type: "preset",
      preset: "claude_code",
      append: "Always include docstrings and type hints.",
    },
  },
})) {
  console.log(message);
}

Current OpenCode SDK Limitation

Currently, the OpenCode SDK does not provide a direct way to modify the system prompt. Available workarounds include:

1. Agent configuration with prompt option - Requires file-based configuration
2. AGENTS.md files - Project-level only, not programmatic
3. noReply: true context injection - Only appends to conversation, doesn't modify system prompt

None of these provide the flexibility of directly setting systemPrompt in SDK calls.

Proposed API

import { createOpencode } from "@opencode-ai/sdk";

const { client } = await createOpencode();

// Option 1: Direct system prompt replacement
const session = await client.session.create({
  body: { 
    title: "My session",
    systemPrompt: "You are a specialized assistant for..."
  },
});

// Option 2: Append to default system prompt
const session = await client.session.create({
  body: { 
    title: "My session",
    systemPrompt: {
      type: "preset",
      preset: "default",
      append: "Additional instructions here..."
    }
  },
});

// Option 3: Per-prompt system prompt override
await client.session.prompt({
  path: { id: session.id },
  body: {
    systemPrompt: "Custom system prompt for this interaction",
    parts: [{ type: "text", text: "Hello!" }],
  },
});

Benefits

1. Programmatic control - Dynamically generate system prompts based on runtime conditions
2. SDK parity with Claude Agent SDK - Easier migration and consistent developer experience
3. Flexibility - No need for file-based configuration for simple customizations
4. Use cases:
   • Building custom agents with specialized behaviors
   • A/B testing different system prompts
   • Multi-tenant applications with different prompts per user/org
   • Reducing token usage by removing unnecessary default instructions

Related Issues

• Dynamic system prompts for custom agents #3195 - Dynamic system prompts for custom agents
• [FEATURE]: Allow custom prompts in global, project or custom directories #7101 - Allow custom prompts in global, project or custom directories
• add optional system prompt environment injection #1894 - Add optional system prompt environment injection
• Allow for system prompts for models hosted elsewhere #6105 - Allow for system prompts for models hosted elsewhere

This feature would address many of the concerns raised in these issues from an SDK perspective.

[github-actions]

This issue might be a duplicate of existing issues. Please check:

• [FEATURE]: Use OpenCode AI as a runtime and have an SDK? Like Claude Agents SDK? #6182: [FEATURE]: Use OpenCode AI as a runtime and have an SDK? Like Claude Agents SDK? - A broader request for SDK parity with Claude Agent SDK, which would include systemPrompt customization
• add optional system prompt environment injection #1894: add optional system prompt environment injection - Requests optional/customizable system prompt functionality to reduce tokens and increase prompt adherence
• Dynamic system prompts for custom agents #3195: Dynamic system prompts for custom agents - Earlier request for dynamic system prompt capabilities
• [FEATURE]: Allow custom prompts in global, project or custom directories #7101: [FEATURE]: Allow custom prompts in global, project or custom directories - Related feature request for custom prompt configuration

Feel free to ignore if this issue addresses your specific systemPrompt SDK API design in ways these don't.