Spike: Leverage MCP 2025-06-18 features for data observability and principle alignment

## Overview
Explore opportunities to incorporate relevant features from the [MCP 2025-06-18 specification](https://modelcontextprotocol.io/specification/2025-06-18/changelog) into our MCP server implementations, focusing on data observability and alignment with our principles rather than security complexity.

## Key Opportunities from MCP 2025-06-18

### 1. **Structured Tool Output** 🎯
- **What**: Tools can now return structured JSON objects instead of just strings
- **Why it matters**: Aligns with **transparency-in-agent-work** principle - structured data makes agent reasoning more observable
- **Use cases in dotfiles**:
- Git operations returning structured commit/diff data
- File system operations returning detailed metadata
- MCP server status/health returning observable metrics

### 2. **Tool Result Metadata** (`_meta` field)
- **What**: Additional metadata can be attached to tool results
- **Why it matters**: Supports **tracer-bullets** principle - each tool call can include trajectory/debugging info
- **Potential uses**:
- Execution timing for performance observability
- Tool call chain tracking
- Decision points and alternatives considered

### 3. **Resource Links in Tool Results**
- **What**: Tools can include links to related resources
- **Why it matters**: Enables **snowball-method** - tools can reference accumulated knowledge
- **Ideas**:
- Link to relevant documentation/procedures
- Reference previous tool calls in the session
- Point to git commits, issues, or PRs created

### 4. **Context Field in Completion Requests**
- **What**: Enhanced context passing between tools
- **Why it matters**: Supports **systems-stewardship** - better context preservation across tool calls
- **Applications**:
- Pass git worktree context between operations
- Maintain tmux session awareness
- Track which principles are guiding current work

## Specific Implementation Ideas

### For our Git MCP Server
```typescript
// Instead of returning string
return "Committed abc123: fix: resolve config issue"

// Return structured data with metadata
return {
content: {
sha: "abc123",
message: "fix: resolve config issue",
files_changed: ["config.json", "README.md"],
stats: { additions: 15, deletions: 3 }
},
_meta: {
execution_time_ms: 234,
principle: "versioning-mindset",
worktree: "/home/user/worktrees/fix-config"
}
}
```

### For File System Operations
```typescript
// Structured output for better observability
return {
content: {
files_written: ["/path/to/file1", "/path/to/file2"],
bytes_written: 1024,
operations: ["create", "update"]
},
_meta: {
timestamp: "2025-01-16T10:30:00Z",
context: "close-issue-123"
}
}
```

## Implementation Approach

1. **Start with backwards compatibility** - Use Zod schemas that support both string and structured output
2. **Incremental adoption** - Update tools one at a time, starting with high-value operations
3. **Focus on observability wins** - Prioritize changes that make agent work more transparent
4. **Document patterns** - Create procedures for consistent structured output across tools

## Questions to Answer

1. Which tools would benefit most from structured output?
2. What metadata would best support our principles (transparency, tracer bullets, etc.)?
3. How can we use resource links to create better knowledge accumulation?
4. Should we create a standard schema pattern for all our MCP tools?

## Success Criteria

- [ ] Agent operations become more observable through structured data
- [ ] Tool outputs align with and reinforce our principles
- [ ] Backwards compatibility maintained for existing clients
- [ ] Clear patterns established for future tool development

## Next Steps

1. Review current MCP server implementations for structured output opportunities
2. Create proof-of-concept with one high-value tool (suggest: git_status or git_diff)
3. Document patterns and create reusable utilities
4. Roll out to other tools based on value/effort ratio

**Principle alignment**: `transparency-in-agent-work`, `tracer-bullets`, `systems-stewardship`

Review the current MCP server implementations and their Zod schemas, starting with the proposed git_status or git_diff proof of concept. Determine which tools benefit from structured output, metadata, and resource links, then document reusable patterns and confirm backward compatibility for existing clients.

Written by the indexing model from the issue text.