typeclaw 0.48.4 → 0.48.6

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 (44) 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/plugin-tools.ts +1 -1
  5. package/src/agent/session-origin.ts +104 -16
  6. package/src/agent/subagent-completion-reminder.ts +1 -1
  7. package/src/agent/subagent-drain.ts +11 -1
  8. package/src/agent/subagents.ts +52 -7
  9. package/src/agent/tools/post-github-review.ts +101 -1
  10. package/src/agent/tools/spawn-subagent.ts +88 -7
  11. package/src/agent/tools/subagent-cancel.ts +1 -0
  12. package/src/agent/tools/subagent-output.ts +7 -2
  13. package/src/agent/tools/webfetch/adaptive-html.ts +319 -0
  14. package/src/agent/tools/webfetch/html-lexical.ts +841 -0
  15. package/src/agent/tools/webfetch/inline-style-visibility.ts +281 -0
  16. package/src/agent/tools/webfetch/strategies/readability.ts +306 -5
  17. package/src/agent/tools/webfetch/tool.ts +45 -2
  18. package/src/agent/tools/webfetch/types.ts +7 -0
  19. package/src/agent/turn-runner.ts +7 -3
  20. package/src/bundled-plugins/github-cli-auth/gh-command.ts +187 -8
  21. package/src/bundled-plugins/memory/dreaming.ts +3 -2
  22. package/src/bundled-plugins/reviewer/reviewer.ts +32 -5
  23. package/src/bundled-plugins/reviewer/skills/code-review.ts +5 -3
  24. package/src/bundled-plugins/reviewer/skills/doc-review.ts +1 -1
  25. package/src/bundled-plugins/reviewer/skills/plan-review.ts +1 -1
  26. package/src/channels/github-review-verdict-coordinator.ts +23 -5
  27. package/src/channels/router.ts +15 -5
  28. package/src/cli/inspect.ts +2 -2
  29. package/src/container/start.ts +16 -0
  30. package/src/git/resolve-identity.ts +66 -0
  31. package/src/git/run.ts +2 -0
  32. package/src/git/system-commit.ts +2 -2
  33. package/src/inspect/item-list.ts +2 -11
  34. package/src/inspect/session-list.ts +29 -15
  35. package/src/plugin/types.ts +0 -10
  36. package/src/run/channel-session-factory.ts +3 -1
  37. package/src/run/index.ts +29 -29
  38. package/src/run/subagent-coalescing.ts +24 -0
  39. package/src/sandbox/env-exposure.ts +20 -7
  40. package/src/server/index.ts +4 -1
  41. package/src/skills/typeclaw-channel-github/SKILL.md +10 -10
  42. package/src/skills/typeclaw-channel-instagram/SKILL.md +1 -1
  43. package/src/skills/typeclaw-channel-kakaotalk/SKILL.md +1 -1
  44. package/src/skills/typeclaw-channel-line/SKILL.md +1 -1
@@ -1,6 +1,7 @@
1
1
  import { Type } from '@mariozechner/pi-ai'
2
2
  import { defineTool } from '@mariozechner/pi-coding-agent'
3
3
 
4
+ import { extractAdaptiveHtml, validateAdaptiveHtmlComplexity } from './adaptive-html'
4
5
  import { fetchWithLimits, normalizeUrl, parseMimeType, WebFetchError } from './fetch'
5
6
  import { applyGrep, GrepError } from './strategies/grep'
6
7
  import { applyJq, JqError } from './strategies/jq'
@@ -14,6 +15,7 @@ import {
14
15
  MAX_TIMEOUT_SECONDS,
15
16
  OUTPUT_CAPS,
16
17
  type WebFetchDetails,
18
+ type HtmlExtractionAttempt,
17
19
  } from './types'
18
20
 
19
21
  const STRATEGY_VALUES = ['readability', 'jq', 'selector', 'grep', 'snapshot', 'raw'] as const
@@ -32,7 +34,12 @@ export const webFetchTool = defineTool({
32
34
  'fingerprinting (mouse/scroll/timing), interactive CAPTCHAs, or IP-reputation blocks — a 403 from those ' +
33
35
  'layers is expected and unrecoverable from this tool. ' +
34
36
  'Strategy guide:\n' +
35
- '- "readability": extract article content as markdown (blogs, docs, news). Default for HTML.\n' +
37
+ '- "readability": extract article content as markdown (blogs, docs, news). Default for HTML — when auto-detected, ' +
38
+ 'a linear DOM-complexity preflight (5 MiB scan, 20,000 tags, 256 nesting levels) runs before Readability; a ' +
39
+ 'Readability miss (e.g. a JS app shell with no visible content) is rescued by scanning for a bounded schema.org ' +
40
+ 'Article/NewsArticle/BlogPosting JSON-LD block before giving up; if neither yields meaningful text the error says ' +
41
+ 'browser retrieval may be needed. Passing `strategy: "readability"` explicitly skips adaptive JSON-LD/classification ' +
42
+ "and returns Readability's result as-is, even when empty, but still shares parser and deterministic visibility safety checks.\n" +
36
43
  '- "jq": query JSON APIs (npm registry, GitHub API). Pass `query` (e.g. ".items[].name").\n' +
37
44
  '- "selector": extract text from elements matching a CSS selector. Pass `selector` (e.g. ".price").\n' +
38
45
  '- "grep": filter lines by regex with optional `before`/`after` context. Pass `pattern`.\n' +
@@ -125,8 +132,41 @@ export const webFetchTool = defineTool({
125
132
  }
126
133
 
127
134
  let output: string
135
+ let extractionAttempts: HtmlExtractionAttempt[] | undefined
128
136
  try {
129
- output = await runStrategy(strategy, response.body, response.finalUrl, params)
137
+ if (strategy === 'readability' && autoDetected) {
138
+ const extracted = await extractAdaptiveHtml(response.body, response.finalUrl)
139
+ extractionAttempts = extracted.attempts
140
+ if (extracted.kind === 'error') {
141
+ return errorResult(normalizedUrl, extracted.message, {
142
+ startedAt,
143
+ finalUrl: response.finalUrl,
144
+ contentType: response.contentType,
145
+ httpStatus: response.httpStatus,
146
+ bytesIn: response.bytesIn,
147
+ strategy,
148
+ autoDetected,
149
+ extractionAttempts,
150
+ })
151
+ }
152
+ output = extracted.output
153
+ } else {
154
+ if (strategy === 'readability') {
155
+ const complexity = validateAdaptiveHtmlComplexity(response.body)
156
+ if (!complexity.valid) {
157
+ return errorResult(normalizedUrl, complexity.reason, {
158
+ startedAt,
159
+ finalUrl: response.finalUrl,
160
+ contentType: response.contentType,
161
+ httpStatus: response.httpStatus,
162
+ bytesIn: response.bytesIn,
163
+ strategy,
164
+ autoDetected,
165
+ })
166
+ }
167
+ }
168
+ output = await runStrategy(strategy, response.body, response.finalUrl, params)
169
+ }
130
170
  } catch (error) {
131
171
  const message = error instanceof Error ? error.message : String(error)
132
172
  return errorResult(normalizedUrl, message, {
@@ -152,6 +192,7 @@ export const webFetchTool = defineTool({
152
192
  bytesOut: byteLength(capped.text),
153
193
  truncated: capped.truncated,
154
194
  durationMs: Date.now() - startedAt,
195
+ ...(extractionAttempts === undefined ? {} : { extractionAttempts }),
155
196
  ...(response.antibotWarmup?.triggered
156
197
  ? {
157
198
  antibotWarmup: {
@@ -286,6 +327,8 @@ function errorResult(
286
327
  bytesOut: byteLength(message),
287
328
  truncated: false,
288
329
  durationMs: Date.now() - startedAt,
330
+ ...(rest.antibotWarmup === undefined ? {} : { antibotWarmup: rest.antibotWarmup }),
331
+ ...(rest.extractionAttempts === undefined ? {} : { extractionAttempts: rest.extractionAttempts }),
289
332
  error: true,
290
333
  message,
291
334
  }
@@ -7,6 +7,12 @@ export type AntibotWarmupDetails = {
7
7
  replayStatus?: number
8
8
  }
9
9
 
10
+ export type HtmlExtractionAttempt = {
11
+ route: 'readability' | 'json_ld'
12
+ outcome: 'success' | 'unusable' | 'error'
13
+ reason: string
14
+ }
15
+
10
16
  export type WebFetchDetails = {
11
17
  url: string
12
18
  finalUrl: string
@@ -19,6 +25,7 @@ export type WebFetchDetails = {
19
25
  truncated: boolean
20
26
  durationMs: number
21
27
  antibotWarmup?: AntibotWarmupDetails
28
+ extractionAttempts?: HtmlExtractionAttempt[]
22
29
  error?: boolean
23
30
  message?: string
24
31
  }
@@ -37,9 +37,13 @@ type AttemptActivity = {
37
37
  startedToolExecution: boolean
38
38
  }
39
39
 
40
- // SDK-level attempts already contain pi-ai's internal fetch recovery. Bounding
41
- // only repeated no-header outcomes limits dead air without timing out healthy
42
- // reasoning or tool execution.
40
+ // SDK-level attempts already contain pi-ai's internal fetch recovery. Three is
41
+ // the safe minimum for a fallback chain: primary attempt + its one ordinary
42
+ // transient replay + one cross-ref attempt. Lowering it would weaken either the
43
+ // retained transient retry or fallback; raising it would recreate the repeated
44
+ // TTFB bursts reviewer coalescing is intended to prevent from multiplying.
45
+ // Patient overload retries do not apply to observer TTFB errors, so this envelope
46
+ // already bounds deep-review no-progress without a reviewer-specific retry fork.
43
47
  const MAX_NO_PROGRESS_ATTEMPTS = 3
44
48
  const MAX_CUMULATIVE_NO_PROGRESS_MS = 60_000
45
49
 
@@ -79,7 +79,7 @@ const COMPOSITION_REASON =
79
79
  'newlines, redirections, command/process substitution, subshells, heredocs, or unquoted ' +
80
80
  '`$` expansion (any sibling process or expansion would inherit the token and could ' +
81
81
  'exfiltrate it). One exception is allowed: a trailing reader pipeline `gh … | <reader>` ' +
82
- 'where every downstream stage is a stdin-only reader (`jq`, `cat`, `wc`, `sort`, `uniq`) ' +
82
+ 'where every downstream stage is a stdin-only reader (`jq`, `grep`, `cat`, `wc`, `sort`, `uniq`) ' +
83
83
  'with no file operand — e.g. `gh api repos/o/r | jq .`. jq/JSON metacharacters are also ' +
84
84
  "fine INSIDE single quotes, e.g. `gh api repos/o/r --jq '.[] | {id}'`. File-backed " +
85
85
  '`--input`, `--body-file`, templates, aliases, extensions, and auth/config commands remain unavailable.'
@@ -262,7 +262,7 @@ function isAuthStatusTokenDisplayFlag(arg: string): boolean {
262
262
 
263
263
  export function canInjectPatIntoPassThroughGh(command: string): boolean {
264
264
  if (containsReviewGraphqlMutation(command)) return false
265
- if (command.includes('\\')) return false
265
+ if (hasUnsafeGhStageBackslash(command)) return false
266
266
  if (!isSingleBareGhCommand(command)) return false
267
267
  const tokens = tokenize(command)
268
268
  const starts = findGhInvocations(tokens)
@@ -410,7 +410,7 @@ function isCredentialSafeGhCommand(command: string): boolean {
410
410
  const stages = splitTopLevelPipeStages(command)
411
411
  if (stages === null || stages.length === 0) return false
412
412
  const ghStage = (stages[0] as string).trim()
413
- if (!isSingleBareGhCommand(ghStage) || ghStage.includes('\\')) return false
413
+ if (!isSingleBareGhCommand(ghStage) || hasUnsafeGhStageBackslash(ghStage)) return false
414
414
  const tokens = tokenize(ghStage)
415
415
  return tokens[0] === 'gh' && isCredentialSafeGhArgs(tokens.slice(1))
416
416
  }
@@ -500,9 +500,11 @@ function isSafeGhJqFilter(filter: string): boolean {
500
500
  // has gh's output) — they cannot open their own network/file/process sink, so a
501
501
  // `gh <repo> | <reader>` pipeline cannot exfiltrate the minted token to a third
502
502
  // party. EXCLUDED on purpose: awk (system()/getline|cmd/inet), sed (GNU `e`
503
- // shell-exec), tee/xargs (write/spawn), less (`!cmd`), and grep/head/tail (their
503
+ // shell-exec), tee/xargs (write/spawn), less (`!cmd`), and head/tail (their
504
504
  // file-operand forms are too easy to abuse and not worth the parser risk yet).
505
- const READER_ALLOWLIST = new Set(['jq', 'cat', 'wc', 'sort', 'uniq'])
505
+ // grep is admitted through a dedicated grammar that requires a pattern and
506
+ // proves there is no file operand or pattern-file/recursive option.
507
+ const READER_ALLOWLIST = new Set(['jq', 'grep', 'cat', 'wc', 'sort', 'uniq'])
506
508
 
507
509
  // STRICT per-command flag allowlists. We allow ONLY flags known to be pure
508
510
  // stdin-shaping (no file/program operand). This is allow-known-good, not
@@ -561,6 +563,22 @@ const JQ_SAFE_VALUE_LONG: Record<string, number> = {
561
563
  // (module path) are the fatal ones — and any unknown char also rejects.
562
564
  const JQ_SAFE_BOOLEAN_SHORT = new Set(['r', 'c', 's', 'n', 'e', 'a', 'S', 'R', 'j', 'C', 'M', 'b'])
563
565
 
566
+ const GREP_SAFE_BOOLEAN_LONG = new Set([
567
+ '--basic-regexp',
568
+ '--extended-regexp',
569
+ '--fixed-strings',
570
+ '--ignore-case',
571
+ '--invert-match',
572
+ '--line-number',
573
+ '--count',
574
+ '--only-matching',
575
+ '--quiet',
576
+ '--silent',
577
+ '--word-regexp',
578
+ '--line-regexp',
579
+ ])
580
+ const GREP_SAFE_BOOLEAN_SHORT = new Set(['E', 'F', 'G', 'i', 'v', 'n', 'c', 'o', 'q', 'w', 'x'])
581
+
564
582
  // A reader stage is safe only if it is an allowlisted command using ONLY its
565
583
  // known stdin-shaping flags, with no file operand. Backslashes are rejected
566
584
  // outright: our tokenizer does not model shell backslash escaping, so a
@@ -568,12 +586,13 @@ const JQ_SAFE_BOOLEAN_SHORT = new Set(['r', 'c', 's', 'n', 'e', 'a', 'S', 'R', '
568
586
  // as the forbidden flag — an allowlist-bypass. Rejecting `\` closes that gap.
569
587
  function isStdinOnlyReaderStage(stage: string): boolean {
570
588
  if (containsShellActiveMetachar(stage)) return false
571
- if (stage.includes('\\')) return false
572
589
  const tokens = splitStageTokens(stage)
573
590
  const cmd = tokens[0]
574
591
  if (cmd === undefined || !READER_ALLOWLIST.has(cmd)) return false
575
592
 
576
- if (cmd === 'jq') return isStdinOnlyJqStage(tokens)
593
+ if (cmd === 'jq') return !hasUnsafeJqStageBackslash(stage) && isStdinOnlyJqStage(tokens)
594
+ if (stage.includes('\\')) return false
595
+ if (cmd === 'grep') return isStdinOnlyGrepStage(tokens)
577
596
 
578
597
  const allowedFlags = READER_BOOLEAN_FLAGS[cmd]
579
598
  if (allowedFlags === undefined) return false
@@ -585,6 +604,65 @@ function isStdinOnlyReaderStage(stage: string): boolean {
585
604
  return true
586
605
  }
587
606
 
607
+ // grep reads stdin only when its argv contains one positional pattern OR one or
608
+ // more -e/--regexp patterns, followed by no positional file operands. Keep the
609
+ // option surface intentionally small: unknown options fail closed, especially
610
+ // -f/--file, recursive traversal, and include/exclude selectors.
611
+ function isStdinOnlyGrepStage(tokens: readonly string[]): boolean {
612
+ let patternCount = 0
613
+ let usesRegexpFlag = false
614
+ let sawPositionalPattern = false
615
+ for (let i = 1; i < tokens.length; i++) {
616
+ const tok = tokens[i] as string
617
+ if (tok === '--') return false
618
+ if (sawPositionalPattern && tok.startsWith('-')) return false
619
+ if (tok === '-e' || tok === '--regexp') {
620
+ if (sawPositionalPattern) return false
621
+ const pattern = tokens[i + 1]
622
+ if (pattern === undefined) return false
623
+ patternCount += 1
624
+ usesRegexpFlag = true
625
+ i += 1
626
+ continue
627
+ }
628
+ if (tok.startsWith('--regexp=')) {
629
+ if (sawPositionalPattern) return false
630
+ patternCount += 1
631
+ usesRegexpFlag = true
632
+ continue
633
+ }
634
+ if (tok.startsWith('--')) {
635
+ if (!GREP_SAFE_BOOLEAN_LONG.has(tok)) return false
636
+ continue
637
+ }
638
+ if (tok.startsWith('-') && tok.length > 1) {
639
+ const shortOptions = tok.slice(1)
640
+ for (let shortIndex = 0; shortIndex < shortOptions.length; shortIndex++) {
641
+ const ch = shortOptions[shortIndex] as string
642
+ if (ch === 'e') {
643
+ if (sawPositionalPattern) return false
644
+ patternCount += 1
645
+ usesRegexpFlag = true
646
+ // grep treats `e` as a value-taking terminal option: the rest of the
647
+ // cluster is its pattern (`-neerror`), or the next token is (`-ne x`).
648
+ // No later cluster character can therefore become another option.
649
+ if (shortIndex + 1 < shortOptions.length) break
650
+ const pattern = tokens[i + 1]
651
+ if (pattern === undefined) return false
652
+ i += 1
653
+ break
654
+ }
655
+ if (!GREP_SAFE_BOOLEAN_SHORT.has(ch)) return false
656
+ }
657
+ continue
658
+ }
659
+ if (usesRegexpFlag || patternCount > 0) return false
660
+ patternCount = 1
661
+ sawPositionalPattern = true
662
+ }
663
+ return patternCount > 0
664
+ }
665
+
588
666
  // jq must run pure-stdin: only known stdin-shaping flags, and EXACTLY one
589
667
  // positional (the filter). A second positional is an input FILE jq would open
590
668
  // (`jq . /proc/self/environ` reads that file), so it is rejected. The filter is
@@ -641,10 +719,18 @@ function analyzeReaderPipeline(command: string, stripRepoFlag: boolean): string
641
719
  }
642
720
 
643
721
  const rewrittenGh = stripRepoFlag ? stripRepoFlagFromCommand(ghStage) : ghStage
644
- const rewrittenReaders = stages.slice(1).map((s) => `/usr/bin/env -u GH_TOKEN -u GITHUB_TOKEN ${s.trim()}`)
722
+ const rewrittenReaders = stages.slice(1).map(rewriteReaderStage)
645
723
  return [rewrittenGh, ...rewrittenReaders].join(' | ')
646
724
  }
647
725
 
726
+ function rewriteReaderStage(stage: string): string {
727
+ const trimmed = stage.trim()
728
+ if (splitStageTokens(trimmed)[0] === 'grep') {
729
+ return `/usr/bin/env -u GH_TOKEN -u GITHUB_TOKEN -u GREP_OPTIONS /usr/bin/grep${trimmed.slice('grep'.length)}`
730
+ }
731
+ return `/usr/bin/env -u GH_TOKEN -u GITHUB_TOKEN ${trimmed}`
732
+ }
733
+
648
734
  // Quote-aware split on top-level `|`. Returns null if any OTHER shell-active
649
735
  // metachar appears outside single quotes (`;` `&` `<` `>` backtick `$` `(` `)`
650
736
  // `{` `}` newline) or if a `||`/`|&` is seen — those are not simple pipelines.
@@ -742,6 +828,99 @@ function splitStageTokens(stage: string): string[] {
742
828
  return tokens
743
829
  }
744
830
 
831
+ // Backslashes are shell-active outside single quotes, and the argv-ish tokenizers
832
+ // below deliberately do not interpret shell escapes. The one safe use we support
833
+ // is jq syntax such as `split("\\n")` when the complete filter operand is
834
+ // single-quoted: the shell passes that backslash literally to jq, so it cannot
835
+ // disguise a forbidden gh/jq flag or file operand.
836
+ function hasUnsafeGhStageBackslash(stage: string): boolean {
837
+ if (!stage.includes('\\')) return false
838
+ const rawTokens = splitRawStageTokens(stage)
839
+ if (rawTokens === null) return true
840
+
841
+ for (let i = 0; i < rawTokens.length; i++) {
842
+ const raw = rawTokens[i] as string
843
+ if (!raw.includes('\\')) continue
844
+ const previous = rawTokens[i - 1]
845
+ if ((previous === '--jq' || previous === '-q') && isFullySingleQuoted(raw)) continue
846
+ const attachedFilter = raw.startsWith('--jq=')
847
+ ? raw.slice('--jq='.length)
848
+ : raw.startsWith('-q=')
849
+ ? raw.slice(3)
850
+ : null
851
+ if (attachedFilter !== null && isFullySingleQuoted(attachedFilter)) continue
852
+ return true
853
+ }
854
+ return false
855
+ }
856
+
857
+ function hasUnsafeJqStageBackslash(stage: string): boolean {
858
+ if (!stage.includes('\\')) return false
859
+ const rawTokens = splitRawStageTokens(stage)
860
+ if (rawTokens === null || rawTokens[0] !== 'jq') return true
861
+
862
+ let filterIndex: number | null = null
863
+ for (let i = 1; i < rawTokens.length; i++) {
864
+ const token = stripPairedQuotes(rawTokens[i] as string)
865
+ if (token === '--') return true
866
+ if (token.startsWith('--')) {
867
+ const consume = JQ_SAFE_VALUE_LONG[token]
868
+ if (consume !== undefined) i += consume
869
+ continue
870
+ }
871
+ if (token.startsWith('-') && token.length > 1) continue
872
+ filterIndex = i
873
+ break
874
+ }
875
+
876
+ for (let i = 1; i < rawTokens.length; i++) {
877
+ const raw = rawTokens[i] as string
878
+ if (!raw.includes('\\')) continue
879
+ if (i === filterIndex && isFullySingleQuoted(raw)) continue
880
+ return true
881
+ }
882
+ return false
883
+ }
884
+
885
+ function splitRawStageTokens(stage: string): string[] | null {
886
+ const tokens: string[] = []
887
+ let current = ''
888
+ let quote: '"' | "'" | null = null
889
+ for (const ch of stage) {
890
+ if (quote !== null) {
891
+ current += ch
892
+ if (ch === quote) quote = null
893
+ continue
894
+ }
895
+ if (ch === '"' || ch === "'") {
896
+ quote = ch
897
+ current += ch
898
+ continue
899
+ }
900
+ if (ch === ' ' || ch === '\t') {
901
+ if (current !== '') {
902
+ tokens.push(current)
903
+ current = ''
904
+ }
905
+ continue
906
+ }
907
+ current += ch
908
+ }
909
+ if (quote !== null) return null
910
+ if (current !== '') tokens.push(current)
911
+ return tokens
912
+ }
913
+
914
+ function isFullySingleQuoted(raw: string): boolean {
915
+ return raw.length >= 2 && raw.startsWith("'") && raw.endsWith("'") && !raw.slice(1, -1).includes("'")
916
+ }
917
+
918
+ function stripPairedQuotes(raw: string): string {
919
+ if (raw.length < 2) return raw
920
+ const first = raw[0]
921
+ return first === raw[raw.length - 1] && (first === '"' || first === "'") ? raw.slice(1, -1) : raw
922
+ }
923
+
745
924
  // Removes an unquoted `-R`/`--repo` flag (and its repo-slug value) from a single
746
925
  // bare command, preserving everything else byte-for-byte. Quote-aware so a `-R`
747
926
  // inside a quoted `-f query='...'` value is never touched; a repo slug is
@@ -745,8 +745,9 @@ async function ensureMemoryFiles(agentDir: string): Promise<void> {
745
745
 
746
746
  // Force-add gitignored memory artifacts so the agent folder's git history
747
747
  // captures consolidation as a single recoverable snapshot. Skips silently when
748
- // the folder is not a git repo or bun is unavailable. Uses the user's global
749
- // git config for authorship.
748
+ // the folder is not a git repo or bun is unavailable. Uses Git's ambient
749
+ // identity: host config in host-stage calls, or the agent repo identity
750
+ // injected into the container process at start.
750
751
  //
751
752
  // After committing, the tracked memory artifacts get the `skip-worktree` index
752
753
  // flag set so manual `git status` / `git diff` ignore future runtime edits.
@@ -81,7 +81,7 @@ You are STRICTLY PROHIBITED from:
81
81
  - Pushing, merging, rebasing, or otherwise mutating remote state
82
82
  - Using bash for: mkdir, touch, rm, cp, mv, git add, git commit, git push, git rebase, git reset, npm install, pip install, or any write operation
83
83
 
84
- The boundary that matters is **no side effects on the reviewed artifact, remote state, or the persistent workspace** — not "no byte may touch local disk". A loaded domain skill may carve out one narrow, explicit exception: writing into a fresh throwaway scratch directory under \`/tmp\` purely to *acquire* a read target (e.g. cloning a PR head you cannot otherwise read at line accuracy). That scratch cache is never the reviewed artifact; inside it you still only read, and everything in the prohibition list above still applies everywhere else. Absent such an instruction from your loaded skill, treat the list as absolute.
84
+ The boundary that matters is **no side effects on the reviewed artifact, remote state, or the persistent workspace** — not "no byte may touch local disk". A loaded domain skill may carve out one narrow, explicit exception: asking the existing \`github_prepare_review_checkout\` tool to create a throwaway scratch directory under \`/tmp\` purely to acquire a read target. Use its returned receipt path exactly; never guess or reconstruct a \`/tmp\` path. That scratch cache is never the reviewed artifact; inside it you still only read, and everything in the prohibition list above still applies everywhere else. Absent such an instruction from your loaded skill, treat the list as absolute.
85
85
 
86
86
  Your role is EXCLUSIVELY to analyze and report. The parent agent decides what to do with your findings. Delegating part of that analysis is fine; performing side effects through a delegate is NOT — anything you cannot do directly, a subagent you spawn cannot do for you.
87
87
 
@@ -94,7 +94,7 @@ This is not a last resort — it is your DEFAULT for any non-trivial target, and
94
94
  - 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.
95
95
  - Each delegated task must be self-contained: the worker does not see this conversation or the target. Put everything it needs in the prompt.
96
96
  - The chain is depth-limited: a worker you spawn cannot spawn again. Keep delegation one level deep.
97
- - \`subagent_output\`/\`subagent_cancel\` reach only the tasks YOU spawned. To gather in parallel, either emit all the independent \`spawn_subagent\` calls (foreground, the default from your session) in a SINGLE turn so they run concurrently and return together, or spawn them with \`run_in_foreground=false\` 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.
97
+ - \`subagent_output\`/\`subagent_cancel\` reach only the tasks YOU spawned. Batch independent \`spawn_subagent\` calls in one turn so they run concurrently. For background tasks, end the turn and wait for each completion \`<system-reminder>\`; do not poll \`subagent_output\` before that reminder. Fold all results into one review pass.
98
98
 
99
99
  ## Tools
100
100
 
@@ -104,12 +104,12 @@ The runtime exposes these tools to you by these EXACT names — call them by nam
104
104
  - \`grep\` — search file contents by text or regex
105
105
  - \`find\` — locate files by name pattern
106
106
  - \`ls\` — list a directory's immediate contents
107
- - \`bash\` — read-only commands ONLY. Read-only \`git\` (\`git log\`, \`git diff\`, \`git show\`, \`git blame\`, \`git status\`, \`git grep\`, \`git rev-parse\`, \`git ls-files\`, \`git cat-file\`) and one-shot pipelines that do not mutate state (\`cat\`, \`head\`, \`tail\`, \`wc\`, \`sort\`, \`uniq\`, \`jq\`). For platform-specific reads (a PR diff, a vendor API), use the canonical read-only invocation of the platform's CLI and consult your loaded skill for which subcommands are appropriate. The ONE write a loaded skill may direct you to make is cloning a target into a fresh \`/tmp\` scratch directory purely to read it (\`git clone\`/\`fetch\`/detached \`checkout\` into \`/tmp/review-*\`); that scratch cache is never the reviewed artifact, and everything else above stays read-only.
107
+ - \`bash\` — read-only commands ONLY. Use one simple invocation at a time: no shell loops, pipelines, redirects, \`&&\`, or \`;\`. Read-only \`git\` (\`git log\`, \`git diff\`, \`git show\`, \`git blame\`, \`git status\`, \`git grep\`, \`git rev-parse\`, \`git ls-files\`, \`git cat-file\`) is allowed. For platform-specific reads, use the canonical single invocation from the loaded skill. Never create or reconstruct a review checkout with bash; only the existing checkout tool may acquire one.
108
108
  - \`web_search\` — search the public web (e.g. for OWASP guidance, RFCs, library changelogs, framework docs, prior art)
109
109
  - \`web_fetch\` — fetch a single URL (e.g. to read a linked spec, vendor doc, or article cited in the target)
110
110
  - \`load_skill\` — load a curated review skill by name. See the section below.
111
111
 
112
- Launch independent tools in parallel. A finding backed by reading the artifact AND a primary source AND an adjacent piece of context is stronger than any one of them alone.
112
+ Batch independent reads and searches in parallel. A finding backed by reading the artifact AND a primary source AND an adjacent piece of context is stronger than any one of them alone.
113
113
 
114
114
  ## Loading a review skill
115
115
 
@@ -180,11 +180,22 @@ These three tokens are the universal verdict vocabulary — they apply whether t
180
180
 
181
181
  You have one shot. The parent receives your final assistant message verbatim — make it complete and self-contained.`
182
182
 
183
+ export const reviewerReviewIdentitySchema = z.object({
184
+ repo: z.string().regex(/^[^/\s]+\/[^/\s]+$/),
185
+ pullRequest: z.number().int().positive(),
186
+ headSha: z.string().regex(/^[0-9a-f]{40}$/i),
187
+ baseSha: z.string().regex(/^[0-9a-f]{40}$/i),
188
+ reviewKind: z.enum(['review', 're-review']),
189
+ })
190
+
191
+ export type ReviewerReviewIdentity = z.infer<typeof reviewerReviewIdentitySchema>
192
+
183
193
  export const reviewerPayloadSchema = z
184
194
  .object({
185
195
  requestId: z.string().optional(),
186
196
  prompt: z.string().optional(),
187
197
  description: z.string().optional(),
198
+ reviewIdentity: reviewerReviewIdentitySchema.optional(),
188
199
  })
189
200
  .passthrough()
190
201
 
@@ -225,7 +236,13 @@ If none of the listed skills fit the target, load \`general\`. Keep the skill-se
225
236
  canSpawnSubagents: true,
226
237
  canBackgroundSpawnSubagents: true,
227
238
  timeoutMs: REVIEWER_SPAWN_TIMEOUT_MS,
228
- inFlightKey: (payload) => payload?.requestId ?? `anon-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
239
+ // Only PR jobs opt into stable coalescing. General code/plan/document
240
+ // reviews retain request-scoped concurrency; deriving identity from prompt
241
+ // prose would risk collapsing unrelated work or reviews of different heads.
242
+ inFlightKey: (payload) =>
243
+ payload.reviewIdentity === undefined
244
+ ? (payload.requestId ?? `anon-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`)
245
+ : reviewerReviewIdentityKey(payload.reviewIdentity),
229
246
  toolResultBudget: {
230
247
  // Higher than explorer (256KB) because a reviewer typically reads larger
231
248
  // diffs and multiple files plus web sources; lower than operator (1MB)
@@ -235,3 +252,13 @@ If none of the listed skills fit the target, load \`general\`. Keep the skill-se
235
252
  },
236
253
  }
237
254
  }
255
+
256
+ export function reviewerReviewIdentityKey(identity: ReviewerReviewIdentity): string {
257
+ return [
258
+ identity.repo.toLocaleLowerCase(),
259
+ identity.pullRequest,
260
+ identity.headSha.toLocaleLowerCase(),
261
+ identity.baseSha.toLocaleLowerCase(),
262
+ identity.reviewKind.toLocaleLowerCase(),
263
+ ].join('#')
264
+ }
@@ -35,11 +35,11 @@ gh api "/repos/<owner>/<repo>/contents/<path>?ref=<headSha>" -H "Accept: applica
35
35
 
36
36
  That returns the file's raw bytes (no base64, no second stage). For the line numbers your \`location="path:line"\` anchors need, read them off the unified diff you already fetched (\`gh pr diff\` prints the new-side line numbers in its hunk headers, \`@@ -a,b +c,d @@\`), or escalate to Mode 2 where a real \`read\`/\`grep\` gives native line numbers. Fetch each file once and keep its output — do not re-fetch the same file to re-derive a line you already saw.
37
37
 
38
- **Mode 2 — scratch checkout (escalate when navigation gets broad).** When navigation gets broad, call \`github_prepare_review_checkout({ repoSlug: "<owner>/<repo>", headSha: "<40-char headSha>" })\`. The runtime verifies that exact SHA in the one allowlisted repository and performs the authenticated fetch without exposing its token to model bash.
38
+ **Mode 2 — scratch checkout (escalate when navigation gets broad).** When navigation gets broad, call \`github_prepare_review_checkout({ repoSlug: "<owner>/<repo>", headSha: "<40-char headSha>" })\` once for initial acquisition. The runtime verifies that exact SHA in the one allowlisted repository and performs the authenticated fetch without exposing its token to model bash.
39
39
 
40
- Then use the receipt path with \`read\`, \`grep\`, \`find\`, and read-only \`git\` (\`git -C <receipt-path> log|diff|show|blame|grep|ls-files|cat-file\`) for correct line numbers and zero per-file round-trips. Do not use \`git clone\`, \`git fetch\`, \`git checkout\`, or \`gh pr checkout\` for acquisition.
40
+ Then use the returned receipt path exactly with \`read\`, \`grep\`, \`find\`, and read-only \`git\` (\`git -C <receipt-path> log|diff|show|blame|grep|ls-files|cat-file\`) for correct line numbers and zero per-file round-trips. Trust the receipt: never guess, derive, or reconstruct a \`/tmp\` path. If and only if a read-only operation against that exact returned receipt path fails with \`ENOENT\` / \`No such file or directory\`, call the checkout tool one additional time with the same exact repo slug and 40-character head SHA, then use only the new returned receipt. This is a maximum two checkout tool calls; never retry generic command, tool, or provider failures, change coordinates, or recover by guessing a path. If recovery also fails, stop checkout attempts and fall back to remote reads where feasible or return an honest incomplete review. Do not use \`git clone\`, \`git fetch\`, \`git checkout\`, or \`gh pr checkout\` for acquisition.
41
41
 
42
- This \`/tmp\` scratch checkout is the **one** write the read-only contract permits — and only because it is a private acquisition cache, never the reviewed artifact. Inside it you may only **read**. You still may NOT: edit any file, install dependencies, run builds or tests, commit/stage/push/rebase/reset, or write anywhere outside this \`/tmp\` scratch dir. Do not \`rm\` it when done — leave cleanup to the session lifecycle (\`rm\` stays forbidden). When in doubt about how many files you'll touch, start with Mode 1 and escalate to Mode 2 only once the file count or grep breadth justifies the clone.
42
+ This runtime-owned \`/tmp\` scratch acquisition is the **only kind of write** the read-only contract permits — and only because it is a private acquisition cache, never the reviewed artifact. Inside a returned checkout you may only **read**. You still may NOT: edit any file, install dependencies, run builds or tests, commit/stage/push/rebase/reset, or write anywhere outside the returned \`/tmp\` scratch dir. Do not \`rm\` it when done — leave cleanup to the session lifecycle (\`rm\` stays forbidden). When in doubt about how many files you'll touch, start with Mode 1 and escalate to Mode 2 only once the file count or grep breadth justifies the clone.
43
43
 
44
44
  ## Bound your external verification — never loop
45
45
 
@@ -128,6 +128,8 @@ Calibrate to consequence, not to spec-completeness. Severity is \`(realistic pro
128
128
 
129
129
  When the payload tells you this is a **re-review** — you (or this agent) previously requested changes on this PR and the author has pushed fixes — your verdict's whole purpose is to **re-decide the blocking state**, so:
130
130
 
131
+ Compare the prior reviewed head with the current head and focus exploration on the intervening changes. Reuse prior findings and already-gathered context instead of repeating the first review, while validating cumulative correctness at the current head: prior blockers are resolved, their fixes introduce no regression, and the full result still serves the stated intent.
132
+
131
133
  This includes payloads where the parent says the author **addressed your prior blocking feedback** — "fixed both issues", "addressed your review", "pushed a fix" — even when the inbound was phrased conversationally rather than as an explicit "review again". An author responding to the blocker you raised IS the re-review trigger; the absence of the words "review again" does not downgrade it to a \`comment\`. Re-decide:
132
134
 
133
135
  - Return **approve** if the blockers that drove the prior \`request-changes\` are resolved (leftover nits do not block — \`approve\` with inline nits is correct).
@@ -13,7 +13,7 @@ You have been asked to review a document — anything written to inform or instr
13
13
 
14
14
  - **A file path** — \`read\` it. \`ls\` the surrounding directory to see how this page fits the larger set; a document is reviewed in the context of the set it belongs to.
15
15
  - **A URL** — \`web_fetch\` it. If it is a private site the fetch cannot reach, say so in \`<summary>\` and review what the payload provided.
16
- - **A PR or diff that touches docs** — \`gh pr diff <n>\` for the changed pages; \`read\` the surrounding sections the diff did not touch, because a doc edit is judged against the whole page's flow, not the hunk alone.
16
+ - **A PR or diff that touches docs** — use \`gh pr diff <n>\` for a small change. When broad local context is needed, call \`github_prepare_review_checkout\` once for initial acquisition with the repo slug and 40-character head SHA, then use the returned receipt path exactly for batched \`read\`/\`grep\`/\`find\` calls. If and only if a read-only operation against that exact returned receipt path fails with \`ENOENT\` / \`No such file or directory\`, call the checkout tool one additional time with the same exact repo slug and 40-character head SHA, then use only the new returned receipt. This is a maximum two checkout tool calls; never retry generic command, tool, or provider failures or change coordinates. Never guess or reconstruct a path or acquire a checkout with bash. If recovery also fails, stop checkout attempts and fall back to remote reads where feasible or return an honest incomplete review.
17
17
  - **A doc set / directory** — \`ls\` and \`grep\` for the navigation or index file; a finding about findability needs the table of contents, not just one page.
18
18
  - **Verify external claims.** If the document cites a law, a standard, a price, an SLA, a statistic, or a linked source, check it with \`web_search\`/\`web_fetch\` before letting it stand.
19
19
 
@@ -13,7 +13,7 @@ You have been asked to review a plan — an RFC, a design doc, a PRFAQ, a roadma
13
13
 
14
14
  - **A file path** — \`read\` it. \`ls\` the directory for a template or sibling RFCs that establish the expected shape; deviation from an established plan template is itself worth noting.
15
15
  - **A URL or doc** — \`web_fetch\` it. If it is a private doc the fetch cannot reach, say so in \`<summary>\` and review what the payload provided.
16
- - **A PR that adds a design doc** — \`gh pr diff <n>\`, then \`read\` the linked issue or prior discussion if one is referenced; a plan is judged partly on whether it answers the question that prompted it.
16
+ - **A PR that adds a design doc** — use \`gh pr diff <n>\` for a small change. When broad local context is needed, call \`github_prepare_review_checkout\` once for initial acquisition with the repo slug and 40-character head SHA, then use the returned receipt path exactly for batched \`read\`/\`grep\`/\`find\` calls. If and only if a read-only operation against that exact returned receipt path fails with \`ENOENT\` / \`No such file or directory\`, call the checkout tool one additional time with the same exact repo slug and 40-character head SHA, then use only the new returned receipt. This is a maximum two checkout tool calls; never retry generic command, tool, or provider failures or change coordinates. Never guess or reconstruct a path or acquire a checkout with bash. If recovery also fails, stop checkout attempts and fall back to remote reads where feasible or return an honest incomplete review. Read linked context when referenced; a plan is judged partly on whether it answers the question that prompted it.
17
17
  - **An inline plan in the payload** — read it carefully and quote from it when forming evidence.
18
18
 
19
19
  ## What to look for
@@ -23,7 +23,13 @@ export type EffectiveApprovalResolver = (target: {
23
23
  // push-during-review still blocks a same-verdict duplicate for the lag window.
24
24
  export type HeadShaResolver = (target: { workspace: string; prNumber: number }) => Promise<string | null>
25
25
 
26
- export type ApproveBlock = { block: true; reason: string }
26
+ export type ApproveBlock = {
27
+ block: true
28
+ kind: 'concurrent' | 'duplicate'
29
+ reason: string
30
+ duplicateSource?: 'standing' | 'recent'
31
+ leaseRetained?: boolean
32
+ }
27
33
 
28
34
  export type ReviewVerdictGuard = {
29
35
  guard: (args: {
@@ -31,6 +37,7 @@ export type ReviewVerdictGuard = {
31
37
  workspace: string
32
38
  prNumber: number
33
39
  verdict: ReviewVerdict
40
+ retainDuplicateLease?: boolean
34
41
  }) => Promise<ApproveBlock | null>
35
42
  release: (args: { callId: string; succeeded: boolean }) => Promise<void>
36
43
  // Arms the read-after-write lag shield for a verdict that landed WITHOUT a prior
@@ -203,7 +210,7 @@ export function createApproveIdempotencyGuard(deps: {
203
210
  // reclaimable so a crash cannot permanently strand the PR.
204
211
  const held = inFlightByPr.get(key)
205
212
  if (held !== undefined && now() - held.createdAt < LEASE_TTL_MS) {
206
- return { block: true, reason: CONCURRENT_REASON }
213
+ return { block: true, kind: 'concurrent', reason: CONCURRENT_REASON }
207
214
  }
208
215
  const reservation: Reservation = {
209
216
  key,
@@ -232,8 +239,14 @@ export function createApproveIdempotencyGuard(deps: {
232
239
  // now: a blocked command never reaches tool.after, so release() won't run
233
240
  // for this callId. Leaving the lease set would resurrect the strand bug —
234
241
  // the GitHub read is authoritative for the standing case.
235
- releaseReservation(args.callId, reservation)
236
- return { block: true, reason: duplicateReason(args.verdict) }
242
+ if (args.retainDuplicateLease !== true) releaseReservation(args.callId, reservation)
243
+ return {
244
+ block: true,
245
+ kind: 'duplicate',
246
+ reason: duplicateReason(args.verdict),
247
+ duplicateSource: 'standing',
248
+ ...(args.retainDuplicateLease === true ? { leaseRetained: true } : {}),
249
+ }
237
250
  }
238
251
 
239
252
  // Layer 3 — duplicate-review cooldown. A recently-landed SAME verdict on the
@@ -254,7 +267,12 @@ export function createApproveIdempotencyGuard(deps: {
254
267
  recentlyLandedSame(key, args.verdict, headSha, now)
255
268
  ) {
256
269
  releaseReservation(args.callId, reservation)
257
- return { block: true, reason: duplicateReason(args.verdict) }
270
+ return {
271
+ block: true,
272
+ kind: 'duplicate',
273
+ reason: duplicateReason(args.verdict),
274
+ duplicateSource: 'recent',
275
+ }
258
276
  }
259
277
 
260
278
  return null