feat(agent): interactive TUI launcher + identity + TOOLS.md (#35)

- scripts/agent.sh <name>: launches interactive pi TUI in the container
  with contracts + optional mission + agent identity + named session +
  optional workspace/tools; the Mosaic alternative to vanilla pi
- pi adapter: MOSAIC_INTERACTIVE branch (clean TUI, no -p, no initial
  prompt); headless exec rebuilt via positional args (no word-splitting
  on the request); MOSAIC_AGENT_NAME optional in headless
- loader: AGENT IDENTITY section when the launcher names the agent
- compose: fixed command removed (request defaults live in run-agent.sh);
  MOSAIC_INTERACTIVE/MOSAIC_AGENT_NAME passthrough
- docs/TOOLS.md: full on-demand tool reference; AGENTS.md routes to it
- RELEASE -> 0.0.8 (container change); build verified

Closes #35

adapters/mock/adapter.sh

@@ -6,7 +6,9 @@
 set -eu
 
 [ -n "${MOSAIC_SYSTEM_PROMPT_FILE:-}" ] || { echo "mock adapter: MOSAIC_SYSTEM_PROMPT_FILE is required" >&2; exit 2; }
-[ -n "${MOSAIC_REQUEST:-}" ] || { echo "mock adapter: MOSAIC_REQUEST is required" >&2; exit 2; }
+if [ "${MOSAIC_INTERACTIVE:-}" != "1" ]; then
+    [ -n "${MOSAIC_REQUEST:-}" ] || { echo "mock adapter: MOSAIC_REQUEST is required" >&2; exit 2; }
+fi
 [ -r "$MOSAIC_SYSTEM_PROMPT_FILE" ] || { echo "mock adapter: system prompt not readable: $MOSAIC_SYSTEM_PROMPT_FILE" >&2; exit 2; }
 
 echo "mock adapter: responding verbatim from MOSAIC_MOCK_RESPONSE" >&2

adapters/pi/adapter.sh

@@ -2,16 +2,24 @@
 # Pi adapter: implements the Mosaic adapter contract for the pinned
 # @earendil-works/pi-coding-agent CLI.
 #
-# Contract: see /opt/mosaic/adapters/README.md. stdout = response only.
+# Contract: see /opt/mosaic/adapters/README.md.
+# Headless (default): stdout = response only; stderr = diagnostics; exit 0.
+# Interactive (MOSAIC_INTERACTIVE=1): full pi TUI on the attached terminal.
 set -eu
 
 [ -n "${MOSAIC_SYSTEM_PROMPT_FILE:-}" ] || { echo "pi adapter: MOSAIC_SYSTEM_PROMPT_FILE is required" >&2; exit 2; }
-[ -n "${MOSAIC_REQUEST:-}" ] || { echo "pi adapter: MOSAIC_REQUEST is required" >&2; exit 2; }
 [ -r "$MOSAIC_SYSTEM_PROMPT_FILE" ] || { echo "pi adapter: system prompt not readable: $MOSAIC_SYSTEM_PROMPT_FILE" >&2; exit 2; }
+# MOSAIC_AGENT_NAME is optional in headless mode (identity section is then
+# omitted); interactive launches always set it via scripts/agent.sh.
 
 : "${PI_PROVIDER:?pi adapter: PI_PROVIDER is required}"
 : "${PI_MODEL:?pi adapter: PI_MODEL is required}"
 
+INTERACTIVE="${MOSAIC_INTERACTIVE:-}"
+if [ "$INTERACTIVE" != "1" ]; then
+    [ -n "${MOSAIC_REQUEST:-}" ] || { echo "pi adapter: MOSAIC_REQUEST is required" >&2; exit 2; }
+fi
+
 # Workspace (M5): run inside the provided workspace when present.
 if [ -n "${MOSAIC_WORKSPACE:-}" ]; then
     mkdir -p "$MOSAIC_WORKSPACE"
@@ -39,13 +47,25 @@ fi
 TOOLS_FLAG="--no-tools"
 [ -n "${MOSAIC_TOOLS:-}" ] && TOOLS_FLAG="--tools $MOSAIC_TOOLS"
 
+# Mode (M13): interactive TUI or one-shot print.
+PRINT_MODE="-p"
+REQUEST_ARG=""
+if [ "$INTERACTIVE" = "1" ]; then
+    PRINT_MODE=""
+else
+    REQUEST_ARG="$MOSAIC_REQUEST"
+fi
+
 # All flags documented in the pi package README (CLI Reference):
-#   -p/--print     noninteractive: print the response and exit
+#   -p/--print     one-shot mode: print the response and exit (omitted in
+#                  interactive TUI mode)
 #   --system-prompt  replace the default prompt with the generated one
 #   --no-*         no ambient context/skills/extensions/templates/themes
-#   --no-session   ephemeral; TOOLS_FLAG per capabilities
+#   SESSION_FLAGS  ephemeral | persistent | forked (per env)
+#   TOOLS_FLAG     per capabilities
 #   --offline      no startup network operations (update checks/telemetry)
-exec pi \
+PROMPT_CONTENT="$(cat "$MOSAIC_SYSTEM_PROMPT_FILE")"
+set -- \
     --offline \
     --no-extensions \
     --no-skills \
@@ -56,5 +76,8 @@ exec pi \
     $SESSION_FLAGS \
     --provider "$PI_PROVIDER" \
     --model "$PI_MODEL" \
-    --system-prompt "$(cat "$MOSAIC_SYSTEM_PROMPT_FILE")" \
-    -p "$MOSAIC_REQUEST"
+    --system-prompt "$PROMPT_CONTENT"
+# One-shot mode appends -p and the request (both safely quoted);
+# interactive mode appends nothing - clean TUI.
+[ "$INTERACTIVE" = "1" ] || set -- "$@" -p "$MOSAIC_REQUEST"
+exec pi "$@"