typeclaw 0.3.1 → 0.5.0

package/src/skills/typeclaw-permissions/SKILL.md

@@ -21,12 +21,12 @@ Each role carries a set of **permissions** — opaque dotted strings like `chann
 
 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).
 
-| Role      | Built-in `match[]`                                                | Default `permissions[]`                                                                                                   |
-| --------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
-| `owner`   | `["tui"]` (always prepended)                                      | `channel.respond`, `cron.schedule`, `cron.modify`, **all `security.bypass.*` contributed by plugins** (wildcard sentinel) |
-| `trusted` | none                                                              | `channel.respond`, `cron.schedule`, `security.bypass.secretExfilBash`                                                     |
-| `member`  | none                                                              | `channel.respond`                                                                                                         |
-| `guest`   | none (fallback when nothing else matches, or stamped role is bad) | none                                                                                                                      |
+| Role      | Built-in `match[]`                                                | Default `permissions[]`                                                                                                                                                                                                                                                                                                                                                                  |
+| --------- | ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `owner`   | `["tui"]` (always prepended)                                      | `channel.respond`, `cron.schedule`, `cron.modify`, `security.bypass.low`, `security.bypass.medium`, **plugin-contributed `security.bypass.*` MINUS high-tier strings** (the wildcard sentinel expands to plugin bypasses but excludes the security plugin's `ownerWildcardExclusions` — today: `gitExfil`, `gitRemoteTainted`, `outboundSecret`, `systemPromptLeak`, plus `bypass.high`) |
+| `trusted` | none                                                              | `channel.respond`, `cron.schedule`, `security.bypass.low`                                                                                                                                                                                                                                                                                                                                |
+| `member`  | none                                                              | `channel.respond`                                                                                                                                                                                                                                                                                                                                                                        |
+| `guest`   | none (fallback when nothing else matches, or stamped role is bad) | none                                                                                                                                                                                                                                                                                                                                                                                     |
 
 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>`.
 
@@ -79,10 +79,24 @@ Things the DSL rejects (the parser emits actionable errors at boot, but you shou
 Three sources contribute permission strings:
 
 1. **Core** (always present): `channel.respond`, `cron.schedule`, `cron.modify`.
-2. **Bundled security plugin** (always loaded): `security.bypass.secretExfilBash`, `security.bypass.gitExfil`, `security.bypass.gitRemoteTainted`, `security.bypass.secretExfilRead`, `security.bypass.ssrf`, `security.bypass.sessionSearchSecrets`, `security.bypass.systemPromptLeak`, `security.bypass.outboundSecret`.
+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`).
 3. **User-declared plugins** (variable): each plugin can contribute its own strings via `definePlugin({ permissions: [...] })`.
 
-`owner` carries every `security.bypass.*` from sources 2 and 3 by default (via a wildcard sentinel expanded at boot). `trusted` carries only `security.bypass.secretExfilBash` by default. `member` and `guest` carry no `security.bypass.*` strings.
+The security plugin classifies each guard on a two-axis policy:
+
+- **high — audience-leak.** Bypass sends data to a third-party audience outside the operator's control loop (channel readers, remote git hosts). Inhabitants: `outboundSecret`, `systemPromptLeak`, `gitExfil`, `gitRemoteTainted`. **No role auto-bypasses high.** Per-call ack required from every role, including `owner`. The canonical case is **owner-in-public-channel**: even an owner asking "post deploy status to #general" must not silently include a `Bearer ghp_…` line; even `git push` from TUI must be ack'd. Operators who knowingly want one role to skip a high-tier guard add the per-guard string explicitly to `roles.<role>.permissions[]`.
+- **medium — silent-attack.** Bypass returns secrets / IAM creds into model context with no immediate operator visibility. Inhabitants: `secretExfilBash`, `secretExfilRead`, `ssrf`, `sessionSearchSecrets`. `owner` bypasses (operator already has host access); `trusted` does NOT.
+- **low — noisy, immediately recoverable.** No inhabitants today. Forward-compat for future guards. `trusted` carries `bypass.low` so a future low-tier guard auto-bypasses for trusted without a config edit.
+
+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).
+
+`owner` carries `security.bypass.low + security.bypass.medium` AND the wildcard sentinel; the sentinel expands to plugin-contributed `security.bypass.*` strings minus the security plugin's `ownerWildcardExclusions` (today: the four high-tier per-guard strings plus `bypass.high`). Net: `owner` auto-bypasses every low- and medium-tier guard; high-tier guards require ack from owner too. `trusted` carries only `bypass.low` — no per-guard medium/high grants by default. `member` and `guest` carry no `security.bypass.*` strings.
+
+**Trusted lost two per-guard grants in PR #255 compared to pre-PR behavior.** Before: trusted carried `bypassSecretExfilBash` and `bypassGitExfil` so they could `bash env` and `git push` without acks. After: those guards (medium and high respectively) need acks for trusted too. Operators who relied on the old ergonomics can restore them by adding the per-guard strings explicitly to `roles.trusted.permissions[]` in `typeclaw.json` — the per-guard path is supported forever via the OR-check. When the user complains "trusted can't push anymore," this is the explanation and the workaround.
+
+Note on the two-step `gitRemoteTainted` defense: even when an operator explicitly grants `security.bypass.gitExfil` to a role (re-opening the high-tier bypass for `git push`), the second-step `gitRemoteTainted` check still fires on the eventual push if origin was re-pointed mid-session. The recorder runs on the first step (the `set-url`) gated by "would the command actually run" — so the second-step checker has taint state to consult. Granting `bypassGitExfil` does NOT silently grant `bypassGitRemoteTainted`; those are independent per-guard strings AND independent high-tier guards.
+
+**Two-layer defense for channel-side git operations**: the runtime `tool.before` guards are not the only layer that gates `git push` from channel messages. The security plugin's `session.prompt` hook also pattern-matches inbound text for `git push` / `git remote add` / `gh repo create --push` and injects a refusal rule into the system prompt. **The prompt-side `git_exfil` defense is gated to non-subagent origins** — it fires for `channel` and `tui` prompts but skips `subagent` prompts. The reason: bundled subagents like `backup-diagnose` legitimately embed git stderr in their payloads (which contains literal "git push --help" hint strings on failures), and triggering the defense there would inject a "do NOT run git push" rule that contradicts the subagent's own system-prompt instructions to retry with an ack. The runtime `tool.before` is the universal backstop for subagents (under the audience-leak policy, even owner-spawned subagents need an ack for `git push`), so the prompt-side check is redundant for them and harmful to bundled-plugin recovery flows. For channel and TUI prompts the two layers agree: nobody auto-bypasses gitExfil at the runtime layer, so the prompt-injection layer's text-match refusal is the same answer the runtime would give. The only case where the two layers disagree is when an operator has explicitly granted `security.bypass.gitExfil` to a channel speaker's role in `typeclaw.json` — then the runtime would allow the push but the prompt-injection text-match would still refuse. That's a known narrow-scope gap (operator opted into the bypass already); if the user is confused why the agent refused a channel-side push despite the per-guard grant they added, this is why.
 
 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.
 
@@ -93,17 +107,19 @@ The security plugin's `tool.before` hook produces block messages of the form:
 ```
 Guard `<guardName>` blocked <what>. If this is genuinely intentional and the user
 explicitly asked for it, retry with `acknowledgeGuards.<guardName>: true` in the
-<tool> arguments. Or run as a role carrying `<permission>` (owner has all
-security.bypass.*; trusted has security.bypass.secretExfilBash).
+<tool> arguments. Or run as a role carrying `<per-guard-permission>` (...role hint...)
+or the tier permission `security.bypass.<low|medium|high>`; see the
+`typeclaw-permissions` skill.
 ```
 
-Three escape hatches, ordered from least to most invasive:
+Four escape hatches, ordered from least to most invasive:
 
 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.
-2. **Run as a role with the bypass permission**. If the user wants this pattern to keep working without an ack every time, they edit `roles.<role>.permissions[]` to include the `security.bypass.<X>` string the block message named. This is the right answer for "I'm `trusted` in this Slack channel and I want to be able to run dangerous bash without confirming each time" — give `trusted` the relevant `security.bypass.*` permission.
-3. **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.
+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.
+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.
+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.
 
-When you see a block, tell the user **which permission would skip it** (the block message now names it) and **which built-in roles have that permission**. Do not just relay the guard reason — that loses the access-control framing entirely.
+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.
 
 ## When the user asks "why aren't you replying in #channel?"
 
@@ -120,7 +136,7 @@ To distinguish cause 1/2 from cause 3: if `typeclaw logs <container> -f` (host s
 This is a `roles` edit. The full procedure:
 
 1. **Resolve the coordinates.** Get the platform name (`slack | discord | telegram | kakao`), the workspace ID, the chat ID. If the user gave you names, ask them or look them up in the participants list of a previous inbound from that channel.
-2. **Pick a role.** Default to `member` for "give them normal channel access". Use `trusted` if they should also be able to schedule cron and bypass the bash secret guard. Only use `owner` if they should have full bypass on every security guard — typically the agent's primary operator.
+2. **Pick a role.** Default to `member` for "give them normal channel access". Use `trusted` if they should also be able to schedule cron — by default trusted gets ONLY `bypass.low` (no inhabitants today), so trusted on its own does NOT skip any security guard. If the user wants the old pre-PR-#255 trusted ergonomics (bypass bash secret guard, push without ack), add per-guard strings explicitly: `roles.trusted.permissions: ["channel.respond", "cron.schedule", "security.bypass.low", "security.bypass.secretExfilBash", "security.bypass.gitExfil"]`. Use `owner` only for the primary operator — owner auto-bypasses every medium-tier guard (`secretExfilBash`, `secretExfilRead`, `ssrf`, `sessionSearchSecrets`) but **still must ack every high-tier guard** (`gitExfil`, `gitRemoteTainted`, `outboundSecret`, `systemPromptLeak`) because audience-leak guards have no role auto-bypass — that's the owner-in-public-channel rule. If the user explicitly wants `git push` from TUI without acks, that's a per-guard explicit grant on `roles.owner.permissions[]` (re-add `security.bypass.gitExfil`), and the user should understand they are re-opening the audience-leak path for that guard.
 3. **Edit `typeclaw.json` `roles.<role>.match[]`.** Append the canonical DSL string. Example: `roles.member.match` adds `"slack:T0123/C0ABCDE"`. If the user wants only a specific person in that channel, append `slack:T0123/C0ABCDE author:U_ME` instead.
 4. **Restart.** `roles` is **restart-required** — `typeclaw reload` does not re-evaluate role config. Tell the user: "edited `roles.<role>.match` — restart-required. Run `typeclaw restart` (host stage)."
 5. **Commit the change.** See the `typeclaw-git` skill. The decision context in the commit message should name the role, the channel, and the author/scope ("let @X talk to me as `member` in #foo in workspace bar").
@@ -150,7 +166,10 @@ If you see a cron job mysteriously failing every fire with `denied by permission
 ## Things you must not do
 
 - **Do not write `*` in user-declared `permissions[]`.** The owner wildcard is a runtime sentinel, not part of the user-facing string format. The schema rejects `*` (it's not a valid dotted permission string anyway).
-- **Do not invent permission strings.** Only the three sources above (core, security plugin, declared plugins) contribute valid strings. A string like `bash.execute` looks plausible but is not gated by anything and will only earn a boot warning. If the user asks for a permission the model doesn't have, tell them — don't invent one.
+- **Do not invent permission strings.** Only the three sources above (core, security plugin including the eight per-guard + three tier strings, declared plugins) contribute valid strings. A string like `bash.execute` looks plausible but is not gated by anything and will only earn a boot warning. If the user asks for a permission the model doesn't have, tell them — don't invent one.
+
+- **Do not grant `security.bypass.high` casually.** High-tier guards (`gitExfil`, `gitRemoteTainted`, `outboundSecret`, `systemPromptLeak`) all defend the audience-leak axis — bypassing them means data leaves the operator's perimeter without per-call confirmation. Even `owner` doesn't have `bypass.high` by default for this exact reason. Granting `security.bypass.high` to any role opens audience-leak bypass on every current high-tier guard PLUS every future high-tier guard added by a security plugin update. If the user wants one specific high-tier bypass (e.g. "let me push from TUI without acks"), grant the **per-guard** string explicitly (`security.bypass.gitExfil`) on the specific role, not the tier — that's narrower and won't widen on plugin updates.
+- **Do not grant `security.bypass.medium` to roles wider than the operator.** Medium-tier bypasses (`secretExfilBash`, `secretExfilRead`, `ssrf`, `sessionSearchSecrets`) silently dump secrets into model context. Granting `bypass.medium` to a `trusted` role that matches a broad Slack workspace means any trusted speaker can ask the agent to dump environment variables and the bypass succeeds — the operator only sees on session review. If the user wants this anyway, name the specific guard with a per-guard grant rather than the whole tier.
 - **Do not promise that `typeclaw reload` applied a `roles` edit.** `roles` is restart-required. The reload tool will return success on the config file change, but the live `PermissionService` was built at boot and is not swapped on reload.
 - **Do not silently change a built-in role's permission list.** Setting `"permissions": []` on `member` is a wholesale replace, not a merge — you just took `channel.respond` away from every speaker who resolves to `member`. If the user said "give member just `channel.respond` and nothing else", that's fine (it's the same as the default), but say so explicitly: "this matches the default for `member`, no behavior change". If the user said "remove cron from `trusted`", make the change but warn that `trusted` no longer carries `cron.schedule` either.
 - **Do not write match rules using display names** (`#general`, `@user`, channel/user names). Match rules are platform IDs. Display names change; IDs don't. Always look up the ID before writing the rule.

package/src/skills/typeclaw-plugins/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: typeclaw-plugins
-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 skills, the typeclaw/plugin import path, or per-plugin config blocks in typeclaw.json. Triggers on mentions of 'TypeClaw plugin', 'definePlugin', 'plugin hook', 'plugin cron', 'plugins[]', 'typeclaw-plugin-', or any file under src/plugin/ or plugins/.
+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/.
 ---
 
 # TypeClaw Plugins
@@ -252,13 +252,59 @@ cronJobs: {
     kind: 'exec',
     command: ['bun', 'run', 'scripts/rotate.ts'],
   },
+  // The canonical shape for scheduled imperative LLM work: a handler
+  // function the cron consumer invokes directly. No shell-out, no WS
+  // round-trip, no Bun.spawn — the handler runs in-process with the same
+  // ctx.prompt / ctx.exec surface a container command sees.
+  'inbox-watch': {
+    schedule: '*/15 * * * *',
+    kind: 'handler',
+    handler: async (ctx) => {
+      const { stdout } = await ctx.exec`gmail unread --count`
+      if (Number(stdout.trim()) === 0) return
+      await ctx.prompt(`Triage ${stdout.trim()} new emails…`)
+    },
+  },
 }
 ```
 
 - The map key is a **suffix**. The runtime constructs the global cron id as `__plugin_<plugin-name>_<key>` (e.g., `__plugin_standup-log_weekly-digest`).
 - `cron.json` user job ids cannot start with underscore, so collision is impossible by construction.
 - A `prompt` job's `subagent` and `payload` are **validated against the registry at boot** — bad references fail loudly on disk, not 6 hours later when the job fires.
-- Only two kinds: `prompt` and `exec`. Plugins do not extend the schema.
+- Three kinds: `prompt`, `exec`, `handler`. **`handler` is plugin-only** — it cannot appear in `cron.json` because the handler is a TypeScript function reference (not JSON-serializable). User-authored cron files are validated by `parseCronFile` which rejects anything outside `prompt | exec`.
+
+#### `kind: 'handler'` — direct function dispatch
+
+When the cron job needs imperative control flow (probe → maybe prompt → write file) and the logic lives in the same plugin as the schedule, declare it as a `handler`. The consumer invokes the function directly with a `CronHandlerContext`:
+
+```ts
+type CronHandlerContext = {
+  readonly jobId: string // __plugin_<name>_<key>
+  readonly name: string // plugin name that registered the job
+  readonly agentDir: string // /agent in container
+  readonly logger: PluginLogger
+  readonly signal: AbortSignal // reserved for future cancellation; currently inert
+  readonly permissions: PermissionService
+  readonly origin: SessionOrigin // { kind: 'cron', jobKind: 'handler', ... }
+  readonly prompt: (text: string) => Promise<string> // full agent session, slim system prompt mode
+  readonly subagent: (name, payload?) => Promise<void>
+  readonly exec: (cmd, ...vals) => Promise<CommandExecResult> // tagged template
+}
+```
+
+The `prompt` / `subagent` / `exec` surface is identical to `ContainerCommandContext` (§5.7) and reuses the same underlying implementation — abort semantics, process-group kill, slim system prompt mode are all shared. Differences from `ContainerCommandContext`: no `stdin` / `stdout` / `stderr` (cron has no caller piping bytes), no `args` (handlers are scheduled, not invoked with flags), no return value (throw to signal failure, the consumer logs).
+
+#### When to use which `kind`
+
+| `kind`          | Use for                                                                                                                                             |
+| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `'prompt'`      | One-shot natural-language prompts. Stable instruction, no shell pre-work, no conditional logic.                                                     |
+| `'exec'`        | Pure shell work — `git commit`, log rotation, calling a script. Can also point at a plugin's `surface: 'host'` command via `['typeclaw', '<cmd>']`. |
+| **`'handler'`** | **The default for plugin-internal scheduled imperative work.** Probe + maybe prompt, multi-step orchestration, anything mixing shell and LLM calls. |
+
+A plugin that exposes a `surface: 'container'` command (§5.7) often does NOT need a corresponding cron handler — if the command's whole `run` body is the scheduled work, just factor the body into a shared private function and have BOTH the command and the cron handler call it. The command stays callable from the TUI / manual shell; the cron handler stays callable from the scheduler without shelling out.
+
+The pre-handler workaround (cron `kind: 'exec'` with `command: ['typeclaw', '<plugin-cmd>']` shelling out to its own container) is still valid but no longer the default — reach for it only when the user owns the cadence (`cron.json` scheduling someone else's command) or when the scheduled work is genuinely a host-side command. See `typeclaw-cron` for the full decision tree.
 
 ### 5.4 `skills` — string-form (per-session tmpdir)
 
@@ -326,6 +372,198 @@ Provider prompt caching makes the **prefix** of the system prompt 5–10× cheap
 
 If your content varies per session, **append**. If it's stable across sessions, prepending is fine but understand the cost.
 
+### 5.7 `commands` — typeclaw CLI subcommands
+
+A plugin can register top-level CLI commands invocable as `typeclaw <name>` from any shell sitting in the agent folder. **Unlike every other contribution in §5, `commands` is declared by-value on `definePlugin(...)`, NOT inside the factory return.** This is so the host-stage CLI can dispatch commands without booting the plugin runtime (no `bun install`, no factory, no engine spin-up just to print `--help`).
+
+```ts
+import { z } from 'zod'
+import { definePlugin } from 'typeclaw/plugin'
+
+export default definePlugin({
+  commands: {
+    'standup-now': {
+      surface: 'container',
+      description: 'Generate a standup write-up for today from sessions/.',
+      args: z.object({
+        date: z.string().optional().describe('YYYY-MM-DD; defaults to today'),
+      }),
+      async run(ctx, args) {
+        const text = await ctx.prompt(
+          `Read sessions/ for ${args.date ?? 'today'} and write a 3-bullet standup to standup/${args.date ?? 'today'}.md.`,
+        )
+        const writer = ctx.stdout.getWriter()
+        await writer.write(new TextEncoder().encode(text + '\n'))
+        writer.releaseLock()
+        return 0
+      },
+    },
+  },
+  plugin: async (ctx) => ({
+    /* tools, hooks, cron, ... */
+  }),
+})
+```
+
+Once installed, the user (or a cron `exec` job) runs `typeclaw standup-now --date=2026-05-18`. `typeclaw --help` lists all discovered plugin commands automatically — no separate registration.
+
+#### The three surfaces
+
+| `surface`     | Runs where                                                          | `ctx` has                                                                 | Use when                                                                                                                                                                                                                                                                                                                              |
+| ------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `'container'` | Inside the running agent container, proxied over WS by the host CLI | `prompt`, `subagent`, `exec`, `permissions`, `origin`, `signal` + streams | The command needs the agent runtime — LLM calls (`ctx.prompt`), subagent invocation, permission checks. Reusable from TUI, manual shell, `compose`, and (as a narrower fallback when reusability is required) cron `exec`. For plugin-internal scheduled `exec → LLM` work, prefer `kind: 'handler'` (§5.3) — see "Cron usage" below. |
+| `'host'`      | On the user's machine, no container required                        | `streams`, `signal`, `logger`, `agentDir` (host path)                     | The command only touches host-side state (files, host binaries, prompts the user). Container does NOT need to be running.                                                                                                                                                                                                             |
+| `'either'`    | Whichever stage invoked it — same author code runs in both          | The intersection (`streams`, `signal`, `logger`, `agentDir`)              | The command's logic is stage-agnostic. `agentDir` resolves to `/agent` in the container and the host path on the host, automatically.                                                                                                                                                                                                 |
+
+The `surface: 'container'` command requires the container to be running. The host CLI opens a WebSocket to `/commands` on the agent's port, sends `exec_command`, and streams stdout/stderr back. Ctrl-C on the host propagates as `AbortSignal` to `ctx.signal` inside the container.
+
+#### `ContainerCommandContext` — what you get inside `run`
+
+```ts
+type ContainerCommandContext = {
+  readonly name: string // plugin name (e.g. 'standup-log'), NOT command name
+  readonly version: string | undefined
+  readonly agentDir: string // /agent inside the container
+  readonly logger: PluginLogger
+  readonly permissions: PermissionService
+  readonly origin: SessionOrigin // caller's origin — cron job, TUI op, etc.
+  readonly signal: AbortSignal // aborts on ws close or host Ctrl-C
+  readonly stdin: ReadableStream<Uint8Array>
+  readonly stdout: WritableStream<Uint8Array>
+  readonly stderr: WritableStream<Uint8Array>
+  readonly prompt: (text: string) => Promise<string> // full LLM session, full toolset, returns last assistant text
+  readonly subagent: (name: string, payload?: unknown) => Promise<void>
+  readonly exec: (cmd: TemplateStringsArray, ...values: unknown[]) => Promise<CommandExecResult>
+}
+```
+
+Key facts about each capability:
+
+- **`ctx.prompt(text)`** opens a brand-new `AgentSession` with the full agent toolset (read/bash/edit/write/grep/find/ls + plugin tools), sends `text` as if a user typed it, and returns the last assistant message. The session is created and disposed inside the call. The session uses **slim system prompt mode** (subagent-shaped origin) so you save ~2000 tokens per LLM call versus a normal TUI session.
+- **`ctx.subagent(name, payload)`** invokes a registered subagent (yours or another plugin's). Returns when the subagent's `runSession` resolves.
+- **`ctx.exec` is a tagged template** — `await ctx.exec\`git log --oneline -10\``runs the command in the agent folder with`ctx.signal` threaded through. Aborts kill the entire process group (SIGTERM → 5s grace → SIGKILL) so daemonized grandchildren don't outlive the abort.
+- **`ctx.origin`** carries the caller's `SessionOrigin`. For host-invoked (TUI op) calls it's `{ kind: 'tui', ... }`; for cron-invoked calls it's the cron job's origin including `scheduledByRole`. **No silent role elevation** — a cron job running as `scheduledByRole: 'member'` invokes the command with that same role, and permission checks inside the command resolve accordingly.
+
+#### Cron usage: prefer `kind: 'handler'` over shelling out to your own command
+
+Plugin cron jobs support `kind: 'handler'` (§5.3) which invokes a TypeScript function directly with a `CronHandlerContext`. The handler ctx exposes the SAME `ctx.prompt` / `ctx.subagent` / `ctx.exec` surface a container command sees — same slim-mode session, same process-group abort semantics — but without the shell-out, the WS round-trip, or the args-parse round-trip.
+
+**If the cron job and the command both live in the same plugin, prefer a handler.** Factor any shared logic into a private function and have BOTH the command's `run` body and the cron handler call it. The command stays callable from the TUI / manual `typeclaw` invocations; the cron handler stays callable from the scheduler with zero shell-out cost.
+
+The shell-out pattern below (cron `exec` → `typeclaw <plugin-cmd>`) is still supported and stays valid in three narrow cases, all rooted in **the same logic needing a callable surface beyond cron**:
+
+1. **The logic is also a reusable CLI command.** The user wants to run it manually as `typeclaw <cmd> --flag=...` from the TUI / shell / `compose`, or another caller needs the same args contract. Write the logic once inside a `surface: 'container'` command's `run`; reuse it from cron by pointing an `exec` job at the same command. "Scheduled work that needs LLM judgement" alone is NOT this case — without an external caller, prefer `kind: 'handler'` and avoid the shell-out overhead.
+2. **The user owns the cadence.** `cron.json` schedules someone else's plugin command at a custom cadence the plugin author didn't anticipate. The user doesn't fork the plugin to change the schedule.
+3. **The scheduled work needs a `surface: 'host'` command.** Host commands run outside the container with no agent runtime, so `ctx.prompt` is unavailable; the shell-out via `typeclaw <host-cmd>` is the only path.
+
+#### The cron-exec → typeclaw shell-out (narrower use case)
+
+For plugin-internal scheduled `exec → LLM` work, `kind: 'handler'` (§5.3) is the best practice — see "Cron usage" above. The pattern below — write a `surface: 'container'` plugin command whose `run` calls `ctx.prompt(...)`, then point a `cron.json` `exec` job at it — is the fallback when **reusability is the actual requirement**: the same logic must also be invocable as a CLI command from TUI / manual shell / `compose`, or the user owns the cadence for a command they didn't write, or the work needs `surface: 'host'` (where `ctx.prompt` doesn't exist).
+
+User-authored `cron.json` itself supports only `prompt` and `exec` — that's by design. `kind: 'handler'` is plugin-only because the handler is a function reference, not JSON-serializable.
+
+```json
+// cron.json
+{
+  "jobs": [
+    {
+      "id": "daily-standup",
+      "schedule": "30 9 * * 1-5",
+      "timezone": "Asia/Seoul",
+      "kind": "exec",
+      "command": ["typeclaw", "standup-now"]
+    }
+  ]
+}
+```
+
+```ts
+// packages/standup-log/index.ts
+export default definePlugin({
+  commands: {
+    'standup-now': {
+      surface: 'container',
+      description: 'Generate today’s standup.',
+      async run(ctx) {
+        await ctx.prompt(
+          `Read sessions/$(date +%F)*.jsonl and append a 3-bullet standup to memory/standups/$(date +%F).md.`,
+        )
+        return 0
+      },
+    },
+  },
+  plugin: async () => ({}),
+})
+```
+
+This `cron.json → typeclaw <cmd>` shape is the right choice in the three narrow cases listed above. For plugin-internal scheduled work where the cadence belongs to the plugin author and nothing outside cron needs to invoke the logic, write a `kind: 'handler'` job (§5.3) instead — same `ctx.prompt` / `ctx.exec` shape, none of the shell-out overhead.
+
+Why a CLI command is worth defining (and exposing via cron `exec`) when one of the three cases applies:
+
+- The command is reusable from the TUI, from `compose` orchestration, or from a manual `typeclaw standup-now` invocation by the user.
+- Args (`--date`, `--dry-run`, etc.) are declared once via `args: z.object({...})` and parsed/validated by the runtime — both at the host CLI and as defense-in-depth in the container.
+- A user who wants a different cadence than the plugin's default can drop a `cron.json` entry pointing at the command without forking the plugin.
+
+If none of those benefits actually apply to your case, the CLI command shape is overhead — write a handler.
+
+For the cron-side decision rules (when to pick `handler` vs `prompt` vs `exec → typeclaw <cmd>`, and how to gate `ctx.prompt` behind a cheap `ctx.exec` probe) read `typeclaw-cron`.
+
+#### `args` — Zod object schema with primitive leaves
+
+```ts
+args: z.object({
+  date: z.string().optional().describe('YYYY-MM-DD; defaults to today'),
+  dryRun: z.boolean().default(false),
+  count: z.number().int().min(1).max(100).default(10),
+})
+```
+
+- The top level **MUST** be `z.object({...})`. Leaves should be primitives (`string`, `number`, `boolean`, `literal`, `enum`) so `--help` can render `--<name>=<type>`.
+- Args are validated locally by the host CLI **before** any WS round-trip, so bad args fail fast with a clean error and exit code 2. The container re-validates as defense-in-depth.
+- `.describe(...)` populates `--help` output. Use it.
+- Omit `args` entirely if the command takes no flags.
+
+#### `permissions: [...]` on the command
+
+```ts
+{
+  surface: 'container',
+  permissions: ['standup-log.write.standup'],
+  async run(ctx, args) {
+    ctx.permissions.assert(ctx.origin, 'standup-log.write.standup')
+    // ...
+  },
+}
+```
+
+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`.
+
+#### `isolated: true` (container surface only)
+
+```ts
+{
+  surface: 'container',
+  isolated: true,  // currently degrades to in-process with a warning on stderr
+  async run(ctx, args) { /* ... */ },
+}
+```
+
+Reserved for a future subprocess sandbox. Today the runtime accepts the flag and emits a warning on the per-command stderr (visible to the invoking CLI) but executes in-process anyway. Set it now if you genuinely want the isolation when it lands; otherwise omit.
+
+#### Discovery and naming
+
+- Command names are **global across all plugins**. Two plugins registering `standup-now` is a discovery error — the second one is dropped and logged on `--help`.
+- Command names are NOT auto-prefixed with the plugin name. Pick discriminating names (`standup-now`, not `run`).
+- `typeclaw --help` (in any agent folder) lists every discovered plugin command with description, surface, and which plugin owns it.
+- `typeclaw <name> --help` renders args, surface, plugin name + version. Free.
+
+#### What's NOT supported
+
+- **No host-stage CLI commands that mutate the live container without going through `restart` / `reload`.** A host command can `Bun.spawn('typeclaw', ['reload'])` if it needs to push a config change, but there's no privileged backdoor.
+- **No tool-style `content: ContentPart[]` return.** Commands write to `ctx.stdout` and return an exit code. They are CLI processes, not LLM tool calls.
+- **No streaming token output from `ctx.prompt`** yet — the full LLM response arrives as one stdout burst. Chunked streaming is on the roadmap.
+- **No nested command dispatch.** A command cannot invoke `typeclaw <other-cmd>` and expect to share state; spawn a subprocess or share a subagent instead.
+
 ---
 
 ## 6. PluginContext
@@ -530,9 +768,8 @@ If you find yourself wanting any of these, the design has gone wrong somewhere
 - **Stream subscriptions**. Plugins observe through the typed `hooks` surface; they cannot subscribe to the in-process pub/sub directly.
 - **Server-side TUI push notifications** from plugin code. Tool calls reach the TUI via existing `tool_start`/`tool_end` events.
 - **Dockerfile fragments** contributed by plugins. The Dockerfile is core-managed.
-- **New cron job kinds** beyond `prompt` and `exec`. (Subagent invocation is a `prompt` variant, not a separate kind.)
+- **New cron job kinds for user-authored `cron.json`** beyond `prompt` and `exec`. (Subagent invocation is a `prompt` variant, not a separate kind. Plugin cron jobs additionally support `kind: 'handler'` — see §5.3 — but that's plugin-only because the handler is a TypeScript function reference, not JSON-serializable.)
 - **Reload-registry scopes** for plugin-owned state.
-- **Host-stage CLI commands** registered by plugins. Plugins are container-stage only.
 - **`extendConfig`** for arbitrary top-level fields outside the plugin's own config block.
 - **Per-LLM-call hooks** (`llm.params` / `llm.headers`). Wait until a real plugin needs them.
 
@@ -575,6 +812,10 @@ export default definePlugin({
   configSchema: z.object({
     /* ... */
   }), // optional
+  commands: {
+    /* name: { surface, run, args?, ... } */
+  }, // optional, declared BY-VALUE (not inside factory)
+  permissions: ['my-plugin.write.x'], // optional
   plugin: async (ctx) => ({
     // required
     tools,
@@ -582,7 +823,8 @@ export default definePlugin({
     cronJobs,
     skills,
     skillsDirs,
-    hooks, // all optional
+    hooks,
+    doctorChecks, // all optional
   }),
 })
 ```
@@ -591,4 +833,8 @@ export default definePlugin({
 
 **Plugin name = derived**: scope-stripped, `typeclaw-plugin-` prefix stripped (npm), or basename minus extension (local).
 
+**Command name = global**: NOT prefixed with plugin name. Two plugins registering the same command name is a discovery error (second is dropped, logged on `--help`).
+
+**`exec → LLM` from cron** (best practice): plugin `cronJobs` entry with `kind: 'handler'` — a TypeScript function the cron consumer invokes directly with `ctx.prompt` / `ctx.subagent` / `ctx.exec`. No shell-out, no WS round-trip. Fall back to `surface: 'container'` command + cron `exec` pointing at `["typeclaw", "<cmd>"]` ONLY when the same logic must also be invocable as a reusable CLI command, the user owns the cadence for someone else's command, or the work needs `surface: 'host'`.
+
 **Boundary**: `src/plugin/**` MUST NOT import `@mariozechner/*`.

package/src/skills/typeclaw-tunnels/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: typeclaw-tunnels
+description: Use when the user mentions tunnel, ngrok, webhook URL, cloudflared, expose to internet, show my friend, public URL, GitHub webhook, port forward to public, reverse proxy, trycloudflare, or making a container-local service reachable from the internet. Read it before suggesting tunnel add/remove/status/logs or editing typeclaw.json tunnels[].
+---
+
+# typeclaw-tunnels
+
+TypeClaw tunnels expose a container-private HTTP/TCP service to the public internet. Use them for inbound webhooks (especially GitHub) or short-lived demos where the user wants a public URL for a local port.
+
+## When to suggest `typeclaw tunnel add`
+
+Suggest a tunnel when the user asks for any of these:
+
+- "give GitHub a webhook URL", "make GitHub webhooks work", or similar webhook delivery work.
+- "expose this to the internet", "show my friend", "public URL", or "share this dashboard".
+- "use ngrok" or "cloudflared" for a port running inside the agent container.
+
+Do **not** suggest a tunnel for host-local browsing only. If the user just needs to open a dev server on their own machine, TypeClaw's port-forwarder usually already maps container LISTEN ports to `127.0.0.1:<port>` on the host. Tunnels are for public internet ingress.
+
+## Provider choices
+
+### Cloudflare Quick Tunnel
+
+Choose Cloudflare Quick when the user wants the easiest path:
+
+- No Cloudflare account or signup.
+- No host-side binary install; `cloudflared` runs inside the container.
+- The URL looks like `https://<random>.trycloudflare.com`.
+- The URL rotates on container restart or tunnel restart. That is expected.
+
+For GitHub channel setup, `typeclaw channel add github` can write a channel-owned Cloudflare Quick tunnel named `github-webhook` and set `docker.file.cloudflared: true`. The first `typeclaw start` or `restart` after that rebuilds the image with `cloudflared` installed.
+
+### External URL
+
+Choose External when the user already has their own reverse proxy or tunnel:
+
+- ngrok, a Cloudflare named tunnel managed outside TypeClaw, Caddy on a VPS, Tailscale Funnel, or any HTTPS reverse proxy.
+- The URL is stable because the user owns it.
+- TypeClaw does not spawn a subprocess for this provider; it records the URL and broadcasts it to channel consumers.
+
+Use `provider: "external"` with `externalUrl: "https://..."`. External URLs must be HTTPS.
+
+## Commands
+
+- `typeclaw tunnel add <name>` — add a manual tunnel to `typeclaw.json`.
+- `typeclaw tunnel list` — show all configured tunnels and their current URL/health.
+- `typeclaw tunnel status <name>` — inspect one tunnel in detail.
+- `typeclaw tunnel logs <name>` — print the tunnel's recent log ring.
+- `typeclaw tunnel logs <name> -f` — follow live tunnel logs.
+- `typeclaw tunnel remove <name>` — remove a manual tunnel. Channel-owned tunnels should be removed through the owning channel flow, not by hand.
+
+Tunnel config is **restart-required**. After adding/removing/changing `tunnels[]` or `docker.file.cloudflared`, the user must run `typeclaw restart` from the host stage.
+
+## Reading `tunnel status`
+
+Healthy Cloudflare Quick tunnels should show:
+
+- provider `cloudflare-quick`.
+- a current `https://...trycloudflare.com` URL after cloudflared has emitted one.
+- health like `healthy` or equivalent live/running state.
+- restart count near zero for a stable tunnel.
+
+Unhealthy signs:
+
+- no URL after startup.
+- repeated restarts or increasing restart count.
+- `unhealthy` / `permanently-failed` state.
+- last error mentioning spawn failure, missing binary, or cloudflared exit.
+
+For External tunnels, the URL should be the configured `externalUrl`; there may be no subprocess health to inspect.
+
+## Reading `tunnel logs`
+
+Healthy Cloudflare Quick logs usually include:
+
+- cloudflared startup lines.
+- a line containing the public `https://...trycloudflare.com` URL.
+- no rapid repeated exit/restart sequence.
+
+Unhealthy logs often show:
+
+- `cloudflared` not found or spawn failure.
+- repeated process exits followed by backoff/restart lines.
+- Cloudflare connection errors or network failures.
+- no URL emission before the process exits.
+
+Use `typeclaw tunnel logs <name> -f` while restarting the agent if you need to watch URL discovery live.
+
+## Common failure modes
+
+### `cloudflared` is not installed
+
+The Cloudflare Quick provider requires `docker.file.cloudflared: true`. If it is missing, add it to `typeclaw.json` or re-run the GitHub channel setup choosing Cloudflare Quick, then run `typeclaw restart` so the Dockerfile is regenerated and the image rebuilds.
+
+### Quick tunnel URL changed
+
+This is normal. Quick Tunnel URLs rotate on restart. GitHub channel-owned tunnels handle this by flowing the resolved URL through the channel manager's `tunnelUrl()` callback and restarting the adapter; do not persist the rotating URL into `typeclaw.json`.
+
+### Repeated restarts
+
+Inspect `typeclaw tunnel status <name>` and `typeclaw tunnel logs <name>`. Look for spawn errors, network restrictions, or cloudflared exiting before URL discovery. The tunnel manager backs off and eventually stops retrying after repeated failures without a URL.
+
+### GitHub webhooks are not delivered
+
+Check in this order:
+
+1. `typeclaw tunnel status github-webhook` has a current URL.
+2. `typeclaw tunnel logs github-webhook` shows a URL and no crash loop.
+3. The GitHub channel config has repos listed under `channels.github.repos`.
+4. The channel adapter was restarted after the URL arrived. Channel-owned tunnel URLs should flow through `tunnelUrl()` into adapter `start()`, not through config mutation.
+5. GitHub repo webhook settings point at the current URL if using External; for Cloudflare Quick, expect TypeClaw to re-register on URL changes.

package/src/test-helpers/wait-for.ts

@@ -0,0 +1,50 @@
+export type WaitForOptions = {
+  timeoutMs?: number
+  intervalMs?: number
+  description?: string
+}
+
+const DEFAULT_TIMEOUT_MS = 1_000
+const DEFAULT_INTERVAL_MS = 1
+
+export async function waitFor<T>(
+  predicate: () => T | Promise<T>,
+  options: WaitForOptions = {},
+): Promise<NonNullable<T>> {
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS
+  const intervalMs = options.intervalMs ?? DEFAULT_INTERVAL_MS
+  const deadline = Date.now() + timeoutMs
+
+  const initial = await predicate()
+  if (initial) return initial as NonNullable<T>
+
+  while (Date.now() < deadline) {
+    await new Promise<void>((resolve) => setTimeout(resolve, intervalMs))
+    const result = await predicate()
+    if (result) return result as NonNullable<T>
+  }
+
+  const label = options.description ?? 'condition'
+  throw new Error(`waitFor: ${label} did not become truthy within ${timeoutMs}ms`)
+}
+
+// Asserts that `predicate` STAYS falsy for the full `durationMs`. Unlike
+// `waitFor`, this MUST pay the full duration — you cannot observe the absence
+// of an event faster than waiting for it. Use sparingly, and keep durations
+// tight.
+export async function expectStable<T>(
+  predicate: () => T | Promise<T>,
+  options: { durationMs: number; intervalMs?: number; description?: string },
+): Promise<void> {
+  const intervalMs = options.intervalMs ?? 5
+  const deadline = Date.now() + options.durationMs
+
+  while (Date.now() < deadline) {
+    const result = await predicate()
+    if (result) {
+      const label = options.description ?? 'condition'
+      throw new Error(`expectStable: ${label} became truthy before ${options.durationMs}ms elapsed`)
+    }
+    await new Promise<void>((resolve) => setTimeout(resolve, intervalMs))
+  }
+}