typeclaw 0.48.1 → 0.48.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (39) hide show
  1. package/package.json +1 -1
  2. package/src/agent/index.ts +35 -9
  3. package/src/agent/plugin-tools.ts +14 -0
  4. package/src/agent/system-prompt.ts +8 -0
  5. package/src/agent/todo/continuation-policy.ts +11 -1
  6. package/src/agent/todo/continuation-state.ts +3 -1
  7. package/src/agent/todo/continuation-wiring.ts +2 -0
  8. package/src/agent/tool-file-safety.ts +7 -1
  9. package/src/agent/tools/channel-reply.ts +18 -1
  10. package/src/bundled-plugins/guard/policies/managed-config.ts +7 -20
  11. package/src/bundled-plugins/guard/policies/non-workspace-write.ts +7 -20
  12. package/src/bundled-plugins/guard/policies/skill-authoring.ts +8 -20
  13. package/src/bundled-plugins/memory/README.md +2 -0
  14. package/src/bundled-plugins/memory/dreaming.ts +2 -0
  15. package/src/bundled-plugins/security/policies/private-surface-read.ts +98 -55
  16. package/src/channels/adapters/discord-bot-reactions.ts +1 -0
  17. package/src/channels/adapters/discord-bot.ts +11 -2
  18. package/src/channels/adapters/discord-reactions.ts +1 -0
  19. package/src/channels/adapters/discord.ts +1 -0
  20. package/src/channels/adapters/slack-bot.ts +11 -2
  21. package/src/channels/adapters/slack.ts +1 -0
  22. package/src/channels/completion-claim.ts +307 -0
  23. package/src/channels/router.ts +275 -55
  24. package/src/channels/types.ts +4 -1
  25. package/src/config/providers.ts +100 -20
  26. package/src/container/start.ts +42 -0
  27. package/src/init/models-dev.ts +25 -8
  28. package/src/mcp/client.ts +65 -7
  29. package/src/mcp/tools.ts +71 -4
  30. package/src/path-safety/real-intended-path.ts +111 -0
  31. package/src/permissions/index.ts +1 -0
  32. package/src/permissions/permissions.ts +23 -0
  33. package/src/plugin/manager.ts +19 -1
  34. package/src/sandbox/canonical-secrets.ts +24 -4
  35. package/src/sandbox/hidden-paths.ts +8 -3
  36. package/src/sandbox/index.ts +2 -0
  37. package/src/skills/typeclaw-permissions/SKILL.md +13 -1
  38. package/src/skills/typeclaw-plugins/SKILL.md +91 -11
  39. package/typeclaw.schema.json +5 -0
@@ -99,6 +99,29 @@ export function findUnknownPermissions(
99
99
  return out
100
100
  }
101
101
 
102
+ // The mirror of findUnknownPermissions. `definePlugin({ permissions })`
103
+ // registers a string but grants nothing, so a plugin gating a surface on a
104
+ // fresh id without a matching `roles.<role>.permissions[]` entry is denied
105
+ // for EVERY caller including owner -- previously with no signal until the
106
+ // block fired at call time. Non-fatal: withholding a capability is a valid
107
+ // operator choice.
108
+ //
109
+ // Resolves the role table rather than reading raw config because
110
+ // expandOwnerWildcard auto-flows a plugin's `security.bypass.*` strings to
111
+ // owner; reading config would report every one of them as ungranted.
112
+ export function findUngrantedPluginPermissions(
113
+ roles: RolesConfig | undefined,
114
+ pluginPermissions: readonly string[],
115
+ ownerWildcardExclusions: readonly string[] = [],
116
+ ): string[] {
117
+ if (pluginPermissions.length === 0) return []
118
+ const granted = new Set<string>()
119
+ for (const role of buildRoleTable(roles ?? {}, pluginPermissions, ownerWildcardExclusions)) {
120
+ for (const permission of role.permissions) granted.add(permission)
121
+ }
122
+ return pluginPermissions.filter((permission) => !granted.has(permission))
123
+ }
124
+
102
125
  function closestPermission(target: string, known: ReadonlySet<string>): string {
103
126
  let best: { name: string; distance: number } | null = null
104
127
  for (const name of known) {
@@ -4,6 +4,7 @@ import type { ResolveGithubTokenForRepo } from '@/channels/github-token-bridge'
4
4
  import type { CronJob } from '@/cron'
5
5
  import {
6
6
  createPermissionService,
7
+ findUngrantedPluginPermissions,
7
8
  findUnknownPermissions,
8
9
  type PermissionService,
9
10
  type RolesConfig,
@@ -154,9 +155,10 @@ export async function loadPlugins(opts: LoadPluginsOptions): Promise<LoadPlugins
154
155
  // captured `permissions` by reference (their hooks read it at request time),
155
156
  // so we mutate that same object in place rather than returning a new one.
156
157
  const declaredPermissions = collectDeclaredPermissions(survivors)
158
+ const ownerWildcardExclusions = collectOwnerWildcardExclusions(survivors)
157
159
  permissions.replacePluginPermissions?.({
158
160
  pluginPermissions: declaredPermissions,
159
- ownerWildcardExclusions: collectOwnerWildcardExclusions(survivors),
161
+ ownerWildcardExclusions,
160
162
  })
161
163
 
162
164
  // Non-fatal: surface user-declared `permissions[]` strings that aren't in
@@ -171,6 +173,22 @@ export async function loadPlugins(opts: LoadPluginsOptions): Promise<LoadPlugins
171
173
  )
172
174
  }
173
175
 
176
+ // The opposite direction, and the one that silently ships dead code: the
177
+ // plugin declared a permission but no role grants it, so every surface
178
+ // gated on it is denied for all callers. Without this the only symptom is
179
+ // a `missing permission` block at call time, long after the boot that
180
+ // could have explained it.
181
+ for (const permission of findUngrantedPluginPermissions(opts.roles, declaredPermissions, ownerWildcardExclusions)) {
182
+ const declaredBy = survivors
183
+ .filter((p) => p.resolved.defined.permissions?.includes(permission))
184
+ .map((p) => p.resolved.name)
185
+ .join(', ')
186
+ console.warn(
187
+ `[permissions] plugin "${declaredBy}" declares "${permission}" but no role grants it — ` +
188
+ `every surface gated on it will be denied. Add it to roles.<role>.permissions[] in typeclaw.json and restart.`,
189
+ )
190
+ }
191
+
174
192
  return {
175
193
  registry,
176
194
  hooks,
@@ -3,16 +3,36 @@ import {
3
3
  LEGACY_AGENT_MESSENGER_CONFIG_RELATIVE_DIR,
4
4
  } from '@/agent-messenger/config-dir'
5
5
 
6
- export const CANONICAL_AGENT_SECRET_DIRS = [
7
- 'workspace/.config/gws',
8
- AGENT_MESSENGER_CONFIG_RELATIVE_DIR,
6
+ // Runtime-owned credential stores: TypeClaw writes and reads these itself, and
7
+ // no shipped skill ever invokes a CLI that reads them. Masked at EVERY role.
8
+ export const RUNTIME_OWNED_SECRET_DIRS = [
9
9
  // Retained permanently for interrupted migrations, operator backups under
10
- // the old name, and older installs. This is not an active config location.
10
+ // the old name, and older installs. This is not an active config location,
11
+ // so nothing an operator provisions today lands here.
11
12
  LEGACY_AGENT_MESSENGER_CONFIG_RELATIVE_DIR,
12
13
  '.typeclaw/home',
13
14
  '.typeclaw/logs',
14
15
  ] as const
15
16
 
17
+ // SECURITY / classification: operator-provisioned CLI credential stores. TypeClaw
18
+ // writes these through its own init/auth flows and points the matching CLI at them
19
+ // (`dockerfile.ts` bakes `ENV AGENT_MESSENGER_CONFIG_DIR`), so the agent is MEANT
20
+ // to read them — the bundled `agent-*` and gws skills shell out to CLIs that
21
+ // resolve exactly these files. Masking them at every role does not withhold a
22
+ // secret, it breaks the skill and leaves the CLI reporting its own "not
23
+ // authenticated", which a model relays as a fact about the upstream service.
24
+ //
25
+ // So they take the ordinary private-surface role gate, which is what applied to
26
+ // them before they were named here (they live under `workspace/`). Add a path
27
+ // here only if a shipped skill needs to read it; anything that must stay hidden
28
+ // from every role belongs in `secrets.json`, not in a masked directory.
29
+ export const OPERATOR_CLI_CREDENTIAL_DIRS = ['workspace/.config/gws', AGENT_MESSENGER_CONFIG_RELATIVE_DIR] as const
30
+
31
+ // Union: every directory that is masked for SOME role. Consumers that need the
32
+ // full set regardless of gating (write-zone vetoes, hardlink-alias scanning)
33
+ // use this; consumers that must respect the gate read the two lists above.
34
+ export const CANONICAL_AGENT_SECRET_DIRS = [...OPERATOR_CLI_CREDENTIAL_DIRS, ...RUNTIME_OWNED_SECRET_DIRS] as const
35
+
16
36
  export const CANONICAL_AGENT_SECRET_FILES = ['.env', 'secrets.json', 'auth.json'] as const
17
37
 
18
38
  // Trusted runtime processes use this ephemeral container HOME. bwrap builds an
@@ -5,7 +5,12 @@ import type { SessionOrigin } from '@/agent/session-origin'
5
5
  import { CORE_PERMISSIONS } from '@/permissions/builtins'
6
6
  import type { PermissionService } from '@/permissions/permissions'
7
7
 
8
- import { CANONICAL_AGENT_SECRET_DIRS, CANONICAL_AGENT_SECRET_FILES } from './canonical-secrets'
8
+ import {
9
+ CANONICAL_AGENT_SECRET_DIRS,
10
+ CANONICAL_AGENT_SECRET_FILES,
11
+ OPERATOR_CLI_CREDENTIAL_DIRS,
12
+ RUNTIME_OWNED_SECRET_DIRS,
13
+ } from './canonical-secrets'
9
14
  import { SandboxMaskTargetError } from './errors'
10
15
  import { CANONICAL_AGENT_RUNTIME_PRIVATE_FILES } from './runtime-private'
11
16
 
@@ -36,8 +41,8 @@ export function resolveHiddenPaths(
36
41
  ): HiddenPaths {
37
42
  const seesPrivate = canSeePrivateSurface(permissions, origin)
38
43
  const dirs = [
39
- ...CANONICAL_AGENT_SECRET_DIRS.map((dir) => join(agentDir, dir)),
40
- ...(seesPrivate ? [] : PRIVATE_DIRS.map((dir) => join(agentDir, dir))),
44
+ ...RUNTIME_OWNED_SECRET_DIRS.map((dir) => join(agentDir, dir)),
45
+ ...(seesPrivate ? [] : [...OPERATOR_CLI_CREDENTIAL_DIRS, ...PRIVATE_DIRS].map((dir) => join(agentDir, dir))),
41
46
  ]
42
47
  const files = [...CANONICAL_AGENT_SECRET_FILES, ...CANONICAL_AGENT_RUNTIME_PRIVATE_FILES].map((f) =>
43
48
  join(agentDir, f),
@@ -5,6 +5,8 @@ export {
5
5
  CANONICAL_HOME_SECRET_DIRS,
6
6
  CANONICAL_HOME_SECRET_FILES,
7
7
  CONTAINER_RUNTIME_HOME,
8
+ OPERATOR_CLI_CREDENTIAL_DIRS,
9
+ RUNTIME_OWNED_SECRET_DIRS,
8
10
  } from './canonical-secrets'
9
11
  export { CANONICAL_AGENT_RUNTIME_PRIVATE_FILES } from './runtime-private'
10
12
  export {
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: typeclaw-permissions
3
- description: Use this skill whenever the user asks who you talk to, why you went silent in a channel, why a tool call was blocked with `blocked:` / "denied by permissions", how to grant access, what a role can or can't do, or whenever you are about to edit the `roles` block in `typeclaw.json`. Triggers include "who can talk to you", "why aren't you replying in #channel", "add me to the agent", "let X talk to you", "grant trusted to Y", "your role", "what permissions do you have", "blocked", "denied by permissions", "owner", "trusted", "member", "guest", "match rule", "channel.respond", "security.bypass", "scheduledByRole", "spawnedByRole", or any mention of `roles` / `roles[*].match` / `roles[*].permissions` in `typeclaw.json`. Read it before editing `roles` — the file has a strict match-rule DSL, restart semantics, and silent failure modes (a missing role match makes you silently drop every inbound), and the agent's own runtime behavior depends on its role and resolved permissions.
3
+ description: Use this skill whenever the user asks who you talk to, why you went silent in a channel, why a tool call was blocked with `blocked:` / "denied by permissions", how to grant access, what a role can or can't do, or whenever you are about to edit the `roles` block in `typeclaw.json`. Triggers include "who can talk to you", "why aren't you replying in #channel", "add me to the agent", "let X talk to you", "grant trusted to Y", "your role", "what permissions do you have", "blocked", "denied by permissions", "owner", "trusted", "member", "guest", "match rule", "channel.respond", "security.bypass", "scheduledByRole", "spawnedByRole", "missing permission", "plugin permission", "always denied", or any mention of `roles` / `roles[*].match` / `roles[*].permissions` in `typeclaw.json`. Read it before editing `roles` — the file has a strict match-rule DSL, restart semantics, and silent failure modes (a missing role match makes you silently drop every inbound), and the agent's own runtime behavior depends on its role and resolved permissions.
4
4
  ---
5
5
 
6
6
  # typeclaw-permissions
@@ -134,6 +134,18 @@ Note on the two-step `gitRemoteTainted` defense: trusted bypasses `gitExfil` via
134
134
 
135
135
  User-declared `permissions[]` strings that don't appear in any of the three sources are **logged as warnings at boot** (`[permissions] role "X" declares unknown permission "Y" — did you mean 'Z'?`) but the role still resolves with the unknown string in its list. This is intentional — the runtime is forward-compatible with strings from plugins that aren't loaded yet — but it also means typos silently fail to bypass guards. If you wrote `security.bypass.secretExfilBach` instead of `Bash`, no guard will be skipped and you will only notice when you read the boot logs.
136
136
 
137
+ ### The mirror failure: a plugin permission no role grants
138
+
139
+ The typo case above is a role naming a permission that doesn't exist. The opposite also happens: a plugin declares a permission via `definePlugin({ permissions: [...] })` (see `typeclaw-plugins`), but no role's `permissions[]` in `typeclaw.json` ever lists it. Declaring a permission only registers the string into the known-permission universe — it does not grant it. The only strings that auto-flow to a role are `security.bypass.*` ones, and only to `owner`, via the wildcard sentinel. Every other plugin-declared string starts out held by **nobody** — not owner, not trusted, not member, not guest.
140
+
141
+ **Symptom**: a plugin tool or command fails every call, for every user including owner, with a message naming the id — `missing permission: <id>`, or a `blocked:` reason citing it. Unlike a security-guard block, there's no acknowledgement and no role that already has it to fall back to; the string simply isn't granted anywhere.
142
+
143
+ **Boot signal**: `[permissions] plugin "<name>" declares "<id>" but no role grants it — every surface gated on it will be denied. Add it to roles.<role>.permissions[] in typeclaw.json and restart.`
144
+
145
+ **Fix**: add the exact string to `roles.<role>.permissions[]` and restart — same restart-required rule as every other `permissions[]` edit in this file. If `<role>` is a built-in (`owner`/`trusted`/`member`), remember an explicit `permissions[]` replaces that role's default list wholesale (see the table above); re-list the role's full default set alongside the new string, or the role silently loses `channel.respond` and everything else.
146
+
147
+ See `typeclaw-plugins` for the authoring side of this — declaring and gating on a permission is a two-part recipe, and shipping the declaration without the grant leaves a surface that looks wired but is dead.
148
+
137
149
  ## When a tool is blocked
138
150
 
139
151
  The security plugin's `tool.before` hook produces block messages. For most guards the message is:
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: typeclaw-plugins
3
- description: TypeClaw plugin authoring and operation guide. Use when writing, editing, configuring, debugging, or installing a TypeClaw plugin — including any work with definePlugin, defineTool, defineSubagent, plugin hooks (session.start/end/idle/prompt, tool.before/after), plugin cron jobs, plugin commands (host/container/either CLI subcommands callable as `typeclaw <name>`), plugin skills, the typeclaw/plugin import path, or per-plugin config blocks in typeclaw.json. Also use when you need to bridge a cron `exec` job to LLM-driven work — the canonical pattern is a `surface: 'container'` plugin command whose `run` calls `ctx.prompt(...)`, invoked as `typeclaw <command>` from cron's `command` array. Triggers on mentions of 'TypeClaw plugin', 'definePlugin', 'plugin hook', 'plugin cron', 'plugin command', 'PluginCommand', 'ContainerCommand', 'HostCommand', 'EitherCommand', 'ctx.prompt', 'ctx.subagent', 'ctx.exec', 'plugins[]', 'typeclaw-plugin-', or any file under src/plugin/ or plugins/.
3
+ description: TypeClaw plugin authoring and operation guide. Use when writing, editing, configuring, debugging, or installing a TypeClaw plugin — including any work with definePlugin, defineTool, defineSubagent, plugin hooks (session.start/end/idle/prompt, tool.before/after), plugin cron jobs, plugin commands (host/container/either CLI subcommands callable as `typeclaw <name>`), plugin skills, the typeclaw/plugin import path, or per-plugin config blocks in typeclaw.json. Also use when you need to bridge a cron `exec` job to LLM-driven work — the canonical pattern is a `surface: 'container'` plugin command whose `run` calls `ctx.prompt(...)`, invoked as `typeclaw <command>` from cron's `command` array. Triggers on mentions of 'TypeClaw plugin', 'definePlugin', 'plugin hook', 'plugin cron', 'plugin command', 'PluginCommand', 'ContainerCommand', 'HostCommand', 'EitherCommand', 'ctx.prompt', 'ctx.subagent', 'ctx.exec', 'plugins[]', 'typeclaw-plugin-', 'plugin permission', 'definePlugin permissions', 'missing permission', 'permission-gated tool', or any file under src/plugin/ or plugins/.
4
4
  ---
5
5
 
6
6
  # TypeClaw Plugins
@@ -203,6 +203,7 @@ tools: {
203
203
  - Args are **validated once** before `tool.before` hooks see them — no double-parse. Hooks receive `event.args` as a **mutable bag** (`Record<string, unknown>`); mutations propagate to later hooks and to `execute`.
204
204
  - `ToolContext` is **stripped down** to `{ signal, sessionId, agentDir, logger }`. It does NOT expose the engine's `ExtensionContext`. If your tool wants `read`/`bash`/etc., it cannot call them — declare a subagent with `tools: [readTool, ...]` instead.
205
205
  - `ToolResult.content` uses TypeClaw's `ContentPart` union: `{ type: 'text'; text }` or `{ type: 'image'; mimeType; data }`.
206
+ - Tools have **no `permissions` field**. To gate one per role, declare the string on the plugin and block from a `tool.before` hook — and grant it in `typeclaw.json`, or the tool is dead for every caller. See "`permissions: [...]` — declaring and gating" in §5.7.
206
207
 
207
208
  #### Declare every filesystem operand
208
209
 
@@ -330,7 +331,7 @@ type CronHandlerContext = {
330
331
  readonly agentDir: string // /agent in container
331
332
  readonly logger: PluginLogger
332
333
  readonly signal: AbortSignal // reserved for future cancellation; currently inert
333
- readonly permissions: PermissionService
334
+ readonly permissions: PermissionService // live service — has() gating, see "permissions: [...] — declaring and gating" in §5.7 below
334
335
  readonly origin: SessionOrigin // { kind: 'cron', jobKind: 'handler', ... }
335
336
  readonly prompt: (text: string) => Promise<string> // full agent session, slim system prompt mode
336
337
  readonly subagent: (name, payload?) => Promise<void>
@@ -481,7 +482,7 @@ type ContainerCommandContext = {
481
482
  readonly version: string | undefined
482
483
  readonly agentDir: string // /agent inside the container
483
484
  readonly logger: PluginLogger
484
- readonly permissions: PermissionService
485
+ readonly permissions: PermissionService // live service — has() gating, see "permissions: [...] — declaring and gating" below
485
486
  readonly origin: SessionOrigin // caller's origin — cron job, TUI op, etc.
486
487
  readonly signal: AbortSignal // aborts on ws close or host Ctrl-C
487
488
  readonly stdin: ReadableStream<Uint8Array>
@@ -579,20 +580,98 @@ args: z.object({
579
580
  - `.describe(...)` populates `--help` output. Use it.
580
581
  - Omit `args` entirely if the command takes no flags.
581
582
 
582
- #### `permissions: [...]` on the command
583
+ #### `permissions: [...]` — declaring and gating
584
+
585
+ **Declaring a permission grants it to nobody.** `definePlugin({ permissions: [...] })` only registers the string into the known-permission universe — used for the boot-time typo warning and, for `security.bypass.*` strings only, owner-wildcard expansion. Every other permission string starts out held by no role: not owner, not trusted, not member, not guest. A plugin that gates a command or tool on a permission and never adds that string to any `roles.<role>.permissions[]` in `typeclaw.json` has shipped a permanently blocked surface — declaring is half the work, granting is the other half. Never ship one without the other.
586
+
587
+ **`definePlugin({ permissions })` is the only declaration that does anything.** `ContainerCommand.permissions` exists in the type but no production path reads it — it is not rendered in `--help` (`renderCommandHelp` prints description, plugin, surface, options), not collected into the known-permission universe (`collectDeclaredPermissions` reads only the plugin-level list), and never checked for you. Declare at the plugin level. Setting it on a command instead is worse than useless: the string stays outside the known universe, so granting it in a role also trips the `unknown permission` typo warning at boot.
588
+
589
+ **Gating a command** — declare the string on the plugin, then check it inside `run`:
583
590
 
584
591
  ```ts
592
+ const WRITE_PERMISSION = 'standup.write.entry'
593
+
594
+ export default definePlugin({
595
+ permissions: [WRITE_PERMISSION],
596
+ commands: {
597
+ standup: {
598
+ surface: 'container',
599
+ description: 'Append a standup entry.',
600
+ async run(ctx, args) {
601
+ if (!ctx.permissions.has(ctx.origin, WRITE_PERMISSION)) {
602
+ const writer = ctx.stderr.getWriter()
603
+ await writer.write(new TextEncoder().encode(`missing permission: ${WRITE_PERMISSION}\n`))
604
+ writer.releaseLock()
605
+ return 1
606
+ }
607
+ // ...
608
+ return 0
609
+ },
610
+ },
611
+ },
612
+ plugin: async () => ({}),
613
+ })
614
+ ```
615
+
616
+ ```jsonc
617
+ // typeclaw.json — the grant this declaration needs, or the command always fails
585
618
  {
586
- surface: 'container',
587
- permissions: ['standup-log.write.standup'],
588
- async run(ctx, args) {
589
- ctx.permissions.assert(ctx.origin, 'standup-log.write.standup')
590
- // ...
619
+ "roles": {
620
+ "trusted": {
621
+ "permissions": ["standup.write.entry" /* ...trusted's full default list too, see below */],
622
+ },
591
623
  },
592
624
  }
593
625
  ```
594
626
 
595
- Declared permissions are surfaced in `--help` and (for container commands) checked against the caller's origin. Same `<plugin>.<verb>.<noun>` shape as the rest of the permission system; see `typeclaw-permissions`.
627
+ `PermissionService` exposes `has(origin, permission)` — a boolean. **There is no `assert`.** Nothing authorizes on your behalf: `has` resolves the caller's origin to a role and returns false unless that role's permission list contains the exact string, and it is on you to fail the call. Same `<plugin>.<verb>.<noun>` shape as the rest of the permission system; see `typeclaw-permissions`.
628
+
629
+ **Permission ids cannot contain hyphens.** `roles[].permissions[]` validates against `^[a-z][a-z0-9]*(\.[a-z][a-zA-Z0-9]*)+$` — dot-separated segments, each starting lowercase, alphanumeric after (camelCase is fine, `-` is not). Nothing validates the `definePlugin({ permissions })` side, so a hyphenated id like `standup-log.write.entry` declares happily and then **cannot be granted at all**: the config edit fails schema validation. A hyphenated plugin name needs a hyphen-free permission namespace — plugin `standup-log` uses `standup.write.entry`.
630
+
631
+ **Gating a tool** — tools have no `permissions` field of their own; gate them from a `tool.before` hook with `pluginContext.permissions.has(event.origin, ...)`:
632
+
633
+ ```ts
634
+ const PUBLISH_PERMISSION = 'standup.publish.remote'
635
+
636
+ export default definePlugin({
637
+ permissions: [PUBLISH_PERMISSION],
638
+ plugin: async (pluginContext) => ({
639
+ tools: {
640
+ standup_publish: defineTool({
641
+ /* ... */
642
+ }),
643
+ },
644
+ hooks: {
645
+ 'tool.before': (event) => {
646
+ if (event.tool !== 'standup_publish') return
647
+ if (pluginContext.permissions.has(event.origin, PUBLISH_PERMISSION)) return
648
+ return { block: true, reason: `missing permission: ${PUBLISH_PERMISSION}` }
649
+ },
650
+ },
651
+ }),
652
+ })
653
+ ```
654
+
655
+ ```jsonc
656
+ // typeclaw.json — same recipe: declaring PUBLISH_PERMISSION above grants nothing on its own
657
+ {
658
+ "roles": {
659
+ "trusted": {
660
+ "permissions": ["standup.publish.remote" /* ...trusted's full default list too, see below */],
661
+ },
662
+ },
663
+ }
664
+ ```
665
+
666
+ Omit that second half and the failure is silent and total: the plugin compiles, boots, and registers the tool, but every call — including from `owner` — is blocked forever, because nothing ever granted the string. The tool looks wired and is dead.
667
+
668
+ **Built-in roles: an explicit `permissions[]` REPLACES the default, it does not add to it.** Add your string to `roles.owner.permissions[]` and you must re-list `owner`'s entire default permission set alongside it, including the `security.bypass.*` strings the wildcard sentinel would otherwise expand for you (the sentinel is an internal runtime value — you cannot write it, and the schema rejects it). Don't copy the default lists from memory; read `typeclaw-permissions` for the current per-role defaults.
669
+
670
+ **Restart required.** `roles.<role>.permissions[]` is a `restart-required` field — `typeclaw reload` will not pick up a new grant. `roles.<role>.match[]` is live-reloadable; permissions are not. Run `typeclaw restart`.
671
+
672
+ **The boot-time signal for a forgotten grant**: `[permissions] plugin "<name>" declares "<id>" but no role grants it — every surface gated on it will be denied. Add it to roles.<role>.permissions[] in typeclaw.json and restart.` If you see this at boot, or a tool/command you just wired is blocked for every caller including yourself, this is why.
673
+
674
+ **When NOT to declare a permission.** If your plugin is the only caller of the surface it gates — no operator will ever want to withhold or grant this capability per role — the check is just an `if (false)` with extra steps. Declare a permission only when you actually want an operator able to grant or withhold it per role.
596
675
 
597
676
  #### `isolated: true` (container surface only)
598
677
 
@@ -631,6 +710,7 @@ type PluginContext<TConfig = never> = {
631
710
  readonly agentDir: string // absolute, agent folder root
632
711
  readonly config: TConfig // inferred from configSchema
633
712
  readonly logger: PluginLogger // prefixed: [plugin:<name>]
713
+ readonly permissions: PermissionService // live service — has() gating, see "permissions: [...] — declaring and gating" in §5.7 above
634
714
  spawnSubagent: (name: string, payload?: unknown) => Promise<void>
635
715
  }
636
716
  ```
@@ -872,7 +952,7 @@ export default definePlugin({
872
952
  commands: {
873
953
  /* name: { surface, run, args?, ... } */
874
954
  }, // optional, declared BY-VALUE (not inside factory)
875
- permissions: ['my-plugin.write.x'], // optional
955
+ permissions: ['myplugin.write.x'], // optional; declares only — grant it in roles.<role>.permissions[] in typeclaw.json or nobody has it
876
956
  plugin: async (ctx) => ({
877
957
  // required
878
958
  tools,
@@ -57,6 +57,7 @@
57
57
  "minimax/MiniMax-M2",
58
58
  "deepseek/deepseek-v4-flash",
59
59
  "deepseek/deepseek-v4-pro",
60
+ "upstage/solar-pro4",
60
61
  "upstage/solar-open2",
61
62
  "upstage/solar-pro3",
62
63
  "upstage/solar-pro2",
@@ -114,6 +115,7 @@
114
115
  "minimax/MiniMax-M2",
115
116
  "deepseek/deepseek-v4-flash",
116
117
  "deepseek/deepseek-v4-pro",
118
+ "upstage/solar-pro4",
117
119
  "upstage/solar-open2",
118
120
  "upstage/solar-pro3",
119
121
  "upstage/solar-pro2",
@@ -172,6 +174,7 @@
172
174
  "minimax/MiniMax-M2",
173
175
  "deepseek/deepseek-v4-flash",
174
176
  "deepseek/deepseek-v4-pro",
177
+ "upstage/solar-pro4",
175
178
  "upstage/solar-open2",
176
179
  "upstage/solar-pro3",
177
180
  "upstage/solar-pro2",
@@ -228,6 +231,7 @@
228
231
  "minimax/MiniMax-M2",
229
232
  "deepseek/deepseek-v4-flash",
230
233
  "deepseek/deepseek-v4-pro",
234
+ "upstage/solar-pro4",
231
235
  "upstage/solar-open2",
232
236
  "upstage/solar-pro3",
233
237
  "upstage/solar-pro2",
@@ -285,6 +289,7 @@
285
289
  "minimax/MiniMax-M2",
286
290
  "deepseek/deepseek-v4-flash",
287
291
  "deepseek/deepseek-v4-pro",
292
+ "upstage/solar-pro4",
288
293
  "upstage/solar-open2",
289
294
  "upstage/solar-pro3",
290
295
  "upstage/solar-pro2",