---
id: SMH-PLAN-CORE0001
type: plan
title: "Core Session and Tool Effects"
spec: SMH-SPEC-SPEC0001
status: approved
depends_on: [SMH-PLAN-WSPC0001]
---

# Core Session and Tool Effects

## Entry

- Workspace shells and architecture gates exist.
- No provider or interface is required.

## Order

1. Define shared IDs, messages, normalized stream events, tool metadata, cancellation, and recoverable errors in `smith`.
2. Add validated runtime configuration types without loading plugins.
3. Add the `smith-core` session model, selected branch, and in-memory restoration.
4. Add deterministic length-prefixed CBOR framing with bounded decode and opaque unknown-frame retention.
5. Add append, load, fork, repair, and writer serialization around the session store.
6. Add replay-relevant trace records without implementing presentation.
7. Add the tool registry and lifecycle event boundary.
8. Add read, write, exact edit, list, find, and grep effects.
9. Add bounded cancellable bash execution after file effects are stable.

## Interfaces

- `smith`: provider-neutral values, errors, cancellation, and tool contracts.
- `smith-core::session`: branch state and durable frame operations.
- `smith-core::trace`: ordered replay evidence.
- `smith-core::tools`: registration, validation, invocation, and recorded outcomes.

## Verification

- Equivalent sessions encode identically.
- Complete frames survive truncated tails; unknown frames round-trip unchanged.
- Corrupt or oversized frames cannot trigger unbounded allocation or scanning.
- Concurrent writers cannot interleave frames or lose committed entries.
- Fork and in-memory restoration preserve IDs, order, leaf, and compaction boundary.
- File mutations are atomic and exact edit rejects stale or ambiguous input.
- Tool effects and their durable outcomes cannot disagree silently.
- Bash timeout and cancellation terminate the owned process tree where supported and retain late output.

## Exit

Provider-free tool activity can be persisted, recovered, and reconstructed deterministically.

## Stop conditions

- Frame recovery semantics remain ambiguous.
- A successful mutation cannot be coupled to a durable outcome.
- Cancellation ownership across a tool effect is unclear.