[FEATURE]:Native Agent-Triggered Session Export

Feature hasn't been suggested before.

• I have verified this feature I'm about to request hasn't been suggested before.

Describe the enhancement you want to request

Note from the author:
I do not speak English fluently. This proposal was drafted with the assistance of DeepSeek (an AI assistant). I am sharing it because I believe it can improve the developer experience for everyone. If you have any questions, feel free to ask me in Portuguese (I'll use a translator) or clarify in English — I'll do my best to follow up. Thank you for your understanding and for building such an amazing tool! 🙏

---

Feature Proposal: Native Agent-Triggered Session Export

1. Overview

Enable the OpenCode agent to automatically export the current session transcript to a project-local directory (e.g., ./conversations/) at the end of each task or upon user request, without requiring additional plugins.

2. Current State & Gap

Capability	Status
Manual export via TUI (/export or Ctrl+X X)	✅ Exists
CLI export: opencode export <session-id>	✅ Exists
CLI export with format (-f markdown) and output (-o <file>)	✅ Exists (PR #32262)
CLI flag to get current session ID (opencode session current)	❌ Does not exist
Agent tool to trigger export natively	❌ Does not exist
Configurable default export directory	❌ Does not exist (Issue #10316)

The gap: The agent cannot programmatically trigger an export because:

1. It has no built-in tool to call opencode export.
2. It cannot reliably obtain the current session ID from the CLI.

3. Proposed Solution

3.1 New CLI Commands

# Get current session ID (returns session ID string to stdout)
opencode session current

# Export current session with project-local defaults
opencode export --current [--format markdown|json] [--output <path>]

3.2 New Agent Tool: session_export

Add a native tool to the agent's toolbox:

// Tool signature
{
  name: "session_export",
  description: "Export the current session transcript to a file",
  parameters: {
    format: { type: "string", enum: ["markdown", "json"], default: "markdown" },
    output_dir: { type: "string", description: "Directory path (default: ./conversations/)" },
    filename: { type: "string", description: "Optional custom filename" }
  }
}

3.3 Configuration Option

Add to opencode.json:

{
  "session": {
    "export": {
      "auto_export": true,
      "format": "markdown",
      "output_dir": "./conversations/",
      "on_task_completion": true,
      "on_compaction": true  // Issue #14164
    }
  }
}

4. Agent Integration: Making It Mandatory

To make session export a mandatory routine in the agent's workflow (without relying on plugins), add the following to AGENTS.md:

## Mandatory Workflow: Session Export

**At the end of every task**, the agent MUST execute:

1. **Get current session ID** (once CLI command is available):
   ```bash
   SESSION_ID=$(opencode session current)

2. Export the session:

   opencode export $SESSION_ID -f markdown -o ./conversations/$(date +%Y-%m-%d_%H-%M-%S)-$SESSION_ID.md
   

3. Verify export:

   ls -la ./conversations/
   

Fallback (if opencode session current is unavailable):

• Use opencode session list to list sessions.
• Identify the most recent session ID (by timestamp).
• Export using that ID.

### 5. Technical Justification

| Requirement | Solution |
|-------------|----------|
| **No external plugins** | Native CLI + agent tool, no npm dependencies |
| **Project-local storage** | Configurable `output_dir` defaults to `./conversations/` |
| **Agent awareness** | Agent tool `session_export` with explicit parameters |
| **Idempotent & safe** | Export only on task completion; skip if already exported |
| **Format flexibility** | Markdown for readability, JSON for programmatic use |
| **Subagent support** | Child sessions can be included inline |
| **Pre-compaction hook** | Auto-export before session compaction |

### 6. Implementation Notes

**Phase 1** (CLI):
- Implement `opencode session current` to return the active session ID.
- Extend `opencode export` with `--current` flag.

**Phase 2** (Agent):
- Add `session_export` tool to the agent's tool registry.
- Tool calls `opencode export --current` internally.

**Phase 3** (Configuration):
- Add `session.export` section to `opencode.json` schema.
- Respect `output_dir` and `format` defaults.

### 7. References

- `opencode export` CLI exists
- `-f/--format` and `-o/--output` flags added in PR #32262
- Feature request for default export directory: #10316
- Pre-compaction auto-export request: #14164
- Plugin `opencode-session-tools` demonstrates session ID retrieval

### 8. Expected Outcome

- Developers can rely on **automatic, agent-driven session exports** without manual intervention.
- Project history is preserved in `./conversations/` for review, debugging, and documentation.
- No additional plugins required — fully native OpenCode functionality.
- The agent workflow becomes **self-documenting**, with every task's transcript saved locally.