typeclaw 0.39.3 → 0.39.5

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 (55) hide show
  1. package/package.json +1 -1
  2. package/src/agent/attention-escalation.ts +11 -1
  3. package/src/agent/index.ts +10 -14
  4. package/src/agent/model-fallback.ts +13 -4
  5. package/src/agent/provider-error.ts +36 -1
  6. package/src/agent/subagents.ts +34 -3
  7. package/src/agent/throttle-circuit.ts +50 -0
  8. package/src/agent/tools/channel-reply.ts +48 -3
  9. package/src/agent/tools/ddg.ts +40 -5
  10. package/src/agent/tools/keyed-semaphore.ts +114 -0
  11. package/src/agent/tools/search-retry.ts +82 -0
  12. package/src/agent/turn-runner.ts +162 -0
  13. package/src/bundled-plugins/explorer/explorer.ts +5 -0
  14. package/src/bundled-plugins/memory/README.md +14 -14
  15. package/src/bundled-plugins/memory/append-tool.ts +98 -8
  16. package/src/bundled-plugins/memory/dreaming.ts +1 -1
  17. package/src/bundled-plugins/memory/fragment-parser.ts +10 -3
  18. package/src/bundled-plugins/memory/load-memory.ts +28 -2
  19. package/src/bundled-plugins/memory/memory-logger.ts +21 -5
  20. package/src/bundled-plugins/memory/search-tool.ts +50 -7
  21. package/src/bundled-plugins/memory/stream-events.ts +23 -0
  22. package/src/bundled-plugins/memory/vector/hybrid.ts +9 -2
  23. package/src/bundled-plugins/reviewer/reviewer.ts +3 -1
  24. package/src/bundled-plugins/scout/scout.ts +5 -0
  25. package/src/bundled-plugins/security/index.ts +24 -1
  26. package/src/bundled-plugins/security/policies/cron-promotion.ts +94 -62
  27. package/src/bundled-plugins/security/policies/plugin-addition.ts +2 -4
  28. package/src/bundled-plugins/security/policies/role-promotion.ts +2 -4
  29. package/src/channels/adapters/github/permission-guidance.ts +18 -0
  30. package/src/channels/adapters/webex-bot.ts +26 -25
  31. package/src/channels/adapters/webex-prefetch-limiter.ts +120 -0
  32. package/src/channels/adapters/webex.ts +27 -30
  33. package/src/channels/manager.ts +64 -57
  34. package/src/channels/router.ts +134 -4
  35. package/src/channels/types.ts +8 -1
  36. package/src/cli/builtins.ts +6 -32
  37. package/src/cli/channel.ts +7 -11
  38. package/src/cli/command-meta.ts +93 -0
  39. package/src/cli/help.ts +24 -0
  40. package/src/cli/index.ts +34 -10
  41. package/src/cli/init.ts +2 -2
  42. package/src/cli/plugin-commands-dispatch.ts +7 -1
  43. package/src/config/config.ts +27 -1
  44. package/src/container/start.ts +22 -2
  45. package/src/hostd/daemon.ts +55 -26
  46. package/src/hostd/spawn.ts +53 -19
  47. package/src/permissions/permissions.ts +12 -0
  48. package/src/run/codex-fetch-observer.ts +11 -6
  49. package/src/secrets/oauth-xai.ts +2 -2
  50. package/src/server/index.ts +27 -2
  51. package/src/skills/typeclaw-channel-github/SKILL.md +59 -13
  52. package/src/skills/typeclaw-channels/SKILL.md +1 -1
  53. package/src/skills/typeclaw-config/SKILL.md +1 -0
  54. package/src/skills/typeclaw-cron/SKILL.md +9 -4
  55. package/src/skills/typeclaw-permissions/SKILL.md +18 -6
@@ -7,6 +7,7 @@ import { formatLocalDate } from '@/shared'
7
7
  import { advanceWatermarkTool, createAppendTool, type FragmentsAppendedHook } from './append-tool'
8
8
  import { findEntryTool } from './find-entry-tool'
9
9
  import { streamFilePath, streamsDir } from './paths'
10
+ import { listReferenceSlugs } from './references/load-references'
10
11
  import { createStoreReferenceTool, type ReferenceStoredHook } from './references/store-reference-tool'
11
12
  import { readEvents } from './stream-io'
12
13
  import { readLatestWatermark } from './watermark'
@@ -146,9 +147,11 @@ Skip these anti-patterns:
146
147
 
147
148
  # Verbatim references (store_reference tool)
148
149
 
149
- When the user explicitly asks to remember a verbatim artifact — SQL, code, a runbook, pasted spec — call \`store_reference({ title, body, origin: 'episode', tags: [] })\` with the byte-for-byte body. Do not distill or summarize it. The tool returns a slug; include it in \`append\` as \`references: ['<slug>']\` when writing the session fragment.
150
+ Store a verbatim artifact whenever its memory value depends on the EXACT text — SQL, code blocks, runbooks, pasted specs, config snippets, API payloads, review comments, or command output the user will want reproduced byte-for-byte later. This is not limited to "please remember this": if you are about to write a fragment that summarizes such an artifact, store the artifact too so the exact text survives. Call \`store_reference({ title, body, origin: 'episode', tags: [] })\` with the byte-for-byte body. Do not distill or summarize the body.
150
151
 
151
- If the reference is the only durable content, still write a fragment (topic "verbatim reference stored") naming what was stored and citing the reference, so the reference is linked into the stream.
152
+ \`store_reference\` returns a slug (the file it wrote under \`memory/references/\`). The ONLY valid contents of \`append\`'s \`references\` field are slugs you received back from \`store_reference\` in THIS run. Never put a topic id, PR name/number, stream path, URL, or any invented label in \`references\` — those are not references and will be silently dropped. If you did not call \`store_reference\`, omit \`references\` entirely. To cross-link a related topic, name it in the body prose instead.
153
+
154
+ If a stored reference is the only durable content, still write a fragment (topic "verbatim reference stored") naming what was stored and citing the returned slug, so the reference is linked into the stream.
152
155
 
153
156
  References are for artifacts whose exact text matters. A distilled memory fragment should name what the artifact is, who/what it applies to, and why it was retained, while the reference body holds the verbatim material. Do not paste large reference bodies into fragment text.
154
157
 
@@ -165,7 +168,7 @@ When a transcript exposes a credential, capture the fact and discovery method, n
165
168
  - Allowed: "The env var \`GH_TOKEN\` is set in this environment and holds a GitHub PAT (discovered via \`env | grep token\`). Use it for private-repo API calls."
166
169
  - Forbidden: "GH_TOKEN=<the literal token characters, in whole or in part>". Even a partial value narrows the search space for an attacker.
167
170
 
168
- The \`append\` tool will refuse content containing a recognizable credential pattern. Treat that as a bug in your fragment: rewrite to name the variable and discovery, then retry.
171
+ The \`append\` tool will refuse content containing a recognizable credential pattern — in \`topic\`, \`body\`, or \`who\`. Treat that as a bug in your fragment: rewrite to name the variable and discovery (or drop a credential-shaped \`who\`), then retry.
169
172
 
170
173
  # Local dedup against today's daily stream
171
174
 
@@ -179,7 +182,12 @@ Recurrence is not duplication. A durable preference, pattern, workaround, or com
179
182
 
180
183
  # Fragment format
181
184
 
182
- Call \`append\` with \`{topic, body, source, entry, latestEntryId}\` or \`{topic, body, source, entry, latestEntryId, references}\`. The runtime serializes your call into the daily stream; you never write raw JSON. \`source\` is the parent session id. \`topic\` is a short noun phrase. \`entry\` is the specific transcript-entry-id that anchors this fragment's evidence. Each fragment carries its own entry id; do not stamp every fragment with the same latest evaluated id. \`latestEntryId\` is the latest entry evaluated in this run and advances the watermark. \`references\` is optional slugs from \`store_reference\`.
185
+ Call \`append\` with \`{topic, body, source, entry, latestEntryId}\` or \`{topic, body, source, entry, latestEntryId, references}\`. The runtime serializes your call into the daily stream; you never write raw JSON. \`source\` is the parent session id. \`topic\` is a short noun phrase. \`entry\` is the specific transcript-entry-id that anchors this fragment's evidence. Each fragment carries its own entry id; do not stamp every fragment with the same latest evaluated id. \`latestEntryId\` is the latest entry evaluated in this run and advances the watermark. \`references\` is optional and may ONLY contain slugs that \`store_reference\` returned to you in this run; anything else (topic ids, PR names, stream paths, invented labels) is dropped — omit the field if you stored nothing.
186
+
187
+ **Situational provenance (\`who\` / \`where\`).** Memory is sharper when it remembers who said something and where. Two fields capture this:
188
+
189
+ - **\`where\` is automatic.** The channel, room, and platform of this session are stamped onto every fragment by the runtime from the session origin. Do NOT pass \`where\` and do NOT restate the channel/workspace/thread in the body just to record provenance — it is already attached. Still name a channel in the body when its *purpose* is the durable fact (e.g. "#incidents is the production-outage channel"); that is content, not provenance plumbing.
190
+ - **\`who\` is your judgment, per fragment.** Set the optional \`who\` to the display name or handle of the person whose words or action the fragment's evidence is attributable to — the speaker on the transcript line you anchored to. The Conversation context lists participant names and ids; use them to attribute correctly. Set \`who\` ONLY when one speaker clearly owns the evidence. OMIT it when: the fact is the user's own instruction (the user is implicit), the evidence spans multiple speakers, or you cannot attribute it to one person with confidence. A single run covers many speakers and turns, so never copy one name onto every fragment — attribute each fragment to its own anchored speaker, or leave \`who\` unset. Do not guess.
183
191
 
184
192
  Every body must be:
185
193
 
@@ -286,7 +294,14 @@ export function createMemoryLoggerSubagent(
286
294
  options: CreateMemoryLoggerSubagentOptions = {},
287
295
  ): Subagent<MemoryLoggerPayload> {
288
296
  const logger = options.logger ?? consoleLogger
289
- const appendTool = createAppendTool(options.onFragmentsAppended)
297
+ // The handler runs one logger spawn at a time per agentDir (inFlightKey), so a
298
+ // single mutable cell safely carries this spawn's origin to the append tool.
299
+ let currentOrigin: SessionOrigin | undefined
300
+ const appendTool = createAppendTool({
301
+ onFragmentsAppended: options.onFragmentsAppended,
302
+ originProvider: () => currentOrigin,
303
+ referenceSlugResolver: (agentDir) => listReferenceSlugs(agentDir),
304
+ })
290
305
  const storeReferenceTool = createStoreReferenceTool(options.onReferenceStored)
291
306
  const customTools = [findEntryTool, appendTool, storeReferenceTool, advanceWatermarkTool]
292
307
  return {
@@ -317,6 +332,7 @@ export function createMemoryLoggerSubagent(
317
332
  exhaustedMessage: memoryLoggerExhaustedMessage,
318
333
  },
319
334
  handler: async (ctx, runSession) => {
335
+ currentOrigin = ctx.payload.origin
320
336
  const today = formatLocalDate()
321
337
  const memoryDir = streamsDir(ctx.payload.agentDir)
322
338
  const streamFile = streamFilePath(ctx.payload.agentDir, today)
@@ -7,7 +7,7 @@ import { defineTool } from '@/plugin'
7
7
  import { loadAllShards, loadShard, type TopicShard } from './load-shards'
8
8
  import { renderReference } from './references/frontmatter'
9
9
  import { loadAllReferences, loadReference, type Reference } from './references/load-references'
10
- import type { FragmentEvent, LegacyProseEvent, StreamEvent } from './stream-events'
10
+ import type { FragmentEvent, FragmentProvenance, LegacyProseEvent, StreamEvent } from './stream-events'
11
11
  import { readAllUndreamedStreamDays, type UndreamedStreamDay } from './stream-io'
12
12
 
13
13
  const DEFAULT_MAX_RESULTS = 10
@@ -31,6 +31,9 @@ export type StreamMatch = {
31
31
  topic: string
32
32
  excerpt: string
33
33
  fullBody?: string
34
+ who?: string
35
+ when?: string
36
+ where?: FragmentProvenance
34
37
  }
35
38
 
36
39
  export type ReferenceMatch = {
@@ -51,7 +54,7 @@ export type Matcher = (haystack: string) => boolean
51
54
  export function createMemorySearchTool() {
52
55
  return defineTool({
53
56
  description:
54
- 'Search the agent\'s long-term memory, or look up one topic shard by exact slug. Covers topic shards under memory/topics/ (consolidated facts), references under memory/references/ (verbatim artifacts), and undreamed daily-stream events under memory/streams/ (recent fragments not yet folded into shards). Pass `query` for search OR `topic` for an exact slug lookup, not both. Search is case-insensitive substring by default: tries the whole query as one phrase first, and if that finds nothing, falls back to OR-matching the individual words (ranked by how many words each hit contains) — so a multi-word query still returns results even when no entry contains the exact phrase. asRegex=true treats query as a JavaScript regex (no word fallback). `topic` skips search entirely and returns that one shard (or reference) with its full body — use it to read a topic OR reference whose slug you already have (e.g. a heading shown in injected memory); it resolves the topic shard first and falls back to a reference of the same slug. Returns matches discriminated by `source: "topic" | "reference" | "stream"`, each with line-context excerpts; full=true includes complete bodies (topic lookups always include the full body). Ordering depends on mode: exact-phrase (and regex) results list all topic matches first (alphabetical by slug), then reference matches, then stream matches (newest day first); word-fallback results are ranked by matched-word count, with that same topic-then-reference-then-stream-newest order as the tiebreak within each score band, so a higher-scoring stream match can precede a lower-scoring topic match.',
57
+ 'Search the agent\'s long-term memory, or look up one topic shard by exact slug. Covers topic shards under memory/topics/ (consolidated facts), references under memory/references/ (verbatim artifacts), and undreamed daily-stream events under memory/streams/ (recent fragments not yet folded into shards). Pass `query` for search OR `topic` for an exact slug lookup, not both. Search is case-insensitive substring by default: tries the whole query as one phrase first, and if that finds nothing, falls back to OR-matching the individual words (ranked by how many words each hit contains) — so a multi-word query still returns results even when no entry contains the exact phrase. asRegex=true treats query as a JavaScript regex (no word fallback). `topic` skips search entirely and returns that one shard (or reference) with its full body — use it to read a topic OR reference whose slug you already have (e.g. a heading shown in injected memory); it resolves the topic shard first and falls back to a reference of the same slug. Returns matches discriminated by `source: "topic" | "reference" | "stream"`, each with line-context excerpts; full=true includes complete bodies (topic lookups always include the full body). Ordering depends on mode: exact-phrase (and regex) results list all topic matches first (alphabetical by slug), then reference matches, then stream matches (newest day first); word-fallback results are ranked by matched-word count, with that same topic-then-reference-then-stream-newest order as the tiebreak within each score band, so a higher-scoring stream match can precede a lower-scoring topic match. Pass `where` (a channel/room name like "#incidents" or its raw chat id) to scope the search to one room — use it for questions like "what did we discuss in #incidents"; it matches a stream fragment by its captured room id or human-readable name (case-insensitive, leading "#" optional) and, because room is fragment-only provenance, returns ONLY stream matches (topic shards and references carry no room).',
55
58
  parameters: z.object({
56
59
  query: z.string().optional(),
57
60
  topic: z.string().optional(),
@@ -60,8 +63,9 @@ export function createMemorySearchTool() {
60
63
  maxResults: z.number().int().min(0).default(DEFAULT_MAX_RESULTS),
61
64
  since: z.string().optional(),
62
65
  before: z.string().optional(),
66
+ where: z.string().optional(),
63
67
  }),
64
- async execute({ query, topic, asRegex, full, maxResults, since, before }, ctx) {
68
+ async execute({ query, topic, asRegex, full, maxResults, since, before, where }, ctx) {
65
69
  if ((query === undefined) === (topic === undefined)) {
66
70
  return resultToToolResult({ error: 'provide exactly one of `query` or `topic`' })
67
71
  }
@@ -83,14 +87,24 @@ export function createMemorySearchTool() {
83
87
  const dateFilter = parseReferenceDateFilter(since, before)
84
88
  if ('error' in dateFilter) return resultToToolResult(dateFilter)
85
89
 
86
- const references = allReferences.filter((reference) => referenceCandidateAllowed(reference, dateFilter))
87
- if (shards.length === 0 && streamDays.length === 0 && references.length === 0) {
90
+ // A `where` filter scopes the search to ONE room. `where` is fragment-only
91
+ // provenance, so a room query excludes topic shards and references (they
92
+ // carry no room) and keeps only stream fragments whose `where` matches.
93
+ const roomFilteredDays = where === undefined ? streamDays : filterStreamDaysByRoom(streamDays, where)
94
+ const scopedShards = where === undefined ? shards : []
95
+ const references =
96
+ where === undefined ? allReferences.filter((r) => referenceCandidateAllowed(r, dateFilter)) : []
97
+
98
+ if (scopedShards.length === 0 && roomFilteredDays.length === 0 && references.length === 0) {
88
99
  return resultToToolResult({ matches: [], truncatedAt: 0 })
89
100
  }
90
101
 
91
- let result = searchAll(shards, streamDays, matcherOrError, { full, maxResults, references })
102
+ let result = searchAll(scopedShards, roomFilteredDays, matcherOrError, { full, maxResults, references })
92
103
  if ('matches' in result && result.matches.length === 0) {
93
- const fallback = tokenFallback(query!, asRegex, shards, streamDays, references, { full, maxResults })
104
+ const fallback = tokenFallback(query!, asRegex, scopedShards, roomFilteredDays, references, {
105
+ full,
106
+ maxResults,
107
+ })
94
108
  if (fallback !== null) result = fallback
95
109
  }
96
110
  if ('matches' in result) await bumpReturnedReferences(allReferences, result.matches)
@@ -449,7 +463,10 @@ function matchFragmentEvent(
449
463
  eventId: `streams/${day.date}#${event.id}`,
450
464
  topic: event.topic,
451
465
  excerpt: firstBodyLineIndex === -1 ? event.topic : excerptForLine(bodyLines, firstBodyLineIndex),
466
+ when: event.ts,
452
467
  }
468
+ if (event.who !== undefined) match.who = event.who
469
+ if (event.where !== undefined) match.where = event.where
453
470
  if (full) match.fullBody = event.body
454
471
  return match
455
472
  }
@@ -513,6 +530,32 @@ function parseDateParam(name: string, value: string): Date | string {
513
530
  return date
514
531
  }
515
532
 
533
+ // Keep only fragments whose `where` names this room, by raw `chat` id (canonical)
534
+ // or `chatName` (convenience, case-insensitive — the agent often knows only
535
+ // "#incidents"). The `#` prefix is stripped so "#incidents" and "incidents"
536
+ // both match. Non-fragment events (watermarks, legacy prose) have no `where` and
537
+ // are dropped under a room filter; days that end up empty are removed.
538
+ function filterStreamDaysByRoom(days: UndreamedStreamDay[], room: string): UndreamedStreamDay[] {
539
+ const normalizedKey = normalizeRoomKey(room)
540
+ return days.flatMap((day) => {
541
+ const events = day.events.filter(
542
+ (event) => event.type === 'fragment' && fragmentMatchesRoom(event, room, normalizedKey),
543
+ )
544
+ return events.length === 0 ? [] : [{ ...day, events }]
545
+ })
546
+ }
547
+
548
+ function fragmentMatchesRoom(event: FragmentEvent, rawRoom: string, normalizedKey: string): boolean {
549
+ const where = event.where
550
+ if (where === undefined) return false
551
+ if (where.chat === rawRoom) return true
552
+ return where.chatName !== undefined && normalizeRoomKey(where.chatName) === normalizedKey
553
+ }
554
+
555
+ function normalizeRoomKey(value: string): string {
556
+ return value.replace(/^#/, '').toLocaleLowerCase()
557
+ }
558
+
516
559
  function referenceCandidateAllowed(reference: Reference, filter: ReferenceDateFilter): boolean {
517
560
  if (reference.frontmatter.demoted) return false
518
561
  const created = new Date(reference.frontmatter.created)
@@ -30,6 +30,21 @@ export function timestampFromId(id: string): string {
30
30
  return new Date(ms).toISOString()
31
31
  }
32
32
 
33
+ // Runtime-stamped (not LLM-supplied): the channel/room/platform is stable for a
34
+ // whole logger run, so unlike `who` it cannot be misattributed across speakers.
35
+ // All-optional so legacy fragments and non-channel (TUI) origins parse with it
36
+ // absent; names are best-effort (resolver may not have run). Never embedded.
37
+ export const fragmentProvenanceSchema = z
38
+ .object({
39
+ adapter: z.string(),
40
+ workspace: z.string(),
41
+ workspaceName: z.string().optional(),
42
+ chat: z.string(),
43
+ chatName: z.string().optional(),
44
+ thread: z.string().nullable().optional(),
45
+ })
46
+ .passthrough()
47
+
33
48
  export const fragmentEventSchema = z
34
49
  .object({
35
50
  type: z.literal('fragment'),
@@ -40,6 +55,13 @@ export const fragmentEventSchema = z
40
55
  topic: z.string(),
41
56
  body: z.string(),
42
57
  references: z.array(z.string()).optional(),
58
+ // WHO the evidence is attributable to (display name/handle of the speaker).
59
+ // LLM-supplied by the memory-logger, set ONLY when one transcript speaker
60
+ // line clearly owns the evidence — a single logger run spans many speakers,
61
+ // so this is per-fragment, never stamped from the spawn-time origin.
62
+ who: z.string().min(1).optional(),
63
+ // WHERE the evidence happened. Runtime-stamped from the session origin.
64
+ where: fragmentProvenanceSchema.optional(),
43
65
  })
44
66
  .passthrough()
45
67
 
@@ -68,6 +90,7 @@ export const streamEventSchema = z.discriminatedUnion('type', [
68
90
  legacyProseEventSchema,
69
91
  ])
70
92
 
93
+ export type FragmentProvenance = z.infer<typeof fragmentProvenanceSchema>
71
94
  export type FragmentEvent = z.infer<typeof fragmentEventSchema>
72
95
  export type WatermarkEvent = z.infer<typeof watermarkEventSchema>
73
96
  export type LegacyProseEvent = z.infer<typeof legacyProseEventSchema>
@@ -12,7 +12,7 @@ import {
12
12
  type MemorySearchMatch,
13
13
  type StreamMatch,
14
14
  } from '../search-tool'
15
- import type { StreamEvent } from '../stream-events'
15
+ import type { FragmentProvenance, StreamEvent } from '../stream-events'
16
16
  import { readAllUndreamedStreamDays, type UndreamedStreamDay } from '../stream-io'
17
17
  import { embed, EMBEDDING_MODEL_ID, type EmbedType } from './embedder'
18
18
  import type { Passage } from './passages'
@@ -29,6 +29,9 @@ export type HybridSearchResult = {
29
29
  heading: string
30
30
  excerpt: string
31
31
  rrfScore: number
32
+ who?: string
33
+ when?: string
34
+ where?: FragmentProvenance
32
35
  }
33
36
 
34
37
  export type EmbedFn = (texts: string[], type: EmbedType) => Promise<Float32Array[]>
@@ -398,12 +401,16 @@ function streamIndexItem(
398
401
  if (event.type === 'watermark') return null
399
402
  if (event.type === 'fragment') {
400
403
  if (supersededFragmentIds.has(event.id)) return null
401
- return {
404
+ const item: Omit<HybridSearchResult, 'rrfScore'> = {
402
405
  source: 'stream',
403
406
  key: `${day.date}#${event.id}`,
404
407
  heading: event.topic,
405
408
  excerpt: excerpt(event.body, event.topic),
409
+ when: event.ts,
406
410
  }
411
+ if (event.who !== undefined) item.who = event.who
412
+ if (event.where !== undefined) item.where = event.where
413
+ return item
407
414
  }
408
415
  return {
409
416
  source: 'stream',
@@ -79,7 +79,9 @@ Your role is EXCLUSIVELY to analyze and report. The parent agent decides what to
79
79
 
80
80
  You run on a deliberately expensive model. Reading a sprawling file tree, a giant diff, or a pile of vendor docs into YOUR context burns that budget on grunt work. When a slice of the job is bulky-but-mechanical — "summarize what these 40 files do", "extract the public API of this module", "gather the relevant passages from this 2,000-line diff" — hand it to a cheaper worker with \`spawn_subagent\` and review the distilled result instead of the raw bulk.
81
81
 
82
- - Spawn read-only/research workers for context-heavy gathering, not for forming the verdict. The findings and the \`<review>\` block are YOURS — never delegate the judgment.
82
+ This is not a last resort — it is your DEFAULT for any non-trivial target, and it makes the review FASTER, not just leaner. Reach for \`scout\` and \`explorer\` first: \`explorer\` maps unfamiliar code and finds where things live, \`scout\` gathers focused facts from a known area. Decompose the target into independent gathering tasks and fan them out IN PARALLEL — emit several \`spawn_subagent\` calls in a SINGLE turn (they run concurrently and return together) rather than reading each slice yourself, one after another, into your own context. A wall-clock-faster review on a fresh, uncluttered context is the win; serial self-reading is the slow path you are explicitly steered away from.
83
+
84
+ - Spawn read-only/research workers (\`scout\`, \`explorer\`) for context-heavy gathering, not for forming the verdict. The findings and the \`<review>\` block are YOURS — never delegate the judgment.
83
85
  - Each delegated task must be self-contained: the worker does not see this conversation or the target. Put everything it needs in the prompt.
84
86
  - The chain is depth-limited: a worker you spawn cannot spawn again. Keep delegation one level deep.
85
87
  - \`subagent_output\`/\`subagent_cancel\` reach only the tasks YOU spawned. To gather in parallel, either emit all the independent \`spawn_subagent\` calls (sync, the default) in a SINGLE turn so they run concurrently and return together, or spawn them with \`run_in_background=true\` and fold each result in as its \`<system-reminder>\` arrives (your session stays alive until every child reports back). Either way, fold the results into your single review pass before you finish.
@@ -68,6 +68,10 @@ End every response with this exact structure:
68
68
  - If the question requires LOCAL information (codebase, files in /agent/, git history, memory), say so explicitly and tell the caller to spawn \`explorer\` instead.
69
69
  - If you cannot find what was asked, say so explicitly with what queries you tried and what you DID find.`
70
70
 
71
+ // `profile` is dropped, not passed through: scout is a fast-tier specialist, so a
72
+ // parent must not bump it off `fast` via a per-spawn `profile` override (which the
73
+ // `spawn_subagent` tool injects into the payload and `profileFromPayload` would
74
+ // otherwise honor). Other fields still pass through untouched.
71
75
  export const scoutPayloadSchema = z
72
76
  .object({
73
77
  requestId: z.string().optional(),
@@ -75,6 +79,7 @@ export const scoutPayloadSchema = z
75
79
  description: z.string().optional(),
76
80
  })
77
81
  .passthrough()
82
+ .transform(({ profile: _profile, ...rest }) => rest)
78
83
 
79
84
  export type ScoutPayload = z.infer<typeof scoutPayloadSchema>
80
85
 
@@ -106,6 +106,24 @@ export default definePlugin({
106
106
  const canBypass = (severity: SecuritySeverity, perGuardPerm: string): boolean =>
107
107
  can(SEVERITY_PERMISSION[severity]) || can(perGuardPerm)
108
108
 
109
+ // The cron guard blocks deferred work that fires as a role granting
110
+ // permissions the caller lacks. Capability dominance — target's
111
+ // permission set must be a SUBSET of the caller's — not the coarse
112
+ // `compareRoleSeverity` tower: every configured custom role ranks
113
+ // equal there, so rank `>= 0` would let one custom role schedule as a
114
+ // different custom role (or `trusted` schedule as a custom role with
115
+ // an extra grant), laundering permissions the caller never had. Unknown
116
+ // caller/target role => undefined permissions => fail closed.
117
+ const callerRole = ctx.permissions.resolveRole(event.origin)
118
+ const canScheduleAs = (targetRole: string | undefined): boolean => {
119
+ if (targetRole === undefined) return false
120
+ const callerPermissions = ctx.permissions.permissionsForRole(callerRole)
121
+ const targetPermissions = ctx.permissions.permissionsForRole(targetRole)
122
+ if (callerPermissions === undefined || targetPermissions === undefined) return false
123
+ const callerSet = new Set(callerPermissions)
124
+ return targetPermissions.every((permission) => callerSet.has(permission))
125
+ }
126
+
109
127
  const rolePromotionResult = canBypass(GUARD_ROLE_PROMOTION_SEVERITY, SECURITY_PERMISSIONS.bypassRolePromotion)
110
128
  ? undefined
111
129
  : withPermissionHint(
@@ -118,7 +136,12 @@ export default definePlugin({
118
136
  const cronPromotionResult = canBypass(GUARD_CRON_PROMOTION_SEVERITY, SECURITY_PERMISSIONS.bypassCronPromotion)
119
137
  ? undefined
120
138
  : withPermissionHint(
121
- await checkCronPromotionGuard({ tool: event.tool, args: event.args, agentDir: ctx.agentDir }),
139
+ await checkCronPromotionGuard({
140
+ tool: event.tool,
141
+ args: event.args,
142
+ agentDir: ctx.agentDir,
143
+ canScheduleAs,
144
+ }),
122
145
  SECURITY_PERMISSIONS.bypassCronPromotion,
123
146
  GUARD_CRON_PROMOTION_SEVERITY,
124
147
  )
@@ -4,7 +4,16 @@ import path from 'node:path'
4
4
  import { parseCronJson, type ParsedCronJob } from '@/cron'
5
5
 
6
6
  import type { SecuritySeverity } from '../permissions'
7
- import { ACKNOWLEDGE_GUARDS, type SecurityBlock, isGuardAcknowledged } from '../policy'
7
+ import type { SecurityBlock } from '../policy'
8
+
9
+ // True iff the caller may legitimately schedule deferred work that fires as
10
+ // `targetRole` — i.e. `targetRole` grants no permission the caller's own role
11
+ // lacks (capability dominance / permission-subset). The caller supplies this;
12
+ // the production wiring in index.ts compares resolved permission sets, NOT the
13
+ // coarse severity tower (which ranks every custom role equal and would let one
14
+ // custom role launder into another). Fails closed: an unknown caller or target
15
+ // role returns false, so the change is treated as an escalation and blocked.
16
+ export type CanScheduleAs = (targetRole: string | undefined) => boolean
8
17
 
9
18
  export const GUARD_CRON_PROMOTION = 'cronPromotion'
10
19
  // Classified `medium` (silent-attack axis). Originally `high`; reclassified
@@ -18,12 +27,12 @@ export const GUARD_CRON_PROMOTION = 'cronPromotion'
18
27
  // audience-leak.
19
28
  //
20
29
  // Net effect on the role-tower model: owner and trusted both bypass
21
- // without ack; member and guest still get blocked. The defense for
22
- // trusted depends on backup-commit review discipline — same tradeoff
23
- // as `rolePromotion`. Operators who want to keep this at high for
24
- // trusted can subtract: replace `roles.trusted.permissions[]` with an
25
- // explicit list that omits `security.bypass.medium`, then add narrower
26
- // per-guard medium grants as needed.
30
+ // (they carry `security.bypass.medium`); member and guest are gated by
31
+ // the caller-role-aware predicate below. This guard does NOT honor
32
+ // `acknowledgeGuards` — an ack flag from an under-privileged session is
33
+ // ignored. Bypassing is a property of the caller's resolved role, not a
34
+ // tool-arg flag, because an args-level ack would let any member/guest
35
+ // launder itself past the guard (it inspected args, not permissions).
27
36
  //
28
37
  // Cron is the deferred-execution sibling of `roles`. Every cron job
29
38
  // carries a `scheduledByRole` field that the runtime stamps into the
@@ -32,57 +41,64 @@ export const GUARD_CRON_PROMOTION = 'cronPromotion'
32
41
  // table"). The `parseCronFile` boot gate rejects entries without
33
42
  // `scheduledByRole`, but it accepts any role name the file declares.
34
43
  //
35
- // Concrete breach pattern blocked at `medium`: a `member`-role agent
36
- // that can `write` `cron.json` authors a brand-new job with
44
+ // Concrete breach pattern blocked: a `member`-role agent that can
45
+ // `write` `cron.json` authors a brand-new job with
37
46
  // `"scheduledByRole": "owner"` and a prompt that does whatever the
38
47
  // agent's tool surface allows when running as owner. The cron consumer
39
- // fires it on schedule; the firing session resolves to `owner` because
40
- // that role name exists in the role table. The agent has laundered
41
- // itself into owner via the schedule. This guard blocks the first step
42
- // — member does not carry `bypass.medium`.
48
+ // fires it on schedule; the firing session resolves to `owner`. The
49
+ // agent has laundered itself into owner via the schedule. This guard
50
+ // blocks it because `canScheduleAs('owner')` is false for a member.
43
51
  //
44
52
  // Same two-step shape as `gitRemoteTainted`: "do a privileged write
45
53
  // now, run the privileged thing later." This guard blocks the first
46
- // step.
54
+ // step. It is the deferred-write analogue of the `spawnedByRole` cap in
55
+ // src/agent/tools/subagent-access.ts: a caller may only commit deferred
56
+ // work that fires at a role it could already act as.
47
57
  //
48
- // What counts as a cron promotion (any of):
49
- // 1. A new job (by id) was added. The job's `scheduledByRole` is the
50
- // privilege grant being introduced; the audit point is the
51
- // addition itself, regardless of the role value.
52
- // 2. An existing job's `scheduledByRole` changed to a different value.
58
+ // What counts as a cron promotion (a finding is raised only when the
59
+ // change introduces deferred authority the caller lacks — i.e. the
60
+ // relevant `scheduledByRole` is NOT schedulable by the caller, where
61
+ // `canScheduleAs(R)` means R's permission set is a SUBSET of the
62
+ // caller's (capability dominance), fail-closed on unknown roles):
63
+ // 1. A new job (by id) was added whose `scheduledByRole` the caller
64
+ // cannot schedule as. Adding a job at-or-below the caller's own
65
+ // role grants nothing new and is allowed.
66
+ // 2. An existing job's `scheduledByRole` was raised to a value the
67
+ // caller cannot schedule as. Lowering it, or a lateral move within
68
+ // the caller's reach, is allowed.
53
69
  // 3. An existing job's EXECUTABLE BODY changed — `kind`, `prompt`,
54
- // `command`, `subagent`, or `payload`. Rewriting only the body of
55
- // an existing privileged job (leaving `scheduledByRole` untouched)
56
- // is the same deferred-laundering attack as job creation: the
57
- // cron consumer fires the new body as the stamped role, and the
58
- // attacker has co-opted the role without changing it. Oracle
59
- // review (PR #305) called this out as a critical bypass of the
60
- // first design. The fields chosen are exactly those the cron
61
- // consumer uses to decide what executes when a job fires; the
62
- // consumer also reads provenance/identity fields (id,
63
- // scheduledByRole, scheduledByOrigin) but those are handled
64
- // separately or are audit metadata, not executable body.
65
- // 4. An existing job had `enabled: false` flipped to true (or
66
- // unset, which schema-defaults to true). A previously-disabled
67
- // privileged job becoming live is a privilege grant in the
68
- // same sense as adding the job fresh.
70
+ // `command`, `subagent`, or `payload` — AND the job fires above
71
+ // the caller either before or after the change. Rewriting the body
72
+ // of an already-privileged job is the same deferred-laundering
73
+ // attack as job creation (Oracle PR #305 critical finding): the
74
+ // cron consumer fires the new body as the stamped role. Requiring
75
+ // BOTH old and new roles to be within the caller's reach preserves
76
+ // that defense — a member cannot rewrite an owner-stamped body even
77
+ // though `scheduledByRole` is untouched. The fields chosen are
78
+ // exactly those the cron consumer uses to decide what executes;
79
+ // provenance/identity fields (id, scheduledByRole,
80
+ // scheduledByOrigin) are handled separately or are audit metadata.
81
+ // 4. An existing job had `enabled: false` flipped to true while it
82
+ // fires above the caller (same both-sides reach check as body
83
+ // changes). Re-enabling a job at-or-below the caller is allowed.
69
84
  //
70
- // What does NOT count (allowed without ack):
85
+ // What does NOT count (allowed):
86
+ // - Any change (add / role-change / body / re-enable) whose resulting
87
+ // job fires at or below the caller's own role: it grants the caller
88
+ // no authority it doesn't already have.
71
89
  // - Removing a job entirely.
72
90
  // - Changing `schedule` or `timezone` on an existing job (cadence
73
91
  // decisions; do not change what runs, only when).
74
- // - Setting `enabled: true -> false` (disabling a privileged job is
75
- // a privilege REDUCTION; allowed).
76
- // - Any change to a job that has no `scheduledByRole` at all (the
77
- // schema rejects such jobs at managedConfig before we run, so
78
- // this branch is unreachable in practice; the guard treats it as
79
- // a non-finding for forward compatibility).
92
+ // - Setting `enabled: true -> false` (disabling is a REDUCTION).
93
+ // - A job with no `scheduledByRole` (`undefined`) is treated as NOT
94
+ // schedulable (fail-closed), so the schema-rejected unset case stays
95
+ // blocked rather than slipping through as a non-finding.
80
96
  //
81
- // Failure-open is deliberate, same direction as `rolePromotion`: if
82
- // the existing `cron.json` cannot be read or parsed, every proposed job
83
- // is treated as new and flagged. The only false positive is "operator
84
- // authored a fresh `cron.json` with privileged jobs," which they
85
- // acknowledge in the same call.
97
+ // Failure-closed on caller role: an unknown/incomparable caller role
98
+ // makes `canScheduleAs` return false, so every change is treated as an
99
+ // escalation and blocked. Failure-open on file read is unchanged: if the
100
+ // existing `cron.json` cannot be read or parsed, every proposed job is
101
+ // treated as new and then subjected to the same caller-role check.
86
102
  export const GUARD_CRON_PROMOTION_SEVERITY: SecuritySeverity = 'medium'
87
103
 
88
104
  export type CronPromotionFinding =
@@ -95,8 +111,9 @@ export async function checkCronPromotionGuard(options: {
95
111
  tool: string
96
112
  args: Record<string, unknown>
97
113
  agentDir: string
114
+ canScheduleAs: CanScheduleAs
98
115
  }): Promise<SecurityBlock | undefined> {
99
- const { tool, args, agentDir } = options
116
+ const { tool, args, agentDir, canScheduleAs } = options
100
117
  if (tool !== 'write' && tool !== 'edit') return undefined
101
118
 
102
119
  const rawPath = args.path
@@ -106,8 +123,6 @@ export async function checkCronPromotionGuard(options: {
106
123
  const isCronJson = await pathIsCronJson(agentDir, targetPath)
107
124
  if (!isCronJson) return undefined
108
125
 
109
- if (isGuardAcknowledged(args, GUARD_CRON_PROMOTION)) return undefined
110
-
111
126
  const editRefusal = refuseRiskyEdit(tool, args, targetPath)
112
127
  if (editRefusal) return editRefusal
113
128
 
@@ -118,7 +133,7 @@ export async function checkCronPromotionGuard(options: {
118
133
  if (newJobs === undefined) return undefined
119
134
 
120
135
  const oldJobs = await readExistingJobs(targetPath)
121
- const findings = diffJobs(oldJobs, newJobs)
136
+ const findings = diffJobs(oldJobs, newJobs, canScheduleAs)
122
137
  if (findings.length === 0) return undefined
123
138
 
124
139
  return {
@@ -208,7 +223,21 @@ async function readExistingJobs(targetPath: string): Promise<readonly ParsedCron
208
223
  return result.file.jobs
209
224
  }
210
225
 
211
- export function diffJobs(before: readonly ParsedCronJob[], after: readonly ParsedCronJob[]): CronPromotionFinding[] {
226
+ // A finding is a *promotion* only when the change introduces deferred authority
227
+ // the caller could not already wield. `canScheduleAs(R)` is true when R's
228
+ // permission set is a subset of the caller's, so a change that lands (and, for
229
+ // mutations, started) at a role granting nothing the caller lacks is not
230
+ // flagged. The laundering shapes still trip every branch: a member
231
+ // adding/role-changing a job to `owner` fails `canScheduleAs('owner')`,
232
+ // rewriting/re-enabling an already-`owner`-stamped body fails the prior-role
233
+ // check, and a custom role scheduling as a different custom role that carries
234
+ // an extra permission fails the subset check — none are schedulable, so all
235
+ // stay blocked.
236
+ export function diffJobs(
237
+ before: readonly ParsedCronJob[],
238
+ after: readonly ParsedCronJob[],
239
+ canScheduleAs: CanScheduleAs,
240
+ ): CronPromotionFinding[] {
212
241
  const findings: CronPromotionFinding[] = []
213
242
  const beforeById = new Map<string, ParsedCronJob>()
214
243
  for (const job of before) beforeById.set(job.id, job)
@@ -217,15 +246,17 @@ export function diffJobs(before: readonly ParsedCronJob[], after: readonly Parse
217
246
  const prior = beforeById.get(job.id)
218
247
  const newRole = job.scheduledByRole
219
248
  if (prior === undefined) {
220
- findings.push({
221
- kind: 'job-added',
222
- id: job.id,
223
- scheduledByRole: newRole ?? '<unset>',
224
- })
249
+ if (!canScheduleAs(newRole)) {
250
+ findings.push({
251
+ kind: 'job-added',
252
+ id: job.id,
253
+ scheduledByRole: newRole ?? '<unset>',
254
+ })
255
+ }
225
256
  continue
226
257
  }
227
258
  const oldRole = prior.scheduledByRole
228
- if (oldRole !== newRole) {
259
+ if (oldRole !== newRole && !canScheduleAs(newRole)) {
229
260
  findings.push({
230
261
  kind: 'role-changed',
231
262
  id: job.id,
@@ -233,8 +264,9 @@ export function diffJobs(before: readonly ParsedCronJob[], after: readonly Parse
233
264
  to: newRole ?? '<unset>',
234
265
  })
235
266
  }
267
+ const withinReach = canScheduleAs(oldRole) && canScheduleAs(newRole)
236
268
  const bodyDelta = diffJobBody(prior, job)
237
- if (bodyDelta.length > 0) {
269
+ if (bodyDelta.length > 0 && !withinReach) {
238
270
  findings.push({
239
271
  kind: 'body-changed',
240
272
  id: job.id,
@@ -242,7 +274,7 @@ export function diffJobs(before: readonly ParsedCronJob[], after: readonly Parse
242
274
  fields: bodyDelta,
243
275
  })
244
276
  }
245
- if (isPreviouslyDisabled(prior) && !isPreviouslyDisabled(job)) {
277
+ if (isPreviouslyDisabled(prior) && !isPreviouslyDisabled(job) && !withinReach) {
246
278
  findings.push({
247
279
  kind: 'enabled-flipped',
248
280
  id: job.id,
@@ -329,9 +361,9 @@ function buildBlockReason(tool: string, targetPath: string, findings: readonly C
329
361
  }
330
362
  }
331
363
  return [
332
- `Guard \`${GUARD_CRON_PROMOTION}\` blocked ${tool} on ${sanitizeForReason(targetPath)}: this change introduces a deferred privilege grant — ${lines.join('; ')}.`,
333
- 'Cron jobs carry `scheduledByRole`, which the runtime stamps into the firing session\'s origin. Adding a job (or changing its scheduledByRole) is the same shape as the `rolePromotion` attack but deferred: "schedule a privileged prompt now, the cron consumer runs it as that role later." Even an `owner` operating from TUI must not silently author cron jobs that fire as elevated roles on behalf of a channel message.',
334
- `If this is genuinely intentional and the operator explicitly asked for it (not a channel message), retry with \`${ACKNOWLEDGE_GUARDS}.${GUARD_CRON_PROMOTION}: true\` in the tool arguments.`,
364
+ `Guard \`${GUARD_CRON_PROMOTION}\` blocked ${tool} on ${sanitizeForReason(targetPath)}: this change schedules deferred work above your role — ${lines.join('; ')}.`,
365
+ 'Cron jobs carry `scheduledByRole`, which the runtime stamps into the firing session\'s origin. Adding a job, raising its scheduledByRole, or rewriting/re-enabling a job that already fires above your role is the deferred form of the `rolePromotion` attack: "schedule a privileged prompt now, the cron consumer runs it as that role later." A change that fires at or below your own role grants nothing new and is allowed; this block means the resulting (or prior) role outranks yours.',
366
+ 'This cannot be acknowledged away from an under-privileged session. The operator must make the change from a session that already resolves to a role at least as high as the cron job — TUI (owner), or a role granted `security.bypass.medium` — or claim the role out-of-band via `typeclaw role claim`.',
335
367
  ].join(' ')
336
368
  }
337
369
 
@@ -5,7 +5,7 @@ import { parseConfigJson } from '@/config'
5
5
  import { splitPluginEntrySpec } from '@/plugin'
6
6
 
7
7
  import type { SecuritySeverity } from '../permissions'
8
- import { ACKNOWLEDGE_GUARDS, type SecurityBlock, isGuardAcknowledged } from '../policy'
8
+ import type { SecurityBlock } from '../policy'
9
9
 
10
10
  export const GUARD_PLUGIN_ADDITION = 'pluginAddition'
11
11
  // Classified `medium` (silent-attack axis), same tier and rationale as
@@ -57,8 +57,6 @@ export async function checkPluginAdditionGuard(options: {
57
57
  const targetPath = path.resolve(agentDir, rawPath)
58
58
  if (!(await pathIsTypeclawJson(agentDir, targetPath))) return undefined
59
59
 
60
- if (isGuardAcknowledged(args, GUARD_PLUGIN_ADDITION)) return undefined
61
-
62
60
  const editRefusal = refuseRiskyEdit(tool, args, targetPath)
63
61
  if (editRefusal) return editRefusal
64
62
 
@@ -205,7 +203,7 @@ function buildBlockReason(tool: string, targetPath: string, findings: readonly P
205
203
  return [
206
204
  `Guard \`${GUARD_PLUGIN_ADDITION}\` blocked ${tool} on ${sanitizeForReason(targetPath)}: this change introduces a deferred host-code-execution grant — ${lines.join('; ')}.`,
207
205
  "Plugin entries in typeclaw.json#plugins are materialized into package.json and installed by the next host `typeclaw start`, where npm lifecycle scripts run as the operator on the host. Even an `owner` operating from TUI must not silently add plugins on behalf of a channel message: the canonical attack is a prompt-injected agent writing a malicious package name into plugins[] so the operator's next start runs its postinstall.",
208
- `If this is genuinely intentional and the operator explicitly asked for it (not a channel message), retry with \`${ACKNOWLEDGE_GUARDS}.${GUARD_PLUGIN_ADDITION}: true\` in the tool arguments.`,
206
+ 'This cannot be acknowledged away from an under-privileged session. The operator must make the change from a session that already resolves to `owner`/`trusted` (TUI, or a role granted `security.bypass.medium`), or claim the role out-of-band via `typeclaw role claim`.',
209
207
  ].join(' ')
210
208
  }
211
209