[Bug] ZCode v3.7.7/v3.8.1: Agent Fails to Use Read Tool with GLM-5-Turbo — Falls Back to ReadSessionContext or Reports Files Not Found

Bug Report: ZCode Agent Fails to Use Read Tool with GLM-5-Turbo Model

📋 Summary

Critical tool selection bug in ZCode v3.7.7+ where the agent refuses to use the Read tool when running GLM-5-Turbo model, instead falling back to ReadSessionContext or incorrectly reporting files as "not found." The same task works perfectly with GLM-5.3.

Severity: HIGH — Core file reading functionality broken for GLM-5-Turbo users

---

🖥️ Environment

Field	Value
App	ZCode IDE
Affected Versions	v3.7.7 (initial), v3.8.1 (confirmed still broken)
Working Model	GLM-5.3 (Low/any variant) ✅
Broken Model	GLM-5-Turbo ❌
OS	Not specified (likely macOS/Linux/Windows)
Reporter	AndreMaz (Discord)
Discord Thread	https://discord.com/channels/1346756824233148527/1539503972652548106

---

🐛 Problem Description

Symptoms

When using GLM-5-Turbo in ZCode:

1. Agent refuses to call Read tool for file operations
2. Agent uses ReadSessionContext instead (wrong tool for reading specific files)
3. Agent reports files as "not found" or "not readable" even when they exist
4. Explicit instruction to use Read tool still fails on GLM-5-Turbo
5. Workaround: Using shell commands (cat) works correctly

Evidence from Screenshots

Screenshot captured (v3.8.1 + GLM-5-Turbo):

User Request:
  "Try to read these files. Don't retry in case of error. Fail fast"
  • /home/.../file1.md
  • /home/.../file2.md

Agent Response (GLM-5-Turbo):
  ⚠️ "Both files don't exist (or aren't readable):"
     • /home/.../file1.md — not found
     • /home/.../file2.md — not found
  ℹ️  "No retry attempted as requested."

User Workaround:
  "Use cat /home/.../file1.md"

Agent Response (GLM-5-Turbo via shell):
  ✅ "Here's the content of file1.md. It outlines the core assumptions..."
     [File content successfully displayed]

Key Observation: The agent can access files via cat (shell) but claims they don't exist when asked to use Read tool → Tool selection/routing issue, not a permissions issue.

---

🔬 Root Cause Analysis

Model-Specific Behavior

Model	Read Tool Status	Behavior
GLM-5.3 (Low)	✅ Working	Correctly selects and uses Read tool
GLM-5-Turbo	❌ Broken	Avoids Read tool; uses wrong tools or reports failure

This is NOT a session corruption issue — tested after:

• Clearing all data
• Starting brand-new session
• Re-authorizing workspace (close folder → reopen → re-grant permissions)
• Updating from v3.7.7 → v3.8.1

This IS a model-specific tool selection issue — same session, same files, different results based on model choice.

Hypothesized Causes

┌─────────────────────────────────────────────────────────────┐
│                POSSIBLE ROOT CAUSES                         │├─────────────────────────────────────────────────────────────┤│                                                             ││  Hypothesis 1: Tool Definition Mismatch                     ││  ─────────────────────────────────────────                  ││  • GLM-5-Turbo receives different tool schema than GLM-5.3 ││  • Read tool may be missing from GLM-5-Turbo's tool list    ││  • Or Read tool has incorrect parameters/description        ││                                                             ││  Hypothesis 2: Model Instruction Bias                      ││  ─────────────────────────────────────────                  ││  • GLM-5-Turbo's system prompt may discourage Read usage   ││  • Model may have learned to prefer ReadSessionContext      ││  • Tool ranking/scoring may deprioritize Read for Turbo     ││                                                             ││  Hypothesis 3: Tool Routing Logic                           ││  ─────────────────────────────────────────                  ││  • ZCode's tool router may handle GLM-5-Turbo differently ││  • Permission checks may fail silently for Turbo           ││  • Error handling may intercept Read calls before execution ││                                                             ││  Hypothesis 4: Context Window / Token Issue                 ││  ─────────────────────────────────────────                  ││  • GLM-5-Turbo (200K context) vs GLM-5.3 (1M context)     ││  • Tool definitions may be truncated in smaller context     ││  • Read tool definition may be incomplete/corrupted         ││                                                             │└─────────────────────────────────────────────────────────────┘```

---

## 🧪 Reproduction Steps

### Reliable Reproduction (Confirmed by Reporter)

Prerequisites:

• ZCode v3.8.1 (or v3.7.7+)
• Workspace with existing .md (or any text) files
• GLM-5-Turbo model selected

Steps:

1. Open ZCode with workspace folder (not parent directory)
2. Start new session (to rule out session corruption)
3. Select GLM-5-Turbo as model
4. Ask agent: "Read the file [filename] using the Read tool"
5. Observe behavior

Expected Result (GLM-5.3):
✅ Agent calls Read tool, displays file contents

Actual Result (GLM-5-Turbo):
❌ Option A: Agent says "file not found" without calling Read
❌ Option B: Agent calls ReadSessionContext instead of Read
❌ Option C: Agent loops/fails repeatedly

Control Test (Same Session):
6. Switch model to GLM-5.3 (Low)
7. Ask: "Use the Read tool to open [same filename]"
8. Observe: ✅ Works correctly

Control Test (Shell Workaround):
9. Switch back to GLM-5-Turbo
10. Ask: "Use cat [filepath] to show me the file"
11. Observe: ✅ Works (agent uses shell, not Read)

---

## 🔧 Workarounds

### Workaround 1: Switch to GLM-5.3
```bash
# In ZCode, change model from GLM-5-Turbo to GLM-5.3
# Read tool works correctly with this model

Pros: Full fix for Read tool functionality
Cons: Loses GLM-5-Turbo's speed advantages; different reasoning quality

Workaround 2: Use Shell Commands Instead

# Instead of asking to "read file.md", ask:
"Run: cat /path/to/file.md"
or
"Use bash to display the contents of file.md"

Pros: Works with GLM-5-Turbo; immediate fix
Cons: Not ideal for large files; loses Read tool's structured output; wastes tokens on shell wrapper

Workaround 3: Explicit Tool Call Instruction

# Be extremely explicit (may work sometimes):
"Call the Read tool with path parameter set to '/path/to/file.md'.
Do NOT use any other tool. Do NOT check if file exists first.
Just call Read directly."

Pros: May force correct tool selection
Cons: Still failed in reporter's testing; verbose; shouldn't be necessary

---

✅ Suggested Fix

Immediate (Hotfix)

Investigate tool definition differences between GLM-5.3 and GLM-5-Turbo:

// In ZCode's model adapter, compare tool schemas:
const glm53Tools = getToolDefinitions('GLM-5.3');
const glmTurboTools = getToolDefinitions('GLM-5-Turbo');

console.log('GLM-5.3 tools:', glm53Tools.map(t => t.name));
console.log('GLM-5-Turbo tools:', glmTurboTools.map(t => t.name));
console.log('Read tool diff:', deepDiff(glm53Tools.Read, glmTurboTools.Read));

// Ensure Read tool is present and identical for both models

Short-Term (Next Release)

1. Add tool selection logging — Log which tools are available to each model and which one the model selects
2. Add fallback logic — If model selects wrong tool (e.g., ReadSessionContext for file read), prompt correction
3. Validate tool definitions — On model switch, verify all expected tools are properly registered
4. Error message improvement — When Read fails, show actual error (permission? not found? timeout?) instead of generic "not found"

Long-Term (Architecture)

1. Unified tool layer — All models should see identical tool definitions regardless of model-specific optimizations
2. Tool selection guidance — System prompt should include explicit guidance: "For reading file contents, always use the Read tool, not ReadSessionContext or shell commands"
3. Model-specific tuning — If GLM-5-Turbo needs different prompting, ensure tool usage instructions are adapted accordingly

---

📊 Impact Assessment

Metric	Value
Severity	HIGH — Core file reading broken for GLM-5-Turbo users
Affected Versions	v3.7.7, v3.8.1 (possibly earlier)
Affected Models	GLM-5-Turbo (confirmed); other models untested
Working Models	GLM-5.3 (all variants confirmed working)
User Impact	Cannot use primary fast model for file-heavy tasks
Workaround Available	✅ Yes (switch model or use shell commands)
Regression Risk	Medium — affects tool routing subsystem

---

📋 Additional Technical Details

Session IDs Provided

• Initial report (v3.7.7): sess_b33e34f9-4fa4-4e67-ab03-28d4c7682a3c
• Follow-up test (v3.8.1): sess_a2d2e338-9c55-4e4c-8f0e-224600cf86ed

Troubleshooting Already Attempted (by Reporter)

Attempt	Result
Clear all data	❌ Did not fix
Start new session	❌ Did not fix
Re-authorize workspace (close/reopen folder)	❌ Did not fix
Update v3.7.7 → v3.8.1	❌ Issue persists
Explicit instruction: "Use the Read tool to open "	❌ Still fails on GLM-5-Turbo
Switch to GLM-5.3 Low	✅ Fixes the issue
Use cat command instead of Read	✅ Worksaround on GLM-5-Turbo

---

💡 Additional Context

• ZCode Staff Response: Agnes|Z.ai provided troubleshooting steps (new session, re-auth, explicit instruction, model comparison test)
• Result of Staff Suggestions: Confirmed the issue is model-specific (GLM-5-Turbo) and not session/permissions related
• Agent Apology: Screenshot shows agent saying "sorry for wasting my tokens 😅" — indicates it knows something went wrong but can't self-correct
• Pattern: This suggests the model wants to help but has a systematic block against using Read tool correctly

---

Submitted by:
Regards,
Roman (Discord: bignavi_x)

• Z.ai Volunteer Ambassador
• Tech resources channel: https://t.me/VibeCodePrompterSystem
• Tech Blog: http://claw.rommark.dev/blog

No repository files or tests are named. Reproduce the issue with the GLM-5-Turbo and GLM-5.3 control cases, then inspect the model adapter, tool registration, and routing paths described in the report. Done means GLM-5-Turbo calls Read for existing files without incorrectly using ReadSessionContext or reporting them missing, with coverage for the model comparison.