mia-code 0.2.0 → 0.3.0

package/rispecs/borrowed_from_opencode/069-config-markdown-frontmatter.rispec.md

@@ -0,0 +1,206 @@
+# RISE-069: Config from Markdown Frontmatter
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/069-config-markdown-frontmatter.rispec.md
+
+## Creative Intent
+
+mia-code reads configuration from YAML frontmatter in markdown files, allowing documentation and configuration to coexist in the same file. An `AGENTS.md` file describes an agent in prose and configures it in frontmatter — the file is simultaneously human-readable documentation and machine-readable configuration. This dual-purpose design eliminates the drift between "what the documentation says" and "what the tool does."
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- Agent definitions, project policies, and conventions live in separate JSON config files and markdown documentation
+- Documentation in files like `CLAUDE.md` or `AGENTS.md` is read by humans but ignored by mia-code's config system
+- Developers maintain parallel files: one describing intent (markdown), one configuring behavior (JSON)
+- Configuration drift is common — the JSON config is updated but the documentation is not, or vice versa
+- Markdown files in repositories serve no functional purpose for mia-code beyond being content the agent can read
+
+**Desired State:**
+- Markdown files with YAML frontmatter (delimited by `---`) are parsed for configuration values
+- Frontmatter config is merged into the config hierarchy at a defined precedence level
+- Agent definition files (e.g., `AGENTS.md`) both describe and configure agents in a single file
+- Multiple markdown files can contribute config, with contributions merged
+- The prose body of the markdown remains pure documentation — only the frontmatter is config
+
+## Desired Outcome Definition
+
+mia-code scans configured directories for markdown files with YAML frontmatter. Frontmatter content is parsed as configuration and merged into the config hierarchy between project config and CLI flags. The markdown body is ignored by the config system (but remains available to agents as context).
+
+## Natural Language Functional Description
+
+### Frontmatter Format
+
+YAML frontmatter is delimited by `---` at the start of a markdown file:
+
+```markdown
+---
+agent: code-reviewer
+model: claude-sonnet-4
+permission:
+  file_write: deny
+  file_read: allow
+  bash: deny
+---
+
+# Code Reviewer Agent
+
+This agent reviews code changes for quality, consistency, and potential bugs.
+It has read-only access to the codebase and cannot modify files or run commands.
+
+## Review Criteria
+
+- Code style consistency
+- Error handling completeness
+- Test coverage adequacy
+```
+
+The frontmatter between the `---` delimiters is parsed as YAML. Everything below the closing `---` is the markdown body.
+
+### Supported Files
+
+By default, mia-code scans for frontmatter config in:
+1. `.mia-code/*.md` — all markdown files in the project's mia-code directory
+2. `AGENTS.md` — agent definitions at the project root
+3. `CLAUDE.md` — Claude-specific conventions (parsed for config frontmatter if present)
+4. `MIA.md` — mia-code specific project conventions
+
+The scan pattern is configurable: `{"config": {"frontmatterFiles": [".mia-code/*.md", "AGENTS.md"]}}`.
+
+### Frontmatter Schema
+
+Frontmatter values map to standard mia-code config keys:
+
+```yaml
+# Agent definition
+agent: reviewer          # Agent name (creates/overrides agent config)
+model: claude-sonnet-4   # Model override for this agent
+engine: claude           # Engine override
+
+# Permissions for this agent
+permission:
+  file_write: deny
+  file_read: allow
+  bash: ask
+  glob: allow
+  grep: allow
+
+# Additional agent config
+temperature: 0.3
+maxTokens: 4096
+systemPrompt: |
+  You are a code reviewer. Focus on correctness and maintainability.
+```
+
+### Multiple File Merging
+
+When multiple markdown files contribute frontmatter config:
+1. Files are processed in alphabetical order within each scan directory
+2. Later files override earlier files for conflicting keys
+3. Agent definitions from different files create separate agents (keyed by `agent` name)
+4. Non-agent config keys merge following standard deep merge rules (RISE-067)
+
+Example:
+- `.mia-code/reviewer.md` defines agent "reviewer" with read-only permissions
+- `.mia-code/builder.md` defines agent "builder" with write permissions
+- Both agents are available in the merged config
+
+### Precedence
+
+Frontmatter config sits between project config and CLI flags:
+
+```
+...
+Project config (./mia-code.json)
+  ↓
+Markdown frontmatter (.mia-code/*.md)   ← this level
+  ↓
+CLI flags
+...
+```
+
+This means frontmatter can override project config (useful for agent-specific overrides that live with agent documentation) but CLI flags still win.
+
+### Parsing Rules
+
+1. **YAML parsing**: Use a YAML parser (e.g., `js-yaml`) to parse the frontmatter block
+2. **Type coercion**: YAML types map to JSON types (strings, numbers, booleans, objects, arrays)
+3. **No frontmatter**: Files without `---` delimiters at the start are ignored by the config system
+4. **Invalid YAML**: Parse errors are warned (with file path and line number) and the file is skipped
+5. **Empty frontmatter**: `---\n---` is valid and contributes nothing (the file is recognized but adds no config)
+
+### Agent Definition Shorthand
+
+When a markdown file's frontmatter includes `agent: <name>`, the entire frontmatter is treated as an agent definition. The remaining keys become properties of that agent:
+
+```yaml
+---
+agent: security-auditor
+model: claude-sonnet-4
+permission:
+  bash: deny
+  file_write: deny
+---
+```
+
+This is equivalent to the JSON config:
+```json
+{
+  "agents": {
+    "security-auditor": {
+      "model": "claude-sonnet-4",
+      "permission": {
+        "bash": "deny",
+        "file_write": "deny"
+      }
+    }
+  }
+}
+```
+
+### Body as System Prompt
+
+If the frontmatter includes `agent: <name>` and no explicit `systemPrompt` key, the markdown body (everything after the closing `---`) is used as the agent's system prompt:
+
+```markdown
+---
+agent: reviewer
+model: claude-sonnet-4
+---
+
+You are a code reviewer for this project. Follow these guidelines:
+
+1. Check for proper error handling
+2. Verify test coverage
+3. Ensure consistent naming conventions
+```
+
+The markdown body becomes the system prompt, complete with markdown formatting. This makes agent documentation and agent instructions identical — what you read is what the agent receives.
+
+### Change Detection
+
+mia-code watches frontmatter files for changes (using file system watchers if available):
+- When a frontmatter file is modified, the config is reloaded automatically
+- A status bar notification shows "Config reloaded from reviewer.md"
+- No restart required — agents pick up new config on next invocation
+
+## Supporting Structures
+
+- **Multi-Level Config (RISE-064)** places frontmatter config in the precedence hierarchy
+- **Config Deep Merging (RISE-067)** merges frontmatter config with other levels
+- **Agent Definition Config (RISE-010)** defines the agent config schema that frontmatter populates
+- **Agent Prompt Templates (RISE-012)** handles the system prompt derived from markdown body
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Self-Documenting Agents:**
+A team creates `.mia-code/reviewer.md` that describes their review standards in prose and configures the reviewer agent in frontmatter. New team members read the file to understand review policy AND mia-code uses it to configure the agent. One file, two purposes, zero drift.
+
+**Scenario 2 — Iterating on Agent Behavior:**
+A developer tweaks an agent's system prompt by editing the markdown body of `.mia-code/planner.md`. They save the file, and mia-code automatically reloads the config. They test the agent immediately without restarting. The markdown file is their development environment for agent prompts.
+
+**Scenario 3 — Project Onboarding Document:**
+A project's `AGENTS.md` lists all available agents with descriptions and configurations. The file serves as onboarding documentation ("here are the agents available in this project") and as the actual agent configuration. `cat AGENTS.md` tells a human everything; mia-code reads the same file for configuration.
+
+**Scenario 4 — Restricted Agent for Junior Developers:**
+A team lead creates `.mia-code/safe-coder.md` with frontmatter that denies bash and file_delete permissions. The markdown body instructs the agent to always explain its reasoning before making changes. Junior developers use this agent for guardrailed coding assistance.

package/rispecs/borrowed_from_opencode/070-managed-config-directory.rispec.md

@@ -0,0 +1,232 @@
+# RISE-070: Managed Config Directory
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/070-managed-config-directory.rispec.md
+
+## Creative Intent
+
+mia-code respects system-wide managed configuration that IT administrators deploy to enforce organizational policies. When an enterprise installs mia-code across developer machines, a managed config directory provides the final word on what the tool can and cannot do — overriding all user, project, and environment settings. This is the "IT department" layer: cost limits enforced, unapproved providers blocked, security policies applied, all without trusting individual developers to configure correctly.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- mia-code configuration is entirely user-controlled — there is no mechanism for administrators to enforce policies
+- An organization cannot prevent developers from using unapproved AI providers or models
+- Cost limits, if they exist, can be overridden by any developer in their personal config
+- Security policies (permission rulesets, tool restrictions) are advisory — developers can always relax them
+- There is no separation between "configurable preferences" and "enforced policies"
+- Enterprise deployment of mia-code requires trusting every developer to follow configuration guidelines
+
+**Desired State:**
+- A managed config directory at a system-level path contains administrator-controlled config
+- Managed config has the HIGHEST precedence — it overrides all other config sources
+- Users cannot override managed settings, even with CLI flags or environment variables
+- The managed config is visible but not editable through mia-code's CLI
+- Use cases include: blocking providers, enforcing permissions, setting cost limits, requiring authentication
+- The managed directory is writable only by system administrators (root/admin)
+
+## Desired Outcome Definition
+
+When a `managed-config.json` file exists in the system-wide managed config directory, its settings override all other configuration sources. Users can view managed settings via `/config --managed` but cannot modify them. Managed config is the final layer in the config precedence hierarchy.
+
+## Natural Language Functional Description
+
+### Managed Config Directory Paths
+
+The managed config directory location is platform-specific:
+
+| Platform | Path |
+|----------|------|
+| Linux | `/etc/mia-code/` |
+| macOS | `/Library/Application Support/mia-code/` |
+| Windows | `%ProgramData%\mia-code\` |
+
+The primary config file is `managed-config.json` (or `managed-config.jsonc`) within this directory.
+
+### Precedence
+
+Managed config has the absolute highest precedence:
+
+```
+Built-in defaults (lowest)
+  ↓
+Remote org config
+  ↓
+Global config
+  ↓
+Environment variables
+  ↓
+Project config
+  ↓
+Markdown frontmatter
+  ↓
+CLI flags
+  ↓
+Inline config
+  ↓
+Managed config (HIGHEST)    ← this level
+```
+
+Values in managed config cannot be overridden by any other source. Period.
+
+### Config Schema
+
+Managed config uses the same schema as regular config, with additional policy-specific fields:
+
+```jsonc
+{
+  // Organization identity
+  "managedBy": "Acme Corp IT Department",
+  "policyVersion": "2025-01-15",
+  "policyUrl": "https://wiki.acme.com/mia-code-policy",
+
+  // Enforce specific provider
+  "allowedProviders": ["anthropic"],
+  "blockedProviders": ["openai", "google"],
+
+  // Enforce model restrictions
+  "allowedModels": ["claude-sonnet-4", "claude-haiku-4"],
+
+  // Cost controls
+  "costLimits": {
+    "perSession": 5.00,      // USD per session
+    "perDay": 50.00,         // USD per day
+    "perMonth": 500.00       // USD per month
+  },
+
+  // Enforce permission policies
+  "permissions": {
+    "bash": "ask",           // Users cannot set bash to "allow"
+    "file_delete": "deny",   // File deletion is always denied
+    "network": "ask"         // Network access requires approval
+  },
+
+  // Require authentication
+  "requireAuth": true,
+  "authProvider": "https://sso.acme.com/oauth",
+
+  // Telemetry and logging
+  "telemetry": {
+    "enabled": true,
+    "endpoint": "https://telemetry.acme.com/mia-code"
+  },
+
+  // Block certain tool capabilities
+  "blockedTools": ["bash_unrestricted"],
+
+  // Custom message shown to users
+  "policyMessage": "mia-code is managed by Acme Corp IT. Contact it-help@acme.com for policy questions."
+}
+```
+
+### Override Prevention
+
+Managed settings are enforced through a lockdown mechanism:
+
+1. During config merge, managed values are applied last
+2. After merge, managed values are marked as "locked"
+3. Any attempt to override a locked value (via CLI flag, env var, or config file) is silently ignored
+4. The attempted override is logged (debug level) for troubleshooting
+
+Example: If managed config sets `"permissions": {"bash": "ask"}`, a developer's project config with `"permissions": {"bash": "allow"}` is ignored for the `bash` key. Other permission keys the developer sets are still respected.
+
+### Allowlists and Blocklists
+
+**Provider restrictions:**
+- `allowedProviders`: only these providers can be used (empty = no restriction)
+- `blockedProviders`: these providers are blocked regardless of user config
+- If a user's config specifies a blocked provider, it is silently removed from the merged config
+
+**Model restrictions:**
+- `allowedModels`: only these models can be used
+- If a user specifies a non-allowed model, mia-code falls back to the first allowed model and warns
+
+### Cost Controls
+
+Managed cost limits are enforced by the agent execution layer:
+- `perSession`: when estimated session cost exceeds this, the agent stops and informs the user
+- `perDay`: daily aggregate across all sessions; new sessions are blocked when exceeded
+- `perMonth`: monthly aggregate; new sessions are blocked when exceeded
+- Cost tracking is approximate (based on token counts and model pricing)
+- Users see their remaining budget in the status bar (if TUI is active)
+
+### User Visibility
+
+Users can inspect managed config but not modify it:
+
+```
+$ mia-code /config --managed
+
+Managed Configuration (set by Acme Corp IT Department)
+Policy version: 2025-01-15
+Policy details: https://wiki.acme.com/mia-code-policy
+
+  allowedProviders: ["anthropic"]         [LOCKED]
+  blockedProviders: ["openai", "google"]  [LOCKED]
+  permissions.bash: "ask"                 [LOCKED]
+  permissions.file_delete: "deny"         [LOCKED]
+  costLimits.perDay: $50.00               [LOCKED]
+
+These settings cannot be overridden. Contact it-help@acme.com for questions.
+```
+
+The `[LOCKED]` indicator makes it clear which values are managed.
+
+### Policy Message
+
+If `policyMessage` is set in managed config, it is displayed:
+- On first run after managed config is installed or updated
+- When a user attempts to override a managed setting
+- Via `/config --managed` command
+- In the TUI status bar (abbreviated) when managed policies are active
+
+### Installation and Deployment
+
+Managed config is typically deployed via:
+- System configuration management tools (Ansible, Puppet, Chef, GPO)
+- MDM (Mobile Device Management) for macOS/Windows
+- Package post-install scripts
+- Manual placement by system administrators
+
+The managed directory and its files should be:
+- Owned by root/Administrator
+- Readable by all users
+- Writable only by root/Administrator
+- Not modifiable by the mia-code process itself
+
+### Absence Behavior
+
+When no managed config directory or file exists:
+- This precedence level contributes nothing to the merge
+- No warnings are emitted (most installations won't have managed config)
+- The config system behaves as if this level doesn't exist
+
+### Update Detection
+
+mia-code checks for managed config changes:
+- On every startup
+- The file modification time is compared against the last-read timestamp
+- If the file has changed, config is reloaded and a notification appears
+- File watching (inotify/FSEvents) is not used for managed config (startup check is sufficient)
+
+## Supporting Structures
+
+- **Multi-Level Config (RISE-064)** defines the precedence hierarchy where managed config sits at the top
+- **Config Deep Merging (RISE-067)** applies managed config as the final merge layer
+- **JSONC Config (RISE-065)** parses the managed config file with comment support
+- **Remote Org Config (RISE-068)** provides a lower-precedence organizational layer that managed config can override
+- **Agent Permission Rulesets (RISE-011)** defines the permission schema that managed config enforces
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Enterprise Security Lockdown:**
+Acme Corp's security team deploys managed config via Ansible to all developer machines. The config blocks OpenAI (data residency concerns), enforces "ask" mode for all bash commands, and sets a $50/day cost limit. Developers can still choose between allowed Claude models and customize non-security settings freely.
+
+**Scenario 2 — Compliance Audit:**
+During a compliance audit, the IT team points auditors to `/etc/mia-code/managed-config.json` on any developer machine. The file documents exactly what policies are enforced, with the `policyVersion` and `policyUrl` fields providing traceability. Auditors verify that the managed config matches the organization's AI usage policy.
+
+**Scenario 3 — Developer Experience with Guardrails:**
+A developer tries to set `"permissions": {"bash": "allow"}` in their project config to speed up a scripting session. mia-code silently ignores the override (managed policy requires "ask"). The developer sees the permission prompt and understands — the status bar shows "Managed policy active." They can still work effectively, just with an approval step for bash commands.
+
+**Scenario 4 — Policy Rollout:**
+Acme Corp decides to allow Google models in addition to Anthropic. IT updates the managed config and pushes it via their configuration management tool. On next startup, every developer's mia-code picks up the change. No individual action required — the policy propagates automatically.

package/rispecs/borrowed_from_opencode/071-plugin-architecture.rispec.md

@@ -0,0 +1,104 @@
+# RISE-071: Plugin Architecture
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/071-plugin-architecture.rispec.md
+
+## Creative Intent
+
+mia-code becomes an extensible platform where third-party code augments agent capabilities without modifying the core. Developers define plugins that introduce new tools, commands, authentication providers, and behavioral modifications — transforming mia-code from a closed system into an ecosystem that evolves through community contribution.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- mia-code has no extension mechanism — all tools, commands, and behaviors are hardcoded in the core
+- Adding a new tool requires modifying source files, rebuilding, and redeploying
+- Users cannot customize agent behavior beyond configuration flags
+- Integration with project-specific tooling (linters, deployers, internal APIs) requires forking the codebase
+- No namespace isolation exists — all code shares global scope
+- Community contributions require pull requests into the main repository
+
+**Desired State:**
+- Plugins extend mia-code through a well-defined interface without touching core code
+- Three plugin sources coexist: built-in (compiled), NPM packages (installed), and local files (project-specific)
+- Each plugin declares its capabilities through a typed manifest: name, version, hooks, tools, commands
+- Plugin lifecycle is managed: discover → load → initialize → active → dispose
+- Plugin failures are isolated — a broken plugin is logged and disabled, never crashing the host
+- Configuration is declarative: a single `plugin` array in `mia-code.json` controls what loads
+
+## Desired Outcome Definition
+
+A developer adds `"plugin": ["mia-code-plugin-eslint", "./plugins/my-custom-tool.js"]` to their `mia-code.json`. On next launch, mia-code discovers both plugins, loads them, and initializes their declared tools and commands. The ESLint plugin adds a `lint` tool the agent can invoke. The local plugin adds a `deploy` command. Both operate within their namespaces. If either throws during initialization, mia-code logs the error and continues without it.
+
+## Natural Language Functional Description
+
+### Plugin Interface
+
+Every plugin exports an object conforming to the `PluginDef` interface:
+
+```typescript
+interface PluginDef {
+  name: string;
+  version: string;
+  hooks?: Record<string, HookHandler>;
+  tool?: Record<string, ToolDef>;
+  command?: Record<string, CommandDef>;
+  init?: (context: PluginContext) => Promise<void>;
+  dispose?: () => Promise<void>;
+}
+```
+
+The `name` field serves as the plugin's namespace. Tools registered by plugin `"acme"` appear as `acme.lint` internally, avoiding collisions with core tools or other plugins.
+
+### Plugin Sources
+
+1. **Built-in plugins** — compiled into the mia-code distribution. These provide core tools (file read/write, bash, git) as plugins themselves, dogfooding the architecture.
+2. **NPM packages** — installed from the registry by name. Package names should follow the convention `mia-code-plugin-{name}` but any valid package exporting a `PluginDef` works.
+3. **Local files** — JavaScript or TypeScript files in `.mia-code/plugins/` or referenced by relative path in config. These support rapid prototyping without publishing.
+
+### Plugin Lifecycle
+
+- **Discover:** On startup, read the `plugin` array from merged configuration. Resolve each entry to a module path (npm package name → `node_modules/`, relative path → filesystem, built-in → internal).
+- **Load:** `require()` or dynamic `import()` the module. Validate the export against `PluginDef` schema using Zod.
+- **Initialize:** Call `init(context)` if defined. The context provides access to logging, configuration, and the event bus.
+- **Active:** Register declared tools, commands, and hooks into the runtime registry.
+- **Dispose:** On shutdown, call `dispose()` in reverse initialization order. Release resources, close connections.
+
+### Plugin Configuration
+
+In `mia-code.json` at project or global level:
+
+```json
+{
+  "plugin": [
+    "mia-code-plugin-eslint",
+    "mia-code-plugin-docker",
+    "./plugins/deploy-tool.js"
+  ]
+}
+```
+
+### Error Isolation
+
+Plugin code runs in the same Node.js process but all plugin entry points are wrapped in try/catch. If `init()` throws, the plugin is marked `failed` and its tools/commands are not registered. If a tool execution throws, the error is returned as a tool result (not a process crash). A `plugin.error` event is published to the event bus for observability.
+
+## Supporting Structures
+
+- **Event Bus (RISE-002)** publishes plugin lifecycle events (`plugin.loaded`, `plugin.failed`, `plugin.disposed`)
+- **Hook System (RISE-072)** defines the extension points plugins attach to
+- **Auto-Install (RISE-073)** handles NPM plugin resolution and installation
+- **Permission System (RISE-074)** governs what plugins are allowed to do
+- **Multi-Level Config (RISE-064)** merges plugin arrays across global, project, and local config layers
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Project-Specific Tooling:**
+A team creates `.mia-code/plugins/jira-tool.js` that exposes a `jira.create_ticket` tool. The agent can now create Jira tickets during code review sessions. The plugin reads API credentials from environment variables and formats ticket descriptions from session context.
+
+**Scenario 2 — Community Plugin Ecosystem:**
+A developer publishes `mia-code-plugin-terraform` to NPM. It adds `terraform.plan`, `terraform.apply`, and `terraform.validate` tools. Other developers install it with one config line. The plugin hooks into `tool.after` to automatically run `terraform fmt` after any file write to `.tf` files.
+
+**Scenario 3 — Plugin Failure Isolation:**
+A plugin's `init()` throws because its required API key is missing. mia-code logs: "Plugin 'acme-deploy' failed to initialize: ACME_API_KEY not set. Plugin disabled." All other plugins and core functionality continue normally. The developer sees the warning and can fix their environment.
+
+**Scenario 4 — Built-in Tools as Plugins:**
+Core tools like `file_read`, `file_write`, and `bash` are implemented as built-in plugins. This validates the plugin architecture against real workloads and ensures the interface is powerful enough for production use. A developer can even override a built-in tool by registering a plugin with the same tool name at higher priority.

package/rispecs/borrowed_from_opencode/072-plugin-hooks.rispec.md

@@ -0,0 +1,123 @@
+# RISE-072: Plugin Hook System
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/072-plugin-hooks.rispec.md
+
+## Creative Intent
+
+Plugins gain the ability to intercept and reshape agent behavior at precisely defined extension points. Rather than replacing core logic wholesale, hooks allow surgical modification — transforming a system prompt, enriching tool output, injecting custom authentication — through a composable middleware pattern where multiple plugins cooperate without conflicts.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- mia-code has no interception points — behavior flows linearly from input to LLM to tool to output
+- Modifying agent behavior (e.g., adding context to every prompt) requires editing core source files
+- No mechanism exists for multiple independent extensions to modify the same behavior
+- Authentication is hardcoded per provider — adding a custom auth flow means changing provider code
+- Permission checks are embedded inline — no external code can participate in access decisions
+- Tool execution has no before/after lifecycle — no way to log, validate, or transform tool calls
+
+**Desired State:**
+- Named hook points exist at every significant boundary in the agent pipeline
+- Plugins register handlers for specific hooks using a typed middleware signature
+- Multiple plugins hooking the same point execute in registration order, each calling `next()` to continue
+- Each hook point defines specific input/output types — handlers receive and return well-typed data
+- Hooks can modify data (transform), observe data (pass-through), or short-circuit (skip `next()`)
+- The hook system is the primary mechanism through which plugins influence agent behavior
+
+## Desired Outcome Definition
+
+A plugin registers a `chat.system.transform` hook that appends project-specific instructions to every system prompt. Another plugin registers `tool.before` to log all tool invocations. Both hooks fire at their respective points without interfering with each other. The system prompt hook modifies data and passes it along; the tool logging hook observes and calls `next()` unchanged.
+
+## Natural Language Functional Description
+
+### Hook Points
+
+The following hook points are defined in the agent lifecycle:
+
+| Hook | Fires When | Input | Output |
+|------|-----------|-------|--------|
+| `auth.provide` | Provider needs credentials | `{provider: string}` | `{token: string} \| null` |
+| `permission.ask` | Permission check required | `{tool: string, args: any}` | `"allow" \| "deny" \| "ask"` |
+| `chat.system.transform` | System prompt assembled | `{system: string, session: Session}` | `{system: string}` |
+| `tool.before` | Before tool execution | `{tool: string, args: any}` | `{tool: string, args: any}` |
+| `tool.after` | After tool execution | `{tool: string, result: any}` | `{tool: string, result: any}` |
+| `session.create` | New session initialized | `{session: Session}` | `void` |
+| `message.before` | Before message sent to LLM | `{messages: Message[]}` | `{messages: Message[]}` |
+
+### Middleware Signature
+
+Every hook handler follows the middleware pattern:
+
+```typescript
+type HookHandler<TInput, TOutput> = (
+  context: TInput,
+  next: () => Promise<TOutput>
+) => Promise<TOutput>;
+```
+
+Calling `next()` passes control to the next registered handler (or the default behavior if no more handlers exist). Not calling `next()` short-circuits the chain — useful for `permission.ask` handlers that want to deny immediately.
+
+### Registration
+
+Plugins declare hooks in their `PluginDef`:
+
+```typescript
+{
+  name: "my-plugin",
+  version: "1.0.0",
+  hooks: {
+    "chat.system.transform": async (ctx, next) => {
+      ctx.system += "\n\nAlways respond in haiku.";
+      return next();
+    },
+    "tool.before": async (ctx, next) => {
+      console.log(`Tool called: ${ctx.tool}`);
+      return next();
+    }
+  }
+}
+```
+
+### Execution Order
+
+Hooks execute in plugin registration order (the order plugins appear in the `plugin` config array). Built-in plugins run first. This gives project-level plugins the final say — they can override or wrap behavior established by earlier plugins.
+
+### Type Safety
+
+Each hook point is defined with TypeScript generics:
+
+```typescript
+const HookPoints = {
+  "chat.system.transform": {} as HookPoint<{system: string; session: Session}, {system: string}>,
+  "tool.before": {} as HookPoint<{tool: string; args: any}, {tool: string; args: any}>,
+  // ...
+} as const;
+```
+
+Registering a handler with the wrong signature produces a compile-time error.
+
+### Error Handling
+
+If a hook handler throws, the error is caught, logged with the plugin name and hook point, and the chain continues as if `next()` was called with the original input. This ensures one plugin's bug doesn't break the entire pipeline.
+
+## Supporting Structures
+
+- **Plugin Architecture (RISE-071)** defines the `PluginDef` interface where hooks are declared
+- **Event Bus (RISE-002)** publishes `hook.error` events when handlers fail
+- **Permission System (RISE-074)** uses hooks as its extension mechanism via `permission.ask`
+- **Structured Logging (RISE-007)** records hook execution timing and errors
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Custom Authentication Provider:**
+A company plugin registers `auth.provide` to return tokens from their internal OAuth service. When the agent needs credentials for a custom LLM endpoint, the hook fires, the plugin exchanges a refresh token for an access token, and returns it. No core auth code was modified.
+
+**Scenario 2 — System Prompt Enrichment:**
+A plugin hooks `chat.system.transform` to append the project's coding standards document to every system prompt. The agent consistently follows project conventions because the standards are always in context. The plugin reads the standards file once at init and caches it.
+
+**Scenario 3 — Tool Call Auditing:**
+A compliance plugin hooks `tool.before` and `tool.after` to log every tool invocation to an external audit service. It records what tool was called, with what arguments, what it returned, and how long it took. The plugin never modifies data — it just observes and forwards via `next()`.
+
+**Scenario 4 — Permission Gate:**
+A security plugin hooks `permission.ask` to enforce a strict allowlist. Only `file_read`, `file_write`, and `grep` are permitted — all other tools return `"deny"` without calling `next()`. The agent operates in a restricted sandbox defined entirely by plugin configuration.