🤖 Add educational note when bash commands use cd

[ammar-agent]

Better UX: Teach instead of block

Instead of blocking redundant cd commands with complex heuristics (which had false positives), we now add an agent-only note field to results when commands start with cd. This educates the agent about the execution model without blocking legitimate commands.

Approach

Problem: Agents don't understand that cd doesn't persist between bash tool calls, leading to redundant cd commands.

Solution: Inform rather than restrict.

1. Detect cd usage: Simple regex checks if command starts with cd
2. Add note field: Include educational message in tool result
3. Agent sees, user doesn't: Note appears in tool result JSON for agent, but UI doesn't display it
4. Agent learns: Explicit feedback about how the execution model works

Example

Agent executes:

cd ~/workspace/project/branch && ls

Tool result:

{
  "success": true,
  "output": "file1.txt\nfile2.txt",
  "exitCode": 0,
  "wall_duration_ms": 45,
  "note": "Note: Each bash command starts in ~/workspace/project/branch. Directory changes (cd) do not persist between commands."
}

User sees in UI:

file1.txt
file2.txt

Agent learns: "Oh, I don't need to cd every time, I'm already in the right directory."

Advantages

Aspect	This approach	Previous (blocking)
False positives	Zero (no heuristics)	Had false positives with short paths
Agent learning	✅ Explicit education	❌ Just blocked without explanation
Works for all cds	✅ Yes (even legitimate ones)	❌ Only redundant cds
Complexity	~15 LoC	~40 LoC with heuristics
User experience	✅ Clean (note hidden)	✅ Clean
Maintenance	✅ Simple regex	⚠️ Complex path matching

Changes

• src/types/tools.ts: Added note?: string field to BashToolResult (+2 lines)
• src/services/tools/bash.ts: Detect cd and add note to success results (+5 lines, -38 lines of heuristics)
• src/services/tools/bash.test.ts: Removed blocking tests, added note verification tests (-259 lines, +2 new tests)

Net change: -275 LoC (much simpler!)

Testing

# Type checking
make typecheck  # ✅ Pass

# Linting
make lint       # ✅ Pass

Test cases:

• ✅ Verify note appears when command starts with cd
• ✅ Verify note absent when command doesn't start with cd
• ✅ All existing tests pass

Why this is better

The original heuristic approach tried to detect redundant cd commands by comparing paths, but:

• Had false positives (e.g., ~/project matched /unrelated/project)
• Only worked for redundant cds, not legitimate directory changes
• Required complex path matching logic

This approach:

• No false positives: Works for ALL cd commands
• More educational: Agent learns the execution model
• Simpler code: No complex heuristics
• Better UX: Clean separation of agent vs user concerns

Generated with cmux

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".