typeclaw 0.3.1 → 0.5.0

package/src/init/oauth-login.ts

@@ -14,16 +14,29 @@ export type OAuthLoginResult = { ok: true } | { ok: false; reason: string }
 export type OAuthLoginRunner = (options: { cwd: string; model: KnownModelRef }) => Promise<OAuthLoginResult>
 
 // Wrap pi-ai's OAuth callbacks so the CLI doesn't have to know about the
-// upstream callback shape. The CLI only sees three lifecycle events:
+// upstream callback shape. The CLI sees four lifecycle events:
 // (1) onAuth(url) — print the URL the user must visit
 // (2) onProgress(message) — show waiting/finalizing status
 // (3) onPrompt(prompt) — ask the user for a manual code if the browser flow
-//     can't reach the local callback server. Most users won't see this; it
-//     fires when they paste the post-redirect URL by hand.
+//     can't reach the local callback server. Fires only after the local
+//     server gave up (bind error -> waitForCode resolves null).
+// (4) onManualCodeInput() — concurrent paste input that RACES the local
+//     callback server. Required for cross-device flows: pi-ai's openai-codex
+//     OAuth hardcodes redirect_uri=http://localhost:1455/auth/callback, which
+//     resolves to the *browser's* machine. When the user runs `typeclaw init`
+//     over SSH or on a remote dev box and completes login on a different
+//     laptop, the browser callback never reaches the CLI's local server and
+//     waitForCode() hangs forever — so onPrompt would never fire either.
+//     onManualCodeInput is the upstream-supported escape hatch: it shows a
+//     paste field IMMEDIATELY alongside the URL, and whichever path lands a
+//     code first wins. parseAuthorizationInput on the upstream side accepts
+//     the full redirect URL, the bare `code=...&state=...` query string, or
+//     just the code value.
 export type OAuthCallbacks = {
   onAuth: (url: string, instructions?: string) => void
   onProgress?: (message: string) => void
   onPrompt: (message: string, placeholder?: string) => Promise<string | null>
+  onManualCodeInput?: () => Promise<string>
 }
 
 // Default runner: real OAuth flow against pi-ai. Tests inject a stub to skip
@@ -50,6 +63,7 @@ export function makeOAuthLoginRunner(callbacks: OAuthCallbacks): OAuthLoginRunne
           }
           return value
         },
+        onManualCodeInput: callbacks.onManualCodeInput,
       })
       return { ok: true }
     } catch (error) {

package/src/init/run-bun-install.ts

@@ -1,12 +1,21 @@
 export type InstallResult = { ok: true } | { ok: false; reason: string }
 
+export type InstallRunnerOptions = {
+  // Append `--force` to the bun install argv to bypass the cache for
+  // `file:` / `link:` deps. Bun treats name+version of a `file:` dep as a
+  // cache hit even after the source on disk has changed, so changes to a
+  // locally-linked typeclaw never propagate into <agent>/node_modules until
+  // either the typeclaw version is bumped or the install is forced.
+  force?: boolean
+}
+
 // Signature for the function `runInit` uses to materialize the agent folder's
 // dependencies. Exposed as a named type so callers (and tests) can pass their
 // own stub without re-declaring the shape, mirroring `HatchRunner` and
 // `KakaotalkAuthRunner` in `./index.ts`.
-export type InstallRunner = (cwd: string) => Promise<InstallResult>
+export type InstallRunner = (cwd: string, opts?: InstallRunnerOptions) => Promise<InstallResult>
 
-export async function runBunInstall(cwd: string): Promise<InstallResult> {
+export async function runBunInstall(cwd: string, opts?: InstallRunnerOptions): Promise<InstallResult> {
   const bun = (globalThis as { Bun?: { spawn: typeof Bun.spawn } }).Bun
   if (!bun) return { ok: false, reason: 'bun runtime not available' }
   try {
@@ -21,7 +30,12 @@ export async function runBunInstall(cwd: string): Promise<InstallResult> {
       // the bug are non-trivial. Hoisted is the fallback strategy bun shipped
       // before 1.3 — slightly slower for huge monorepos, indistinguishable
       // for an agent folder, and not affected by the bug.
-      cmd: ['bun', 'install', '--linker=hoisted'],
+      //
+      // `--force` is conditional: it bypasses the package cache so file:/link:
+      // deps re-copy their current on-disk source into node_modules. Bun's
+      // file-dep cache is keyed on name+version, so without --force, edits to
+      // a `file:..` typeclaw never reach the container after the first install.
+      cmd: opts?.force ? ['bun', 'install', '--linker=hoisted', '--force'] : ['bun', 'install', '--linker=hoisted'],
       cwd,
       stdout: 'pipe',
       stderr: 'pipe',

package/src/init/run-owner-claim.ts

@@ -8,6 +8,7 @@ import type { ChannelKind } from './index'
 const CHANNEL_LABELS: Record<ChannelKind, string> = {
   'slack-bot': 'Slack',
   'discord-bot': 'Discord',
+  github: 'GitHub',
   'telegram-bot': 'Telegram',
   kakaotalk: 'KakaoTalk',
 }
@@ -25,9 +26,17 @@ export type RunOwnerClaimOptions = {
 // normal hatching path so the TUI still opens — the operator can run
 // `typeclaw role claim` later.
 export async function runOwnerClaim({ url, configuredChannels }: RunOwnerClaimOptions): Promise<void> {
-  if (configuredChannels.length === 0) return
+  // GitHub has no DM affordance, and the github adapter doesn't yet route
+  // claim codes (the `typeclaw role claim` CLI explicitly lists only the
+  // four chat adapters as --channel values). Owner authorization for github
+  // is handled by the `roles.member.match[]` repo allowlist that
+  // runAddChannel writes during init. Filtering here keeps the auto-claim
+  // working for chat channels mixed with github, and skips the flow
+  // entirely when github is the only wired channel.
+  const claimable = configuredChannels.filter((c) => c !== 'github')
+  if (claimable.length === 0) return
 
-  const channelList = configuredChannels.map((c) => CHANNEL_LABELS[c] ?? c).join(', ')
+  const channelList = claimable.map((c) => CHANNEL_LABELS[c] ?? c).join(', ')
 
   const proceed = await confirm({
     message: `Claim owner role on ${channelList} now?`,

package/src/permissions/builtins.ts

@@ -25,6 +25,21 @@ export type BuiltinRoleSpec = {
   readonly permissions: readonly string[]
 }
 
+// Owner carries low + medium tier strings explicitly AND the wildcard
+// sentinel. The sentinel expands to plugin-contributed `security.bypass.*`
+// strings minus the security plugin's `ownerWildcardExclusions` (today:
+// `security.bypass.high` plus high-tier per-guard strings). Net effect:
+// owner auto-bypasses every low- and medium-tier guard, and high-tier
+// guards require per-call ack from owner too (the audience-leak rule —
+// owner-in-public-channel must not silently post credentials).
+//
+// Trusted carries only `security.bypass.low`. Trusted does NOT carry the
+// pre-PR per-guard grants (`bypassSecretExfilBash`, `bypassGitExfil`):
+// those guards are medium/high under the audience-leak axis and per-guard
+// grants would re-introduce exactly the bypass holes the tier system
+// exists to prevent. Operators who want the pre-PR ergonomics can add the
+// per-guard strings explicitly to `roles.trusted.permissions[]` in
+// typeclaw.json — that path stays alive forever.
 export const BUILTIN_ROLES: Readonly<Record<BuiltinRoleName, BuiltinRoleSpec>> = {
   owner: {
     match: [{ kind: 'tui' }],
@@ -32,12 +47,14 @@ export const BUILTIN_ROLES: Readonly<Record<BuiltinRoleName, BuiltinRoleSpec>> =
       CORE_PERMISSIONS.channelRespond,
       CORE_PERMISSIONS.cronSchedule,
       CORE_PERMISSIONS.cronModify,
+      'security.bypass.low',
+      'security.bypass.medium',
       OWNER_SECURITY_WILDCARD,
     ],
   },
   trusted: {
     match: [],
-    permissions: [CORE_PERMISSIONS.channelRespond, CORE_PERMISSIONS.cronSchedule, 'security.bypass.secretExfilBash'],
+    permissions: [CORE_PERMISSIONS.channelRespond, CORE_PERMISSIONS.cronSchedule, 'security.bypass.low'],
   },
   member: {
     match: [],
@@ -49,11 +66,21 @@ export const BUILTIN_ROLES: Readonly<Record<BuiltinRoleName, BuiltinRoleSpec>> =
   },
 }
 
+// Expands the owner wildcard sentinel against plugin-contributed
+// `security.bypass.*` strings. `wildcardExclusions` is an optional set of
+// permission strings the sentinel must NOT expand to — used by the
+// bundled security plugin to exclude `security.bypass.high` AND the
+// per-guard strings for high-tier guards, so the wildcard does not
+// auto-grant audience-leak bypass to owner. Explicit operator grants of
+// those strings in `roles.owner.permissions[]` still take effect (they
+// flow through the non-sentinel branch).
 export function expandOwnerWildcard(
   ownerPermissions: readonly string[],
   pluginContributed: readonly string[],
+  wildcardExclusions: readonly string[] = [],
 ): readonly string[] {
-  const bypass = pluginContributed.filter((p) => p.startsWith('security.bypass.'))
+  const excludeSet = new Set(wildcardExclusions)
+  const bypass = pluginContributed.filter((p) => p.startsWith('security.bypass.') && !excludeSet.has(p))
   const out: string[] = []
   for (const p of ownerPermissions) {
     if (p === OWNER_SECURITY_WILDCARD) {

package/src/permissions/match-rule.ts

@@ -16,7 +16,7 @@
 // error messages with typo suggestions; a single big regex would only ever
 // say "didn't match".
 
-export const PLATFORMS = ['slack', 'discord', 'telegram', 'kakao'] as const
+export const PLATFORMS = ['slack', 'discord', 'telegram', 'kakao', 'github'] as const
 export type Platform = (typeof PLATFORMS)[number]
 
 const SUBAGENT_NAME = /^[a-z][a-z0-9-]*$/
@@ -50,7 +50,7 @@ export type ParseMatchRuleResult = { ok: true; value: MatchRule } | { ok: false;
 // this to `author:` only, the JSON schema would reject typos with a generic
 // "did not match pattern" error and the user would lose the actionable hint.
 export const MATCH_RULE_REGEX_SOURCE =
-  '^(tui|cron|subagent(:[a-z][a-z0-9-]*)?|\\*|(slack|discord|telegram|kakao):[^\\s]+)(\\s+[a-zA-Z][a-zA-Z0-9_]*:[^\\s]+)*$'
+  '^(tui|cron|subagent(:[a-z][a-z0-9-]*)?|\\*|(slack|discord|telegram|kakao|github):[^\\s]+)(\\s+[a-zA-Z][a-zA-Z0-9_]*:[^\\s]+)*$'
 
 export function parseMatchRule(input: string): ParseMatchRuleResult {
   if (input !== input.trim() || input.length === 0) {
@@ -138,6 +138,8 @@ function parseChannelScope(platform: Platform, rest: string, author: string | un
     return { ok: true, value: buildChannelRule(platform, { author }) }
   }
 
+  if (platform === 'github') return parseGithubChannelScope(rest, author)
+
   // Bucket scopes: `dm/*`, `dm/<id>`, `group/*`, `open/*`. Slack's `im` is
   // renamed to `dm`; that mapping is enforced by the legacy-prefix table at
   // the top of parseMatchRule for unprefixed forms — here we just refuse the
@@ -203,6 +205,26 @@ function parseChannelScope(platform: Platform, rest: string, author: string | un
   return { ok: true, value: buildChannelRule(platform, { workspace: rest, author }) }
 }
 
+function parseGithubChannelScope(rest: string, author: string | undefined): ParseMatchRuleResult {
+  const [owner, repo, ...chatParts] = rest.split('/')
+  if (owner === undefined || owner === '' || repo === undefined || repo === '') {
+    return { ok: false, error: "github scope requires 'owner/repo' format" }
+  }
+  if (repo === '*') {
+    return {
+      ok: false,
+      error: `'github:${owner}/*' is not supported; use 'github:${owner}/repo' for a specific repo or 'github:*' for all github events`,
+    }
+  }
+  const workspace = `${owner}/${repo}`
+  if (chatParts.length === 0) return { ok: true, value: buildChannelRule('github', { workspace, author }) }
+  const chat = chatParts.join('/')
+  if (chat === '' || chat.includes('/')) {
+    return { ok: false, error: "github chat scope must be a single segment like 'issue:42'" }
+  }
+  return { ok: true, value: buildChannelRule('github', { workspace, chat, author }) }
+}
+
 function buildChannelRule(
   platform: Platform,
   parts: {

package/src/permissions/permissions.ts

@@ -38,6 +38,12 @@ type ResolvedRole = {
 export type CreatePermissionServiceOptions = {
   roles?: RolesConfig
   pluginPermissions?: readonly string[]
+  // Permission strings that the owner wildcard sentinel must NOT
+  // auto-expand to. Today populated from the bundled security plugin's
+  // high-tier list so audience-leak guards do not get auto-granted to
+  // owner. Generic by design — any future plugin could contribute
+  // exclusions through the plugin manager. See expandOwnerWildcard.
+  ownerWildcardExclusions?: readonly string[]
 }
 
 // Returns warnings for user-declared `permissions[]` strings that aren't
@@ -97,7 +103,8 @@ function levenshtein(a: string, b: string): number {
 
 export function createPermissionService(opts: CreatePermissionServiceOptions = {}): PermissionService {
   const pluginPermissions = opts.pluginPermissions ?? []
-  let resolved = buildRoleTable(opts.roles ?? {}, pluginPermissions)
+  const ownerWildcardExclusions = opts.ownerWildcardExclusions ?? []
+  let resolved = buildRoleTable(opts.roles ?? {}, pluginPermissions, ownerWildcardExclusions)
   let byName = new Map(resolved.map((r) => [r.name, r]))
 
   function resolveRole(origin: SessionOrigin | undefined): string {
@@ -139,36 +146,46 @@ export function createPermissionService(opts: CreatePermissionServiceOptions = {
       return { role: name, permissions: role?.permissions ?? [] }
     },
     replaceRoles(roles) {
-      resolved = buildRoleTable(roles ?? {}, pluginPermissions)
+      resolved = buildRoleTable(roles ?? {}, pluginPermissions, ownerWildcardExclusions)
       byName = new Map(resolved.map((r) => [r.name, r]))
     },
   }
 }
 
-function buildRoleTable(roles: RolesConfig, pluginPermissions: readonly string[]): ResolvedRole[] {
+function buildRoleTable(
+  roles: RolesConfig,
+  pluginPermissions: readonly string[],
+  ownerWildcardExclusions: readonly string[],
+): ResolvedRole[] {
   const out: ResolvedRole[] = []
   const seen = new Set<string>()
 
   for (const name of Object.keys(roles)) {
     if (seen.has(name)) continue
     seen.add(name)
-    out.push(resolveOne(name, roles[name], pluginPermissions))
+    out.push(resolveOne(name, roles[name], pluginPermissions, ownerWildcardExclusions))
   }
 
   for (const name of BUILTIN_ROLE_NAMES) {
     if (seen.has(name)) continue
-    out.push(resolveOne(name, undefined, pluginPermissions))
+    out.push(resolveOne(name, undefined, pluginPermissions, ownerWildcardExclusions))
   }
 
   return out
 }
 
-function resolveOne(name: string, user: RoleConfig | undefined, pluginPermissions: readonly string[]): ResolvedRole {
+function resolveOne(
+  name: string,
+  user: RoleConfig | undefined,
+  pluginPermissions: readonly string[],
+  ownerWildcardExclusions: readonly string[],
+): ResolvedRole {
   if (isBuiltinRoleName(name)) {
     const builtin = BUILTIN_ROLES[name]
     const match = [...builtin.match, ...(user?.match ?? [])]
     const rawPerms = user?.permissions !== undefined ? user.permissions : [...builtin.permissions]
-    const permissions = name === 'owner' ? expandOwnerWildcard(rawPerms, pluginPermissions) : rawPerms
+    const permissions =
+      name === 'owner' ? expandOwnerWildcard(rawPerms, pluginPermissions, ownerWildcardExclusions) : rawPerms
     return { name, match, permissions }
   }
   return {

package/src/permissions/resolve.ts

@@ -5,6 +5,7 @@ import type { MatchRule, Platform } from './match-rule'
 const ADAPTER_TO_PLATFORM: Record<AdapterId, Platform> = {
   'slack-bot': 'slack',
   'discord-bot': 'discord',
+  github: 'github',
   'telegram-bot': 'telegram',
   kakaotalk: 'kakao',
 }

package/src/plugin/define.ts

@@ -1,16 +1,31 @@
 import type { z } from 'zod'
 
-import type { BuiltinToolRef, DefinedPlugin, PluginContext, PluginExports, Subagent, Tool } from './types'
+import type {
+  BuiltinToolRef,
+  ContainerCommand,
+  DefinedPlugin,
+  EitherCommand,
+  HostCommand,
+  PluginCommand,
+  PluginContext,
+  PluginExports,
+  Subagent,
+  Tool,
+} from './types'
 
 type DefinePluginSpec<S extends z.ZodType<unknown> | undefined> =
   S extends z.ZodType<infer T>
     ? {
         configSchema: S
         permissions?: readonly string[]
+        ownerWildcardExclusions?: readonly string[]
+        commands?: Record<string, PluginCommand>
         plugin: (ctx: PluginContext<T>) => Promise<PluginExports>
       }
     : {
         permissions?: readonly string[]
+        ownerWildcardExclusions?: readonly string[]
+        commands?: Record<string, PluginCommand>
         plugin: (ctx: PluginContext<unknown>) => Promise<PluginExports>
       }
 
@@ -28,6 +43,34 @@ export function defineSubagent<P>(subagent: Subagent<P>): Subagent<P> {
   return subagent
 }
 
+type ContainerCommandSpec<S extends z.ZodObject<z.ZodRawShape> | undefined> =
+  S extends z.ZodObject<z.ZodRawShape>
+    ? Omit<ContainerCommand<z.infer<S>>, 'args'> & { args: S }
+    : Omit<ContainerCommand<unknown>, 'args'> & { args?: undefined }
+
+type HostCommandSpec<S extends z.ZodObject<z.ZodRawShape> | undefined> =
+  S extends z.ZodObject<z.ZodRawShape>
+    ? Omit<HostCommand<z.infer<S>>, 'args'> & { args: S }
+    : Omit<HostCommand<unknown>, 'args'> & { args?: undefined }
+
+type EitherCommandSpec<S extends z.ZodObject<z.ZodRawShape> | undefined> =
+  S extends z.ZodObject<z.ZodRawShape>
+    ? Omit<EitherCommand<z.infer<S>>, 'args'> & { args: S }
+    : Omit<EitherCommand<unknown>, 'args'> & { args?: undefined }
+
+export function defineCommand<S extends z.ZodObject<z.ZodRawShape> | undefined = undefined>(
+  cmd: ContainerCommandSpec<S>,
+): ContainerCommand<S extends z.ZodObject<z.ZodRawShape> ? z.infer<S> : unknown>
+export function defineCommand<S extends z.ZodObject<z.ZodRawShape> | undefined = undefined>(
+  cmd: HostCommandSpec<S>,
+): HostCommand<S extends z.ZodObject<z.ZodRawShape> ? z.infer<S> : unknown>
+export function defineCommand<S extends z.ZodObject<z.ZodRawShape> | undefined = undefined>(
+  cmd: EitherCommandSpec<S>,
+): EitherCommand<S extends z.ZodObject<z.ZodRawShape> ? z.infer<S> : unknown>
+export function defineCommand(cmd: PluginCommand): PluginCommand {
+  return cmd
+}
+
 export const readTool: BuiltinToolRef = { __builtinTool: 'read' }
 export const bashTool: BuiltinToolRef = { __builtinTool: 'bash' }
 export const editTool: BuiltinToolRef = { __builtinTool: 'edit' }

package/src/plugin/index.ts

@@ -1,8 +1,9 @@
 export {
   bashTool,
-  defineTool,
+  defineCommand,
   definePlugin,
   defineSubagent,
+  defineTool,
   editTool,
   findTool,
   grepTool,
@@ -13,14 +14,24 @@ export {
 
 export type {
   BuiltinToolRef,
+  CommandExecResult,
+  CommandStreams,
+  ContainerCommand,
+  ContainerCommandContext,
   ContentPart,
   DefinedPlugin,
+  EitherCommand,
+  EitherCommandContext,
   HookContext,
   HookName,
   Hooks,
+  HostCommand,
+  HostCommandContext,
   PluginCheckResult,
   PluginCheckStatus,
+  PluginCommand,
   PluginContext,
+  CronHandlerContext,
   PluginCronJob,
   PluginDoctorCheck,
   PluginDoctorContext,
@@ -28,6 +39,7 @@ export type {
   PluginExports,
   PluginFixResult,
   PluginFixSuggestion,
+  PluginHandlerCronJob,
   PluginLogger,
   PluginPromptCronJob,
   PluginSkill,
@@ -61,12 +73,15 @@ export { loadPluginEntry, derivePluginNameFromPackage } from './loader'
 export { materializeSkills, type MaterializedSkills, type SkillEntry } from './skills'
 export {
   buildPluginCronGlobalId,
+  RESERVED_COMMAND_NAMES,
+  validateCommandDeclaration,
   type PluginRegistry,
+  type RegisteredCommand,
   type RegisteredCronJob,
   type RegisteredDoctorCheck,
+  type RegisteredSkillDir,
+  type RegisteredSkillEntry,
   type RegisteredSubagent,
   type RegisteredTool,
-  type RegisteredSkillEntry,
-  type RegisteredSkillDir,
 } from './registry'
 export { createHookBus, type HookBus } from './hooks'

package/src/plugin/manager.ts

@@ -56,9 +56,11 @@ export async function loadPlugins(opts: LoadPluginsOptions): Promise<LoadPlugins
   ]
 
   const declaredPermissions = collectDeclaredPermissions(allPlugins)
+  const ownerWildcardExclusions = collectOwnerWildcardExclusions(allPlugins)
   const permissions = createPermissionService({
     ...(opts.roles !== undefined ? { roles: opts.roles } : {}),
     pluginPermissions: declaredPermissions,
+    ownerWildcardExclusions,
   })
 
   // Non-fatal: surface user-declared `permissions[]` strings that aren't in
@@ -117,6 +119,7 @@ export async function loadPlugins(opts: LoadPluginsOptions): Promise<LoadPlugins
         pluginName: resolved.name,
         logger,
         exports,
+        ...(resolved.defined.commands !== undefined ? { commands: resolved.defined.commands } : {}),
         registry,
         hooks,
         agentDir: opts.agentDir,
@@ -157,6 +160,18 @@ function collectDeclaredPermissions(
   return out
 }
 
+function collectOwnerWildcardExclusions(
+  plugins: readonly { entry: string; resolved: ResolvedPlugin }[],
+): readonly string[] {
+  const out: string[] = []
+  for (const { resolved } of plugins) {
+    for (const perm of resolved.defined.ownerWildcardExclusions ?? []) {
+      if (!out.includes(perm)) out.push(perm)
+    }
+  }
+  return out
+}
+
 export function summarizeLoaded(loaded: LoadPluginsResult['loadedPlugins'], registry: PluginRegistry): string {
   const head = loaded.map((p) => (p.version !== undefined ? `${p.name} v${p.version}` : p.name)).join(', ')
   const counts = [
@@ -166,6 +181,7 @@ export function summarizeLoaded(loaded: LoadPluginsResult['loadedPlugins'], regi
     `${registry.skills.length} skill(s)`,
     `${registry.skillsDirs.length} skills dir(s)`,
     `${registry.doctorChecks.length} doctor check(s)`,
+    `${registry.commands.length} command(s)`,
   ].join(', ')
   return `${loaded.length} plugin(s): ${head} [${counts}]`
 }

package/src/plugin/registry.ts

@@ -1,9 +1,11 @@
 import { existsSync } from 'node:fs'
 
+import { BUILTIN_COMMAND_NAMES } from '@/cli/builtins'
 import type { CronJob, PromptJob } from '@/cron'
 
 import type { HookBus } from './hooks'
 import type {
+  PluginCommand,
   PluginCronJob,
   PluginDoctorCheck,
   PluginExports,
@@ -12,6 +14,7 @@ import type {
   Subagent,
   Tool,
 } from './types'
+import { isPrimitiveZodObject } from './zod-introspect'
 
 export type RegisteredTool = { pluginName: string; toolName: string; tool: Tool<any>; logger: PluginLogger }
 export type RegisteredSubagent = { pluginName: string; subagentName: string; subagent: Subagent<any> }
@@ -25,6 +28,12 @@ export type RegisteredDoctorCheck = {
   logger: PluginLogger
   check: PluginDoctorCheck
 }
+export type RegisteredCommand = {
+  pluginName: string
+  commandName: string
+  command: PluginCommand
+  logger: PluginLogger
+}
 
 export type PluginRegistry = {
   tools: RegisteredTool[]
@@ -33,18 +42,28 @@ export type PluginRegistry = {
   skills: RegisteredSkillEntry[]
   skillsDirs: RegisteredSkillDir[]
   doctorChecks: RegisteredDoctorCheck[]
+  commands: RegisteredCommand[]
 }
 
 export type RegisterContributionsOptions = {
   pluginName: string
   logger: PluginLogger
   exports: PluginExports
+  // Static commands declared on `DefinedPlugin.commands`. Passed alongside
+  // `exports` because they live outside the factory's return value.
+  commands?: Record<string, PluginCommand>
   registry: PluginRegistry
   hooks: HookBus
   agentDir: string
   pluginConfig: unknown
 }
 
+const COMMAND_NAME_REGEX = /^[a-z][a-z0-9-]*$/
+
+// CLI subcommands plugins MUST NOT shadow. Derived from BUILTIN_COMMAND_NAMES
+// so cli/index.ts and registry.ts cannot drift apart.
+export const RESERVED_COMMAND_NAMES: ReadonlySet<string> = new Set(BUILTIN_COMMAND_NAMES)
+
 export function buildPluginCronGlobalId(pluginName: string, localId: string): string {
   return `__plugin_${pluginName}_${localId}`
 }
@@ -127,6 +146,19 @@ export function registerContributions(opts: RegisterContributionsOptions): void
       registry.doctorChecks.push({ pluginName, checkName, pluginConfig, logger, check })
     }
   }
+
+  if (opts.commands) {
+    for (const [commandName, command] of Object.entries(opts.commands)) {
+      validateCommandDeclaration(pluginName, commandName, command)
+      const conflict = registry.commands.find((c) => c.commandName === commandName)
+      if (conflict) {
+        throw new Error(
+          `plugin ${pluginName}: command "${commandName}" already registered by plugin ${conflict.pluginName}`,
+        )
+      }
+      registry.commands.push({ pluginName, commandName, command, logger })
+    }
+  }
 }
 
 export function discardRegistrationsBy(pluginName: string, registry: PluginRegistry, hooks: HookBus): void {
@@ -136,11 +168,20 @@ export function discardRegistrationsBy(pluginName: string, registry: PluginRegis
   registry.skills = registry.skills.filter((s) => s.pluginName !== pluginName)
   registry.skillsDirs = registry.skillsDirs.filter((d) => d.pluginName !== pluginName)
   registry.doctorChecks = registry.doctorChecks.filter((d) => d.pluginName !== pluginName)
+  registry.commands = registry.commands.filter((c) => c.pluginName !== pluginName)
   hooks.unregisterAll(pluginName)
 }
 
 export function emptyRegistry(): PluginRegistry {
-  return { tools: [], subagents: [], cronJobs: [], skills: [], skillsDirs: [], doctorChecks: [] }
+  return {
+    tools: [],
+    subagents: [],
+    cronJobs: [],
+    skills: [],
+    skillsDirs: [],
+    doctorChecks: [],
+    commands: [],
+  }
 }
 
 function assertNotEmpty(kind: string, value: string, pluginName: string): void {
@@ -149,6 +190,36 @@ function assertNotEmpty(kind: string, value: string, pluginName: string): void {
   }
 }
 
+function assertValidCommandArgsSchema(pluginName: string, commandName: string, command: PluginCommand): void {
+  if (command.args === undefined) return
+  if (!isPrimitiveZodObject(command.args)) {
+    throw new Error(
+      `plugin ${pluginName}: command "${commandName}" args must be a z.object({...}) with primitive (string/number/boolean) leaves`,
+    )
+  }
+}
+
+// Reuses the same checks `registerContributions` runs at boot, so host-stage
+// discovery and runtime registration agree on what is a valid command. Throws
+// a precise error referencing the plugin and command; callers translate the
+// error into a discovery `loadError` rather than failing the whole CLI.
+export function validateCommandDeclaration(pluginName: string, commandName: string, command: PluginCommand): void {
+  if (commandName.length === 0) {
+    throw new Error(`plugin ${pluginName}: empty command name`)
+  }
+  if (!COMMAND_NAME_REGEX.test(commandName)) {
+    throw new Error(
+      `plugin ${pluginName}: command "${commandName}" does not match ${COMMAND_NAME_REGEX.source} (lowercase letters, digits, dashes; must start with a letter)`,
+    )
+  }
+  if (RESERVED_COMMAND_NAMES.has(commandName)) {
+    throw new Error(
+      `plugin ${pluginName}: command "${commandName}" shadows a built-in typeclaw subcommand and cannot be registered`,
+    )
+  }
+  assertValidCommandArgsSchema(pluginName, commandName, command)
+}
+
 function toCronJob(globalId: string, spec: PluginCronJob): CronJob {
   // Plugin-contributed jobs default to `owner` because they are part of the
   // agent's bundled (or operator-installed) runtime, not user-channel
@@ -171,12 +242,23 @@ function toCronJob(globalId: string, spec: PluginCronJob): CronJob {
     }
     return job
   }
+  if (spec.kind === 'exec') {
+    return {
+      id: globalId,
+      schedule: spec.schedule,
+      enabled: spec.enabled ?? true,
+      kind: 'exec',
+      command: spec.command,
+      scheduledByRole,
+      ...(spec.timezone !== undefined ? { timezone: spec.timezone } : {}),
+    }
+  }
   return {
     id: globalId,
     schedule: spec.schedule,
     enabled: spec.enabled ?? true,
-    kind: 'exec',
-    command: spec.command,
+    kind: 'handler',
+    handler: spec.handler,
     scheduledByRole,
     ...(spec.timezone !== undefined ? { timezone: spec.timezone } : {}),
   }