typeclaw 0.48.4 → 0.48.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 (31) hide show
  1. package/package.json +1 -1
  2. package/src/agent/index.ts +6 -1
  3. package/src/agent/live-subagents.ts +15 -0
  4. package/src/agent/session-origin.ts +104 -16
  5. package/src/agent/subagent-completion-reminder.ts +1 -1
  6. package/src/agent/subagent-drain.ts +11 -1
  7. package/src/agent/subagents.ts +52 -7
  8. package/src/agent/tools/spawn-subagent.ts +88 -7
  9. package/src/agent/tools/subagent-cancel.ts +1 -0
  10. package/src/agent/tools/subagent-output.ts +7 -2
  11. package/src/agent/tools/webfetch/adaptive-html.ts +319 -0
  12. package/src/agent/tools/webfetch/html-lexical.ts +841 -0
  13. package/src/agent/tools/webfetch/inline-style-visibility.ts +281 -0
  14. package/src/agent/tools/webfetch/strategies/readability.ts +306 -5
  15. package/src/agent/tools/webfetch/tool.ts +45 -2
  16. package/src/agent/tools/webfetch/types.ts +7 -0
  17. package/src/agent/turn-runner.ts +7 -3
  18. package/src/bundled-plugins/github-cli-auth/gh-command.ts +187 -8
  19. package/src/bundled-plugins/reviewer/reviewer.ts +32 -5
  20. package/src/bundled-plugins/reviewer/skills/code-review.ts +5 -3
  21. package/src/bundled-plugins/reviewer/skills/doc-review.ts +1 -1
  22. package/src/bundled-plugins/reviewer/skills/plan-review.ts +1 -1
  23. package/src/plugin/types.ts +0 -10
  24. package/src/run/channel-session-factory.ts +3 -1
  25. package/src/run/index.ts +29 -29
  26. package/src/run/subagent-coalescing.ts +24 -0
  27. package/src/server/index.ts +4 -1
  28. package/src/skills/typeclaw-channel-github/SKILL.md +6 -6
  29. package/src/skills/typeclaw-channel-instagram/SKILL.md +1 -1
  30. package/src/skills/typeclaw-channel-kakaotalk/SKILL.md +1 -1
  31. package/src/skills/typeclaw-channel-line/SKILL.md +1 -1
package/src/run/index.ts CHANGED
@@ -17,6 +17,7 @@ import {
17
17
  invokeSubagent,
18
18
  isSubagentTimeoutError,
19
19
  resolveSubagentProfile,
20
+ SubagentCoalescer,
20
21
  type Subagent as InternalSubagent,
21
22
  type SubagentConsumer,
22
23
  type SubagentRegistry,
@@ -90,6 +91,7 @@ import { installFatalGuard } from './fatal-guard'
90
91
  import { installLlmFetchObserver } from './llm-fetch-observer'
91
92
  import { createPluginRuntime, type PluginRuntime, type PluginSubagentEntry } from './plugin-runtime'
92
93
  import { logResourceReport } from './resource-report'
94
+ import { acquireSubagentCoalesceLease } from './subagent-coalescing'
93
95
 
94
96
  type BunServer = ReturnType<Server['start']>
95
97
 
@@ -439,6 +441,7 @@ async function startAgentRuntime(
439
441
  })
440
442
 
441
443
  const liveSubagentRegistry = new LiveSubagentRegistry()
444
+ const subagentCoalescer = new SubagentCoalescer()
442
445
  const liveSessionRegistry = new LiveSessionRegistry()
443
446
 
444
447
  const channelManager = createChannelManagerFor({
@@ -459,6 +462,7 @@ async function startAgentRuntime(
459
462
  permissions: pluginsLoaded.permissions,
460
463
  reloadRoles: () => reloadRolesFromDisk(cwd),
461
464
  liveSubagentRegistry,
465
+ subagentCoalescer,
462
466
  liveSessionRegistry,
463
467
  subagentRegistry: pluginRuntime.get().subagents,
464
468
  getCreateSessionForSubagent: () => createSessionForSubagent,
@@ -569,6 +573,7 @@ async function startAgentRuntime(
569
573
  ...(entry.pluginSubagent.canSpawnSubagents === true
570
574
  ? {
571
575
  liveSubagentRegistry,
576
+ subagentCoalescer,
572
577
  subagentRegistry: snap.subagents,
573
578
  createSessionForSubagent,
574
579
  allowBackgroundFromSubagent,
@@ -637,17 +642,18 @@ async function startAgentRuntime(
637
642
  getRegistry: () => pluginRuntime.get().subagents,
638
643
  agentDir: cwd,
639
644
  createSessionForSubagent,
640
- inFlightKey: (name, payload) => {
641
- const entry = pluginSubagentByName.get(name)
642
- const fn = entry?.pluginSubagent.inFlightKey
645
+ coalescer: subagentCoalescer,
646
+ inFlightKey: (name, payload, parentSessionId) => {
647
+ const fn = pluginRuntime.get().subagents[name]?.inFlightKey
643
648
  if (fn !== undefined) {
644
649
  try {
645
- return `${name}:${fn(payload)}`
650
+ const key = `${name}:${fn(payload)}`
651
+ return parentSessionId === undefined ? key : `${parentSessionId}:${key}`
646
652
  } catch {
647
- return name
653
+ return parentSessionId === undefined ? name : `${parentSessionId}:${name}`
648
654
  }
649
655
  }
650
- return name
656
+ return parentSessionId === undefined ? name : `${parentSessionId}:${name}`
651
657
  },
652
658
  })
653
659
  registerBootCleanup(() => subagentConsumer.stop())
@@ -755,6 +761,7 @@ async function startAgentRuntime(
755
761
  }
756
762
  : {}),
757
763
  liveSubagentRegistry,
764
+ subagentCoalescer,
758
765
  subagentRegistry: pluginRuntime.get().subagents,
759
766
  createSessionForSubagent,
760
767
  ...containerNameOpt,
@@ -911,23 +918,19 @@ async function startAgentRuntime(
911
918
  // subagent declares one, else just `${name}`. Collisions resolve cleanly
912
919
  // (logged + return) instead of rejecting, because callers from
913
920
  // session.prompt are detached and a colliding spawn is a noop, not an error.
914
- const directSpawnInFlight = new Set<string>()
915
921
  const dispatchSpawnSubagent: CommandSpawnSubagent = async (name, payload, options) => {
916
- const entry = pluginSubagentByName.get(name)
917
- const keyFn = entry?.pluginSubagent.inFlightKey
918
- let coalesceKey = name
919
- if (keyFn !== undefined) {
920
- try {
921
- coalesceKey = `${name}:${keyFn(payload)}`
922
- } catch {
923
- coalesceKey = name
924
- }
925
- }
926
- if (directSpawnInFlight.has(coalesceKey)) {
927
- console.warn(`[subagent] ${coalesceKey}: previous direct spawn still in progress, skipping`)
922
+ const registry = pluginRuntime.get().subagents
923
+ const lease = acquireSubagentCoalesceLease({
924
+ coalescer: subagentCoalescer,
925
+ subagentName: name,
926
+ subagent: registry[name],
927
+ payload,
928
+ ...(options?.parentSessionId !== undefined ? { parentSessionId: options.parentSessionId } : {}),
929
+ })
930
+ if (lease === null) {
931
+ console.warn(`[subagent] ${name}: previous direct spawn still in progress, skipping`)
928
932
  return
929
933
  }
930
- directSpawnInFlight.add(coalesceKey)
931
934
  try {
932
935
  // Resolve the spawning session's role from its origin so the subagent
933
936
  // inherits it. Callers (hooks like session.idle) pass the parent origin
@@ -937,7 +940,6 @@ async function startAgentRuntime(
937
940
  options?.spawnedByOrigin !== undefined
938
941
  ? pluginsLoaded.permissions.resolveRole(options.spawnedByOrigin)
939
942
  : undefined
940
- const registry = pluginRuntime.get().subagents
941
943
  try {
942
944
  await awaitWithSubagentTimeout(
943
945
  invokeSubagent(name, {
@@ -952,18 +954,18 @@ async function startAgentRuntime(
952
954
  ...(options?.spawnedByOrigin !== undefined ? { spawnedByOrigin: options.spawnedByOrigin } : {}),
953
955
  }),
954
956
  name,
955
- coalesceKey,
957
+ lease.key,
956
958
  registry[name]?.timeoutMs,
957
959
  )
958
960
  } catch (err) {
959
961
  if (isSubagentTimeoutError(err)) {
960
- console.warn(`[subagent] ${coalesceKey} timed out after ${err.timeoutMs}ms; releasing coalesce key`)
962
+ console.warn(`[subagent] ${lease.key} timed out after ${err.timeoutMs}ms; releasing coalesce key`)
961
963
  return
962
964
  }
963
965
  throw err
964
966
  }
965
967
  } finally {
966
- directSpawnInFlight.delete(coalesceKey)
968
+ lease.release()
967
969
  }
968
970
  }
969
971
  pluginsLoaded.setSpawnSubagent(dispatchSpawnSubagent)
@@ -1031,6 +1033,7 @@ async function startAgentRuntime(
1031
1033
  commandRunnerFactory,
1032
1034
  tunnelManager,
1033
1035
  liveSubagentRegistry,
1036
+ subagentCoalescer,
1034
1037
  createSessionForSubagent,
1035
1038
  liveSessionRegistry,
1036
1039
  ...containerNameOpt,
@@ -1310,7 +1313,6 @@ type PluginOnlySubagentKeys = Exclude<keyof import('@/plugin').Subagent<any>, ke
1310
1313
  const PLUGIN_ONLY_KEYS_DROPPED_BY_SHIM = {
1311
1314
  tools: true,
1312
1315
  customTools: true,
1313
- inFlightKey: true,
1314
1316
  } satisfies Record<PluginOnlySubagentKeys, true>
1315
1317
  // Reference the table so it's not dead code. The value is a runtime no-op;
1316
1318
  // the load-bearing work is the `satisfies` clause above which forces
@@ -1322,15 +1324,13 @@ function pluginSubagentShim(subagent: import('@/plugin').Subagent<any>): Interna
1322
1324
  // `AgentSessionTools` internal-side; `customTools` similarly differs) are
1323
1325
  // resolved later in `createSessionForSubagent` via the
1324
1326
  // `pluginSubagentByShim` lookup, which recovers the original plugin
1325
- // reference. `inFlightKey` is consumed only by the SubagentConsumer via
1326
- // `pluginSubagentByName`, not through this shim's registry path. Every
1327
- // other plugin-side field lives on `SubagentShared` and is structurally
1327
+ // reference. Every other plugin-side field lives on `SubagentShared` and is structurally
1328
1328
  // assignable to the internal `Subagent`, so a rest-spread carries them
1329
1329
  // verbatim — including `visibility` and `requiresSpecificPermission`,
1330
1330
  // whose silent drop in the previous shim made every plugin-contributed
1331
1331
  // public subagent (scout, explorer, operator) invisible to the
1332
1332
  // `spawn_subagent` tool. The list of keys removed here is enforced
1333
1333
  // exhaustive at compile time by `PLUGIN_ONLY_KEYS_DROPPED_BY_SHIM` above.
1334
- const { tools: _tools, customTools: _customTools, inFlightKey: _inFlightKey, ...shared } = subagent
1334
+ const { tools: _tools, customTools: _customTools, ...shared } = subagent
1335
1335
  return shared
1336
1336
  }
@@ -0,0 +1,24 @@
1
+ import { type Subagent, SubagentCoalescer, subagentCoalesceKey } from '@/agent/subagents'
2
+
3
+ export type SubagentCoalesceLease = {
4
+ key: string
5
+ release: () => void
6
+ }
7
+
8
+ export function acquireSubagentCoalesceLease<P>(options: {
9
+ coalescer: SubagentCoalescer
10
+ subagentName: string
11
+ subagent: Subagent<P> | undefined
12
+ payload: P
13
+ parentSessionId?: string
14
+ }): SubagentCoalesceLease | null {
15
+ const key = subagentCoalesceKey({
16
+ subagentName: options.subagentName,
17
+ payload: options.payload,
18
+ fallbackKey: options.subagentName,
19
+ ...(options.subagent?.inFlightKey !== undefined ? { inFlightKey: options.subagent.inFlightKey } : {}),
20
+ ...(options.parentSessionId !== undefined ? { parentSessionId: options.parentSessionId } : {}),
21
+ })
22
+ if (!options.coalescer.tryAcquire(key)) return null
23
+ return { key, release: () => options.coalescer.release(key) }
24
+ }
@@ -22,7 +22,7 @@ import { promptWithSameRefRetryOnly } from '@/agent/retry-same-ref'
22
22
  import { sessionMetaPayload } from '@/agent/session-meta'
23
23
  import type { SessionOrigin } from '@/agent/session-origin'
24
24
  import { parseSubagentCompletedPayload, renderSubagentCompletionReminder } from '@/agent/subagent-completion-reminder'
25
- import type { CreateSessionForSubagent } from '@/agent/subagents'
25
+ import type { CreateSessionForSubagent, SubagentCoalescer } from '@/agent/subagents'
26
26
  import { TODO_CONTINUATION_SOURCE } from '@/agent/todo/continuation'
27
27
  import {
28
28
  armRestartKickForOrigin,
@@ -135,6 +135,7 @@ export type ServerOptions = {
135
135
  // surface diverges across origin kinds — exactly the gap PR #281 flagged
136
136
  // as out-of-scope follow-up.
137
137
  liveSubagentRegistry?: LiveSubagentRegistry
138
+ subagentCoalescer?: SubagentCoalescer
138
139
  createSessionForSubagent?: CreateSessionForSubagent
139
140
  // Id-keyed registry of live AgentSessions, used by `/inspect` (and any
140
141
  // future read-only session-event consumer) to subscribe to session
@@ -293,6 +294,7 @@ export function createServer({
293
294
  claimController,
294
295
  commandRunnerFactory,
295
296
  liveSubagentRegistry,
297
+ subagentCoalescer,
296
298
  createSessionForSubagent,
297
299
  liveSessionRegistry,
298
300
  }: ServerOptions) {
@@ -538,6 +540,7 @@ export function createServer({
538
540
  ...(containerName !== undefined ? { containerName } : {}),
539
541
  ...(runtimeVersion !== undefined ? { runtimeVersion } : {}),
540
542
  ...(liveSubagentRegistry !== undefined ? { liveSubagentRegistry } : {}),
543
+ ...(subagentCoalescer !== undefined ? { subagentCoalescer } : {}),
541
544
  ...(subagentRegistry !== undefined ? { subagentRegistry } : {}),
542
545
  ...(createSessionForSubagent !== undefined ? { createSessionForSubagent } : {}),
543
546
  })
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: typeclaw-channel-github
3
- description: Use this skill BEFORE every `channel_reply` or `channel_send` call whose adapter is `github`, AND before composing replies to GitHub-originated inbounds, AND before opening new issues with model-driven `gh` or preparing a PR for host-stage operator creation, AND ALWAYS when you are asked to review a PR — whether the inbound says "requested your review on PR #N" / "requested a review from team @… on PR #N", or a human asks for a review in plain language in an issue/PR body or comment ("@bot review this", "can you take a look at #123"). On a review request you delegate the analysis to the `reviewer` subagent, which produces line-anchored findings, then you post them as a formal review via `post_github_review`. ALWAYS settle PR authorship first (triage #0): on a PR **you** opened you are the CONTRIBUTOR/author, not its reviewer — "address the review" / "리뷰 반영" / "fix the feedback" / a `CHANGES_REQUESTED` on your own PR means ask the operator for host-stage checkout, change and commit the code, ask the operator to push, and reply, NOT spawn the reviewer or post a formal verdict; you never review your own PR. The reviewer persona is for other people's PRs only. GitHub renders **real markdown** — `**bold**`, `## headings`, `| tables |`, fenced code blocks, and `inline code` all render natively. Use rich markdown freely. GitHub cannot send file attachments via API — do not call `channel_send` with attachments on github chats. GitHub has no typing indicator. PR review threads use `thread` keyed on the root comment id; reply to a thread to stay in it, or omit `thread` to post a top-level issue/PR comment. When a review comment **you authored** gets addressed — the author pushed a fix or replied that resolves it — verify the fix at the PR's head SHA and then resolve the thread by acknowledging with `channel_reply({ …, resolve_review_thread: true })`, which resolves the thread before posting the reply (see "Resolving review threads you authored" below); resolving is the close-out that tells the author the concern is settled. Model-driven `gh issue create` may open new issues with a command-scoped credential brokered by the adapter. PR creation, checkout, and push are host-stage operator actions. Read this skill before composing anything on GitHub.
3
+ description: Use this skill ALWAYS for PR review requests in any phrasing, including "requested your review on PR #N", "requested a review from team @… on PR #N", "@bot review this", "can you take a look at #123", "이 PR 리뷰해줘", and "리뷰 반영"; delegate reviews of other people's PRs to the `reviewer` subagent and post line-anchored findings with `post_github_review`. ALWAYS settle PR authorship first (triage #0): on a PR you opened, act as the CONTRIBUTOR/author, never review your own PR, and use host-stage operator checkout/push help to address feedback. Also use this skill to resolve threads you authored with `resolve_review_thread`, create issues with model-driven `gh issue create`, or prepare host-stage PR creation, checkout, and push actions.
4
4
  ---
5
5
 
6
6
  GitHub renders normal Markdown in issues, PRs, discussions, and review comments. Use headings, lists, tables, fenced code blocks, links, and inline code when they improve clarity.
@@ -117,10 +117,10 @@ The `reviewer` subagent is the analyst; you are the integration layer between it
117
117
 
118
118
  **HARD RULE — a review with actionable findings is a formal review, never a flat comment.** If the reviewer returns **one or more** actionable findings (`blocker`/`concern`/`nit`), the ONLY acceptable way to deliver them is a formal review via `POST /pulls/<N>/reviews` (step 4) — `REQUEST_CHANGES`, `COMMENT`, or `APPROVE` per the verdict, with the line-anchored findings in `comments[]`. You may **never** flatten those findings into a `channel_reply` or a top-level issue comment, **even when** the `gh api` call fails. A 422 means an anchor is wrong (almost always a `line` not in the diff): re-anchor it or move that one finding into the top-level review `body`, then resubmit the formal review — do **not** abandon the formal review and post prose instead. A flat "## Review … two blockers" comment is a bug, not a fallback: it strands the findings without line anchors and is the exact failure this rule exists to prevent. The flat/issue-comment path is reserved for the **zero-actionable-findings** branch only (see below). If you genuinely cannot land a formal review after fixing anchors, say so plainly and post nothing that claims a review happened — silence beats a false receipt.
119
119
 
120
- 1. **Confirm the target, and check whether you already reviewed it.** Capture the PR number, the repo, and the head SHA — you may need the SHA to read files at the revision the reviewer analyzed.
120
+ 1. **Minimal intake, then delegate immediately.** Capture only the repo, PR number, current head SHA, exact base OID, authorship, and the prior blocking context needed to identify a re-review. Do not inspect the diff or changed files. Batch the independent metadata/history reads where the tool interface permits.
121
121
 
122
122
  ```sh
123
- gh pr view <N> --repo owner/repo --json title,body,baseRefName,headRefOid,files
123
+ gh pr view <N> --repo owner/repo --json author,headRefOid,baseRefOid
124
124
  ```
125
125
 
126
126
  Then check for an **unresolved blocking obligation of yours** — this is what makes the current request a _re-review_ (the author pushed fixes after you previously blocked the PR). As in triage #1, a block can live in **two** places, and you must check both:
@@ -138,13 +138,13 @@ The `reviewer` subagent is the analyst; you are the integration layer between it
138
138
  - **Filter to _decision_ states, not the latest review row.** GitHub's sticky block is cleared only by a later `APPROVED` (or a dismissal) from the same reviewer — a later `COMMENTED` review does **not** clear it. So a history of `CHANGES_REQUESTED` → `COMMENTED` is _still blocked_, even though the latest row is `COMMENTED`. Selecting `last` over the raw review list would misread that as "not a re-review". Filtering to `{CHANGES_REQUESTED, APPROVED}` first, then taking `last`, asks the right question: "what is my latest _blocking decision_, ignoring non-deciding comments?" (Dismissed reviews surface as `state: "DISMISSED"`, so they're correctly excluded from the decision set too.)
139
139
  - **`--paginate --slurp` is mandatory.** GitHub returns reviews 30 per page; a bot on a long-lived PR can have its blocking `CHANGES_REQUESTED` past the first page. Without paginating, that review is invisible and a genuine re-review silently falls back to the plain-comment path. `--slurp` collects every page into one array of arrays; the `add` concatenates them before filtering.
140
140
 
141
- 2. **Spawn the `reviewer` subagent with the PR target.** The reviewer runs on the deep profile, so it always runs in the background — you stay responsive while it works. Pass the PR URL (or `owner/repo#N`) plus any context the requester gave you (focus areas, specific files, etc.). The reviewer fetches the diff itself (`gh pr diff`, `gh api /repos/.../pulls/<n>`), loads the `code-review` skill, and returns a `<review>` block whose code findings carry `location="path:line"`.
141
+ 2. **Spawn the `reviewer` subagent with the PR target immediately after minimal intake.** The reviewer runs on the deep profile, so it always runs in the background — you stay responsive while it works. Pass the repo, PR number, captured head SHA, captured base OID, any re-review context, and any requester focus. Also pass the exact typed identity from step 1 as `review_identity: { repo: "owner/repo", pull_request: N, head_sha: "<40-char headRefOid>", base_sha: "<40-char baseRefOid>", review_kind: "review" }`; use `review_kind: "re-review"` when step 1 found an unresolved blocking obligation. This is runtime coalescing metadata, not prose: identical repo/PR/head/base/kind jobs within this parent session share one in-flight analysis, while a new head, different base, different kind, or different parent session stays independent. Never guess or parse these fields from the request text — source both `headRefOid` and `baseRefOid` from the values returned by `gh pr view`. Do not use a base branch name as identity. Do not run `gh pr diff`, read changed files, or otherwise pre-analyze first. The reviewer acquires its own context, loads the `code-review` skill, and returns a `<review>` block whose code findings carry `location="path:line"`.
142
142
 
143
143
  **If step 1 found an unresolved blocking obligation — a formal `CHANGES_REQUESTED` _or_ an unretracted flat-comment blocker — say so in the spawn payload** — e.g. _"This is a re-review: you previously blocked this PR (the prior blockers were …; the block was a formal `CHANGES_REQUESTED` / a flat PR comment). Verify they are resolved and return `approve` or `request-changes` — a re-review must re-decide the blocking state, not return `comment`."_ The reviewer's `code-review` skill enforces the same rule, but telling it the prior blockers (and which form they took) is what lets it apply that rule; a fresh reviewer session has no memory of your earlier block. The flat-comment case especially must be passed through — the reviewer cannot recover it from review state, so omitting it would silently drop the re-review context the moment the flow starts.
144
144
 
145
145
  Do **not** post an "on it" acknowledgement comment before spawning the reviewer — the runtime already adds an :eyes: reaction to the PR the moment it engages, so a "looking into this" comment is redundant noise. Just spawn the reviewer (it runs in the background); the formal review is your reply. If you want to acknowledge explicitly, use `channel_react({ emoji: "eyes" })`, which reacts without posting a comment.
146
146
 
147
- After spawning, **end your turn** — the background reviewer wakes you with a completion `<system-reminder>` (step 3). "Stay responsive" means you remain free to handle _other_ chats meanwhile; it does **not** license you to keep working _this_ PR. Do not poll `subagent_output` in a busy-wait, and do not fill the wait by reviewing the diff yourself (see the exclusivity rule at the top of this flow). The next thing you do on this PR is read the reviewer's `<review>` block when the reminder arrives.
147
+ After spawning, **end your turn** — the background reviewer wakes you with a completion `<system-reminder>` (step 3). "Stay responsive" means you remain free to handle _other_ chats meanwhile; it does **not** license you to keep working _this_ PR. Do not poll `subagent_output` at all before completion, and do not fill the wait by reviewing the diff yourself. Only after that reminder may you fetch the result.
148
148
 
149
149
  3. **On the completion `<system-reminder>`, first check you have not already posted — then** call `subagent_output({ task_id })` to read the reviewer's final assistant message.
150
150
 
@@ -171,7 +171,7 @@ The `reviewer` subagent is the analyst; you are the integration layer between it
171
171
  - **Re-spawn the reviewer once** (step 2) with the same target — a fresh `deep` context usually completes; if it now returns a real `<review>` block, post it normally.
172
172
  - **If the re-spawn is still incomplete**, post a brief, honest `channel_reply` on the PR — e.g. _"리뷰를 자동 완료하지 못했어요 (reviewer returned no verdict). 다시 시도하거나 직접 확인이 필요합니다."_ — and remove your in-review label. An honest "couldn't complete the review" comment is the correct fallback; silence after you engaged, or a fabricated formal verdict, is not.
173
173
 
174
- 4. **Translate findings into a `post_github_review` call.** Each `<finding>` with `severity` of `blocker`, `concern`, or `nit` and a `location="path:line"` becomes one entry in `comments[]`. Compose the inline `body` from the reviewer's `<issue>` + `<evidence>` + `<suggestion>` verbatim (modulo markdown). Findings whose `location` is `general` (no file:line anchor) go into the top-level review `body` instead. **Skip `praise` findings when building `comments[]`** — if you want to surface them, weave them into the top-level `body`.
174
+ 4. **Validate anchors proportionally, then translate into a `post_github_review` call.** Validate only the cited anchors needed for posting: confirm each actionable `path:line` belongs to the captured head/diff and that the cited text supports the finding. Batch independent anchor checks. Do not re-review the diff, inspect unrelated files, or second-guess the verdict; parent verification is proportional to the findings returned. Each `<finding>` with `severity` of `blocker`, `concern`, or `nit` and a valid `location="path:line"` becomes one entry in `comments[]`. Compose the inline `body` from the reviewer's `<issue>` + `<evidence>` + `<suggestion>` verbatim (modulo markdown). Findings whose `location` is `general` go into the top-level review `body`. **Skip `praise` findings when building `comments[]`**.
175
175
 
176
176
  **The verdict and the inline comments are independent. The verdict sets only the `event` field; it never decides whether you post `comments[]`.** Whenever there is at least one actionable finding (`blocker`/`concern`/`nit`) with a `location="path:line"`, you MUST submit a formal review via `POST /pulls/<N>/reviews` carrying those findings in `comments[]` — including when the verdict is `approve`. An `approve` with three nits is still a formal `APPROVE` review with three inline comments, **not** a plain approval and **not** a flattened summary. Collapsing inline findings into a single `channel_reply` or issue comment loses the line anchors the reviewer worked to produce.
177
177
 
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: typeclaw-channel-instagram
3
- description: Use this skill BEFORE every `channel_reply` or `channel_send` call whose adapter is `instagram`. Instagram DMs render messages as plain text — no markdown, no surfaced @-mention syntax, no threads, and no outbound attachments or stickers. Read this skill before composing anything on Instagram.
3
+ description: Use this skill for Instagram inbound media being metadata-only, workspace types and engagement rules, transport fallback, or operator-side 2FA/checkpoint handling.
4
4
  ---
5
5
 
6
6
  # typeclaw-channel-instagram
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: typeclaw-channel-kakaotalk
3
- description: Use this skill BEFORE every `channel_reply` or `channel_send` call whose adapter is `kakaotalk`, AND before fetching/viewing KakaoTalk inbound attachments. KakaoTalk renders messages as plain text — `**bold**`, `## headings`, `| tables |`, fenced code blocks, and other markdown all appear literally. There is no `@mention` syntax, no message threads, no replies-with-quote, and no outbound stickers. Outbound file attachments (photos, videos, audio, generic files, multi-photo galleries) ARE supported — pass them via `attachments[]` on `channel_send` / `channel_reply` and the adapter routes by MIME. Inbound attachments appear as `[KakaoTalk attachment #N: ...]`; fetch with `channel_fetch_attachment({ attachment_id: N })` or view images with `look_at_channel_attachment({ attachment_id: N })`. Read this skill before composing or fetching anything on KakaoTalk.
3
+ description: Use this skill for KakaoTalk inbound attachment/emoticon handling with `channel_fetch_attachment` or `look_at_channel_attachment`, outbound attachment/gallery MIME routing, engagement/stickiness and group-chat permission questions, mark-read behavior, or self-loop troubleshooting.
4
4
  ---
5
5
 
6
6
  # typeclaw-channel-kakaotalk
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: typeclaw-channel-line
3
- description: Use this skill BEFORE every `channel_reply` or `channel_send` call whose adapter is `line`. LINE renders messages as plain text — `**bold**`, `## headings`, `| tables |`, fenced code blocks, and other markdown all appear literally. There is no `@mention` syntax, no message threads, no replies-with-quote, and no outbound attachments or stickers. Inbound non-text content (images, stickers, files) is not fetchable through this adapter. Read this skill before composing anything on LINE.
3
+ description: Use this skill for LINE inbound non-text content being unfetchable, workspace bucket semantics, or engagement behavior.
4
4
  ---
5
5
 
6
6
  # typeclaw-channel-line