typeclaw 0.45.0 → 0.46.0

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 (147) hide show
  1. package/README.md +1 -1
  2. package/package.json +3 -2
  3. package/src/agent/git-nudge.ts +2 -1
  4. package/src/agent/index.ts +67 -25
  5. package/src/agent/live-subagents.ts +18 -0
  6. package/src/agent/loop-guard.ts +208 -10
  7. package/src/agent/multimodal/index.ts +1 -1
  8. package/src/agent/multimodal/look-at.ts +78 -44
  9. package/src/agent/multimodal/looker.ts +151 -39
  10. package/src/agent/network/response-body.ts +26 -0
  11. package/src/agent/network/safe-http.ts +198 -0
  12. package/src/agent/plugin-tools.ts +438 -162
  13. package/src/agent/provider-error.ts +62 -4
  14. package/src/agent/restart/index.ts +61 -40
  15. package/src/agent/restart-handoff/index.ts +73 -4
  16. package/src/agent/retry-same-ref.ts +66 -0
  17. package/src/agent/reviewer-bash-policy.ts +42 -1
  18. package/src/agent/session-origin.ts +2 -0
  19. package/src/agent/subagent-drain.ts +117 -7
  20. package/src/agent/subagents.ts +77 -18
  21. package/src/agent/throttle-circuit.ts +25 -5
  22. package/src/agent/tool-error-remediation.ts +72 -0
  23. package/src/agent/tool-file-safety.ts +1050 -0
  24. package/src/agent/tools/channel-fetch-attachment.ts +10 -3
  25. package/src/agent/tools/channel-reply.ts +15 -1
  26. package/src/agent/tools/channel-send.ts +17 -1
  27. package/src/agent/tools/ddg.ts +16 -2
  28. package/src/agent/tools/post-github-review.ts +199 -0
  29. package/src/agent/tools/spawn-subagent.ts +21 -18
  30. package/src/agent/tools/webfetch/fetch.ts +143 -183
  31. package/src/agent/tools/webfetch/tool.ts +2 -3
  32. package/src/agent/tools/websearch.ts +23 -2
  33. package/src/agent/tools-without-local-file-operands.ts +27 -0
  34. package/src/agent/turn-runner.ts +109 -15
  35. package/src/bundled-plugins/backup/index.ts +2 -1
  36. package/src/bundled-plugins/backup/runner.ts +2 -1
  37. package/src/bundled-plugins/doc-render/render.ts +93 -12
  38. package/src/bundled-plugins/doc-render/skills/typeclaw-render-pdf/SKILL.md +13 -13
  39. package/src/bundled-plugins/github-cli-auth/effective-approval.ts +16 -6
  40. package/src/bundled-plugins/github-cli-auth/gh-command.ts +555 -15
  41. package/src/bundled-plugins/github-cli-auth/index.ts +131 -135
  42. package/src/bundled-plugins/github-cli-auth/review-checkout.ts +138 -0
  43. package/src/bundled-plugins/guard/policies/uncommitted-changes.ts +2 -1
  44. package/src/bundled-plugins/memory/README.md +23 -11
  45. package/src/bundled-plugins/memory/append-tool.ts +15 -8
  46. package/src/bundled-plugins/memory/citations.ts +22 -9
  47. package/src/bundled-plugins/memory/dreaming.ts +13 -8
  48. package/src/bundled-plugins/memory/find-entry-tool.ts +4 -0
  49. package/src/bundled-plugins/memory/index.ts +0 -4
  50. package/src/bundled-plugins/memory/load-memory.ts +8 -3
  51. package/src/bundled-plugins/memory/provenance-index.ts +717 -0
  52. package/src/bundled-plugins/memory/provenance-sanitize.ts +40 -0
  53. package/src/bundled-plugins/memory/references/store-reference-tool.ts +4 -0
  54. package/src/bundled-plugins/memory/search-tool.ts +163 -60
  55. package/src/bundled-plugins/memory/stream-events.ts +2 -0
  56. package/src/bundled-plugins/memory/vector/hybrid.ts +126 -13
  57. package/src/bundled-plugins/researcher/write-report.ts +6 -3
  58. package/src/bundled-plugins/reviewer/index.ts +2 -2
  59. package/src/bundled-plugins/reviewer/reviewer.ts +10 -3
  60. package/src/bundled-plugins/reviewer/skills/code-review.ts +24 -9
  61. package/src/bundled-plugins/scout/scout.ts +8 -0
  62. package/src/bundled-plugins/security/index.ts +4 -4
  63. package/src/bundled-plugins/security/policies/outbound-secret-scan.ts +1 -0
  64. package/src/bundled-plugins/security/policies/private-surface-read.ts +220 -29
  65. package/src/bundled-plugins/security/policies/secret-exfil-read.ts +1 -0
  66. package/src/bundled-plugins/security/policies/ssrf.ts +29 -9
  67. package/src/channels/adapters/discord-bot-channel-resolver.ts +26 -14
  68. package/src/channels/adapters/discord-bot-thread-room.ts +44 -12
  69. package/src/channels/adapters/discord-bot.ts +91 -10
  70. package/src/channels/adapters/discord-channel-resolver.ts +91 -23
  71. package/src/channels/adapters/discord-id.ts +4 -0
  72. package/src/channels/adapters/discord-resolver-cache.ts +41 -0
  73. package/src/channels/adapters/discord.ts +57 -7
  74. package/src/channels/adapters/github/auth-app.ts +41 -12
  75. package/src/channels/adapters/github/index.ts +23 -11
  76. package/src/channels/adapters/github/review-submitter.ts +302 -0
  77. package/src/channels/adapters/kakaotalk-channel-resolver.ts +12 -1
  78. package/src/channels/adapters/kakaotalk-fetch-attachment.ts +8 -4
  79. package/src/channels/adapters/kakaotalk-typing.ts +127 -0
  80. package/src/channels/adapters/kakaotalk.ts +19 -0
  81. package/src/channels/adapters/slack-attachment-download.ts +71 -0
  82. package/src/channels/adapters/slack-bot.ts +19 -8
  83. package/src/channels/adapters/slack-classify.ts +21 -2
  84. package/src/channels/adapters/slack.ts +59 -7
  85. package/src/channels/adapters/telegram-bot.ts +18 -5
  86. package/src/channels/adapters/webex-bot.ts +8 -3
  87. package/src/channels/adapters/webex.ts +8 -3
  88. package/src/channels/fetch-attachment.ts +43 -0
  89. package/src/{bundled-plugins/github-cli-auth/approve-idempotency.ts → channels/github-review-verdict-coordinator.ts} +25 -1
  90. package/src/channels/github-token-bridge.ts +10 -3
  91. package/src/channels/manager.ts +9 -0
  92. package/src/channels/router.ts +568 -12
  93. package/src/channels/types.ts +28 -1
  94. package/src/cli/channel.ts +1 -1
  95. package/src/cli/init.ts +1 -1
  96. package/src/cli/model.ts +57 -7
  97. package/src/compose/stop.ts +17 -5
  98. package/src/config/config.ts +6 -6
  99. package/src/config/models-mutation.ts +13 -1
  100. package/src/config/providers.ts +176 -0
  101. package/src/container/start.ts +49 -10
  102. package/src/doctor/checks.ts +3 -1
  103. package/src/doctor/commit.ts +2 -1
  104. package/src/doctor/file-ownership.ts +52 -0
  105. package/src/dreams/git.ts +2 -1
  106. package/src/git/hookless.ts +5 -0
  107. package/src/git/reconcile-ignored.ts +18 -5
  108. package/src/git/secret-history.ts +371 -0
  109. package/src/git/system-commit.ts +12 -6
  110. package/src/init/dockerfile.ts +86 -5
  111. package/src/init/index.ts +17 -5
  112. package/src/init/models-dev.ts +4 -0
  113. package/src/init/validate-api-key.ts +2 -0
  114. package/src/mcp/tools.ts +16 -3
  115. package/src/permissions/builtins.ts +3 -1
  116. package/src/plugin/context.ts +2 -0
  117. package/src/plugin/index.ts +1 -0
  118. package/src/plugin/manager.ts +4 -0
  119. package/src/plugin/types.ts +21 -0
  120. package/src/run/index.ts +40 -0
  121. package/src/run/llm-fetch-observer.ts +188 -13
  122. package/src/sandbox/build.ts +37 -15
  123. package/src/sandbox/canonical-secrets.ts +18 -0
  124. package/src/sandbox/env-exposure.ts +80 -0
  125. package/src/sandbox/errors.ts +13 -6
  126. package/src/sandbox/hidden-paths.ts +102 -44
  127. package/src/sandbox/index.ts +22 -4
  128. package/src/sandbox/package-install.ts +3 -27
  129. package/src/sandbox/policy.ts +11 -25
  130. package/src/sandbox/privileged-runtime.ts +255 -0
  131. package/src/sandbox/session-tmp.ts +8 -2
  132. package/src/sandbox/writable-zones.ts +204 -140
  133. package/src/secrets/index.ts +8 -0
  134. package/src/secrets/refresh-provider-oauth.ts +128 -0
  135. package/src/server/command-runner.ts +48 -4
  136. package/src/server/index.ts +4 -0
  137. package/src/skills/typeclaw-channel-github/SKILL.md +49 -56
  138. package/src/skills/typeclaw-claude-code/SKILL.md +24 -60
  139. package/src/skills/typeclaw-claude-code/references/auth-flow.md +17 -158
  140. package/src/skills/typeclaw-codex-cli/SKILL.md +19 -49
  141. package/src/skills/typeclaw-codex-cli/references/auth-flow.md +17 -154
  142. package/src/skills/typeclaw-config/SKILL.md +5 -5
  143. package/src/skills/typeclaw-config/references/recommended-mounts.md +24 -24
  144. package/src/skills/typeclaw-github-contributing/SKILL.md +23 -26
  145. package/src/skills/typeclaw-memory/SKILL.md +9 -3
  146. package/src/skills/typeclaw-permissions/SKILL.md +19 -15
  147. package/typeclaw.schema.json +20 -0
@@ -416,6 +416,8 @@ Do **not** edit `typeclaw.json` to a model the registry doesn't know, even if th
416
416
 
417
417
  `typeclaw.json` does **not** hold API keys or OAuth tokens. Credentials live in two gitignored files, with `secrets.json` as the canonical store and `.env` retained for env-var overrides and parity with non-typeclaw tooling that reads from the environment:
418
418
 
419
+ **Model boundary:** this section documents operator-owned state; it is not an editing runbook for the agent. Model-driven tools must never read, create, modify, validate, or delete `.env`, `secrets.json`, or `auth.json`, even when the user supplies a value or an acknowledgement flag. Tell the operator to use the TypeClaw host-stage init/provider/channel commands and restart the container. Do not ask them to paste credentials into chat.
420
+
419
421
  - **`./secrets.json`** (canonical structured store): a `v2` envelope managed by `SecretsBackend` (wraps `pi-coding-agent`'s `AuthStorage`). Written by `typeclaw init`, the OAuth refresh path, and explicit user-driven rotation. Two top-level slices:
420
422
  - `providers.*` — per-provider credentials. API-key providers store `{ type: 'api_key', key: <Secret> }`. OAuth providers store the `pi-coding-agent` token blob `{ type: 'oauth', access_token, refresh_token, expires_at, ... }`. The container auto-refreshes OAuth tokens with file locking; api-key writes only happen on explicit user-driven rotation.
421
423
  - `channels.*` — per-adapter credentials, with named fields per adapter:
@@ -430,7 +432,7 @@ Do **not** edit `typeclaw.json` to a model the registry doesn't know, even if th
430
432
  - `FIREWORKS_API_KEY` — for any `fireworks/...` model.
431
433
  - `ANTHROPIC_API_KEY` — for any `anthropic/...` model when using API-key auth.
432
434
 
433
- New typeclaw secrets should land in `secrets.json` (via `typeclaw init` or a structured edit) — `.env` is no longer the default home.
435
+ New TypeClaw secrets should be provisioned by the operator through host-stage TypeClaw setup. A model must not perform a "structured edit" of either secret store.
434
436
 
435
437
  ### The `Secret` shape and env-wins resolution
436
438
 
@@ -465,11 +467,9 @@ Every secret-bearing field in `secrets.json` is a **`Secret`**: either a plain s
465
467
 
466
468
  ### Switching credentials
467
469
 
468
- If a user wants to switch from API key to OAuth (or vice versa) for a provider that supports both, the easiest path is to delete the relevant entry from `secrets.json#providers` (and any matching env-var override in `.env`) and re-run `typeclaw init` from inside the agent folder — it'll prompt for the auth method again.
469
-
470
- If the user wants to rotate an api-key, edit `secrets.json#providers.<provider>.key` — rewrite the `value` field (preserving any `env` binding), or remove the entry entirely if an env-var override is taking over. `.env` is a secondary path that still works (env-wins picks it up immediately), but `secrets.json` is the durable home. After either, `typeclaw restart` on the host stage.
470
+ Credential switching and rotation are direct-operator host actions. Tell the operator to use the host-stage TypeClaw provider/init flow appropriate to the provider, then run `typeclaw restart`. The model must not delete provider entries, rewrite `Secret` values, remove env overrides, or verify the result by reading either file.
471
471
 
472
- Never echo, log, or commit values from `secrets.json` or `.env`. Both are gitignored by default — keep them that way.
472
+ Never request, echo, log, or commit values from `secrets.json` or `.env`. Gitignore is not an authorization boundary; both files remain inaccessible to model-driven tools.
473
473
 
474
474
  ## Editing `typeclaw.json` safely
475
475
 
@@ -106,14 +106,14 @@ Treat the act of suggesting these as a moment to pause and confirm. They are ans
106
106
 
107
107
  ### macOS Mail — local mailboxes
108
108
 
109
- | Platform | Path | `readOnly` | TCC | Notes |
110
- | ---------------------------------- | ----------------------------------------------------------- | ---------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
111
- | macOS 14+ (Sonoma, Sequoia, Tahoe) | `~/Library/Mail/V10` | `true` | **FDA** | The `V10` directory holds per-account `.mbox`-like dirs containing `.emlx` files (one per message). The format is parseable as RFC822 + a small Apple-specific binary plist trailer. |
112
- | macOS 13 (Ventura) | `~/Library/Mail/V9` | `true` | **FDA** | Same shape, older version dir. |
113
- | macOS ≤12 | `~/Library/Mail/V8` or earlier | `true` | **FDA** | Same shape. |
114
- | Linux — Thunderbird | `~/.thunderbird/<profile>.default-release/Mail/` | `true` | — | `.msf` index + `mbox` files. No TCC. |
115
- | Linux — Evolution | `~/.local/share/evolution/mail/` | `true` | — | Maildir layout. No TCC. |
116
- | WSL — Outlook (Win32) | `/mnt/c/Users/<name>/AppData/Local/Microsoft/Outlook/*.pst` | `true` | — | PST is a proprietary binary format; the agent needs `libpff` or similar to read it. Not as plug-and-play as `.emlx`. Warn the user. |
109
+ | Platform | Path | `readOnly` | TCC | Notes |
110
+ | ------------------------------------------- | ------------------------------------------------------------------- | ---------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
111
+ | macOS 13+ (Ventura, Sonoma, Sequoia, Tahoe) | `~/Library/Mail/V10` | `true` | **FDA** | The `V10` directory holds per-account `.mbox`-like dirs containing `.emlx` files (one per message). The format is parseable as RFC822 + a small Apple-specific binary plist trailer. The version bumped to `V10` in Ventura and has stayed there through Tahoe. |
112
+ | macOS 12 (Monterey) | `~/Library/Mail/V9` | `true` | **FDA** | Same shape, previous version dir. |
113
+ | macOS 11 (Big Sur) | `~/Library/Mail/V8` | `true` | **FDA** | Same shape. Older releases use lower `V<n>` numbers (V7 = Catalina, and down). |
114
+ | Linux — Thunderbird | `~/.thunderbird/<profile>.default-release/Mail/` | `true` | — | `.msf` index + `mbox` files. No TCC. |
115
+ | Linux — Evolution | `~/.local/share/evolution/mail/` | `true` | — | Maildir layout. No TCC. |
116
+ | WSL — Outlook (Win32) | `/mnt/c/Users/<name>/AppData/Local/Microsoft/Outlook/<mailbox>.pst` | `true` | — | Replace `<mailbox>` with a real PST filename, or mount the `.../Microsoft/Outlook/` dir and point at the file — mounts don't expand globs, so a literal `*.pst` won't resolve. PST is a proprietary binary format; the agent needs `libpff` or similar to read it. Not as plug-and-play as `.emlx`. |
117
117
 
118
118
  If unsure which `V<n>` the user has, ask them to run `ls ~/Library/Mail/` on the host — there's usually only one.
119
119
 
@@ -197,20 +197,20 @@ Apps whose storage is opaque, proprietary, or actively-mutated-by-the-app-while-
197
197
 
198
198
  ## Dev / workflow staples — minor but worth mentioning
199
199
 
200
- Quick wins that solve common questions without being privacy-loaded. **The recurring pattern**: for dotfiles that pair a `config` file with a `credentials` file, mount the **config**, never the credentials — credentials belong in `.env` or the typeclaw secrets store, not in a bind mount.
201
-
202
- | Use case | Path | `readOnly` | Notes |
203
- | ---------------------------------------- | ------------------------------------------------------------------------ | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
204
- | Shell history | `~/.zsh_history` or `~/.bash_history` (mount the file or its parent dir) | `true` | "What command did I run yesterday?" Mounting the parent (`~`) is **not** the answer — mount the specific file. |
205
- | SSH **config** (NOT keys) | `~/.ssh/config` | `true` | Single file. Useful for "ssh me into the staging box you set up." **Never mount `~/.ssh/` wholesale** — private keys live there. |
206
- | Git config | `~/.gitconfig` | `true` | Lets the agent see the user's identity, aliases, signing config. |
207
- | AWS **config** (NOT credentials) | `~/.aws/config` | `true` | Profile names, region defaults, SSO start URLs. Useful for "what AWS profiles do I have?". **Never mount `~/.aws/` wholesale** — `credentials` lives next to `config` in the same dir and carries access keys. For actual AWS work, plumb credentials through `.env` (`AWS_ACCESS_KEY_ID`, `AWS_PROFILE`, etc.), not a bind mount. |
208
- | Kubernetes config | `~/.kube/config` | `true` | "What clusters do I have access to?" **Caveat**: depending on the auth method, `~/.kube/config` itself can contain bearer tokens or certificate data inline (older OIDC flows, EKS pre-IAM-auth, direct service-account tokens). Read the file before recommending — if it has inline tokens, treat it like a credential. |
209
- | Editor configs (nvim, fish, helix, etc.) | `~/.config/nvim/`, `~/.config/fish/`, `~/.config/helix/` | `true` | "Why is my prompt broken?" / "What plugins do I have?" Generally safe (these dirs don't carry secrets), but check before recommending — some users put API keys in nvim plugin configs. |
210
- | `/etc/hosts` | `/etc/hosts` | `true` | "What's in my hosts file?" Single-file mount. **Linux/macOS only.** WSL has a Windows-side hosts file at `/mnt/c/Windows/System32/drivers/etc/hosts` that takes precedence over the WSL-internal one — mount whichever the user actually edits. |
211
- | macOS LaunchAgents (user-level) | `~/Library/LaunchAgents/` | `true` | "What auto-starts on my Mac?" Plist files declaring user-scope launchd jobs. System-level `/Library/LaunchAgents/` and `/Library/LaunchDaemons/` exist too but are SIP-adjacent and rarely useful. |
212
- | Time Machine-excluded scratch | `~/scratch` (user creates with `tmutil addexclusion ~/scratch`) | `false` | Ephemeral agent output the user doesn't want backed up. |
213
- | iCloud Drive top-level | `~/Library/Mobile Documents/com~apple~CloudDocs` | mixed | iCloud lazy-loads — same warning as the Obsidian iCloud row above. |
200
+ Quick wins that solve common questions without being privacy-loaded. **The recurring pattern**: for dotfiles that pair a `config` file with a `credentials` file, mount the **config**, never the credentials. Credentials are provisioned directly by the operator through host-side TypeClaw/provider setup; the model never reads or edits `.env` or the TypeClaw secrets store.
201
+
202
+ | Use case | Path | `readOnly` | Notes |
203
+ | ---------------------------------------- | --------------------------------------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
204
+ | Shell history | `~/.zsh_history` or `~/.bash_history` | `true` | "What command did I run yesterday?" Mount the specific history file — its parent is the home directory, which the anti-patterns forbid mounting. |
205
+ | SSH **config** (NOT keys) | `~/.ssh/config` | `true` | Single file. Useful for "ssh me into the staging box you set up." **Never mount `~/.ssh/` wholesale** — private keys live there. |
206
+ | Git config | `~/.gitconfig` | `true` | Lets the agent see the user's identity, aliases, signing config. |
207
+ | AWS **config** (NOT credentials) | `~/.aws/config` | `true` | Profile names, region defaults, SSO start URLs. Useful for "what AWS profiles do I have?". **Never mount `~/.aws/` wholesale** — `credentials` lives next to `config` in the same dir and carries access keys. Any AWS authentication must be provisioned directly by the operator outside model-driven tools. |
208
+ | Kubernetes config | `~/.kube/config` | `true` | "What clusters do I have access to?" **Caveat**: depending on the auth method, `~/.kube/config` itself can contain bearer tokens or certificate data inline (older OIDC flows, EKS pre-IAM-auth, direct service-account tokens). Read the file before recommending — if it has inline tokens, treat it like a credential. |
209
+ | Editor configs (nvim, fish, helix, etc.) | `~/.config/nvim/`, `~/.config/fish/`, `~/.config/helix/` | `true` | "Why is my prompt broken?" / "What plugins do I have?" Generally safe (these dirs don't carry secrets), but check before recommending — some users put API keys in nvim plugin configs. |
210
+ | `/etc/hosts` | `/etc/hosts` | `true` | "What's in my hosts file?" Single-file mount. **Linux/macOS only.** WSL has a Windows-side hosts file at `/mnt/c/Windows/System32/drivers/etc/hosts` that takes precedence over the WSL-internal one — mount whichever the user actually edits. |
211
+ | macOS LaunchAgents (user-level) | `~/Library/LaunchAgents/` | `true` | "What auto-starts on my Mac?" Plist files declaring user-scope launchd jobs. System-level `/Library/LaunchAgents/` and `/Library/LaunchDaemons/` exist too but are SIP-adjacent and rarely useful. |
212
+ | Time Machine-excluded scratch | `~/scratch` (user creates with `tmutil addexclusion ~/scratch`) | `false` | Ephemeral agent output the user doesn't want backed up. |
213
+ | iCloud Drive top-level | `~/Library/Mobile Documents/com~apple~CloudDocs` | mixed | iCloud lazy-loads — same warning as the Obsidian iCloud row above. |
214
214
 
215
215
  ## Anti-patterns
216
216
 
@@ -219,14 +219,14 @@ Append-only list, no overlap with `SKILL.md`'s existing anti-patterns (which cov
219
219
  - **Never recommend mounting `~` (the entire home directory).** It's tempting and it's a security disaster: SSH keys, browser cookies, app credentials, `.env` files from every project, shell history with leaked tokens, Keychain blobs. If the user asks for "everything", push back and ask what they actually need.
220
220
  - **Never mount `~/.ssh/` wholesale.** Private keys (`id_*`, `id_*.pub` ok but the bare files without `.pub` are private) should not enter the container. Mount the specific file `~/.ssh/config` read-only if the user wants SSH host visibility.
221
221
  - **Never mount `~/Library/Keychains/`.** Even read-only, even with FDA. The keychain is encrypted blobs the agent can't use, and the act of bind-mounting it expands the attack surface for no benefit.
222
- - **Never mount `~/.aws/`, `~/.gcp/`, `~/.azure/`, or any cloud-CLI credential dir.** Same reasoning as keychains — credentials, not data. If the user wants the agent to do cloud work, plumb credentials through `.env` (env vars the cloud SDK reads), not through a bind mount of the secret store. **The `config` file inside `~/.aws/` is fine to mount individually** (see the staples table) — it's the `credentials` file you have to keep out.
222
+ - **Never mount `~/.aws/`, `~/.gcp/`, `~/.azure/`, or any cloud-CLI credential dir.** Same reasoning as keychains — credentials, not data. Authentication must be configured directly by the operator outside model-driven tools; do not respond by editing `.env`. **The `config` file inside `~/.aws/` is fine to mount individually** (see the staples table) — it's the `credentials` file you have to keep out.
223
223
  - **Never mount these credential-bearing dotfiles**, even though they look innocuous: `~/.aws/credentials`, `~/.npmrc` (often carries `//registry.npmjs.org/:_authToken=...` for private packages), `~/.pip/pip.conf` and `~/.pypirc` (PyPI upload tokens), `~/.docker/config.json` (Docker registry auth tokens, sometimes inline), `~/.cargo/credentials` (crates.io token), `~/.gradle/gradle.properties` (often carries signing keys and repo creds), `~/.m2/settings.xml` (Maven repo passwords). These pair with safe config files in similar paths — mount the config file individually if the user needs it, never the credentials file, never the parent directory.
224
224
  - **`/Volumes/<external-drive>` is fragile.** Bind mounts to removable drives don't recover when the drive is ejected — the container sees the path become an empty stub, and the only fix is `typeclaw restart` after the drive is reattached. Tell the user before mounting, and consider whether copying the data to an internal path is wiser.
225
225
  - **iCloud Drive paths lazy-load.** `~/Library/Mobile Documents/com~apple~CloudDocs/` and the per-app `iCloud~<bundle>` dirs only materialize files when the host system opens them. Inside the container, an unmaterialized file appears as a 0-byte stub or a `.icloud` placeholder. The fix is host-side: have the user open the file (or `brctl download` it) before the agent tries to read it. The agent cannot trigger iCloud materialization from inside the container.
226
226
  - **`/private/var/db/` and other system stores are not yours.** TCC database, Spotlight metadata, system logs — all gated by SIP (System Integrity Protection) on top of FDA, and none of them are useful to the agent. If the user asks for Spotlight-style search, the answer is `mdfind` from the host (out of scope for the container), not a mount.
227
227
  - **Don't mount the same host path twice under different mount names.** Docker allows it, but the agent now has two views of the same data and writes through one are immediately visible through the other. It looks like a bug from the agent's side ("why did `mounts/notes-ro/foo.md` change when I wrote `mounts/notes-rw/foo.md`?"). Pick one mount per host path.
228
228
  - **`readOnly: true` is not encryption-at-rest.** A read-only mount prevents the agent from writing back, but reads still happen through the kernel's normal file path — no obfuscation, no privacy gain beyond write-prevention. If the data is so sensitive that read-access itself is a problem, the answer is **don't mount it**, not "mount it read-only".
229
- - **macOS path versioning will drift.** Apple has moved `~/Library/Mail/V<n>`, Voice Memos, and other paths across macOS versions. The paths in this file are good for macOS 12–26 as of this writing; if a future macOS reorganization breaks one, the symptom is `ls mounts/<name>` returning empty after a successful mount. Update this file, don't paper over it.
229
+ - **macOS path versioning will drift.** Apple has moved `~/Library/Mail/V<n>`, Voice Memos, and other paths across macOS versions. The paths in this file are good for macOS 11–26 as of this writing; if a future macOS reorganization breaks one, the symptom is `ls mounts/<name>` returning empty after a successful mount. Update this file, don't paper over it.
230
230
 
231
231
  ## When the path you need isn't here
232
232
 
@@ -24,29 +24,22 @@ A contribution composed from your defaults and one composed from the repo's conv
24
24
  The cheapest reliable check is to list each base directory once and scan the names, rather than guessing exact filenames:
25
25
 
26
26
  ```sh
27
- # PR template — scan all three base dirs for any case of the file OR a PULL_REQUEST_TEMPLATE/ dir.
28
- # (Listing the dir surfaces both the single-file and the multi-template-directory forms at once.)
29
- for base in "" "docs/" ".github/"; do
30
- gh api "repos/OWNER/REPO/contents/${base}" --jq '.[].name' 2>/dev/null \
31
- | grep -iE '^pull_request_template(\.md)?$'
32
- done
33
- # If a PULL_REQUEST_TEMPLATE/ directory exists in ANY base, list the choices inside it
34
- # (the directory form is supported at root, docs/, and .github/ alike):
35
- for base in "" "docs/" ".github/"; do
36
- gh api "repos/OWNER/REPO/contents/${base}PULL_REQUEST_TEMPLATE" --jq '.[].name' 2>/dev/null
37
- done
38
-
39
- # Issue templates — the modern form is an ISSUE_TEMPLATE/ directory of forms;
40
- # the legacy form is a single ISSUE_TEMPLATE.md. Check both, in all three base dirs.
41
- for base in "" "docs/" ".github/"; do
42
- gh api "repos/OWNER/REPO/contents/${base}ISSUE_TEMPLATE" --jq '.[].name' 2>/dev/null # directory of forms
43
- gh api "repos/OWNER/REPO/contents/${base}" --jq '.[].name' 2>/dev/null \
44
- | grep -iE '^issue_template(\.md)?$' # single legacy file
45
- done
27
+ # Run each as its own bare invocation. Inspect the returned names case-insensitively
28
+ # for PULL_REQUEST_TEMPLATE(.md), PULL_REQUEST_TEMPLATE/, ISSUE_TEMPLATE(.md),
29
+ # and ISSUE_TEMPLATE/. A missing directory may return 404; continue with the next.
30
+ gh api repos/OWNER/REPO/contents/ --jq '.[].name'
31
+ gh api repos/OWNER/REPO/contents/docs --jq '.[].name'
32
+ gh api repos/OWNER/REPO/contents/.github --jq '.[].name'
33
+ gh api repos/OWNER/REPO/contents/PULL_REQUEST_TEMPLATE --jq '.[].name'
34
+ gh api repos/OWNER/REPO/contents/docs/PULL_REQUEST_TEMPLATE --jq '.[].name'
35
+ gh api repos/OWNER/REPO/contents/.github/PULL_REQUEST_TEMPLATE --jq '.[].name'
36
+ gh api repos/OWNER/REPO/contents/ISSUE_TEMPLATE --jq '.[].name'
37
+ gh api repos/OWNER/REPO/contents/docs/ISSUE_TEMPLATE --jq '.[].name'
38
+ gh api repos/OWNER/REPO/contents/.github/ISSUE_TEMPLATE --jq '.[].name'
46
39
 
47
40
  # Contribution guide (root or .github/)
48
- gh api repos/OWNER/REPO/contents/CONTRIBUTING.md 2>/dev/null
49
- gh api repos/OWNER/REPO/contents/.github/CONTRIBUTING.md 2>/dev/null
41
+ gh api repos/OWNER/REPO/contents/CONTRIBUTING.md
42
+ gh api repos/OWNER/REPO/contents/.github/CONTRIBUTING.md
50
43
 
51
44
  # What do existing titles look like?
52
45
  gh pr list --repo OWNER/REPO --state all --limit 20 --json title --jq '.[].title'
@@ -100,12 +93,16 @@ The same applies to PRs: a quick `gh pr list --search` avoids opening a PR for s
100
93
 
101
94
  1. **Identify the target repo** (`OWNER/REPO`) and whether you're filing an issue or a PR.
102
95
  2. **Read the room** — run the checks in "Do this first": templates, CONTRIBUTING, existing titles, duplicate search.
103
- 3. **Compose to the conventions** — fill the template, honor CONTRIBUTING, match the title style. Write the body to a file when it's long or contains backticks/markdown that shell-quoting would mangle, then pass it with `--body-file`.
104
- 4. **Open it** with `gh`:
96
+ 3. **Compose to the conventions** — fill the template, honor CONTRIBUTING, match the title style. Keep the body inline and single-quoted. `--body-file`, `--template`, editor/fill/recovery modes, shell substitution, and command composition are intentionally unavailable to model-driven `gh`.
97
+ 4. **Open an issue** with the supported model-driven `gh` form:
105
98
  ```sh
106
- gh issue create --repo OWNER/REPO --title "<conventional title>" --body-file /tmp/issue-body.md
107
- gh pr create --repo OWNER/REPO --title "<conventional title>" --body-file /tmp/pr-body.md --base <branch>
99
+ gh issue create --repo OWNER/REPO --title '<conventional title>' --body '<filled body>'
108
100
  ```
101
+ For a **pull request**, prepare the exact title, body, pushed head branch, and base branch, then ask the operator to run this at the host stage from the repository checkout:
102
+ ```sh
103
+ gh pr create --repo OWNER/REPO --title '<conventional title>' --body '<filled body>' --head <branch> --base <branch>
104
+ ```
105
+ Model-driven bash cannot create or push a PR: TypeClaw deliberately withholds reusable credentials from network Git and blocks `gh pr create` because it may invoke local Git hooks.
109
106
  5. **Verify it landed** as intended (`gh issue view` / `gh pr view`) — confirm the template rendered and nothing got truncated.
110
107
 
111
108
  ## Things you must not do
@@ -121,4 +118,4 @@ The same applies to PRs: a quick `gh pr list --search` avoids opening a PR for s
121
118
 
122
119
  - **Replying to inbound GitHub events, and running PR reviews** — `typeclaw-channel-github`. That skill owns triage of github-channel inbounds, formal reviews via the reviews API, and resolving review threads. This skill owns only the act of _opening_ a new issue/PR.
123
120
  - **Committing to your own agent folder** — `typeclaw-git`. Local commit hygiene and decision-context messages live there; this skill is about GitHub artifacts, not your local history.
124
- - **The `gh` CLI's full surface** — auth, sub-commands, flags. Defer to `gh <command> --help`. Under the github channel adapter, `GH_TOKEN` is pre-injected; see `typeclaw-channel-github` for the single-bare-invocation constraint that applies to repo-targeting `gh` calls (no pipes, `;`, `&&`, heredocs, or command substitution).
121
+ - **The `gh` CLI's full surface** — auth, sub-commands, flags. TypeClaw brokers a command-scoped token only after statically validating the repo and command shape; it is not a broadly exposed `GH_TOKEN`. See `typeclaw-channel-github` for the single-bare-invocation constraint (no pipes, `;`, `&&`, heredocs, redirections, or substitution).
@@ -25,14 +25,20 @@ Citations in shard bodies use the canonical form `streams/yyyy-MM-dd#<fragment-i
25
25
 
26
26
  ## `memory_search` tool
27
27
 
28
- When index-mode injection hides bodies, or when you need recent fragments the dreaming subagent hasn't consolidated yet, use `memory_search({query, asRegex?, full?, maxResults?})`. It searches BOTH topic shards under `memory/topics/` and undreamed stream events under `memory/streams/`. Substring (case-insensitive) by default; `asRegex: true` for regex.
28
+ When index-mode injection hides bodies, or when you need recent fragments the dreaming subagent hasn't consolidated yet, use `memory_search({query, asRegex?, full?, maxResults?, workspace?, chat?, thread?})`. It searches topic shards, active cited-child provenance, and undreamed stream events. Substring (case-insensitive) by default; `asRegex: true` for regex. The legacy `where` argument is an alias for `chat`.
29
+
30
+ Use `memory_search({topic: "<slug>", workspace?, chat?, thread?})` for an exact shard lookup. Scope applies here too: the shard is returned only when an active cited child matches every supplied coordinate. Scoped lookup does not return references because references have no origin children.
31
+
32
+ Workspace/chat/thread IDs and captured names are searchable lexical metadata and appear in result provenance, but they are never embedded. Recall is globally visible by default across roles and origins. Optional `workspace`, `chat`, and `thread` arguments narrow query and exact-topic results to matching coordinates; names and aliases participate in lexical matching only. A mixed-scope shard remains eligible when any active child matches an explicit scope, and returned provenance contains only matching children. Automatic hybrid retrieval and channel heading injection remain global.
33
+
34
+ Historical Discord names and parent-room metadata live only in a bounded runtime registry rebuilt by adapter-start maintenance. There is no provenance sidecar to edit. Do not rewrite stream JSONL. Resolver failure intentionally falls back to raw IDs, and `memory_search` never performs network calls.
29
35
 
30
36
  Plain queries are **phrase-first with a word fallback**: the whole query is tried as one substring, and only if that finds nothing is the query split on whitespace and the distinct words OR-matched (ranked by how many words each hit contains). So a descriptive multi-word query like `quarterly regional revenue summary` still returns results even when no entry contains that exact phrase. You don't need to pre-split queries into single keywords — but a focused phrase still wins when an entry contains it verbatim. Regex queries never fall back (whitespace stays part of the pattern).
31
37
 
32
38
  Results are discriminated by `source`:
33
39
 
34
- - `source: "topic"` — fields `shardPath`, `slug`, `heading`, `excerpt`, `fullBody?`
35
- - `source: "stream"` — fields `streamPath`, `date`, `eventId?` (citation-format `streams/yyyy-MM-dd#<id>` for fragments; absent for legacy prose), `topic`, `excerpt`, `fullBody?`
40
+ - `source: "topic"` — fields `shardPath`, `slug`, `heading`, `excerpt`, `fullBody?`, `provenance`
41
+ - `source: "stream"` — fields `streamPath`, `date`, `eventId?` (citation-format `streams/yyyy-MM-dd#<id>` for fragments; absent for legacy prose), `topic`, `excerpt`, `fullBody?`, and optional `who`/`when`/`where`
36
42
 
37
43
  Ordering depends on mode. Exact-phrase (and regex) results list all topic matches first (alphabetical by slug), then stream matches (newest day first), and `maxResults` truncates streams before topics. Word-fallback results are instead ranked by matched-word count — that same topic-first/stream-newest order is only the tiebreak within a score band, so a higher-scoring stream can precede a lower-scoring topic, and `maxResults` drops the lowest-scored tail regardless of source. `full: true` returns the entire shard or fragment body.
38
44
 
@@ -15,20 +15,22 @@ Every session you run in has a `SessionOrigin` (TUI / channel / cron / subagent)
15
15
  - **Cron** sessions resolve from `scheduledByRole`, a string stamped on the cron job record itself (in `cron.json` for hand-authored entries, or by the runtime for plugin-contributed cron). Match rules of the form `cron` parse but never grant a role to a running cron session — provenance wins.
16
16
  - **Subagent** sessions resolve from `spawnedByRole`, snapshotted from the spawning session's resolved role at spawn time. Same story: `subagent` / `subagent:<name>` rules parse but don't grant roles at runtime; the spawn provenance is the source of truth.
17
17
 
18
- Each role carries a set of **permissions** — opaque dotted strings like `channel.respond`, `cron.schedule`, `security.bypass.gitExfil`. The runtime checks `permissions.has(origin, '<perm>')` at three places: the channel router (gates `channel.respond` before creating a session for an inbound message), the security plugin's `tool.before` hook (gates each `security.bypass.*` so the corresponding guard can be skipped), and plugin code that opts in. There is no other access-control surface — no per-tool ACL, no file-system isolation, no per-author allowlist outside `match` rules.
18
+ Each role carries a set of **permissions** — opaque dotted strings like `channel.respond`, `cron.schedule`, `security.bypass.gitExfil`. The runtime checks them in the channel router, session/tool construction, the security plugin, and permission-aware plugin code. Separate core wrappers and the bash sandbox enforce canonical credential isolation independently of role permissions and plugin hooks.
19
+
20
+ **Non-bypassable canonical-secret invariant:** no role, including `owner`, may read `.env`, `secrets.json`, `auth.json`, canonical credential directories, reusable CLI profiles, or their hardlink/symlink aliases through model-driven tools. `fs.see.secrets` authorizes runtime-owned use through dedicated mediation; it does not reveal raw stores. `security.bypass.*`, severity tiers, wildcard expansion, and `acknowledgeGuards` affect plugin policy only. They never remove canonical masks, preserve reusable credential env vars for arbitrary commands, disable immutable input pinning, or authorize model-driven credential edits.
19
21
 
20
22
  ## The four built-in roles
21
23
 
22
24
  You always have these four, even if `typeclaw.json` declares zero `roles`. User-declared roles **append** match rules to the built-ins but **replace** the permission list entirely (so `"permissions": []` on a built-in role means "no permissions" — be careful).
23
25
 
24
- Roles form a strict tower: each role bypasses every guard at its tier and below.
26
+ Roles form a strict tower for **bypassable plugin guards**: each role bypasses guards at its tier and below. The canonical-secret invariant sits outside this tower.
25
27
 
26
- | Role | Built-in `match[]` | Tier bypass cap | Default `permissions[]` |
27
- | --------- | ----------------------------------------------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
28
- | `owner` | `["tui"]` (always prepended) | `high` | `channel.respond`, `cron.schedule`, `cron.modify`, `subagent.*`, `security.bypass.low`, `security.bypass.medium`, `security.bypass.high`, plus every plugin-contributed `security.bypass.<guard>` (wildcard expansion) |
29
- | `trusted` | none | `medium` | `channel.respond`, `cron.schedule`, `subagent.*`, `security.bypass.low`, `security.bypass.medium` |
30
- | `member` | none | `low` | `channel.respond`, `subagent.spawn`, `subagent.cancel`, `subagent.output`, `security.bypass.low` |
31
- | `guest` | none (fallback when nothing else matches, or stamped role is bad) | (none) | none |
28
+ | Role | Built-in `match[]` | Tier bypass cap | Default `permissions[]` |
29
+ | --------- | ----------------------------------------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
30
+ | `owner` | `["tui"]` (always prepended) | `high` | `channel.respond`, `session.control`, `session.admin`, `cron.schedule`, `cron.modify`, `subagent.spawn`, `subagent.cancel`, `subagent.output`, `subagent.spawn.operator`, `fs.see.private`, `fs.see.secrets`, `security.bypass.low`, `security.bypass.medium`, `security.bypass.high`, plus every plugin-contributed `security.bypass.<guard>` (wildcard expansion) |
31
+ | `trusted` | none | `medium` | `channel.respond`, `session.control`, `session.admin`, `cron.schedule`, `subagent.spawn`, `subagent.cancel`, `subagent.output`, `subagent.spawn.operator`, `fs.see.private`, `fs.see.secrets`, `security.bypass.low`, `security.bypass.medium` |
32
+ | `member` | none | `low` | `channel.respond`, `session.control`, `subagent.spawn`, `subagent.cancel`, `subagent.output`, `fs.see.private`, `security.bypass.low` |
33
+ | `guest` | none (fallback when nothing else matches, or stamped role is bad) | (none) | none |
32
34
 
33
35
  A session that doesn't match anything resolves to `guest`. `guest` has no `channel.respond`, so the router silently drops inbound messages whose author resolves to `guest`. **This is the most common cause of "the agent stopped responding"**: the user added a channel but did not add a match rule, so every speaker in that channel is `guest` and every inbound is dropped before you ever see it. There is no message in your session log when this happens — only a host-side line `[channels] <key>: denied by permissions (channel.respond) author=<id>`.
34
36
 
@@ -56,6 +58,8 @@ For each user turn, the current speaker's effective role is delivered in the tur
56
58
 
57
59
  **The permission list (cron/subagent block) is exhaustive at session-creation time** for the resolved role. If a permission you expect isn't listed there, the role doesn't carry it — adding it requires editing `roles.<role>.permissions[]` and restarting.
58
60
 
61
+ Memory recall is globally visible by default across all roles and origins. Provenance is additive searchable metadata, not an authorization boundary. The optional `workspace`, `chat`, and `thread` parameters on `memory_search` narrow results when a focused subset is needed; no memory-specific permission grant is required.
62
+
59
63
  ## The match-rule DSL
60
64
 
61
65
  `roles.<role>.match[]` is an array of compact strings. The parser is hand-rolled in `src/permissions/match-rule.ts`; the canonical shapes are:
@@ -88,14 +92,14 @@ Things the DSL rejects (the parser emits actionable errors at boot, but you shou
88
92
 
89
93
  Three sources contribute permission strings:
90
94
 
91
- 1. **Core** (always present): `channel.respond`, `cron.schedule`, `cron.modify`.
95
+ 1. **Core** (always present): `channel.respond`, `session.control`, `session.admin`, `cron.schedule`, `cron.modify`, `subagent.spawn`, `subagent.cancel`, `subagent.output`, `subagent.spawn.operator`, `fs.see.private`, `fs.see.secrets`.
92
96
  2. **Bundled security plugin** (always loaded): the eight per-guard strings (`security.bypass.secretExfilBash`, `security.bypass.gitExfil`, `security.bypass.gitRemoteTainted`, `security.bypass.secretExfilRead`, `security.bypass.ssrf`, `security.bypass.sessionSearchSecrets`, `security.bypass.systemPromptLeak`, `security.bypass.outboundSecret`) AND three severity-tier strings (`security.bypass.low`, `security.bypass.medium`, `security.bypass.high`).
93
97
  3. **User-declared plugins** (variable): each plugin can contribute its own strings via `definePlugin({ permissions: [...] })`.
94
98
 
95
99
  The security plugin classifies each guard on a two-axis policy:
96
100
 
97
101
  - **high — direct audience-leak.** Bypass sends data to a third-party audience outside the operator's control loop with NO operator-visible intermediate step. Inhabitants: `outboundSecret`, `systemPromptLeak`, `gitRemoteTainted`. **`owner` bypasses by default; `trusted`, `member`, `guest` do not.** The canonical case is **owner-in-public-channel**: an owner-permissioned operator asking the agent to "post deploy status to #general" can silently leak a `Bearer ghp_…` line. The defense lives in `roles.owner.match[]` discipline — the default is TUI-only, where a human is present. Configs that widen owner to a channel author should narrow the match or strip `security.bypass.high` (and the wildcard sentinel) from `roles.owner.permissions[]` for those origins.
98
- - **medium — silent-attack OR operator-reviewable state.** Two sub-shapes share this tier because they share a defense story (operator review catches it before the privileged effect escapes). (a) _silent-attack_: bypass returns secrets / IAM creds into model context with no immediate operator visibility — `secretExfilBash`, `secretExfilRead`, `ssrf`, `sessionSearchSecrets`. (b) _operator-reviewable state_: bypass writes to a file the operator force-commits and reviews before the privileged effect takes hold — `gitExfil` (push to a clean operator-configured remote; the retarget-and-push path stays blocked by `gitRemoteTainted` at high), `rolePromotion` (`roles` is restart-required so the operator has wall-clock time), `cronPromotion` (deferred execution gives wall-clock time to revert). **`owner` and `trusted` bypass; `member`, `guest` do not.**
102
+ - **medium — silent-attack OR operator-reviewable state.** Two sub-shapes share this tier because they share a defense story (operator review catches it before the privileged effect escapes). (a) _silent-attack_: `secretExfilBash`, `secretExfilRead`, `ssrf`, and `sessionSearchSecrets` are heuristic/plugin defenses for non-canonical surfaces; bypassing them still cannot expose canonical credential stores or reusable child auth. (b) _operator-reviewable state_: bypass writes to a file the operator force-commits and reviews before the privileged effect takes hold — `gitExfil` (push to a clean operator-configured remote; the retarget-and-push path stays blocked by `gitRemoteTainted` at high), `rolePromotion` (`roles` is restart-required so the operator has wall-clock time), `cronPromotion` (deferred execution gives wall-clock time to revert). **`owner` and `trusted` bypass these plugin guards; `member`, `guest` do not.**
99
103
 
100
104
  **Important:** `cronPromotion`, `rolePromotion`, and `pluginAddition` no longer honor `acknowledgeGuards`. For these three guards the bypass is **permission-only** — an actor bypasses them automatically by holding `security.bypass.medium` (owner and trusted have it by default) or the per-guard `security.bypass.<guard>` string. No per-call ack is accepted or possible. Additionally, `cronPromotion` is **caller-role-aware**: it only blocks changes that schedule deferred work above the caller's own resolved role (see `typeclaw-cron` for the full model). The `gitExfil` guard and all other guards still accept `acknowledgeGuards` per-call acks as before.
101
105
 
@@ -103,7 +107,7 @@ The security plugin classifies each guard on a two-axis policy:
103
107
 
104
108
  At `tool.before` time, an actor bypasses a guard if they hold **either** the tier permission **or** the per-guard permission (OR-check, both axes work forever).
105
109
 
106
- `owner` carries `security.bypass.low + security.bypass.medium + security.bypass.high` AND the wildcard sentinel. The bundled security plugin sets `ownerWildcardExclusions: []`, so the sentinel expands to every plugin-contributed `security.bypass.*` string. Net: `owner` auto-bypasses every tier and every per-guard string by default. `trusted` carries `bypass.low + bypass.medium` — no high-tier grants by default. `member` carries `bypass.low` — no medium/high. `guest` carries no `security.bypass.*` strings.
110
+ `owner` carries `security.bypass.low + security.bypass.medium + security.bypass.high` AND the wildcard sentinel. The bundled security plugin sets `ownerWildcardExclusions: []`, so the sentinel expands to every plugin-contributed `security.bypass.*` string. Net: `owner` auto-bypasses every plugin tier and per-guard string by default, but never the core canonical-secret boundary. `trusted` carries `bypass.low + bypass.medium` — no high-tier grants by default. `member` carries `bypass.low` — no medium/high. `guest` carries no `security.bypass.*` strings.
107
111
 
108
112
  **Trusted is operator-class for the agent's own state.** Because `gitExfil`, `rolePromotion`, and `cronPromotion` are medium-tier, trusted users can push to operator-configured remotes, edit `typeclaw.json#roles`, and add cron jobs without per-call acks. The two-step taint defense (`gitRemoteTainted`, still high) still blocks the retarget-and-push attack. The privilege-escalation defense for `roles`/`cron` edits now leans on operator review of auto-backup commits — `typeclaw.json` and `cron.json` are force-committed on idle, and the operator sees diffs before reload/restart. Deployments that don't review backup commits should keep `roles.trusted.match[]` narrow, OR subtract by replacing `roles.trusted.permissions[]` with an explicit list that omits `security.bypass.medium`.
109
113
 
@@ -138,12 +142,12 @@ already resolves to a role carrying `<per-guard-permission>` or
138
142
  via `typeclaw role claim` from the host CLI.
139
143
  ```
140
144
 
141
- Four escape hatches, ordered from least to most invasive:
145
+ Four escape hatches for **bypassable plugin guards**, ordered from least to most invasive. If the block concerns a canonical credential path or reusable authentication, there is no escape hatch; direct the operator to a host-side redacted workflow instead.
142
146
 
143
- 1. **`acknowledgeGuards.<guardName>: true`** in the tool args. This is a per-call, in-session bypass. Use it when the user has just explicitly told you to run the dangerous thing (e.g. "yes, push the secret to a private gist on purpose"). Never use it without explicit user confirmation — the guard exists for a reason. **Exception: this escape hatch does NOT apply to `cronPromotion`, `rolePromotion`, or `pluginAddition`.** Those three guards ignore the ack flag entirely — they are bypassed only by holding the appropriate permission (see options 2-4 below) or via `typeclaw role claim` from the host CLI. For those guards, skip directly to option 2, 3, or 4.
147
+ 1. **`acknowledgeGuards.<guardName>: true`** in the tool args. This is a per-call, in-session bypass for guards that support acknowledgements. Never use it without explicit user confirmation. It cannot authorize canonical secret access or credential handling. **Exception: this escape hatch also does NOT apply to `cronPromotion`, `rolePromotion`, or `pluginAddition`.** Those three guards ignore the ack flag entirely — they are bypassed only by holding the appropriate permission (see options 2-4 below) or via `typeclaw role claim` from the host CLI.
144
148
  2. **Run as a role with the per-guard bypass permission**. If the user wants this pattern to keep working without an ack every time, they edit `roles.<role>.permissions[]` to include the specific `security.bypass.<guardName>` string the block message named. This is the most granular grant — it only opens up that one guard. Use this when the user wants exactly one capability and nothing else.
145
- 3. **Run as a role with the tier bypass permission**. The block message also names the tier permission (`security.bypass.low` / `.medium` / `.high`). Granting the tier opens up every guard of that tier at once — broader than option 2, narrower than full owner. Use this when "let trusted users post credentials to chat AND view system prompt fingerprints AND search session history" is the user's actual intent rather than three separate per-guard grants.
146
- 4. **Run from a session that already resolves to a role with the bypass**. The TUI is always `owner`, so a guard that blocks in channel sessions for a `member` author will not block at all from the TUI. This is why "the agent can do X in TUI but not in Slack" is normal, not a bug. For `cronPromotion`, `rolePromotion`, and `pluginAddition` specifically, this is the primary resolution path: make the change from the TUI (always `owner`), from a session whose role carries `security.bypass.medium`, or claim the role out-of-band via `typeclaw role claim` from the host CLI.
149
+ 3. **Run as a role with the tier bypass permission**. The block message also names the tier permission (`security.bypass.low` / `.medium` / `.high`). Granting the tier opens every bypassable plugin guard of that tier at once — never canonical secrets.
150
+ 4. **Run from a session that already resolves to a role with the bypass**. The TUI is always `owner`, so a bypassable plugin guard that blocks a `member` channel author may permit the TUI. Canonical credential denial remains identical in both places. For `cronPromotion`, `rolePromotion`, and `pluginAddition` specifically, use a session carrying `security.bypass.medium` or claim the role out-of-band via `typeclaw role claim` from the host CLI.
147
151
 
148
152
  When you see a block, tell the user **which permission would skip it** (the block message now names both the per-guard and the tier options) and **which built-in roles have those permissions**. Do not just relay the guard reason — that loses the access-control framing entirely.
149
153
 
@@ -57,6 +57,10 @@
57
57
  "minimax/MiniMax-M2",
58
58
  "deepseek/deepseek-v4-flash",
59
59
  "deepseek/deepseek-v4-pro",
60
+ "upstage/solar-open2",
61
+ "upstage/solar-pro3",
62
+ "upstage/solar-pro2",
63
+ "upstage/solar-mini",
60
64
  "moonshot/kimi-k2.7-code",
61
65
  "moonshot/kimi-k2.6",
62
66
  "moonshot/kimi-k2.5",
@@ -109,6 +113,10 @@
109
113
  "minimax/MiniMax-M2",
110
114
  "deepseek/deepseek-v4-flash",
111
115
  "deepseek/deepseek-v4-pro",
116
+ "upstage/solar-open2",
117
+ "upstage/solar-pro3",
118
+ "upstage/solar-pro2",
119
+ "upstage/solar-mini",
112
120
  "moonshot/kimi-k2.7-code",
113
121
  "moonshot/kimi-k2.6",
114
122
  "moonshot/kimi-k2.5",
@@ -162,6 +170,10 @@
162
170
  "minimax/MiniMax-M2",
163
171
  "deepseek/deepseek-v4-flash",
164
172
  "deepseek/deepseek-v4-pro",
173
+ "upstage/solar-open2",
174
+ "upstage/solar-pro3",
175
+ "upstage/solar-pro2",
176
+ "upstage/solar-mini",
165
177
  "moonshot/kimi-k2.7-code",
166
178
  "moonshot/kimi-k2.6",
167
179
  "moonshot/kimi-k2.5",
@@ -213,6 +225,10 @@
213
225
  "minimax/MiniMax-M2",
214
226
  "deepseek/deepseek-v4-flash",
215
227
  "deepseek/deepseek-v4-pro",
228
+ "upstage/solar-open2",
229
+ "upstage/solar-pro3",
230
+ "upstage/solar-pro2",
231
+ "upstage/solar-mini",
216
232
  "moonshot/kimi-k2.7-code",
217
233
  "moonshot/kimi-k2.6",
218
234
  "moonshot/kimi-k2.5",
@@ -265,6 +281,10 @@
265
281
  "minimax/MiniMax-M2",
266
282
  "deepseek/deepseek-v4-flash",
267
283
  "deepseek/deepseek-v4-pro",
284
+ "upstage/solar-open2",
285
+ "upstage/solar-pro3",
286
+ "upstage/solar-pro2",
287
+ "upstage/solar-mini",
268
288
  "moonshot/kimi-k2.7-code",
269
289
  "moonshot/kimi-k2.6",
270
290
  "moonshot/kimi-k2.5",