{"version":"2.1.267","anchor":"plugin-api-gains-fsreadwritelist-rename-plus-new-settings","canonical_anchor":"new-plugin-surface-ui-system-for-terminal-rendered-plugin","heading":"Plugin\/hook capability API expands: renamed fs actions, new env\/settings\/session capabilities, and a terminal UI surface system","tier":"use","area":"Plugins","scope":null,"heads_up":null,"url":"https:\/\/changelogs.core-directive.com\/v\/2.1.267\/e\/plugin-api-gains-fsreadwritelist-rename-plus-new-settings","release_url":"https:\/\/changelogs.core-directive.com\/v\/2.1.267","markdown":"### Plugin\/hook capability API expands: renamed fs actions, new env\/settings\/session capabilities, and a terminal UI surface system\n\nPlugins and hooks gain renamed filesystem actions, new capabilities for settings\/env\/session usage, stricter validation, and a new terminal UI system\n\n**What**\n\n- The plugin capability actions `fs.readFile`, `fs.writeFile`, and `fs.listDir` are renamed to `fs.read`, `fs.write`, and `fs.list` (including the underlying IPC event name).\n\n- Plugins and hooks gain four new capabilities: `session.usage` (read session usage stats), `settings.read` (read merged settings from a named source), and `env.get`\/`env.set` (read and write environment variables) \u2014 all fully wired with permission checks and handlers.\n\n- New validation guards these and other hook APIs: a hook's `on('event')` matcher can't be a nested object matched against a primitive; `next(e)` handlers for `env.get`\/`env.set` can only change the value's data, not other fields; and `ui.message` calls can't rewrite fields like `surface`, `component`, `requestId`, `element`, or `module` (only `data` may change), and are rejected if their serialized data is too deeply nested or too large.\n\n- A large new subsystem lets plugins mount custom terminal UI elements (\"Clients\") declared via a `surface` field in `hooks.json`. It handles rendering, mounting\/unmounting, resizing, mouse and keyboard input, hover\/focus state, a row-budget that can reject renders pushing a dialog over its row limit, and message dispatch between the plugin and its UI.\n\n**Why** Together these give plugins and hooks a broader, more capable API \u2014 access to environment variables, settings, and session usage, plus the ability to draw real interactive terminal UI \u2014 while the renamed, more consistent action names and new validation keep that expanded surface from letting a plugin corrupt data it shouldn't touch or send oversized payloads.\n\n- Area: Plugins\n- Names: `fs.read`, `fs.write`, `fs.list`, `settings.read`, `env.get`\n- Tier: Use it now\n- Useful: 4\/5\n- Signal: 4\/5"}