mia-code 0.2.0 → 0.3.0

package/rispecs/borrowed_from_opencode/044-plan-mode-tool.rispec.md

@@ -0,0 +1,139 @@
+# RISE-044: Plan Mode Tool
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/044-plan-mode-tool.rispec.md
+
+## Creative Intent
+
+mia-code provides tools for entering and exiting a dedicated planning mode where the agent operates in read-only mode. In plan mode, the agent can read files, search code, analyze architecture, and generate detailed implementation plans — but it cannot modify files, run destructive commands, or alter project state. This creates a safe space for exploration and analysis before committing to action. The transition between plan and build modes is explicit and visible, giving the developer confidence about when the agent is observing versus acting.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- mia-code has no distinction between analysis and execution — the agent can read and write at any time
+- Developers who want "just look, don't touch" must verbally instruct the agent, which is unreliable
+- There is no visual indicator of whether the agent is in an analysis or execution mindset
+- The agent may begin editing files before fully understanding the codebase — premature action
+- No mechanism to generate a plan as a structured artifact before executing it
+- Accidental file modifications during exploration require manual reversion
+
+**Desired State:**
+- A `plan_enter` tool switches the agent to read-only mode with analysis-focused prompting
+- A `plan_exit` tool returns the agent to build mode with full permissions restored
+- During plan mode: file reads, code search, and analysis are enabled; file writes and destructive commands are disabled
+- Plan mode output emphasizes: observations, recommendations, structural analysis, and implementation plans
+- A visual indicator (e.g., `[PLAN]` prefix) shows plan mode is active in the UI
+- Plan mode can generate todo items (RISE-043) for build mode execution
+
+## Desired Outcome Definition
+
+The developer types `/plan`. The agent enters plan mode — the prompt changes to `[PLAN] >`, file write tools are disabled, and the system prompt shifts to analysis focus. The developer asks "how should we restructure the auth module?" The agent reads files, analyzes dependencies, and produces a structured plan with 6 implementation steps — each created as a todo item. The developer types `/build`, the agent exits plan mode, reads the todos, and begins executing step 1.
+
+## Natural Language Functional Description
+
+### Plan Mode Entry
+
+```typescript
+interface PlanEnterInput {
+  focus?: string;     // optional focus area for the analysis prompt
+}
+```
+
+When `plan_enter` is invoked:
+
+1. **Permission restriction** — the agent's permission ruleset is temporarily replaced with a read-only variant:
+   - File read: allowed
+   - File write: denied
+   - Code search: allowed
+   - Bash execution: restricted to read-only commands (ls, cat, find, grep — not rm, mv, write operations)
+   - Web fetch: allowed (reading documentation is part of planning)
+2. **Prompt augmentation** — the system prompt gains plan-mode instructions:
+   - "You are in PLAN mode. Analyze, observe, and recommend — do not modify files or execute destructive commands."
+   - "Structure your analysis with clear sections: Current State, Issues, Recommendations, Implementation Steps."
+   - "Create todo items for each implementation step to prepare for build mode."
+3. **UI indicator** — the prompt prefix changes to `[PLAN]` and a status bar shows "Plan Mode Active"
+4. **Event emission** — `mode.changed` event with `{mode: "plan"}` is broadcast (RISE-002)
+
+### Plan Mode Exit
+
+```typescript
+interface PlanExitInput {}  // no parameters needed
+```
+
+When `plan_exit` is invoked:
+
+1. **Permission restoration** — the agent's original permission ruleset is restored
+2. **Prompt restoration** — the plan-mode system prompt additions are removed
+3. **UI indicator** — the prompt returns to normal, status bar shows "Build Mode"
+4. **Event emission** — `mode.changed` event with `{mode: "build"}` is broadcast
+5. **Todo awareness** — the agent is prompted to check for pending todos created during planning
+
+### Plan Mode Analysis Patterns
+
+During plan mode, the agent follows analysis-oriented patterns:
+
+**Architecture Analysis:**
+- Read key files (entry points, configs, type definitions)
+- Map dependency relationships
+- Identify patterns and anti-patterns
+- Note coupling points and separation concerns
+
+**Codebase Assessment:**
+- Search for code smells (duplicated code, large files, complex functions)
+- Identify test coverage gaps
+- Review documentation completeness
+- Assess dependency health
+
+**Implementation Planning:**
+- Break work into discrete, ordered steps
+- Identify dependencies between steps
+- Estimate complexity per step
+- Create todo items with detailed descriptions
+
+### Slash Commands
+
+Plan mode integrates with the slash command system:
+
+- `/plan` — equivalent to invoking `plan_enter` with no focus
+- `/plan auth module` — enters plan mode with focus on auth module
+- `/build` — equivalent to invoking `plan_exit`
+- `/mode` — shows current mode (plan or build)
+
+### Integration with Todo Tool
+
+Plan mode is designed to feed into the todo tool (RISE-043):
+
+```
+During plan mode, the agent creates:
+  1. [todo] Install JWT dependencies (priority: high)
+  2. [todo] Create token utility module (priority: high)
+  3. [todo] Refactor auth middleware (priority: high)
+  4. [todo] Update route handlers (priority: medium)
+  5. [todo] Add integration tests (priority: medium)
+  6. [todo] Update API documentation (priority: low)
+```
+
+When build mode is entered, these todos guide execution in order.
+
+## Supporting Structures
+
+- **Tool Registry (RISE-034)** registers plan_enter and plan_exit tools
+- **Agent Permission Rulesets (RISE-011)** provides the read-only permission variant
+- **Plan/Build Mode Toggle (RISE-014)** defines the broader mode switching architecture
+- **Todo Tool (RISE-043)** captures plan outputs as actionable items
+- **Event Bus (RISE-002)** broadcasts mode change events to UI and clients
+- **Keybinding System (RISE-063)** can bind a key to toggle plan/build mode
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Safe Exploration:**
+A new developer opens an unfamiliar codebase and enters plan mode. They ask "explain the architecture." The agent reads key files, maps the module structure, and produces a clear architectural overview — without any risk of accidentally modifying code during its exploration.
+
+**Scenario 2 — Plan-Then-Execute:**
+The developer enters plan mode and asks "how should we add WebSocket support?" The agent analyzes the current HTTP setup, identifies integration points, and creates 7 todo items. The developer reviews the plan, adjusts priorities, then enters build mode. The agent begins executing the plan from the todos — the transition from analysis to action is clean and intentional.
+
+**Scenario 3 — Code Review Mode:**
+A developer enters plan mode to review a colleague's recent changes. The agent reads the diff, analyzes the changes, identifies potential issues, and writes a structured review — all without modifying any files. Plan mode is naturally suited for read-only review workflows.
+
+**Scenario 4 — Interrupted Planning:**
+The developer enters plan mode and starts analyzing the database layer. Mid-analysis, they realize they need to fix a quick bug. They type `/build`, fix the bug, then `/plan` to resume analysis. The mode toggle is instant and non-destructive — the conversation context includes both the plan analysis and the bug fix.

package/rispecs/borrowed_from_opencode/045-task-tool.rispec.md

@@ -0,0 +1,146 @@
+# RISE-045: Background Task Tool
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/045-task-tool.rispec.md
+
+## Creative Intent
+
+mia-code provides a task tool that spawns sub-agents to execute work in the background while the main conversation continues. The developer asks a complex question, and instead of blocking for minutes while the agent researches, the task tool launches a sub-agent in a separate context, returns a task ID immediately, and delivers results when ready. Multiple tasks can run concurrently — exploring one part of the codebase while refactoring another. Each task runs in an isolated context with its own tool access, and results are summarized to keep the main conversation clean.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- All agent work is synchronous — the developer waits while the agent processes each request
+- Complex multi-step tasks (full codebase analysis, large refactorings) block the conversation for minutes
+- There is no way to run parallel workstreams — exploring and building cannot happen simultaneously
+- Failed tasks produce verbose error output that pollutes the conversation context
+- The developer cannot ask a follow-up question while the agent is processing the previous one
+
+**Desired State:**
+- A `task` tool launches sub-agents in separate contexts for background execution
+- The tool returns a task ID immediately — the main conversation is unblocked
+- Three task types: "explore" (read-only analysis), "task" (command execution), "general" (full capability)
+- Tasks run in isolated contexts — they don't see subsequent main conversation messages
+- Results are summarized: success returns a brief summary; failure returns full output for debugging
+- Multiple tasks can run concurrently with independent completion
+- Task status can be queried at any time
+
+## Desired Outcome Definition
+
+The developer asks two things: "analyze the test coverage" and "refactor the logger module." The agent launches two background tasks — an explore task for coverage analysis and a general task for refactoring. Both run concurrently. The coverage analysis completes first and returns "Coverage: 73% overall, gaps in auth/ and billing/." The refactoring completes moments later with "Refactored logger.ts into 3 modules, updated 12 imports." The main conversation stays clean and responsive throughout.
+
+## Natural Language Functional Description
+
+### Input Format
+
+```typescript
+interface TaskInput {
+  description: string;                           // task description/prompt
+  agentType?: "explore" | "task" | "general";   // sub-agent type (default: "general")
+  model?: string;                                // optional model override
+}
+```
+
+### Task Types
+
+**Explore** — read-only codebase analysis. The sub-agent can read files, search code, and analyze architecture but cannot modify anything. Uses a fast/cheap model by default for rapid iteration. Best for: "find all files that use X", "explain how Y works", "map the dependency graph."
+
+**Task** — command execution with brief output. The sub-agent can run commands, read/write files, and execute tools. On success, returns a brief summary ("All 247 tests passed", "Build succeeded in 12s"). On failure, returns full output (stack traces, compiler errors). Best for: "run the tests", "build the project", "lint and fix."
+
+**General** — full-capability agent in a separate context. Uses the primary model for high-quality reasoning. Can perform complex multi-step work requiring analysis, planning, and execution. Best for: "refactor this module", "implement this feature", "review and fix these issues."
+
+### Task Lifecycle
+
+1. **Launch** — the main agent calls the task tool with a description and type
+2. **Return** — the tool returns immediately with a task ID: `{taskId: "task_abc123", status: "running"}`
+3. **Execution** — the sub-agent works independently in its own context
+4. **Completion** — results are stored and the main agent is notified
+5. **Retrieval** — the main agent reads results via `task_result` or they are injected automatically
+
+### Task Context Isolation
+
+Each task runs in an isolated context:
+
+- **Own message history** — the sub-agent starts with the task description as its first message
+- **Own tool access** — filtered by the task type's permission level
+- **Own model** — configurable, defaults based on task type
+- **No cross-talk** — messages sent in the main conversation after task launch are not visible to the task
+- **Shared filesystem** — the task operates on the same project directory
+
+This isolation means tasks are reproducible and predictable — they don't depend on conversation state that may change during execution.
+
+### Result Summarization
+
+Task results are formatted based on outcome:
+
+**Success (brief):**
+```json
+{
+  "taskId": "task_abc123",
+  "status": "completed",
+  "summary": "Found 23 files importing SessionStore. Largest consumers: routes.ts (7 imports), middleware.ts (5 imports).",
+  "duration": "4.2s"
+}
+```
+
+**Failure (detailed):**
+```json
+{
+  "taskId": "task_def456",
+  "status": "failed",
+  "error": "Build failed with 3 errors",
+  "output": "src/auth.ts:42 - error TS2345: Argument of type...\nsrc/routes.ts:18 - error TS2304...",
+  "duration": "8.1s"
+}
+```
+
+Success produces minimal output to preserve main conversation context. Failure produces full output because debugging requires detail.
+
+### Concurrent Execution
+
+Multiple tasks can run simultaneously:
+
+```
+Main conversation:
+> Agent: I'll analyze coverage and refactor the logger in parallel.
+  → Launched task_001 (explore): "analyze test coverage"
+  → Launched task_002 (general): "refactor logger module"
+> Developer: while those run, what's the status of the auth PR?
+> Agent: [answers immediately, not blocked by tasks]
+  ← task_001 completed: "Coverage: 73%, gaps in auth/ and billing/"
+  ← task_002 completed: "Refactored logger.ts into 3 modules, updated 12 imports"
+```
+
+### Status Querying
+
+The main agent can check task status at any time:
+
+```typescript
+interface TaskStatusInput {
+  taskId: string;
+}
+// Returns: { taskId, status: "running" | "completed" | "failed", result?: ... }
+```
+
+## Supporting Structures
+
+- **Tool Registry (RISE-034)** registers the task tool with id `task`
+- **Multi-Agent System (RISE-009)** provides the sub-agent framework that tasks use
+- **Sub-Agent Task Delegation (RISE-015)** defines the delegation protocol
+- **Agent Permission Rulesets (RISE-011)** enforce per-task-type permission boundaries
+- **Event Bus (RISE-002)** notifies the main conversation when tasks complete
+- **Tool Context Injection (RISE-035)** provides cancellation via abort signal
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Parallel Exploration:**
+The developer asks "summarize the auth module and the billing module." The agent launches two explore tasks concurrently. Both complete within seconds, and the agent presents a side-by-side comparison. Serial execution would have taken twice as long.
+
+**Scenario 2 — Non-Blocking Build:**
+The agent makes code changes and launches a task: "run the test suite." While tests run (30 seconds), the developer asks a question about the codebase. The agent answers immediately. When tests complete, results appear: "247 passed, 2 failed" with the failure details.
+
+**Scenario 3 — Complex Refactoring Delegation:**
+The main agent identifies 3 independent refactoring tasks. It launches each as a general task with a detailed description. All 3 run concurrently, each with full tool access. The main conversation coordinates and verifies results as they complete.
+
+**Scenario 4 — Graceful Cancellation:**
+A task is taking too long. The developer says "cancel that search." The agent cancels the task via its abort signal. The task sub-agent stops gracefully and returns partial results.

package/rispecs/borrowed_from_opencode/046-question-tool.rispec.md

@@ -0,0 +1,170 @@
+# RISE-046: User Question Tool
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/046-question-tool.rispec.md
+
+## Creative Intent
+
+mia-code provides a question tool that lets the agent ask the user questions during execution — pausing to gather information, confirm decisions, or get preferences rather than guessing. When the agent encounters ambiguity, needs clarification, or faces a decision with multiple valid paths, it uses this tool to present a clear question and wait for the user's response. The tool supports both multiple-choice questions (for fast, structured answers) and freeform input (for open-ended responses). This creates a collaborative dialogue where the agent asks for what it needs instead of making potentially wrong assumptions.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- The agent cannot ask questions during tool execution — it must complete its response before the user can input
+- When facing ambiguity (which config format? which migration strategy?), the agent guesses or picks arbitrarily
+- There is no structured way for the agent to present choices — it embeds questions in free text and hopes the user notices
+- Multiple-choice questions appear as plain text, requiring the user to type exact strings to respond
+- The agent cannot pause mid-operation to confirm a destructive action with specific context
+
+**Desired State:**
+- A `question` tool pauses execution, presents a question to the user, and returns their answer
+- Multiple-choice questions display as selectable options with keyboard navigation
+- Freeform input allows open-ended answers with optional validation
+- Questions are formatted distinctively in the UI — clearly separated from agent output
+- Configurable timeout prevents indefinite blocking if the user doesn't respond
+- The agent uses questions strategically — not for every decision, but for genuinely ambiguous ones
+
+## Desired Outcome Definition
+
+The agent needs to create a configuration file but there are 3 valid formats (JSON, YAML, TOML). Instead of guessing, it invokes the question tool: "Which config format do you prefer?" with choices ["JSON", "YAML", "TOML"]. The user selects "YAML" from a visual picker. The agent receives "YAML" as the answer and creates the config in YAML format. The interaction took 3 seconds — less than correcting a wrong guess.
+
+## Natural Language Functional Description
+
+### Input Format
+
+```typescript
+interface QuestionInput {
+  question: string;                    // the question text
+  choices?: string[];                  // optional list of choices for multiple-choice
+  allowFreeform?: boolean;            // allow free text even with choices (default: false)
+  default?: string;                    // default answer if timeout or empty input
+  timeout?: number;                    // timeout in seconds (default: 300 — 5 minutes)
+  context?: string;                    // optional context shown below the question
+}
+```
+
+### Question Types
+
+**Multiple Choice (choices provided, allowFreeform: false):**
+The user sees a list of options with arrow-key navigation:
+
+```
+🤔 Which testing framework should I use?
+
+  › Jest
+    Vitest
+    Mocha
+
+  (Use ↑↓ to select, Enter to confirm)
+```
+
+The user navigates with arrow keys and presses Enter. The tool returns the selected option as a string.
+
+**Multiple Choice with Freeform (choices provided, allowFreeform: true):**
+Same as above, but with an additional "Other..." option:
+
+```
+🤔 Which database should I use?
+
+  › PostgreSQL
+    MySQL
+    SQLite
+    Other (type your answer)
+
+  (Use ↑↓ to select, Enter to confirm)
+```
+
+If "Other" is selected, the user is prompted to type a custom answer.
+
+**Freeform (no choices):**
+The user sees a text input prompt:
+
+```
+🤔 What should the API endpoint prefix be?
+
+  > /api/v2
+  
+  (Type your answer, Enter to confirm)
+```
+
+### Question Display
+
+Questions are visually distinct from agent output:
+
+- **Icon prefix** — 🤔 indicates a question (not agent commentary)
+- **Visual separation** — horizontal rule or box drawing above and below
+- **Context section** — if provided, shown in muted text below the question
+- **Input area** — clearly separated from the question text
+
+Example with context:
+
+```
+🤔 The auth module has two possible refactoring approaches. Which do you prefer?
+
+  Context: Approach A keeps backward compatibility but adds complexity.
+           Approach B is cleaner but requires updating 12 call sites.
+
+  › Approach A (backward compatible)
+    Approach B (clean break)
+```
+
+### Timeout Behavior
+
+When a timeout is configured:
+
+1. A countdown appears in the question prompt: `(auto-selecting "JSON" in 45s)`
+2. If the timeout expires, the default value is used
+3. If no default is provided and timeout expires, the tool returns `{timedOut: true, answer: null}`
+4. The agent handles timeout by proceeding with a reasonable default or aborting
+
+### Output Format
+
+```json
+{
+  "answer": "YAML",
+  "timedOut": false,
+  "method": "choice"    // "choice", "freeform", or "timeout"
+}
+```
+
+### Strategic Use Guidelines
+
+The agent should use the question tool when:
+
+- Multiple valid approaches exist and user preference matters
+- A destructive or irreversible action needs confirmation with specific context
+- Required information is genuinely missing (not inferable from context)
+- The decision significantly impacts the result quality
+
+The agent should NOT use it for:
+
+- Trivially inferable decisions (file naming conventions visible in existing code)
+- Every small choice (this creates "question fatigue")
+- Decisions it can make and easily undo if wrong
+
+### Integration with Permission System
+
+The question tool is distinct from the permission system's `ask` mode (RISE-074). Permissions ask "should I be allowed to do X?" — a security question. The question tool asks "what should I do?" — a preference question. Both pause for user input but serve different purposes.
+
+## Supporting Structures
+
+- **Tool Registry (RISE-034)** registers the question tool with id `question`
+- **Tool Context Injection (RISE-035)** provides session context for the question display
+- **Permission System (RISE-074)** handles security-oriented permission asks (separate from preference questions)
+- **Rich TUI (RISE-058)** renders the question with visual distinction and keyboard navigation
+- **Event Bus (RISE-002)** broadcasts `question.asked` and `question.answered` events
+- **Keybinding System (RISE-063)** handles arrow-key navigation in multiple-choice mode
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Format Preference:**
+The developer asks "create a CI config." The agent knows the project uses GitHub Actions but could use either YAML or the new JSON format. It asks: "GitHub Actions config format?" with choices ["YAML (standard)", "JSON (experimental)"]. The developer picks YAML. The agent creates `.github/workflows/ci.yml` — the right format on the first try.
+
+**Scenario 2 — Migration Strategy:**
+The agent is asked to upgrade a database ORM. There are two migration paths: gradual (dual-write period) and cutover (stop-the-world migration). The agent presents both with context explaining trade-offs. The developer chooses gradual. Without the question, the agent would have guessed — and might have chosen the wrong path for the team's risk tolerance.
+
+**Scenario 3 — Freeform Input:**
+The agent needs to create a new API endpoint but doesn't know the preferred URL pattern. It asks: "What should the endpoint path be?" with freeform input and a default of `/api/v1/users`. The developer types `/v2/members`. The agent uses exactly what the developer specified.
+
+**Scenario 4 — Timeout with Default:**
+The agent asks a non-critical question with a 60-second timeout and a sensible default. The developer is reviewing another terminal and doesn't respond. After 60 seconds, the agent proceeds with the default: "Using 'src/components/' as the component directory (auto-selected after timeout)." The workflow isn't blocked by a minor decision.

package/rispecs/borrowed_from_opencode/047-external-directory-tool.rispec.md

@@ -0,0 +1,166 @@
+# RISE-047: External Directory Access Tool
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/047-external-directory-tool.rispec.md
+
+## Creative Intent
+
+mia-code provides a controlled mechanism for accessing files outside the project directory. By default, all file tools are sandboxed to the project root — the agent cannot read system configs, examine other repositories, or access shared libraries. The external directory tool enables explicit, permissioned access to paths outside this sandbox. Every access is gated by the permission system: if the permission is "ask," the user sees the exact path and operation before access is granted. Write access to external directories is blocked entirely — the tool is read-only by design. This balances the agent's need for broader context with the security principle of least privilege.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- mia-code's file tools have no explicit path sandboxing — the underlying CLI may access any path the user can
+- There is no distinction between accessing project files and system files — both are equally unrestricted
+- An agent with file read access can read `/etc/passwd`, `~/.ssh/id_rsa`, or any other sensitive file
+- No audit trail exists for file accesses outside the project directory
+- There is no mechanism to explicitly grant access to a specific external path while keeping everything else restricted
+
+**Desired State:**
+- File tools are sandboxed to the project root by default — any path outside it is rejected
+- The external directory tool provides a controlled escape hatch for reading external paths
+- The "external_directory" permission gates access: "allow" permits silently, "ask" prompts the user, "deny" blocks
+- When "ask" mode is active, the user sees the exact path and operation before granting access
+- Write access to external directories is blocked entirely — no exceptions
+- All external access is logged with path, operation, and outcome for audit
+
+## Desired Outcome Definition
+
+The developer asks the agent to compare their project's ESLint config with a team-shared config at `/shared/configs/.eslintrc.json`. The agent calls the external directory tool to read the shared config. The user sees: "🔒 Read external file: /shared/configs/.eslintrc.json — Allow?" The user confirms. The agent reads the file, compares both configs, and reports differences. The access is logged. The agent could not write to the external path even if it tried.
+
+## Natural Language Functional Description
+
+### Input Format
+
+```typescript
+interface ExternalDirectoryInput {
+  path: string;                       // absolute path to read
+  operation: "read" | "list";         // read file content or list directory
+}
+```
+
+### Operations
+
+**Read** — returns the content of a file at the specified path:
+
+```json
+{
+  "operation": "read",
+  "path": "/shared/configs/.eslintrc.json",
+  "content": "{\n  \"extends\": \"@myorg/eslint-config\",\n  ...\n}",
+  "size": 1234,
+  "encoding": "utf-8"
+}
+```
+
+**List** — returns the contents of a directory (non-recursive by default):
+
+```json
+{
+  "operation": "list",
+  "path": "/shared/configs/",
+  "entries": [
+    {"name": ".eslintrc.json", "type": "file", "size": 1234},
+    {"name": ".prettierrc", "type": "file", "size": 456},
+    {"name": "tsconfig/", "type": "directory"}
+  ]
+}
+```
+
+### Permission Enforcement
+
+The tool checks the "external_directory" permission before any operation:
+
+1. **"deny" (default)** — the operation is rejected immediately:
+   ```json
+   {"error": "External directory access denied. Configure 'external_directory' permission to enable."}
+   ```
+
+2. **"ask"** — the user is prompted with the specific path:
+   ```
+   🔒 External access requested:
+      Operation: read
+      Path: /shared/configs/.eslintrc.json
+   
+      Allow? (y/n)
+   ```
+   If the user denies, the operation returns a permission-denied error. If they allow, the operation proceeds and is logged.
+
+3. **"allow"** — the operation proceeds silently (for trusted environments).
+
+### Path Restrictions
+
+Even with permission granted, certain paths are always blocked:
+
+- `~/.ssh/` — SSH keys and configuration
+- `~/.gnupg/` — GPG keys
+- `~/.aws/credentials` — cloud credentials
+- `/etc/shadow` — system password hashes
+- Any path matching configured blocklist patterns
+
+These restrictions cannot be overridden — they are hardcoded security boundaries.
+
+### Write Access
+
+Write operations to external directories are unconditionally blocked:
+
+```json
+{
+  "error": "Write access to external directories is not supported. External directory access is read-only."
+}
+```
+
+This restriction is by design — the agent should never modify files outside the project. If cross-project changes are needed, the developer should open mia-code in the target project.
+
+### Audit Logging
+
+Every external access (whether allowed or denied) is logged:
+
+```json
+{
+  "timestamp": "2026-03-01T14:30:00Z",
+  "tool": "external_directory",
+  "operation": "read",
+  "path": "/shared/configs/.eslintrc.json",
+  "outcome": "allowed",
+  "permission": "ask",
+  "sessionId": "sess_abc123",
+  "agent": "build"
+}
+```
+
+Logs are written to `.mia-code/audit.log` (append-only) for security review.
+
+### Symlink Resolution
+
+When a path within the project directory is a symlink pointing outside the project, the tool:
+
+1. Resolves the symlink to its real path
+2. Checks if the real path is outside the project root
+3. If outside, applies external directory permission checks
+4. If inside, allows normal access
+
+This prevents symlink-based sandbox escapes.
+
+## Supporting Structures
+
+- **Tool Registry (RISE-034)** registers the external_directory tool with id `external_directory`
+- **Tool Context Injection (RISE-035)** provides session context and the `ask()` function for permission prompts
+- **Permission System (RISE-074)** provides the "external_directory" permission with allow/ask/deny modes
+- **Agent Permission Rulesets (RISE-011)** configure per-agent external access policies
+- **Structured Logging (RISE-007)** records audit entries for external access
+- **File Read/Write Tools (RISE-048)** delegate to this tool when paths are outside the project root
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Shared Configuration Comparison:**
+The developer maintains a shared config repository at `/repos/shared-config/`. They ask the agent to ensure their project's TypeScript config aligns with the shared base. The agent reads the external `tsconfig.json` (after user permission), compares it with the project's config, and identifies 3 misaligned compiler options.
+
+**Scenario 2 — Reference Implementation:**
+The developer says "look at how the auth module works in the API project at /repos/api-service/." The agent reads the external auth module files, understands the pattern, and adapts it for the current project. External access enables cross-project learning without copy-pasting.
+
+**Scenario 3 — Blocked Sensitive Access:**
+A prompt injection in a README file attempts to make the agent read `~/.ssh/id_rsa`. The hardcoded path blocklist rejects the request regardless of permission settings: "Path ~/.ssh/ is restricted for security." The agent reports the blocked attempt in the audit log.
+
+**Scenario 4 — System Config Inspection:**
+The developer asks "why isn't my Node.js version correct?" The agent requests to read `/usr/local/etc/nodenv/version` (external path, user prompted). After permission, it reads the file and identifies a version mismatch with the project's `.node-version` — diagnosing the issue.