feat: agent-initiated session reset via new_session tool

[raykao]

Summary

Add a new_session built-in tool that allows an agent to queue a self-initiated session reset at the end of its current turn. This enables agents to manage context pressure autonomously - saving state, completing their response, then starting a clean session - without requiring human intervention via /new.

---

Problem

Agent sessions accumulate context over time. When a session approaches the context window limit, response quality degrades. Today the only reset path is the human operator issuing /new manually. This means:

• Agents cannot self-manage long-running workflows that naturally exceed one session
• Autonomous pipelines stall or degrade silently rather than recovering cleanly
• Agents cannot signal "I need a fresh start" without interrupting the user

No major agent harness (Claude Code, Gemini CLI, Codex CLI) exposes a self-restart tool to the agent itself. They all rely on human-triggered resets or infrastructure-level supervisors. The bridge owns session lifecycle - this is the right place to close the gap.

---

Proposed Solution

Add a new_session built-in tool with deferred execution semantics: calling the tool does not terminate the current turn. It sets a restart flag that the bridge executes after the turn's response is fully delivered.

Tool contract

// Tool name
new_session

// Parameters
{
  reason?: string   // Optional. Logged for observability. No effect on behavior.
}

// Return value
{
  status: "queued",
  message: "Session reset queued. Will start after this turn completes."
}

Execution flow

1. Agent calls new_session during its turn
   -> Bridge sets restart_queued = true on session state
   -> Tool returns { status: "queued" } immediately
   -> Agent continues - remaining tool calls and response proceed normally

2. Agent finishes turn, sends final response
   -> Bridge delivers response to user channel

3. Bridge checks restart_queued
   -> Tears down current session
   -> Starts new session (same bot, same channel)
   -> sessionStart hook fires
   -> External memory store (Beads, files, etc.) injects handoff context

Key design constraint

new_session queues a restart - it does not fire one immediately. This ensures:

• All tool calls in the turn complete before the session ends
• The response reaches the user before teardown
• No race condition between state persistence and session reset

---

Rationale

Why deferred and not immediate

The intended usage is a sequence: save state -> verify -> call new_session. If the tool fired immediately, the verification step would be cut off. Deferred execution makes the tool safe to use in multi-step turns without special ordering requirements.

Prior art

Harness	Agent-initiated reset?
Claude Code	No - /compact and /new are human-triggered. PreCompact hook is passive.
Gemini CLI	No - /resume is human-triggered.
Codex CLI	No - no session persistence mechanism.
LangGraph	Supervisor-level restart only - not a tool the agent calls.

This is a novel capability at the harness level.

---

Usage via AGENTS.md

The intended pattern is to declare the behavior in the agent's instruction file so it is predictable and auditable.

Example section for an agent's AGENTS.md or system prompt:

## Self-Initiated Session Reset

When context pressure is high or after completing a major task with significant
accumulated context, you may reset your session:

1. Complete all pending work - push commits, close finished tasks
2. Save handoff state to your memory store:
   `bd remember "session-handoff-<timestamp>: <current state summary>"`
3. Verify the save succeeded
4. Call `new_session` as the FINAL tool call of your turn

Rules:
- Never call new_session without first confirming the memory save succeeded
- new_session queues a restart - it does not fire immediately
- All prior tool calls in the turn complete normally
- The session restarts after your response is delivered

---

Acceptance Criteria

• new_session tool is registered and visible to the agent when enabled
• Calling new_session returns { status: "queued" } without terminating the turn
• Subsequent tool calls after new_session in the same turn complete normally
• The response is delivered to the user before the session restarts
• A new session starts after response delivery (same bot, same channel)
• The sessionStart hook fires on the new session
• Bridge logs the restart event including the optional reason value
• Behavior is unchanged for sessions that never call new_session
• Opt-in per bot via config (default: false)

---

Configuration

{
  "bots": [
    {
      "name": "bob",
      "tools": {
        "new_session": { "enabled": true }
      }
    }
  ]
}

Default false - the tool does not appear in agent context unless explicitly enabled.