Feature Request: Context Control for Subagents

Problem

Subagents currently receive full repository context even for focused tasks, which:

Increases token usage for small models (e.g., llama3.2:1b)
Degrades performance for specialised, narrow-scope tasks
Makes it difficult to optimise local models for specific use cases
Wastes resources when only a minimal prompt is needed

Use Case

When using lightweight local models (1B-7B parameters) as subagents for focused tasks like:

doc-reader: Extract key points from a single documentation file
codegen: Generate a small code snippet
log-analyser: Analyse a specific log file
editor: Refine a single paragraph

These tasks require only the prompt and perhaps a single file reference, yet the subagent receives the entire repository context including:

Full project structure
Git history
All configuration files
Build scripts
Documentation files

This is particularly problematic for resource-constrained local models where context window size directly impacts inference speed and quality.

Proposed Solution

Add a context configuration option in agent definitions to control what contextual information is passed to subagents:

{
  "agent": {
    "doc-reader": {
      "mode": "subagent",
      "model": "ollama/llama3.2:1b",
      "context": {
        "repo": false,           // Disable full repository context
        "files": "prompt-only",  // Only include files mentioned in the prompt
        "maxTokens": 2000,       // Maximum context tokens to pass
        "git": false,            // Exclude git history
        "config": false          // Exclude configuration files
      }
    }
  }
}

Configuration Options

repo (boolean, default: true): Include full repository structure
files (string, default: "all"): Control which files to include
- "all": All repository files
- "prompt-only": Only files explicitly mentioned in the prompt
- "none": No file context
maxTokens (number, optional): Hard limit on context tokens
git (boolean, default: true): Include git history and metadata
config (boolean, default: true): Include configuration files

Alternative: Markdown Configuration

---
description: Reads documentation and summarises key insights
mode: subagent
model: ollama/llama3.2:1b
temperature: 0.1
context:
  repo: false
  files: prompt-only
  maxTokens: 2000
---

Extract key points, APIs, and caveats from documentation.
Provide a short summary and a Q&A with likely follow-ups.

Benefits

Performance: Faster inference for small local models
Cost: Reduced token usage for API-based models
Quality: Less noise, more focused responses
Flexibility: Different subagents can have different context requirements
Resource optimisation: Better support for constrained environments

Real-World Example

Current configuration (16 subagents using llama3.2:1b):

{
  "doc-reader": {
    "mode": "subagent",
    "model": "ollama/llama3.2:1b",
    "prompt": "Extract key points, APIs, and caveats from documentation.\nProvide a short summary and a Q&A with likely follow-ups.",
    "tools": {
      "write": false,
      "edit": false,
      "bash": false
    }
  }
}

When invoked with:

@doc-reader summarise the authentication section in README.md

Current behaviour: Receives entire repository context (potentially 50,000+ tokens)
Desired behaviour: Receives only the prompt + README.md content (~2,000 tokens)

This would make local small models significantly more practical for production use.

Compatibility

This would be a backwards-compatible addition:

Default behaviour remains unchanged (full context)
Existing agents continue to work without modification
New context option is entirely optional

Related Work

Similar context control exists in other AI systems:

LangChain's context_window parameter
LlamaIndex's chunk_size configuration
Anthropic's explicit context management in Claude

Would this feature align with OpenCode's roadmap? Happy to provide additional details or contribute to implementation if helpful.

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

Feature request: let subagents inherit context #2588: Feature request for subagents to inherit context - addresses similar context control concerns but from the opposite direction
Feature: Subagents should support auto compaction #3153: Auto compaction for subagents when they exceed context limits - addresses context management for subagents
[Question] detailed per-interaction telemetry (token counts and input composition) for opencode-model communications #2666: Detailed telemetry for token counts and input composition - related to token usage optimization which is a core concern here

Feel free to ignore if none of these address your specific case.

Update: Temporary Workaround Implemented

While waiting for native context control in OpenCode, I've implemented a transparent HTTP proxy that solves this issue for small local models.

Repository: https://github.com/gunnarnordqvist/opencode-context-filter

How It Works

Sits between OpenCode and Ollama (port 11435 → 11434)
Automatically filters context for configured small models (llama3.2:1b, qwen2.5:1.5b)
Removes <project>, <env>, AGENTS.md, and custom instructions
Zero modifications to OpenCode required

Performance Results

Token reduction: 45,000 → 200 tokens (99%)
Inference speed: 8s → 1s (8× faster)
Time savings: ~112 seconds per cycle (16 subagents)
Overhead: <50ms additional latency

Installation

git clone https://github.com/gunnarnordqvist/opencode-context-filter.git
cd opencode-context-filter
./scripts/install.sh
# Update OpenCode baseURL to http://localhost:11435/v1

The proxy launches automatically with OpenCode via a wrapper script. Works with any OpenCode version, pure Python (no dependencies).

This serves as a proof-of-concept demonstrating the value of context control for small models. Would still love to see this implemented natively in OpenCode!

Hi,
I just stumbled upon this PR, but didn't see anything related to it in the doc that I am currently looking at:
https://opencode.ai/docs/agents/
Could we have the doc completed with all the context-related features? Or is it elsewhere (in which case a link in the agent page might be useful) ?

Hi, I just stumbled upon this PR, but didn't see anything related to it in the doc that I am currently looking at: https://opencode.ai/docs/agents/ Could we have the doc completed with all the context-related features? Or is it elsewhere (in which case a link in the agent page might be useful) ?

Yes, it's really strange that it wasn't addressed. Neither the configuration is available, nor a description of what currently is passed to the subagent as context. It seems that only a prompt is passed, which makes it pretty much unusable with sol, as all subagents do a lot of repeated work

@jlongster

Related to this: I’d like a static per-agent cap as a complement to the dynamic nudge. Something like context: 30000 on an agent, mirroring how steps works today. When the estimated prompt reaches the cap, the next step is the last one: tools off, tool definitions kept for cache stability, and a wrap-up prompt so the subagent reports back.

Today a subagent on a large-window model only compacts at about 90% of the window, and there’s no way to set it lower. A cap is predictable and needs no new events. The nudge here would still be useful for cases where the threshold depends on runtime state.

@jlongster, would you rather I fold this into this issue or open a separate one? I’m happy to implement it either way once you’re okay with the shape.

Navigation Menu

Repository navigation

Feature Request: Context Control for Subagents #4096

Feature Request: Context Control for Subagents

Problem

Use Case

Proposed Solution

Configuration Options

Alternative: Markdown Configuration

Benefits

Real-World Example

Compatibility

Related Work

Update: Temporary Workaround Implemented

How It Works

Performance Results

Installation

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Feature Request: Context Control for Subagents #4096

Description

Feature Request: Context Control for Subagents

Problem

Use Case

Proposed Solution

Configuration Options

Alternative: Markdown Configuration

Benefits

Real-World Example

Compatibility

Related Work

Activity

github-actions commented on Nov 8, 2025

gunnarnordqvist commented on Nov 8, 2025

Update: Temporary Workaround Implemented

How It Works

Performance Results

Installation

matthieu-vergne commented on Apr 5, 2026

mister-choo commented on Jul 22, 2026

boxabirds commented on Oct 18, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions