Still confused about Task / Sub-Agents and how to properly clean Skills & Workflows from unavailable tools

[HaroldFinchIFT]

Hi again 👋

I’m still a bit confused about the overall tools / agents / workflows setup, and I think there’s some hidden coupling with tools or services that aren’t available in my environment.

I’m running PAI-OpenCode locally with:

• Local models only
• No Claude / Perplexity / external subscriptions / APIs

After a fresh install things mostly work, but the LLM still sometimes tries to use tools or agents that don’t exist in my setup.

---

Task tool confusion

I see Task mentioned in several skills/workflows, and sometimes the LLM tries to call it, but it fails.

My questions are:

• Is Task supposed to be a built-in tool?
• Does it need permissions like websearch?
• Or is it a leftover reference from other environments (Claude, etc)?

---

Sub-agent not found

Sometimes the model tries to spawn a sub-agent that doesn’t exist and fails.

Am I missing some registration step for agents, or is this just a dangling reference inside workflows?

---

Cleaning skills/workflows from unavailable services

This is probably the main point 🙂

Some skills/workflows still reference:

• Claude
• ClaudeResearch
• Perplexity
• other online services

Since I’m fully local, I tried to clean them manually with the help of the model, but I’m not satisfied and I’m pretty sure I broke parts of the intended flow.

So I’d really appreciate some guidance on:

• Best practices to remove unused tools/workflow/depending third-party paid service skills safely
• How to audit workflows/skills for invalid references
• What is safe to delete vs what is core
• Whether there’s a “minimal local-only” configuration pattern

Right now it feels easy to accidentally create invisible breakpoints in PAI’s logic.

My goal is a minimal setup, keeping the core features of PAI, without add-ons that I currently can’t use (maybe in the future).

---

Let me know if you can point me in the right direction.
Thanks again for the work on PAI-OpenCode!

[HaroldFinchIFT]

Just to add a bit of information: the websearch error discussed in the previous issue occurred again (#9):

It happened even though I added the configuration you provided in the opencode.json:

What am I missing?

[Steffen025]

Hey @HaroldFinchIFT, thanks for the detailed writeup. You've identified a real problem — and we've fixed it in v1.3.0.

Root Cause

In pre-v1.3.0, all agent .md files contained YAML frontmatter like this:

---
name: Engineer
model: anthropic/claude-sonnet-4-5
color: "#3B82F6"
voiceId: iLVmqjzCGGvqtMCk6vVQ
voice:
  stability: 0.62
  similarity_boost: 0.80
---

OpenCode passes all YAML frontmatter fields through as options to the LLM API call. Strict APIs (including Ollama) reject the request because fields like voiceId, color, voice are not valid LLM API parameters.

So when the Task tool tries to spawn a sub-agent → it loads the agent .md → sends invalid parameters to your local model → API rejects → you see "sub-agent not found" or Task tool errors.

We hit exactly this problem ourselves when moving beyond Anthropic's API.

The Fix in v1.3.0

Two changes:

1. Custom OpenCode dev build — We patched OpenCode to distinguish between agent metadata (voiceId, color, etc.) and actual LLM API options. Only fields explicitly recognized as LLM options get passed to the API. Everything else is treated as metadata.

2. Model routing moved to opencode.json — The model: field was removed from all agent .md files. Model assignment now happens centrally in opencode.json with dynamic 3-tier routing (quick, standard, advanced per agent).

What To Do

1. Update to v1.3.0:

   git pull origin main

2. Run the wizard and select the local-ollama preset:

   bun run .opencode/PAIOpenCodeWizard.ts

3. Use our OpenCode dev build — The wizard in v1.3.0 guides you through building it. This is required because the YAML passthrough fix is in our patched version of OpenCode, not in upstream yet.

After this, Task tool delegation and sub-agents should work with Ollama.

Websearch

The websearch error is a separate issue — it depends on your OpenCode version and tool configuration. Check your opencode.json for tool permissions.

Honest Note

I haven't tested v1.3.0 end-to-end with local models myself yet. If you still hit issues after upgrading, please report back and we'll debug together.

Thanks for pushing us to improve the local experience!

[Steffen025]

Hi @HaroldFinchIFT — update since v2.0.0 shipped (Feb 19):

YAML Frontmatter Fix

The fix described in my previous comment is now included in the v2.0.0 release. Agent .md files still contain metadata fields (voiceId, color, voice settings) but these are treated as metadata by our patched OpenCode build — they won't be sent to your LLM API.

If you're on the stable OpenCode release (not our dev build), you can still hit this. The dev build remains the recommended path for local setups — the wizard guides you through building it.

Websearch Error

For your websearch error: the LLM is trying to use a tool that isn't available in your setup. To disable it, add this to your opencode.json:

{
  "tools": {
    "websearch": { "enabled": false }
  }
}

This prevents the model from attempting to use websearch entirely.

Local-Only Documentation

We've added a docs/LOCAL-ONLY-SETUP.md guide covering:

• How to disable external tools (websearch, browser)
• Which skills work locally vs. need external APIs
• How to audit your setup for invalid references
• Model configuration for Ollama

Closing

The root cause (YAML passthrough) is fixed in v2.0.0, and the documentation gap is now filled. Closing this issue — if you still hit problems after updating, please open a fresh issue and we'll debug together.

Thanks for pushing us to improve the local-only experience!