typeclaw 0.48.6 → 0.48.8

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 (105) hide show
  1. package/auth.schema.json +15 -1
  2. package/package.json +1 -1
  3. package/secrets.schema.json +15 -1
  4. package/src/agent/guard-types.ts +25 -0
  5. package/src/agent/guards.ts +102 -0
  6. package/src/agent/index.ts +33 -3
  7. package/src/agent/live-subagents.ts +14 -0
  8. package/src/agent/multimodal/read-redirect.ts +8 -9
  9. package/src/agent/plugin-tools.ts +283 -148
  10. package/src/agent/provider-error.ts +6 -1
  11. package/src/agent/reload-tool.ts +12 -5
  12. package/src/agent/retry-same-ref.ts +95 -36
  13. package/src/agent/session-origin.ts +13 -1
  14. package/src/agent/system-prompt.ts +14 -3
  15. package/src/agent/todo/continuation-policy.ts +3 -4
  16. package/src/agent/tool-file-safety.ts +36 -13
  17. package/src/agent/tools/channel-reply.ts +39 -2
  18. package/src/agent/tools/channel-send.ts +45 -2
  19. package/src/agent/tools/post-github-review.ts +31 -13
  20. package/src/agent/tools/spawn-subagent.ts +15 -0
  21. package/src/agent/tools/webfetch/inline-style-visibility.ts +2 -2
  22. package/src/agent/tools/webfetch/strategies/readability.ts +109 -10
  23. package/src/agent/turn-runner.ts +23 -19
  24. package/src/bundled-plugins/backup/git-auth.ts +7 -4
  25. package/src/bundled-plugins/backup/subagents.ts +1 -1
  26. package/src/bundled-plugins/bun-hygiene/README.md +23 -20
  27. package/src/bundled-plugins/bun-hygiene/index.ts +1 -7
  28. package/src/bundled-plugins/bun-hygiene/policy.ts +111 -35
  29. package/src/bundled-plugins/github-cli-auth/gh-review-detect.ts +44 -2
  30. package/src/bundled-plugins/github-cli-auth/gh-store.ts +733 -0
  31. package/src/bundled-plugins/github-cli-auth/git-askpass.ts +25 -0
  32. package/src/bundled-plugins/github-cli-auth/git-command.ts +231 -30
  33. package/src/bundled-plugins/github-cli-auth/git-credential-env.ts +151 -0
  34. package/src/bundled-plugins/github-cli-auth/index.ts +249 -42
  35. package/src/bundled-plugins/github-cli-auth/review-recorder.ts +5 -0
  36. package/src/bundled-plugins/guard/index.ts +2 -25
  37. package/src/bundled-plugins/guard/keys.ts +8 -0
  38. package/src/bundled-plugins/guard/policies/non-workspace-write.ts +7 -8
  39. package/src/bundled-plugins/guard/policy.ts +1 -7
  40. package/src/bundled-plugins/security/policies/git-exfil.ts +22 -30
  41. package/src/bundled-plugins/security/policies/outbound-secret-scan.ts +2 -4
  42. package/src/bundled-plugins/security/policies/private-surface-read.ts +8 -6
  43. package/src/bundled-plugins/security/policies/secret-exfil-bash.ts +2 -5
  44. package/src/bundled-plugins/security/policies/secret-exfil-read.ts +2 -4
  45. package/src/bundled-plugins/security/policies/session-search-secrets.ts +2 -4
  46. package/src/bundled-plugins/security/policies/system-prompt-leak.ts +2 -4
  47. package/src/bundled-plugins/security/policy.ts +0 -8
  48. package/src/channels/adapters/discord-bot-slash-commands.ts +22 -0
  49. package/src/channels/adapters/discord-bot.ts +2 -1
  50. package/src/channels/adapters/discord-classify.ts +16 -4
  51. package/src/channels/adapters/discord.ts +20 -8
  52. package/src/channels/adapters/github/dedup.ts +37 -8
  53. package/src/channels/adapters/github/inbound.ts +241 -46
  54. package/src/channels/adapters/github/review-state.ts +13 -9
  55. package/src/channels/adapters/github/review-thread-resolver.ts +52 -20
  56. package/src/channels/adapters/slack-classify.ts +40 -5
  57. package/src/channels/adapters/slack.ts +3 -9
  58. package/src/channels/adapters/webex-bot-classify.ts +4 -33
  59. package/src/channels/adapters/webex-bot.ts +2 -4
  60. package/src/channels/adapters/webex-classify.ts +4 -33
  61. package/src/channels/adapters/webex-format.ts +36 -0
  62. package/src/channels/adapters/webex.ts +2 -4
  63. package/src/channels/continuation-willingness.ts +64 -39
  64. package/src/channels/github-rereview-guard.ts +20 -0
  65. package/src/channels/github-review-turn-ledger.ts +11 -1
  66. package/src/channels/github-review-verdict-coordinator.ts +475 -41
  67. package/src/channels/github-verdict-activity.ts +14 -5
  68. package/src/channels/persistence.ts +89 -5
  69. package/src/channels/router.ts +1223 -225
  70. package/src/channels/types.ts +21 -5
  71. package/src/cli/compose-stats.ts +6 -7
  72. package/src/cli/compose-status.ts +6 -7
  73. package/src/cli/compose-usage.ts +6 -7
  74. package/src/cli/stats.ts +6 -7
  75. package/src/cli/status.ts +7 -8
  76. package/src/cli/ui.ts +4 -4
  77. package/src/container/start.ts +41 -1
  78. package/src/cron/consumer.ts +30 -9
  79. package/src/cron/scheduler.ts +24 -9
  80. package/src/doctor/channel-checks.ts +64 -0
  81. package/src/doctor/report.ts +8 -8
  82. package/src/dreams/render.ts +2 -2
  83. package/src/init/dockerfile.ts +8 -1
  84. package/src/inspect/render.ts +2 -2
  85. package/src/path-safety/real-intended-path.ts +14 -1
  86. package/src/permissions/permissions.ts +10 -2
  87. package/src/permissions/resolve.ts +8 -2
  88. package/src/plugin/core-tool-names.ts +15 -0
  89. package/src/plugin/hooks.ts +37 -3
  90. package/src/plugin/registry.ts +7 -3
  91. package/src/run/index.ts +35 -15
  92. package/src/sandbox/build.ts +19 -3
  93. package/src/sandbox/policy.ts +1 -0
  94. package/src/secrets/export-github-cli-store.ts +158 -0
  95. package/src/secrets/index.ts +19 -1
  96. package/src/secrets/provision-github-cli-store.ts +322 -0
  97. package/src/secrets/schema.ts +13 -7
  98. package/src/secrets/storage.ts +30 -0
  99. package/src/shared/index.ts +2 -0
  100. package/src/shared/style-text.ts +13 -0
  101. package/src/skills/typeclaw-channel-github/SKILL.md +24 -12
  102. package/src/skills/typeclaw-config/SKILL.md +3 -1
  103. package/src/skills/typeclaw-github-contributing/SKILL.md +6 -2
  104. package/src/skills/typeclaw-permissions/SKILL.md +11 -22
  105. package/src/usage/report.ts +3 -3
package/auth.schema.json CHANGED
@@ -885,9 +885,23 @@
885
885
  },
886
886
  "additionalProperties": {}
887
887
  }
888
+ },
889
+ "githubCli": {
890
+ "type": "object",
891
+ "properties": {
892
+ "hosts": {
893
+ "type": "string",
894
+ "minLength": 1
895
+ }
896
+ },
897
+ "required": [
898
+ "hosts"
899
+ ],
900
+ "additionalProperties": false
888
901
  }
889
902
  },
890
903
  "required": [
891
904
  "version"
892
- ]
905
+ ],
906
+ "additionalProperties": {}
893
907
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "typeclaw",
3
- "version": "0.48.6",
3
+ "version": "0.48.8",
4
4
  "homepage": "https://github.com/typeclaw/typeclaw#readme",
5
5
  "bugs": {
6
6
  "url": "https://github.com/typeclaw/typeclaw/issues"
@@ -885,9 +885,23 @@
885
885
  },
886
886
  "additionalProperties": {}
887
887
  }
888
+ },
889
+ "githubCli": {
890
+ "type": "object",
891
+ "properties": {
892
+ "hosts": {
893
+ "type": "string",
894
+ "minLength": 1
895
+ }
896
+ },
897
+ "required": [
898
+ "hosts"
899
+ ],
900
+ "additionalProperties": false
888
901
  }
889
902
  },
890
903
  "required": [
891
904
  "version"
892
- ]
905
+ ],
906
+ "additionalProperties": {}
893
907
  }
@@ -0,0 +1,25 @@
1
+ import type { ToolFileOperands, ToolProvenance } from '@/plugin'
2
+
3
+ import type { SessionOrigin } from './session-origin'
4
+
5
+ export type InternalGuardEvent = {
6
+ readonly tool: string
7
+ readonly sessionId: string
8
+ readonly callId: string
9
+ readonly args: Readonly<Record<string, unknown>>
10
+ readonly origin?: SessionOrigin
11
+ readonly toolProvenance?: ToolProvenance
12
+ readonly fileOperands?: ToolFileOperands
13
+ }
14
+
15
+ export type InternalGuardResult =
16
+ | undefined
17
+ | { readonly kind: 'block'; readonly reason: string }
18
+ | { readonly kind: 'acknowledgement-required'; readonly reason: string }
19
+
20
+ export type InternalGuard = {
21
+ readonly owner: string
22
+ readonly key: string
23
+ readonly tools: ReadonlySet<string>
24
+ readonly check: (event: InternalGuardEvent) => InternalGuardResult | Promise<InternalGuardResult>
25
+ }
@@ -0,0 +1,102 @@
1
+ import {
2
+ checkGlobalInstallGuard,
3
+ checkNonBunPackageManagerGuard,
4
+ checkNonBunPackageRunnerGuard,
5
+ } from '@/bundled-plugins/bun-hygiene/policy'
6
+ import {
7
+ GUARD_GLOBAL_INSTALL,
8
+ GUARD_IMAGE_READ_REDIRECT,
9
+ GUARD_NON_BUN_PACKAGE_MANAGER,
10
+ GUARD_NON_BUN_PACKAGE_RUNNER,
11
+ GUARD_NON_WORKSPACE_WRITE,
12
+ } from '@/bundled-plugins/guard/keys'
13
+ import {
14
+ checkManagedConfigGuard,
15
+ checkNonWorkspaceWriteGuard,
16
+ checkSkillAuthoringGuard,
17
+ } from '@/bundled-plugins/guard/policy'
18
+ import { CORE_TOOL_NAMES } from '@/plugin/core-tool-names'
19
+
20
+ import type { InternalGuard } from './guard-types'
21
+ import { checkImageReadRedirect } from './multimodal/read-redirect'
22
+
23
+ export type { InternalGuard } from './guard-types'
24
+
25
+ type InternalGuardDeclaration = Omit<InternalGuard, 'tools'> & {
26
+ readonly tools: readonly [string, ...string[]]
27
+ }
28
+
29
+ const GUARD_KEY_REGEX = /^[a-z][A-Za-z0-9]*$/
30
+ const ACKNOWLEDGE_GUARDS = 'acknowledgeGuards'
31
+
32
+ export function buildInternalGuards(agentDir: string): readonly InternalGuard[] {
33
+ const declarations: readonly InternalGuardDeclaration[] = [
34
+ {
35
+ owner: 'guard',
36
+ key: GUARD_IMAGE_READ_REDIRECT,
37
+ tools: ['read'],
38
+ check: checkImageReadRedirect,
39
+ },
40
+ {
41
+ owner: 'guard',
42
+ key: GUARD_NON_WORKSPACE_WRITE,
43
+ tools: ['write', 'edit'],
44
+ check: async (event) => {
45
+ const options = { tool: event.tool, args: event.args, agentDir }
46
+ const managedConfigResult = await checkManagedConfigGuard(options)
47
+ if (managedConfigResult) return { kind: 'block', reason: managedConfigResult.reason }
48
+ const skillResult = await checkSkillAuthoringGuard(options)
49
+ if (skillResult) return { kind: 'block', reason: skillResult.reason }
50
+ return checkNonWorkspaceWriteGuard({ ...options, origin: event.origin })
51
+ },
52
+ },
53
+ {
54
+ owner: 'bun-hygiene',
55
+ key: GUARD_GLOBAL_INSTALL,
56
+ tools: ['bash'],
57
+ check: checkGlobalInstallGuard,
58
+ },
59
+ {
60
+ owner: 'bun-hygiene',
61
+ key: GUARD_NON_BUN_PACKAGE_MANAGER,
62
+ tools: ['bash'],
63
+ check: checkNonBunPackageManagerGuard,
64
+ },
65
+ {
66
+ owner: 'bun-hygiene',
67
+ key: GUARD_NON_BUN_PACKAGE_RUNNER,
68
+ tools: ['bash'],
69
+ check: checkNonBunPackageRunnerGuard,
70
+ },
71
+ ]
72
+ validateInternalGuardDeclarations(declarations, CORE_TOOL_NAMES)
73
+ return declarations.map((declaration) => ({ ...declaration, tools: new Set(declaration.tools) }))
74
+ }
75
+
76
+ export function validateInternalGuardDeclarations(
77
+ guards: readonly InternalGuardDeclaration[],
78
+ availableToolNames: ReadonlySet<string>,
79
+ ): void {
80
+ const keysByOwner = new Map<string, Set<string>>()
81
+ for (const guard of guards) {
82
+ if (!GUARD_KEY_REGEX.test(guard.key)) {
83
+ throw new Error(`internal guard ${guard.owner}.${guard.key} does not match ${GUARD_KEY_REGEX.source}`)
84
+ }
85
+ if (guard.key === ACKNOWLEDGE_GUARDS) {
86
+ throw new Error(`internal guard ${guard.owner}.${guard.key} collides with the acknowledgement structure`)
87
+ }
88
+ const keys = keysByOwner.get(guard.owner) ?? new Set<string>()
89
+ if (keys.has(guard.key)) throw new Error(`duplicate internal guard key ${guard.owner}.${guard.key}`)
90
+ keys.add(guard.key)
91
+ keysByOwner.set(guard.owner, keys)
92
+
93
+ if (new Set(guard.tools).size !== guard.tools.length) {
94
+ throw new Error(`internal guard ${guard.owner}.${guard.key} has duplicate tool names`)
95
+ }
96
+ for (const tool of guard.tools) {
97
+ if (!availableToolNames.has(tool)) {
98
+ throw new Error(`internal guard ${guard.owner}.${guard.key} targets nonexistent tool "${tool}"`)
99
+ }
100
+ }
101
+ }
102
+ }
@@ -34,6 +34,7 @@ import type {
34
34
  Tool as PluginTool,
35
35
  } from '@/plugin'
36
36
  import { createHookBus, materializeSkills } from '@/plugin'
37
+ import { CORE_SYSTEM_TOOL_NAMES } from '@/plugin/core-tool-names'
37
38
  import type { ReloadRegistry } from '@/reload'
38
39
  import { resolveHiddenPaths } from '@/sandbox'
39
40
  import type { Stream } from '@/stream'
@@ -42,6 +43,8 @@ import { applyAdaptiveThinkingCompat } from './adaptive-thinking-compat'
42
43
  import { getAuthFor } from './auth'
43
44
  import { createCompactionSettingsManager } from './compaction'
44
45
  import { renderGitNudge } from './git-nudge'
46
+ import type { InternalGuard } from './guard-types'
47
+ import { buildInternalGuards } from './guards'
45
48
  import type { LiveSubagentRegistry } from './live-subagents'
46
49
  import { sanitizeMessagesForLlmReplay } from './llm-replay-sanitizer'
47
50
  import { applyModelRuntimeOverrides } from './model-overrides'
@@ -316,6 +319,7 @@ export async function createSessionWithDispose(options: CreateSessionOptions = {
316
319
  const getAbort: () => ((reason?: string) => void) | undefined = () => abortHolder.abort
317
320
  let loopGuardTurnId = 0
318
321
  const getLoopGuardTurn = () => loopGuardTurnId
322
+ const guards = buildInternalGuards(options.plugins?.agentDir ?? process.cwd())
319
323
 
320
324
  // Subagent built-in tool refs resolve to `ToolDefinition`s (see
321
325
  // plugin-tools.ts). Their NAMES narrow the session via `tools:`; their wrapped
@@ -406,9 +410,7 @@ export async function createSessionWithDispose(options: CreateSessionOptions = {
406
410
  }),
407
411
  ]
408
412
  : [
409
- webSearchTool,
410
- webFetchTool,
411
- createLookAtTool(options.permissions),
413
+ ...buildCoreSystemTools(options.permissions),
412
414
  ...(options.mcpManager
413
415
  ? buildMcpDispatcherToolDefinitions(options.mcpManager, {
414
416
  permissions: options.permissions,
@@ -468,6 +470,7 @@ export async function createSessionWithDispose(options: CreateSessionOptions = {
468
470
  agentDir: options.plugins?.agentDir ?? process.cwd(),
469
471
  sessionId: options.plugins?.sessionId ?? sessionManager.getSessionId(),
470
472
  hooks: options.plugins?.hooks ?? createHookBus(),
473
+ guards,
471
474
  getOrigin,
472
475
  getAbort,
473
476
  getLoopGuardTurn,
@@ -478,6 +481,7 @@ export async function createSessionWithDispose(options: CreateSessionOptions = {
478
481
  agentDir: options.plugins?.agentDir ?? process.cwd(),
479
482
  sessionId: options.plugins?.sessionId ?? sessionManager.getSessionId(),
480
483
  hooks: options.plugins?.hooks ?? createHookBus(),
484
+ guards,
481
485
  getOrigin,
482
486
  getAbort,
483
487
  getLoopGuardTurn,
@@ -732,11 +736,20 @@ export function buildChannelTools(
732
736
  if (!channelRouter) return []
733
737
  const tools: ToolDefinition[] = []
734
738
  if (origin?.kind === 'channel') {
739
+ // adapter/workspace/chat/thread are session-key fields and never vary across
740
+ // a session's turns, so they stay snapshotted. The review round does: it is
741
+ // stamped per follow-up inbound, so reading it off the creation-time snapshot
742
+ // would hand every turn a stale (usually absent) round and silently disable
743
+ // carrier scoping in production while origin-injecting unit tests still pass.
735
744
  const channelOrigin = {
736
745
  adapter: origin.adapter,
737
746
  workspace: origin.workspace,
738
747
  chat: origin.chat,
739
748
  thread: origin.thread,
749
+ get githubReviewRound() {
750
+ const current = getOrigin?.()
751
+ return current?.kind === 'channel' ? current.githubReviewRound : origin.githubReviewRound
752
+ },
740
753
  }
741
754
  tools.push(
742
755
  createChannelReplyTool({
@@ -915,6 +928,19 @@ export function buildTodoTools(
915
928
  return createTodoTools({ agentDir, getOrigin })
916
929
  }
917
930
 
931
+ function buildCoreSystemTools(permissions: PermissionService | undefined): ToolDefinition[] {
932
+ const definitions = [webSearchTool, webFetchTool, createLookAtTool(permissions)]
933
+ const byName = new Map(definitions.map((tool) => [tool.name, tool]))
934
+ if (byName.size !== definitions.length || byName.size !== CORE_SYSTEM_TOOL_NAMES.length) {
935
+ throw new Error('core system tool catalog does not match its registered definitions')
936
+ }
937
+ return CORE_SYSTEM_TOOL_NAMES.map((name) => {
938
+ const tool = byName.get(name)
939
+ if (tool === undefined) throw new Error(`core system tool "${name}" has no registered definition`)
940
+ return tool
941
+ })
942
+ }
943
+
918
944
  function wrapRegistryTools(
919
945
  plugins: PluginSessionWiring | undefined,
920
946
  getOrigin: () => SessionOrigin | undefined,
@@ -931,6 +957,7 @@ function wrapRegistryTools(
931
957
  sessionId: plugins.sessionId,
932
958
  logger: t.logger,
933
959
  hooks: plugins.hooks,
960
+ guards: buildInternalGuards(plugins.agentDir),
934
961
  getOrigin,
935
962
  getAbort,
936
963
  getLoopGuardTurn,
@@ -945,6 +972,7 @@ export function wrapSystemTools(
945
972
  agentDir: string
946
973
  sessionId: string
947
974
  hooks: HookBus
975
+ guards?: readonly InternalGuard[]
948
976
  getOrigin: () => SessionOrigin | undefined
949
977
  getAbort: () => ((reason?: string) => void) | undefined
950
978
  getLoopGuardTurn?: () => number | undefined
@@ -962,6 +990,7 @@ export function wrapSystemTools(
962
990
  agentDir: options.agentDir,
963
991
  sessionId: options.sessionId,
964
992
  hooks: options.hooks,
993
+ guards: options.guards,
965
994
  getOrigin: options.getOrigin,
966
995
  getAbort: options.getAbort,
967
996
  getLoopGuardTurn: options.getLoopGuardTurn,
@@ -988,6 +1017,7 @@ export function wrapSubagentCustomTools(
988
1017
  sessionId: plugins.sessionId,
989
1018
  logger,
990
1019
  hooks: plugins.hooks,
1020
+ guards: buildInternalGuards(plugins.agentDir),
991
1021
  getOrigin,
992
1022
  getAbort,
993
1023
  getLoopGuardTurn,
@@ -38,6 +38,20 @@ export type LiveSubagent = {
38
38
  export const MAX_EVENTS_PER_SUBAGENT = 100
39
39
  export const MESSAGE_PREVIEW_CHARS = 200
40
40
 
41
+ // Newest — not oldest — so a long-running child that crossed a caller's backstop
42
+ // cannot unpin a parent while a more recently spawned sibling is still inside its
43
+ // window. Foreground children are excluded on purpose: they return inline, so a
44
+ // parent is never left waiting on one.
45
+ export function newestRunningBackgroundChildStartedAt(children: readonly LiveSubagent[]): number | null {
46
+ return children.reduce<number | null>(
47
+ (newest, child) =>
48
+ child.status === 'running' && child.background === true && (newest === null || child.startedAt > newest)
49
+ ? child.startedAt
50
+ : newest,
51
+ null,
52
+ )
53
+ }
54
+
41
55
  type AgentSessionEvent =
42
56
  | { type: 'message_update'; assistantMessageEvent: { type: string; delta?: string } }
43
57
  | { type: 'message_end'; message: unknown }
@@ -1,8 +1,9 @@
1
1
  import path from 'node:path'
2
2
 
3
- import { ACKNOWLEDGE_GUARDS, type GuardBlock, isGuardAcknowledged } from '@/bundled-plugins/guard/policy'
3
+ import type { InternalGuardResult } from '@/agent/guard-types'
4
+ import { GUARD_IMAGE_READ_REDIRECT } from '@/bundled-plugins/guard/keys'
4
5
 
5
- export const GUARD_IMAGE_READ_REDIRECT = 'imageReadRedirect'
6
+ export { GUARD_IMAGE_READ_REDIRECT } from '@/bundled-plugins/guard/keys'
6
7
 
7
8
  // Mirrors the IMAGE_MIME_TYPES set in @mariozechner/pi-coding-agent
8
9
  // (dist/utils/mime.ts). Keeping the trigger surface aligned with the upstream
@@ -13,18 +14,16 @@ export const GUARD_IMAGE_READ_REDIRECT = 'imageReadRedirect'
13
14
  // Extension-only matching is preferred over the upstream MIME sniffer's
14
15
  // 4100-byte file open because this check runs on every `read` call;
15
16
  // extensionless image files still leak as before (no regression), and the
16
- // agent can force-read via `acknowledgeGuards.imageReadRedirect: true` when
17
+ // agent can force-read via `acknowledgeGuards.guard.imageReadRedirect: true` when
17
18
  // it genuinely needs the bytes (e.g. writing image-processing code).
18
19
  const IMAGE_EXTENSIONS = new Set(['.png', '.jpg', '.jpeg', '.gif', '.webp'])
19
20
 
20
21
  export function checkImageReadRedirect(options: {
21
22
  tool: string
22
- args: Record<string, unknown>
23
- }): GuardBlock | undefined {
23
+ args: Readonly<Record<string, unknown>>
24
+ }): InternalGuardResult {
24
25
  const { tool, args } = options
25
26
  if (tool !== 'read') return undefined
26
- if (isGuardAcknowledged(args, GUARD_IMAGE_READ_REDIRECT)) return undefined
27
-
28
27
  const rawPath = args.path
29
28
  if (typeof rawPath !== 'string' || rawPath === '') return undefined
30
29
 
@@ -32,12 +31,12 @@ export function checkImageReadRedirect(options: {
32
31
  if (!IMAGE_EXTENSIONS.has(ext)) return undefined
33
32
 
34
33
  return {
35
- block: true,
34
+ kind: 'acknowledgement-required',
36
35
  reason: [
37
36
  `Guard \`${GUARD_IMAGE_READ_REDIRECT}\` blocked read of an image file: ${rawPath}.`,
38
37
  `Reading images via \`read\` injects the raw bytes into your message history as an image attachment, which can quickly fill your context window.`,
39
38
  `Use \`look_at\` with \`path: ${JSON.stringify(rawPath)}\` instead — it routes the bytes through a vision-capable subagent and returns only text to you. Pass an optional \`prompt\` to ask a specific question (returns shorter text than the default describe-everything path).`,
40
- `If you genuinely need the raw image bytes (e.g. writing image-processing code), retry with \`${ACKNOWLEDGE_GUARDS}.${GUARD_IMAGE_READ_REDIRECT}: true\` in the tool arguments.`,
39
+ `If you genuinely need the raw image bytes (e.g. writing image-processing code), retry with \`acknowledgeGuards.guard.${GUARD_IMAGE_READ_REDIRECT}: true\` in the tool arguments.`,
41
40
  ].join(' '),
42
41
  }
43
42
  }