mia-code 0.2.0 → 0.3.0

package/rispecs/borrowed_from_opencode/083-deferred-effects.rispec.md

@@ -0,0 +1,148 @@
+# RISE-083: Deferred Effects
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/083-deferred-effects.rispec.md
+
+## Creative Intent
+
+Side effects — event publishing, cache invalidation, file operations, notifications — are separated from database mutations and executed only after the data is safely committed. This eliminates an entire class of consistency bugs: no event about a session that wasn't persisted, no cache invalidation for a write that rolled back, no notification about an action that never completed.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- mia-code performs side effects inline with data mutations — no separation of concerns
+- If a JSON write fails mid-operation, any events or notifications already fired cannot be retracted
+- Cache state can become stale if a write operation partially succeeds
+- No mechanism exists to queue side effects and conditionally execute them
+- Event publishing and data persistence are tightly coupled — testing either in isolation is difficult
+- Concurrent operations can interleave mutations and effects in unpredictable order
+
+**Desired State:**
+- Side effects are registered during transactions via `tx.effect()` but not executed until commit
+- If the transaction rolls back, all registered effects are silently discarded
+- Effects execute in registration order after the transaction successfully commits
+- Effect errors are logged but never cause transaction rollback (effects are post-commit)
+- The pattern is consistent and enforced — all side effects go through the deferred mechanism
+- Testing is simplified: verify mutations and effects independently
+
+## Desired Outcome Definition
+
+Within a transaction, code registers three effects: publish a `session.created` event, invalidate the session list cache, and write an audit log entry. The transaction commits — all three effects execute in order. In another case, the transaction fails on the second insert — the transaction rolls back and none of the three effects execute. The system is always consistent.
+
+## Natural Language Functional Description
+
+### Effect Registration
+
+Within a transaction, effects are registered using `tx.effect()`:
+
+```typescript
+await db.transaction(async (tx) => {
+  const session = { id: "abc", root: "/project" };
+  
+  await tx.run("INSERT INTO sessions ...", [session.id, session.root]);
+  
+  // Effect 1: Publish event
+  tx.effect(() => {
+    Bus.publish("session.created", session);
+  });
+  
+  // Effect 2: Invalidate cache
+  tx.effect(() => {
+    sessionCache.invalidate(session.root);
+  });
+  
+  // Effect 3: Audit log
+  tx.effect(() => {
+    auditLog.write("session_created", session.id);
+  });
+  
+  await tx.run("INSERT INTO messages ...", [msgId, session.id]);
+});
+// All three effects execute here, in order, only if transaction committed
+```
+
+### Effect Types
+
+Effects can encapsulate any side effect:
+
+**Event Publishing** — the most common effect. Ensures events about data changes only fire after the data is persisted:
+```typescript
+tx.effect(() => Bus.publish("message.added", { sessionId, messageId }));
+```
+
+**Cache Invalidation** — ensures caches are invalidated only after the underlying data actually changed:
+```typescript
+tx.effect(() => queryCache.delete(`sessions:${projectRoot}`));
+```
+
+**File Operations** — ensures files are only written/modified after the database records the intent:
+```typescript
+tx.effect(() => fs.writeFileSync(exportPath, sessionExport));
+```
+
+**Notifications** — ensures users/plugins are notified only about completed operations:
+```typescript
+tx.effect(() => pluginManager.notify("session.created", sessionData));
+```
+
+**UI Updates** — ensures the interface reflects committed state:
+```typescript
+tx.effect(() => tui.refresh("session-list"));
+```
+
+### Execution Semantics
+
+1. **Registration:** `tx.effect(callback)` appends the callback to an internal queue. No execution occurs.
+2. **On commit:** After the SQL transaction commits, iterate the queue and execute each callback in order.
+3. **On rollback:** Discard the entire queue. No callbacks execute. No logging needed.
+4. **Error handling:** If an effect callback throws, catch the error, log it with context, and continue to the next effect. Effects are best-effort — they cannot retroactively undo the committed transaction.
+
+### Error Isolation
+
+```typescript
+await db.transaction(async (tx) => {
+  await tx.run("INSERT INTO sessions ...");
+  
+  tx.effect(() => {
+    throw new Error("Event bus unavailable");
+    // This error is caught and logged
+    // Does NOT rollback the transaction
+    // Does NOT prevent subsequent effects
+  });
+  
+  tx.effect(() => {
+    sessionCache.invalidate(root);
+    // This still executes even if the previous effect failed
+  });
+});
+// Transaction committed. First effect logged error. Second effect ran.
+```
+
+### Implementation
+
+The `Transaction` class maintains an internal effect queue. `effect()` appends callbacks; `commit()` executes them in order after SQL commit (catching and logging errors); `rollback()` discards the queue. Effects registered within savepoints follow the savepoint's fate — if a savepoint rolls back, its effects are discarded while the outer transaction's effects remain.
+
+### Testing
+
+Deferred effects simplify testing by separating mutations from triggers. Test data inserts independently from event assertions — verify the transaction wrote correct rows, then separately verify the correct events fired after commit.
+
+## Supporting Structures
+
+- **Database Transactions (RISE-082)** provides the transactional context where effects are registered
+- **Event Bus (RISE-002)** is the primary consumer of deferred effects for event publishing
+- **SQLite Storage (RISE-080)** provides the database layer that commits trigger effect execution
+- **Structured Logging (RISE-007)** records effect failures for debugging
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Consistent Event Publishing:**
+A session is created in a transaction. The `session.created` event is deferred. Mid-transaction, the message insert fails due to a constraint violation. The transaction rolls back. The event never fires. No UI component, no plugin, no logger ever learns about a session that doesn't exist.
+
+**Scenario 2 — Cache Coherence:**
+A batch update modifies 50 messages within a transaction. Cache invalidation is deferred. If the batch fails at message #30, the cache is never invalidated — it still holds the correct (pre-update) data. If the batch succeeds, the cache is invalidated once (not 50 times).
+
+**Scenario 3 — Plugin Notification Safety:**
+A plugin subscribes to `session.created` events. The deferred effect ensures the plugin only receives the event after the session is queryable in the database. The plugin can immediately call `db.get("SELECT * FROM sessions WHERE id = ?")` and find the session — guaranteed.
+
+**Scenario 4 — Effect Error Resilience:**
+An audit logging service is down. The deferred effect that writes to the audit log throws. The error is logged locally. The next effect (cache invalidation) runs normally. The committed transaction is unaffected. When the audit service recovers, the gap is acceptable — effects are best-effort.

package/rispecs/borrowed_from_opencode/084-permission-rules.rispec.md

@@ -0,0 +1,123 @@
+# RISE-084: Permission Rules
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/084-permission-rules.rispec.md
+
+## Creative Intent
+
+mia-code gives developers explicit, composable control over what an agent is allowed to do. Each permission rule is a small declarative statement — a single fact about what is permitted, denied, or worth asking about. By stacking these rules into an ordered array, a developer builds a security posture that fits their exact workflow without reaching for a `--yolo` flag or manually approving every action.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- mia-code relies on the `--yolo` flag to bypass all safety prompts — it is all-or-nothing
+- Without `--yolo`, every write and bash operation triggers an interactive confirmation
+- There is no way to express "allow writes to test files but ask for production files"
+- Permission logic is scattered across tool execution paths with ad-hoc checks
+- Developers who trust the agent for some tasks but not others have no middle ground
+- No concept of a permission rule as a data structure — decisions are hardcoded behavior
+
+**Desired State:**
+- Each permission is a typed rule object: `{permission: string, pattern?: string, action: "allow"|"deny"|"ask"}`
+- Rules are stored as an ordered array — evaluation is first-match-wins, like firewall rules
+- Permission names map to tool IDs or resource categories: "read", "write", "edit", "bash", "external_directory", "question", plus any registered tool ID
+- A default ruleset provides a reasonable security baseline out of the box
+- Custom rules in project or global config override defaults naturally
+- Rules are composable: a developer adds one rule to change one behavior without touching the rest
+
+## Desired Outcome Definition
+
+An agent attempting any action is checked against an ordered array of permission rules. The first rule whose permission name and optional pattern match the action determines the outcome: allow silently, deny silently, or ask the user. Developers configure rules declaratively in config files without writing code.
+
+## Natural Language Functional Description
+
+### Rule Structure
+
+A permission rule is a plain object with three required fields and one optional field:
+
+```typescript
+interface PermissionRule {
+  permission: string    // tool ID or category: "read", "write", "edit", "bash", "external_directory", "question", or any tool ID
+  pattern?: string      // optional glob pattern scoping the rule to specific paths or commands
+  action: "allow" | "deny" | "ask"  // what happens when this rule matches
+}
+```
+
+### Default Rules
+
+When no custom rules are configured, mia-code applies this baseline:
+
+```json
+[
+  {"permission": "read", "action": "allow"},
+  {"permission": "write", "action": "ask"},
+  {"permission": "edit", "action": "ask"},
+  {"permission": "bash", "action": "ask"},
+  {"permission": "external_directory", "action": "deny"},
+  {"permission": "question", "action": "allow"}
+]
+```
+
+This default is conservative: reading and asking questions are safe, writing and bash require approval, and accessing directories outside the project is blocked.
+
+### Evaluation Algorithm
+
+When the agent invokes a tool, the permission system:
+
+1. Identifies the permission name (tool ID or mapped category)
+2. Determines the target (file path, command string, or directory)
+3. Iterates through the rule array in order
+4. For each rule: if the permission name matches AND (no pattern OR pattern matches target), this rule applies
+5. Returns the action from the first matching rule
+6. If no rule matches, the default action is "ask"
+
+First-match-wins means rule ordering matters. More specific rules go before general ones.
+
+### Rule Examples
+
+- `{"permission": "bash", "pattern": "rm *", "action": "deny"}` — blocks destructive bash commands
+- `{"permission": "write", "pattern": "*.test.ts", "action": "allow"}` — auto-allows writing test files
+- `{"permission": "write", "pattern": "src/**/*.ts", "action": "allow"}` — auto-allows all TypeScript writes in src
+- `{"permission": "bash", "pattern": "npm test*", "action": "allow"}` — auto-allows running tests
+- `{"permission": "external_directory", "pattern": "/tmp/**", "action": "allow"}` — allows access to temp directory
+- `{"permission": "edit", "action": "allow"}` — blanket allow all edits (placed last as a catch-all)
+
+### Configuration
+
+Rules are specified in mia-code config under the `permissions` key:
+
+```json
+{
+  "permissions": {
+    "rules": [
+      {"permission": "write", "pattern": "*.test.ts", "action": "allow"},
+      {"permission": "bash", "pattern": "rm *", "action": "deny"},
+      {"permission": "bash", "pattern": "npm *", "action": "allow"}
+    ]
+  }
+}
+```
+
+Custom rules are prepended to the default rules, so they take priority by virtue of position.
+
+## Supporting Structures
+
+- **Permission Glob Patterns (RISE-085)** defines the glob matching syntax used in rule patterns
+- **Permission Merging (RISE-086)** defines how rules from multiple sources combine into one effective ruleset
+- **Permission Modes (RISE-087)** defines the three action modes and their user interaction behavior
+- **Zod Schema Validation (RISE-005)** validates rule objects at configuration load time
+- **Named Error System (RISE-006)** provides typed errors for permission denials
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Test-Driven Trust:**
+A developer adds `{"permission": "write", "pattern": "*.test.ts", "action": "allow"}` and `{"permission": "bash", "pattern": "npm test", "action": "allow"}` to their project config. The agent writes and runs tests freely but still asks before modifying production code. Trust is earned incrementally.
+
+**Scenario 2 — Locked-Down Production:**
+A team adds `{"permission": "bash", "pattern": "rm *", "action": "deny"}` and `{"permission": "write", "pattern": "*.env*", "action": "deny"}` to the global config. No agent on any project can delete files or modify environment files, regardless of other settings.
+
+**Scenario 3 — Progressive Relaxation:**
+A new developer starts with all defaults. Over time they add allow rules for specific patterns they trust. Their permission config becomes a document of what they've learned to trust — a personal security policy that grows with experience.
+
+**Scenario 4 — Per-Tool Precision:**
+A developer creates rules using specific tool IDs: `{"permission": "grep", "action": "allow"}`, `{"permission": "glob", "action": "allow"}`, `{"permission": "bash", "pattern": "git *", "action": "allow"}`. Each tool gets its own permission treatment.

package/rispecs/borrowed_from_opencode/085-permission-glob-patterns.rispec.md

@@ -0,0 +1,113 @@
+# RISE-085: Permission Glob Patterns
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/085-permission-glob-patterns.rispec.md
+
+## Creative Intent
+
+mia-code uses file-path glob patterns to give developers surgical precision over permission scoping. Instead of blanket allow-or-deny, a developer writes a pattern like `src/**/*.test.ts` and the rule applies only to test files under src. Glob syntax is the universal language developers already know from `.gitignore`, shell expansion, and build tools — no new DSL to learn, no regex complexity to debug.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- mia-code has no pattern-based permission scoping — permissions are all-or-nothing per tool
+- Developers cannot distinguish between "write to test files" and "write to production files"
+- Bash command filtering does not exist — any bash command is treated the same
+- The `--yolo` flag removes all checks; without it, every action of the same type gets the same treatment
+- No glob matching library is integrated for permission purposes
+
+**Desired State:**
+- Permission rules accept an optional `pattern` field containing a glob expression
+- Glob patterns match against file paths (for read/write/edit), command strings (for bash), and directory paths (for external_directory)
+- Standard glob syntax is used: `*`, `**`, `?`, `{a,b}`, negation via `!`
+- Pattern matching is efficient and cached — no performance penalty on hot paths
+- A rule without a pattern matches all targets universally (acts as a catch-all)
+- Case sensitivity follows the platform convention: case-insensitive on macOS/Windows, case-sensitive on Linux
+
+## Desired Outcome Definition
+
+When a permission rule includes a `pattern` field, the pattern is evaluated against the relevant target string (file path, command, or directory). The glob syntax supports the same wildcards developers use in `.gitignore` and shell scripts. Matching is fast, correct, and platform-aware.
+
+## Natural Language Functional Description
+
+### Glob Syntax Reference
+
+| Pattern    | Meaning                                      | Example Match                  |
+|------------|----------------------------------------------|--------------------------------|
+| `*`        | Any characters within a single path segment  | `*.ts` matches `foo.ts`       |
+| `**`       | Any characters across multiple path segments | `src/**/*.ts` matches `src/a/b/c.ts` |
+| `?`        | Exactly one character                        | `?.ts` matches `a.ts`         |
+| `{a,b}`    | Alternatives — matches either `a` or `b`    | `*.{ts,js}` matches both      |
+| `!pattern` | Negation — excludes matches                 | `!node_modules/**` excludes   |
+
+### Target Types
+
+Patterns are matched against different targets depending on the permission category:
+
+- **read / write / edit**: matched against the file path relative to the project root. Example: `src/utils/helper.ts`.
+- **bash**: matched against the full command string. Example: `npm test --watch`.
+- **external_directory**: matched against the absolute directory path. Example: `/home/user/other-project`.
+
+### Matching Algorithm
+
+1. Receive the target string (file path, command, or directory path)
+2. Normalize path separators to forward slashes for cross-platform consistency
+3. If the rule has no pattern, it matches (universal rule)
+4. If the pattern starts with `!`, invert the match result
+5. Apply glob matching using micromatch or picomatch semantics
+6. Return boolean: does this pattern match the target?
+
+### Path Normalization
+
+Before matching, paths are normalized:
+
+- Backslashes converted to forward slashes (`\` → `/`)
+- Trailing slashes removed
+- Relative paths resolved against the project root
+- `./` prefix stripped if present
+- No symlink resolution — match against the literal path
+
+### Case Sensitivity
+
+- **Linux**: case-sensitive matching (default)
+- **macOS**: case-insensitive matching (HFS+ / APFS default)
+- **Windows**: case-insensitive matching (NTFS default)
+
+The platform is detected at startup. Override via config: `{"permissions": {"caseSensitive": true}}`.
+
+### Pattern Examples for Common Scenarios
+
+```
+*.env              → matches .env, production.env, .env.local
+src/**/*.ts        → matches any .ts file at any depth under src/
+!node_modules/**   → excludes everything under node_modules
+*.{test,spec}.ts   → matches foo.test.ts, bar.spec.ts
+rm *               → matches bash commands starting with "rm "
+git push*          → matches "git push", "git push origin main"
+/tmp/**            → matches any path under /tmp
+**/*.secret        → matches any .secret file anywhere
+```
+
+### No Pattern Behavior
+
+When a permission rule omits the `pattern` field, the rule applies to every target for that permission category. This is the catch-all case — useful for broad defaults like `{"permission": "read", "action": "allow"}` where no path filtering is needed.
+
+## Supporting Structures
+
+- **Permission Rules (RISE-084)** defines the rule structure that contains optional patterns
+- **Permission Merging (RISE-086)** controls how pattern-bearing rules from multiple sources combine
+- **Namespace Module Pattern (RISE-004)** organizes the glob matching utility under a permissions namespace
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Protecting Secrets:**
+A developer adds `{"permission": "read", "pattern": "*.env*", "action": "deny"}` to block the agent from reading environment files containing API keys. The pattern `*.env*` catches `.env`, `.env.local`, `.env.production`, and any variant.
+
+**Scenario 2 — Bash Command Guardrails:**
+Rules like `{"permission": "bash", "pattern": "rm -rf *", "action": "deny"}` and `{"permission": "bash", "pattern": "git push --force*", "action": "deny"}` create guardrails around the most dangerous commands while allowing everyday bash usage.
+
+**Scenario 3 — Scoped Write Access:**
+A developer configures `{"permission": "write", "pattern": "src/**/*.test.ts", "action": "allow"}` and `{"permission": "write", "pattern": "src/**/*.ts", "action": "ask"}`. Test files are auto-allowed; production TypeScript files still prompt. The ordering ensures tests match first.
+
+**Scenario 4 — Cross-Platform Team:**
+A team working across macOS and Linux sets `{"permissions": {"caseSensitive": false}}` in their shared project config. Pattern matching behaves identically on both platforms, preventing surprises where `README.md` matches on Mac but not on Linux.

package/rispecs/borrowed_from_opencode/086-permission-merging.rispec.md

@@ -0,0 +1,134 @@
+# RISE-086: Permission Merging
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/086-permission-merging.rispec.md
+
+## Creative Intent
+
+mia-code resolves permissions from multiple layers — built-in defaults, global config, project config, agent-specific overrides, and live session choices. Each layer can refine or override the previous one without replacing it entirely. A developer's global "deny rm" rule persists across all projects while a project-specific "allow writes to tests" rule applies only where needed. The merge algorithm is simple: concatenate arrays in precedence order, first match wins.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- mia-code has no layered configuration for permissions — behavior is hardcoded or toggled by `--yolo`
+- No concept of global vs. project-level permission settings
+- Agent-specific permissions do not exist — all agents share identical capability constraints
+- When a user says "always allow" or "never allow" during a session, that choice is not persisted or layered
+- There is no way to view what the effective merged permission set looks like
+
+**Desired State:**
+- Five distinct permission layers merge into one effective ruleset
+- Each layer prepends its rules, giving it higher priority (first-match-wins)
+- Session-scoped choices (user "always"/"never" responses) sit at the top — user intent is supreme
+- Agent-specific rules sit above project/global — specialized agents get specialized permissions
+- A `/permissions` command shows the effective merged ruleset with source annotations
+- A `/permissions reset` command clears session-scoped overrides
+
+## Desired Outcome Definition
+
+When the permission system evaluates an action, it walks a single merged rule array that was assembled from five layers. The merge is a simple array concatenation in precedence order. Developers can inspect the merged result and understand exactly which rule from which source controls each decision.
+
+## Natural Language Functional Description
+
+### Layer Hierarchy
+
+Layers are numbered from lowest to highest precedence:
+
+| Layer | Source                        | Example Location                              |
+|-------|-------------------------------|-----------------------------------------------|
+| 1     | Built-in defaults             | Hardcoded in source                           |
+| 2     | Global config permissions     | `~/.mia-code/config.json` → `permissions.rules` |
+| 3     | Project config permissions    | `.mia-code/config.json` → `permissions.rules`   |
+| 4     | Agent-specific permissions    | Agent definition → `permissions` field          |
+| 5     | Session-scoped permissions    | Runtime "always"/"never" choices                |
+
+### Merge Algorithm
+
+The merge algorithm is deliberately simple:
+
+1. Start with an empty array: `merged = []`
+2. Prepend session-scoped rules (layer 5) → `merged = [...session, ...merged]`
+3. Prepend agent-specific rules (layer 4) → `merged = [...agent, ...merged]`
+4. Prepend project config rules (layer 3) → wait — these go *after* agent rules
+5. Final order: `[...session, ...agent, ...project, ...global, ...defaults]`
+
+Because evaluation is first-match-wins, rules earlier in the array (higher precedence layers) naturally override rules later in the array (lower precedence layers).
+
+### Detailed Merge Steps
+
+```
+effectiveRules = [
+  ...sessionRules,      // Layer 5: user "always"/"never" choices this session
+  ...agentRules,        // Layer 4: agent-specific overrides
+  ...projectRules,      // Layer 3: project .mia-code/config.json
+  ...globalRules,       // Layer 2: global ~/.mia-code/config.json
+  ...defaultRules       // Layer 1: built-in baseline
+]
+```
+
+No deduplication is performed. If two rules in different layers match the same permission+pattern, the first one encountered wins. Redundant rules in lower layers are simply never reached.
+
+### Session-Scoped Rules
+
+When a user responds "always" to a permission prompt, a new allow rule is prepended to the session layer:
+```json
+{"permission": "write", "pattern": "src/**/*.ts", "action": "allow", "source": "session"}
+```
+
+When a user responds "never", a deny rule is prepended:
+```json
+{"permission": "bash", "pattern": "rm *", "action": "deny", "source": "session"}
+```
+
+Session rules are ephemeral — they exist only for the current session and are discarded on exit.
+
+### Source Annotations
+
+Each rule in the merged array carries a `source` annotation for introspection:
+
+```json
+{"permission": "read", "action": "allow", "source": "default"}
+{"permission": "write", "pattern": "*.test.ts", "action": "allow", "source": "project"}
+{"permission": "bash", "pattern": "rm *", "action": "deny", "source": "global"}
+{"permission": "write", "action": "ask", "source": "default"}
+```
+
+### Viewing Merged Permissions
+
+The `/permissions` slash command displays the effective merged ruleset:
+
+```
+Effective Permission Rules (12 rules):
+  #1  [session]  write src/**/*.ts → allow
+  #2  [agent]    bash npm *        → allow
+  #3  [project]  write *.test.ts   → allow
+  #4  [global]   bash rm *         → deny
+  ...
+  #12 [default]  question          → allow
+```
+
+### Resetting Session Permissions
+
+`/permissions reset` clears all session-scoped rules (layer 5), returning to the config-defined state. This is useful when a user's "always" or "never" choice was made in error.
+
+## Supporting Structures
+
+- **Permission Rules (RISE-084)** defines the individual rule objects that are merged
+- **Permission Glob Patterns (RISE-085)** defines pattern matching within rules
+- **Permission Modes (RISE-087)** defines how "always"/"never" responses create session rules
+- **Agent Definition Config (RISE-010)** defines per-agent permission configuration
+- **Instance State (RISE-003)** scopes the session layer to the active session
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Team Safety Net:**
+A global config includes `{"permission": "bash", "pattern": "rm -rf *", "action": "deny"}`. A project config adds `{"permission": "write", "pattern": "*.test.ts", "action": "allow"}`. The merged ruleset blocks destructive bash everywhere while allowing test writes in this project.
+
+**Scenario 2 — Agent Specialization:**
+A "code-review" agent has `{"permission": "write", "action": "deny"}` in its agent definition — it should never write files. A "test-writer" agent has `{"permission": "write", "pattern": "*.test.ts", "action": "allow"}`. Same project, different agents, different permissions.
+
+**Scenario 3 — Session Learning:**
+A developer approves a bash command with "always". The session layer gains an allow rule. Later they realize it was too broad and run `/permissions reset`. The session layer clears, and the next occurrence asks again.
+
+**Scenario 4 — Debugging Permissions:**
+A developer runs `/permissions` and sees that a write to `src/index.ts` is being denied. The output shows rule #4 from the global config is the culprit. They adjust the global config and the denial disappears.