docs: garden repository notes (#48)

* docs: record R graphics device decision

* docs: add plugin skill bundle futurework

* Add Glossary to AGENTS.md

* futurework: server-worker boundary

* Add Codex install network defaults futurework

* Add project-local mcp-repl config futurework

* Refine client config futurework notes

* docs: add futurework notes for sessions

Author: t-kalinowski

AGENTS.md

@@ -22,6 +22,38 @@ Keep this file short. It is a table of contents, not the full manual.
 - `docs/sandbox.md`: sandbox modes and writable-root policy.
 - `docs/plans/AGENTS.md`: when to create checked-in execution plans.
 
+## Glossary
+
+- Agent: The model-facing actor using an MCP client to call `repl` or `repl_reset`.
+- MCP client: Codex, Claude, or another app that starts `mcp-repl` over MCP stdio and sends tool calls.
+- Server: The main `mcp-repl` Rust process in MCP server mode. It owns the MCP surface, worker lifecycle, sandbox application, timeout policy, stdout/stderr capture, sideband interpretation, and response finalization.
+- Worker: The child process spawned by the server to run the selected R or Python REPL. It runs inside the effective sandbox and owns the worker-side endpoint of sideband IPC.
+- Worker child process: Any direct or indirect process spawned by user code or the backend under the worker. It may inherit stdout/stderr, but it must not own sideband IPC.
+- Backend / interpreter: `backend` is the worker-side implementation that presents a selected REPL runtime to the server and MCP client. `interpreter` is the user-facing selector for that presented runtime, currently `r` or `python`; it does not describe the implementation language of the worker binary.
+- Runtime: The live R or Python execution environment inside the worker. This is where client-submitted code via `repl` is evaluated.
+- REPL session: The stateful runtime in the active worker. One session per worker process instance.
+- Tool call: One MCP client invocation of `repl` or `repl_reset`.
+- Request: The unit of input accepted by the server for the worker to execute. A request may outlive the initial tool call when it times out and later polls drain output.
+- Reply: The MCP tool result returned to the client. Reply finalization is server-owned and may combine worker-originated content with server-only status notices.
+- Poll: An empty `repl` input used to drain pending output, wait again on a previously timed-out request, return idle status, or advance pager mode.
+- Host: The user's machine and OS environment outside the worker sandbox. Avoid `host-owned` unless the owner is explicitly distinguished from the MCP client, server, worker, and OS/user.
+- Sandbox policy: The effective OS-level permissions applied to the worker: `read-only`, `workspace-write`, `danger-full-access`, or `external-sandbox`.
+- Sandbox metadata: Codex per-tool-call `_meta["codex/sandbox-state-meta"]` used by `--sandbox inherit` to choose the effective worker sandbox for that call.
+- Writable root: An absolute path that a `workspace-write` worker may write, subject to forced read-only subpaths like `.git`, `.codex`, and `.agents`.
+- Session temp directory: The server-allocated per-session temp path exposed to the worker as `TMPDIR` and `MCP_REPL_R_SESSION_TMPDIR`.
+- Sideband IPC: The JSON-lines server/worker pipe for structural facts such as `readline_start`, `readline_result`, `plot_image`, `request_end`, and `session_end`.
+- stdout/stderr pipes: The normal process output streams captured by the server. They are the authoritative visible text source; sideband only helps interpret them.
+- Output timeline: The server-side reconstruction of visible output order from captured stdout/stderr plus sideband facts.
+- Server-owned: State, files, or notices created and retained by the main server process, not by the runtime or the worker. Use this for output bundles, response finalization, debug logs, and server temp roots.
+- Worker-originated text: Text that came from the worker REPL or worker child processes and can be written to `transcript.txt`.
+- Server-originated text: Status text synthesized by the server, such as timeout, busy, restart, sandbox, or bundle notices. Also called server-only text when contrasting with worker-originated transcript text.
+- Output bundle: A server-owned directory for oversized (potentially mixed text/image) output in files mode, with a bounded inline preview plus inspectable files.
+- `transcript.txt`: Bundle file containing worker-originated REPL text only, including echoed input, prompts, stdout, and rendered stderr text.
+- `events.log`: Bundle index for mixed text/image history. `T` rows point into `transcript.txt`, `I` rows point to image history, and `S` rows are server-originated omission notices.
+- Files mode / pager mode: `--oversized-output files` spills large replies into output bundles; `--oversized-output pager` keeps oversized text in an interactive pager that consumes tool-call input locally instead of forwarding it to the worker until the pager exits or reaches the end.
+- Debug REPL: `--debug-repl`, a local interactive driver for the worker that bypasses MCP client/server traffic.
+- Wire trace: The external stdio proxy log of exact bytes between an MCP client and the `mcp-repl` server.
+
 ## Snapshot Workflow
 
 - Preferred loop:

docs/futurework/claude-sandbox-inherit.md

@@ -0,0 +1,65 @@
+# Claude Sandbox Inherit
+
+## Motivation
+
+Claude users should not have to describe the same sandbox policy twice. If a
+project already has Claude sandbox settings, `mcp-repl` should be able to use
+the equivalent policy for its worker when Claude starts the MCP server.
+
+Minimal task:
+
+1. A project has Claude settings in `.claude/settings.json` or
+   `.claude/settings.local.json`.
+2. The user runs `mcp-repl install --client claude`.
+3. The generated MCP config starts `mcp-repl` in a Claude-inherit mode.
+4. The server reads the effective Claude sandbox shape for the active project.
+5. The worker uses the corresponding `mcp-repl` sandbox and managed-network
+   policy, or fails closed when the shape cannot be represented safely.
+
+## Current Shape
+
+- Claude install currently writes `.claude.json` MCP server entries and updates
+  `.claude/settings.json` permissions so Claude can call the generated tools.
+- Claude install uses an explicit `mcp-repl` sandbox mode because Claude does
+  not send Codex-style per-tool-call sandbox metadata to MCP servers.
+- Claude's public settings shape is JSON, not TOML. Project settings live under
+  `.claude/settings.json` and `.claude/settings.local.json`, and sandbox options
+  are nested under `sandbox`.
+- Claude sandbox settings include network-related fields such as local binding
+  and proxy ports. Filesystem and network intent may also interact with Claude
+  permission rules.
+
+Reference: <https://docs.claude.com/en/docs/claude-code/settings>
+
+## Notes
+
+- This should be a separate feature from managed-network install defaults.
+- Claude's sandbox implementation and documentation are useful prior art for
+  this feature. Re-inspect the current Claude source or docs when implementing
+  instead of preserving stale assumptions about settings shape or permission
+  semantics.
+- Decide whether to add a Claude-specific inherit mode, for example
+  `--sandbox inherit-claude`, or to extend `--sandbox inherit` with a documented
+  client source.
+- Claude inheritance is likely startup/project scoped, not per-tool-call scoped,
+  unless Claude later sends sandbox metadata with MCP tool calls.
+- Do not silently broaden permissions. If the Claude settings shape cannot be
+  mapped to `mcp-repl` sandbox state, fail closed or require explicit
+  `mcp-repl` config.
+- Preserve Claude settings precedence. If implementation reads settings files
+  directly, it needs a tested merge order for user, project, local project, and
+  managed settings, or it needs to consume an already-resolved Claude-provided
+  shape.
+- Keep the first slice small. A reasonable first pass could map sandbox enabled
+  state, local binding, and managed proxy ports before attempting full
+  permission-rule parity.
+
+## Acceptance Shape
+
+- Add fixture tests for representative Claude settings files.
+- Add an install test showing `mcp-repl install --client claude` can write the
+  selected Claude-inherit mode.
+- Add a sandbox test proving unsupported or broader-than-representable Claude
+  settings fail closed.
+- Add a runtime smoke test showing a supported Claude sandbox setting affects
+  the worker sandbox as expected.

docs/futurework/claude-session-lifecycle-and-integration.md

@@ -0,0 +1,103 @@
+# Claude Session Lifecycle And Integration
+
+## Motivation
+
+`mcp-repl` should behave predictably in Claude Code even though Claude does not
+currently expose all client lifecycle events or agent identities through MCP.
+The important workflows are session reset on `/clear`, reliable install/tool
+visibility, and clear documentation of shared-session behavior for subagents.
+
+## Target Scenarios
+
+### `/clear` Resets The Runtime
+
+Minimal task:
+
+1. A user starts Claude Code with `mcp-repl` installed.
+2. The agent creates runtime state through the `repl` tool.
+3. The user runs `/clear` in Claude Code.
+4. The next `repl` call uses a fresh worker session.
+
+MCP does not define a `/clear` notification, and Claude does not currently send
+one to MCP servers. A Claude-specific implementation would need to use Claude
+hooks:
+
+- a `SessionStart` hook injects the Claude session ID into the environment,
+- `mcp-repl` records the active REPL control endpoint for that session ID,
+- a `SessionEnd` hook looks up that endpoint and asks `mcp-repl` to restart the
+  worker externally.
+
+Codex already closes and restarts MCP connections on `/clear`, so this is a
+Claude-specific lifecycle bridge rather than a general MCP requirement.
+
+### Claude Subagents Share A REPL Session
+
+Current Claude subagents share the same MCP connection as the main agent. Since
+`mcp-repl` owns one long-lived runtime per MCP server connection, those subagents
+also share the same REPL session.
+
+There is no clean server-side fix under the current Claude MCP shape. Tool calls
+do not include a stable agent or subagent ID. `toolUseId` might be correlated by
+polling Claude transcript files, but that would be brittle and should not be
+implemented as the happy path.
+
+If Claude later sends a stable agent identity on MCP tool calls, revisit
+per-agent worker routing. Until then, document the shared session in installer
+output, the plugin skill, or Claude-specific guidance.
+
+### Install And Protocol Drift Stay Covered
+
+Minimal task:
+
+1. A user runs `mcp-repl install --client claude`.
+2. A fresh Claude Code session shows the installed R and Python tools.
+3. A one-call smoke test succeeds for each installed interpreter.
+4. A raw MCP `initialize` request with normal JSON-RPC shape succeeds.
+
+The March 2026 install regression and initialize-handshake bug were both caused
+by client/protocol drift not being covered by the same integration surface as
+Codex. Future changes to install code, server initialization, and tool
+description registration should include Claude coverage when practical.
+
+### Claude Permission Snippets Stay Current
+
+Claude Code permission syntax can change independently of `mcp-repl`. Generated
+or documented Claude permission snippets should avoid known-deprecated patterns
+such as the old `:*` suffix and should be checked against the current Claude
+syntax when touched.
+
+## Current Public Reset Surface
+
+- `repl_reset` explicitly restarts the runtime.
+- `\u0003` interrupts the current runtime request.
+- `\u0004` resets the runtime and runs any remaining input in the fresh
+  session.
+- `q()` or EOF exits the runtime; the next request starts a fresh worker.
+- Claude's `/mcp reconnect` exists as a user command, but there is no known
+  programmatic hook for an MCP server to trigger it.
+
+## Constraints
+
+- Do not depend on MCP behavior that is not in the spec unless the feature is
+  clearly Claude-specific and tested as such.
+- Do not implement transcript polling to infer subagent identity.
+- Do not broaden sandbox or network policy as part of lifecycle handling.
+- Keep the runtime reset action server-owned. Hook scripts should only signal
+  the already-running `mcp-repl` instance.
+
+## Acceptance Shape
+
+- Add install tests or smoke coverage showing Claude config generation still
+  exposes the expected tools.
+- Add a protocol test for the raw `initialize` request shape that previously
+  failed.
+- If `/clear` support is implemented, add hook fixture tests and a manual smoke
+  scenario for Claude Code.
+- Add skill or installer text that states Claude subagents share one REPL
+  session under the current client behavior.
+
+## Non-Goals
+
+- Per-subagent REPL sessions for Claude before Claude exposes stable agent IDs.
+- A generic MCP `/clear` protocol extension.
+- Programmatically driving Claude's `/mcp reconnect` command from `mcp-repl`.

docs/futurework/external-mcp-console-config.md

@@ -20,6 +20,9 @@ The important future tasks are:
 - Let the runtime call an explicitly allowed local service, such as a local API
   used by tests or examples, without also allowing arbitrary remote network
   access.
+- Support a restricted read-only web/data-fetching shape where the runtime can
+  perform HTTP GET requests to allowed hosts but cannot make state-changing
+  requests such as POST.
 
 This note is not a final design. It records the target scenarios, current
 constraints, and implementation tradeoffs so the next slice can choose an
@@ -84,6 +87,24 @@ Minimal task:
 This needs explicit loopback connect permission. It is separate from Shiny app
 iteration, where the worker binds a port and a browser tool connects to it.
 
+### GET-Only Web Access
+
+Minimal task:
+
+1. Start `mcp-repl` with a policy that allows HTTP(S) access to a specific host
+   for read-only retrieval.
+2. The agent asks the runtime to download or inspect a public data resource.
+3. GET requests to the allowed host succeed.
+4. POST, PUT, DELETE, and other non-GET methods fail closed.
+5. Requests to unrelated hosts still fail closed.
+
+This is a distinct policy from domain allowlisting. For plain HTTP proxy
+requests, the proxy can see and enforce the method. For ordinary HTTPS
+`CONNECT`, the proxy sees only the tunnel endpoint, not the inner HTTP method.
+Enforcing GET-only semantics for HTTPS would require TLS interception,
+package/client-specific integration, a controlled mirror, or another design
+that makes request methods visible.
+
 ## Current Shape
 
 - The server starts a server-owned HTTP/SOCKS proxy when domain allow/deny rules
@@ -138,6 +159,9 @@ Open boundaries found during the same investigation:
 - Managed package/web access, explicit TCP connect, and local app serving are
   different capabilities. They may need different policy fields and different
   enforcement paths.
+- HTTP method restrictions, such as GET-only web access, are a separate
+  capability from host/domain allowlisting. Do not imply method-level
+  enforcement for HTTPS until the implementation can actually see the method.
 - Tools that honor proxy environment variables should work transparently.
   Tools that ignore them must still be constrained by the OS sandbox.
 - Local database connect does not imply local app bind. Local app bind does not
@@ -232,6 +256,8 @@ These are implementation options, not a prescribed roadmap.
   example `db.example.com:5432`.
 - Split local loopback connect from local loopback bind/inbound permissions, so
   database workflows and Shiny workflows can be enabled independently.
+- Add GET-only enforcement for visible HTTP proxy requests, with HTTPS support
+  deferred until there is a concrete TLS-visibility or controlled-mirror design.
 - Restrict HTTP `CONNECT` to package-repository-shaped traffic, such as port
   443 by default, unless an explicit TCP policy grants a different port.
 - Add TLS ClientHello SNI validation for `CONNECT` to reduce host/SNI mismatch
@@ -251,6 +277,7 @@ Choose the next design by starting from one concrete task. Good first slices are
 - explicit TCP connect for one database endpoint,
 - explicit loopback bind/inbound for Shiny app iteration,
 - explicit loopback connect for one local service endpoint,
+- GET-only enforcement for plain HTTP plus a documented HTTPS limitation,
 - TLS SNI gating for the existing package-repository proxy path.
 
 Each slice should include a minimal end-to-end scenario that proves the intended