@tduyng/pi-subagent 0.0.0-stage → 0.0.2

package/src/subagent/guards/cloak.ts

@@ -0,0 +1,396 @@
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { getAgentDir } from '@earendil-works/pi-coding-agent'
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent'
+import { Validator } from 'ata-validator'
+import { t } from 'ata-validator/t'
+
+const isOpenObject = new Validator(t.object({}, { additionalProperties: true })).isValidObject
+const isString = new Validator(t.string()).isValidObject
+const isNumber = new Validator(t.number()).isValidObject
+
+export const CLOAK_CONFIG_FILE = 'cloak.json'
+
+function configPath(): string {
+    return join(getAgentDir(), CLOAK_CONFIG_FILE)
+}
+
+function projectConfigPath(): string {
+    return join(process.cwd(), '.pi', CLOAK_CONFIG_FILE)
+}
+
+interface CloakPattern {
+    pattern: string
+    replace?: string
+}
+
+interface CloakRule {
+    filePattern: string | string[]
+    cloakPattern: string | CloakPattern[]
+    replace?: string
+}
+
+export interface CloakConfig {
+    enabled?: boolean
+    cloakCharacter?: string
+    cloakLength?: number | null
+    tryAllPatterns?: boolean
+    patterns?: CloakRule[]
+    vendorKeys?: boolean
+    pemBlocks?: boolean
+    sensitiveFileTypes?: boolean
+}
+
+/** What the file on disk parsed to: the two scalars below are narrowed there, once. */
+interface LoadedConfig extends CloakConfig {
+    cloakCharacter: string
+    cloakLength?: number
+}
+
+interface CompiledRegex {
+    regex: RegExp
+    replace?: string
+}
+
+interface CompiledRule {
+    fileRegex: RegExp
+    regexes: CompiledRegex[]
+}
+
+function globToRegExp(glob: string): RegExp {
+    let out = '^'
+    for (let index = 0; index < glob.length; index++) {
+        const char = glob[index]
+        if (char === undefined) break
+        const next = glob[index + 1]
+        if (char === '*' && next === '*') {
+            out += '.*'
+            index++
+            if (glob[index + 1] === '/') index++
+            continue
+        }
+        if (char === '*') {
+            out += '[^/]*'
+            continue
+        }
+        out += char.replace(/[.+?^${}()|[\]\\]/g, '\\$&')
+    }
+    return new RegExp(`${out}$`)
+}
+
+function compileRule(rule: CloakRule): CompiledRule {
+    const filePatterns = Array.isArray(rule.filePattern) ? rule.filePattern : [rule.filePattern]
+    const specs: CloakPattern[] = Array.isArray(rule.cloakPattern)
+        ? rule.cloakPattern
+        : [{ pattern: rule.cloakPattern, replace: rule.replace }]
+    return {
+        fileRegex: new RegExp(filePatterns.map((pattern) => globToRegExp(pattern).source).join('|')),
+        regexes: specs.map((spec) => ({ regex: new RegExp(spec.pattern, 'gi'), replace: spec.replace }))
+    }
+}
+
+export function compileRules(patterns: CloakRule[]): CompiledRule[] {
+    const compiled: CompiledRule[] = []
+    for (const rule of patterns) {
+        try {
+            compiled.push(compileRule(rule))
+        } catch {}
+    }
+    return compiled
+}
+
+function readConfigFile(path: string): CloakConfig {
+    try {
+        const parsed: unknown = JSON.parse(readFileSync(path, 'utf8'))
+        return isOpenObject(parsed) && !Array.isArray(parsed) ? (parsed as CloakConfig) : {}
+    } catch {
+        return {}
+    }
+}
+
+export function mergeCloakConfig(base: CloakConfig, project: CloakConfig): CloakConfig {
+    return {
+        ...base,
+        patterns: [
+            ...(Array.isArray(base.patterns) ? base.patterns : []),
+            ...(Array.isArray(project.patterns) ? project.patterns : [])
+        ]
+    }
+}
+
+function loadConfig(): LoadedConfig {
+    try {
+        const parsed = mergeCloakConfig(readConfigFile(configPath()), readConfigFile(projectConfigPath()))
+        const length = parsed.cloakLength
+
+        return {
+            enabled: true,
+            ...parsed,
+            cloakCharacter: isString(parsed.cloakCharacter) ? parsed.cloakCharacter : '*',
+            cloakLength: isNumber(length) && Number.isFinite(length) && length >= 0 ? length : undefined,
+            patterns: Array.isArray(parsed.patterns) ? parsed.patterns : []
+        }
+    } catch {
+        return { enabled: true, cloakCharacter: '*', patterns: [] }
+    }
+}
+
+function mask(match: string, cloakChar: string, cloakLength: number | null | undefined): string {
+    const visible = match.slice(0, 1)
+    const target = cloakLength ?? Math.max(match.length, 1)
+    return visible + cloakChar.repeat(Math.max(0, target - 1))
+}
+
+interface Match {
+    start: number
+    end: number
+    replacement: string
+}
+
+interface VendorPattern {
+    name: string
+    prefix: string
+    tail: RegExp
+    wordBoundary: boolean
+}
+
+const VENDOR: VendorPattern[] = [
+    { name: 'AWS Access Key', prefix: 'AKIA', tail: /^AKIA[A-Z0-9]{16}\b/, wordBoundary: true },
+    { name: 'AWS Temp Access Key', prefix: 'ASIA', tail: /^ASIA[A-Z0-9]{16}\b/, wordBoundary: true },
+    { name: 'Bearer Token', prefix: 'Bearer', tail: /^Bearer\s+[a-zA-Z0-9._-]{20,}\b/, wordBoundary: true },
+    { name: 'OpenAI/Anthropic API Key', prefix: 'sk-', tail: /^sk-[a-zA-Z0-9._-]{20,}\b/, wordBoundary: true },
+    { name: 'Stripe Live Key', prefix: 'sk_live_', tail: /^sk_live_[a-zA-Z0-9]{20,}\b/, wordBoundary: true },
+    { name: 'Stripe Test Key', prefix: 'sk_test_', tail: /^sk_test_[a-zA-Z0-9]{20,}\b/, wordBoundary: true },
+    { name: 'GitHub Token', prefix: 'gh', tail: /^gh[pousr]_[a-zA-Z0-9]{36,}\b/, wordBoundary: true },
+    {
+        name: 'GitHub Fine-grained PAT',
+        prefix: 'github_pat_',
+        tail: /^github_pat_[a-zA-Z0-9_]{20,}\b/,
+        wordBoundary: true
+    },
+    {
+        name: 'JWT',
+        prefix: 'eyJ',
+        tail: /^eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/,
+        wordBoundary: true
+    },
+    { name: 'Slack Token', prefix: 'xoxb-', tail: /^xox[baprs]-[A-Za-z0-9-]{20,}\b/, wordBoundary: true },
+    { name: 'GitLab Token', prefix: 'glpat-', tail: /^glpat-[A-Za-z0-9_-]{20,}\b/, wordBoundary: true },
+    { name: 'Google API Key', prefix: 'AIza', tail: /^AIza[A-Za-z0-9_-]{35}\b/, wordBoundary: true },
+    { name: 'npm Token', prefix: 'npm_', tail: /^npm_[a-zA-Z0-9]{36,}\b/, wordBoundary: true },
+    {
+        name: 'SendGrid API Key',
+        prefix: 'SG.',
+        tail: /^SG\.[A-Za-z0-9_-]{16,}\.[A-Za-z0-9_-]{32,}\b/,
+        wordBoundary: true
+    }
+]
+
+function isWordChar(c: string): boolean {
+    const code = c.charCodeAt(0)
+    return (
+        (code >= 0x30 && code <= 0x39) ||
+        (code >= 0x41 && code <= 0x5a) ||
+        (code >= 0x61 && code <= 0x7a) ||
+        code === 0x5f
+    )
+}
+
+function buildMarker(value: string, type: string): string {
+    const prefix = value.slice(0, 4)
+    const stars = '*'.repeat(Math.min(20, Math.max(8, value.length - 4)))
+    return `${prefix}${stars}[REDACTED:${type}]`
+}
+
+export function vendorScan(text: string): Match[] {
+    const matches: Match[] = []
+    for (const { name, prefix, tail, wordBoundary } of VENDOR) {
+        let idx = 0
+        while (idx < text.length) {
+            const found = text.indexOf(prefix, idx)
+            if (found === -1) break
+            if (wordBoundary) {
+                const prev = found > 0 ? text[found - 1] : ''
+                if (prev && isWordChar(prev)) {
+                    idx = found + 1
+                    continue
+                }
+            }
+            const window = text.slice(found)
+            const m = tail.exec(window)
+            if (!m) {
+                idx = found + 1
+                continue
+            }
+            const start = found
+            const end = found + m[0].length
+            matches.push({ start, end, replacement: buildMarker(m[0], name) })
+            idx = end
+        }
+    }
+    return matches
+}
+
+const PEM_BLOCK_REGEX = /-----BEGIN ([A-Z ]+)-----\r?\n([\s\S]*?)(?:\r?\n-----END \1-----|$)/g
+
+export function pemScan(text: string): Match[] {
+    const matches: Match[] = []
+    PEM_BLOCK_REGEX.lastIndex = 0
+    let m: RegExpExecArray | null
+    while ((m = PEM_BLOCK_REGEX.exec(text)) !== null) {
+        matches.push({ start: m.index, end: m.index + m[0].length, replacement: `[REDACTED:PEM ${m[1] ?? ''}]` })
+    }
+    return matches
+}
+
+/**
+ * A quoted JSON field whose name is a credential word, and whose value is shaped like one:
+ * no whitespace, at least 16 characters, and a digit. Without the shape the name alone
+ * masks `"tokenizers": "0.22.2"` and `"token": "ts-node -T -s scripts/cli/ts/token"`,
+ * which is most of a package.json.
+ */
+const CREDENTIAL_FIELD_REGEX =
+    /("(?:[a-z0-9_-]*(?:password|passwd|secret|token|api[_-]?key|authorization|private[_-]?key)[a-z0-9_-]*)"\s*:\s*")(?=[^"\s]{16,}")(?=[^"]*\d)[^"]+"/gi
+
+export function credentialFieldScan(text: string): Match[] {
+    const matches: Match[] = []
+    CREDENTIAL_FIELD_REGEX.lastIndex = 0
+    let m: RegExpExecArray | null
+    while ((m = CREDENTIAL_FIELD_REGEX.exec(text)) !== null) {
+        const start = m.index + m[1]!.length
+        matches.push({ start, end: m.index + m[0].length - 1, replacement: '[REDACTED:credential field]' })
+    }
+    return matches
+}
+
+export function applyMatches(text: string, matches: Match[]): string {
+    if (matches.length === 0) return text
+    const sorted = matches.toSorted((a, b) => a.start - b.start)
+    const parts: string[] = []
+    let cursor = 0
+    for (const m of sorted) {
+        if (m.start < cursor) continue
+        if (m.start > cursor) parts.push(text.slice(cursor, m.start))
+        parts.push(m.replacement)
+        cursor = m.end
+    }
+    if (cursor < text.length) parts.push(text.slice(cursor))
+    return parts.join('')
+}
+
+const SENSITIVE_PATH_PATTERNS: { pattern: RegExp; type: string }[] = [
+    { pattern: /\.pem$/i, type: 'PEM File' },
+    { pattern: /\.crt$/i, type: 'Certificate File' },
+    { pattern: /\.cer$/i, type: 'Certificate File' },
+    { pattern: /\.p12$/i, type: 'PKCS12 File' },
+    { pattern: /\.pfx$/i, type: 'PKCS12 File' },
+    { pattern: /(^|\/)\.ssh\/id_(rsa|ed25519|ecdsa|dsa)(\.pub)?$/i, type: 'SSH Key' },
+    { pattern: /\.ssh\/known_hosts$/i, type: 'SSH Known Hosts' },
+    { pattern: /\.ssh\/authorized_keys$/i, type: 'SSH Authorized Keys' },
+    { pattern: /\.aws\/credentials$/i, type: 'AWS Credentials' },
+    { pattern: /\.npmrc$/i, type: 'npm Config' },
+    { pattern: /\.pypirc$/i, type: 'PyPI Config' },
+    { pattern: /\.netrc$/i, type: 'Netrc File' },
+    { pattern: /\.docker\/config\.json$/i, type: 'Docker Config' },
+    { pattern: /\.kube\/config$/i, type: 'Kube Config' },
+    { pattern: /(?:^|\/)\.env(?:\.[\w-]+)?$/i, type: 'Environment File' }
+]
+
+export function matchSensitivePath(path: string): string | null {
+    for (const { pattern, type } of SENSITIVE_PATH_PATTERNS) if (pattern.test(path)) return type
+    return null
+}
+
+// Canonical copy; pi-subagent/src/redact.ts mirrors it so that package stands alone.
+const SIDE_MODEL_REDACTIONS: Array<[RegExp, string]> = [
+    [
+        /-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z0-9 ]*PRIVATE KEY-----/g,
+        '[redacted private key block]'
+    ],
+    [/\bAKIA[0-9A-Z]{16}\b/g, '[redacted aws access key]'],
+    [/\bsk-[A-Za-z0-9_-]{20,}/g, '[redacted api key]'],
+    [/\bBearer\s+[A-Za-z0-9._~+/=-]{8,}/gi, 'Bearer [redacted]'],
+    [/^(\s*(?:export\s+)?[A-Za-z_]*(?:KEY|TOKEN|SECRET|PASSWORD)[A-Za-z_]*\s*=\s*)("?)[^"]+\2$/gm, '$1$2[redacted]$2']
+]
+
+export function redactSecrets(text: string): string {
+    let out = text
+    for (const [re, replacement] of SIDE_MODEL_REDACTIONS) out = out.replace(re, replacement)
+    return out
+}
+
+export default function (pi: ExtensionAPI) {
+    const config = loadConfig()
+
+    pi.registerCommand('cloak-status', {
+        description: 'Show cloak config status',
+        handler: async (_args, ctx) => {
+            const status = config.enabled === false ? 'disabled' : 'enabled'
+            ctx.ui.notify(
+                `cloak ${status}, patterns=${(config.patterns ?? []).length}, ` +
+                    `vendorKeys=${config.vendorKeys !== false}, pemBlocks=${config.pemBlocks !== false}, ` +
+                    `sensitiveFileTypes=${config.sensitiveFileTypes !== false}`,
+                'info'
+            )
+        }
+    })
+
+    if (config.enabled === false) return
+    const rules = compileRules(config.patterns ?? [])
+    const vendorKeysEnabled = config.vendorKeys !== false
+    const pemBlocksEnabled = config.pemBlocks !== false
+    const sensitiveFileTypesEnabled = config.sensitiveFileTypes !== false
+    if (rules.length === 0 && !vendorKeysEnabled && !pemBlocksEnabled && !sensitiveFileTypesEnabled) return
+
+    const cloakChar = config.cloakCharacter
+    const cloakLength = config.cloakLength ?? null
+
+    pi.on('tool_result', (event) => {
+        if (!Array.isArray(event.content)) return
+        const input = event.input as { path?: string }
+        const rawPath = event.toolName === 'read' ? (input.path ?? '') : ''
+
+        const sensitiveType = sensitiveFileTypesEnabled && rawPath ? matchSensitivePath(rawPath) : null
+        const matchingRules = rawPath ? rules.filter((rule) => rule.fileRegex.test(rawPath)) : []
+        if (!sensitiveType && matchingRules.length === 0 && !vendorKeysEnabled && !pemBlocksEnabled) return
+
+        let changed = false
+        const content = event.content.map((part) => {
+            if (part.type !== 'text') return part
+
+            if (sensitiveType) {
+                changed = true
+                return { ...part, text: `[REDACTED:Protected File (${sensitiveType})]` }
+            }
+
+            let text = part.text
+            for (const rule of matchingRules) {
+                for (const compiled of rule.regexes) {
+                    const next =
+                        compiled.replace !== undefined
+                            ? text.replace(compiled.regex, compiled.replace)
+                            : text.replace(compiled.regex, (match) => mask(match, cloakChar, cloakLength))
+                    if (next !== text) {
+                        changed = true
+                        text = next
+                    }
+                }
+                if (config.tryAllPatterns === false) break
+            }
+
+            const structuralMatches = [
+                ...(vendorKeysEnabled ? [...vendorScan(text), ...credentialFieldScan(text)] : []),
+                ...(pemBlocksEnabled ? pemScan(text) : [])
+            ]
+            if (structuralMatches.length > 0) {
+                changed = true
+                text = applyMatches(text, structuralMatches)
+            }
+
+            return changed ? { ...part, text } : part
+        })
+
+        if (!changed) return
+        return { content }
+    })
+}

package/src/subagent/guards/git-interceptor.ts

@@ -0,0 +1,73 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent'
+import { Validator } from 'ata-validator'
+import { t } from 'ata-validator/t'
+
+const SENSITIVE_COMMAND_RE =
+    /(?:^|[\s"'=:~]|\/)\.env(?:\.[A-Za-z0-9_-]+)?(?=$|[\s"';&|),\]} ])|(?:^|[\s"'=:~]|\/)(?:[^\s"';&|]*\/)?(?:id_rsa|id_dsa|id_ecdsa|id_ed25519)(?=$|[\s"';&|),\]} ])|(?:^|[\s"'=:~]|\/)[^\s"';&|]*\.(?:pem|key|p12|pfx)(?=$|[\s"';&|),\]} ])/i
+
+const SENSITIVE_REASON =
+    'BLOCKED: shell access to a credential or private-key file is not allowed, and a read of one ' +
+    'comes back redacted. Ask the user for the value you need.'
+
+const BLOCK_REASON =
+    'BLOCKED: --no-verify is not allowed. Git hooks exist for a reason. ' +
+    'Do not attempt to bypass them. Instead: fix the underlying issue causing ' +
+    'the hook to fail, or ask the user for help.'
+
+const CommandInput = t.object({
+    command: t.optional(t.string()),
+    then_run: t.optional(t.union([t.string(), t.object({ command: t.string() })]))
+})
+const isCommandInput = new Validator(CommandInput).isValidObject
+const isThenRunCommand = new Validator(t.object({ command: t.string() })).isValidObject
+const isThenRunText = new Validator(t.string()).isValidObject
+
+function words(segment: string): string[] {
+    const found = segment.match(/"(?:[^"\\]|\\.)*"|'[^']*'|[^\s]+/g) ?? []
+    return found.map((word) => word.replace(/^(["'])(.*)\1$/, '$2'))
+}
+
+function blocksHooks(command: string): boolean {
+    if (!/\bgit\b/.test(command)) return false
+    for (const segment of command.split(/[;&|\n]+/)) {
+        const tokens = words(segment)
+        const git = tokens.findIndex((token) => token === 'git' || token.endsWith('/git'))
+        if (git === -1) continue
+        const args = tokens.slice(git + 1)
+        const commit = args.findIndex((token) => token === 'commit')
+        if (commit === -1) continue
+        if (args.includes('--no-verify')) return true
+        if (args.some((token, index) => token === '-c' && (args[index + 1]?.startsWith('core.hooksPath=') ?? false)))
+            return true
+        const after = args.slice(commit + 1)
+        const message = after.findIndex(
+            (token) => token === '-m' || token === '--message' || token.startsWith('--message=')
+        )
+        const flags = message === -1 ? after : after.slice(0, message)
+        if (flags.some((token) => /^-[A-Za-z]*n[A-Za-z]*$/.test(token))) return true
+    }
+    return false
+}
+
+function commands(input: { command?: string; then_run?: string | { command: string } }): string[] {
+    const found: string[] = []
+    if (input.command !== undefined) found.push(input.command)
+    if (isThenRunCommand(input.then_run)) found.push(input.then_run.command)
+    else if (isThenRunText(input.then_run)) found.push(input.then_run)
+    return found
+}
+
+export default function (pi: ExtensionAPI) {
+    process.env['GIT_EDITOR'] = 'true'
+    process.env['GIT_SEQUENCE_EDITOR'] = 'true'
+    process.env['GIT_MERGE_AUTOEDIT'] = 'no'
+
+    pi.on('tool_call', (event) => {
+        if (!isCommandInput(event.input)) return
+        for (const command of commands(event.input)) {
+            if (command.trim() === '') continue
+            if (blocksHooks(command)) return { block: true, reason: BLOCK_REASON }
+            if (SENSITIVE_COMMAND_RE.test(command)) return { block: true, reason: SENSITIVE_REASON }
+        }
+    })
+}

package/src/subagent/helpers.ts

@@ -0,0 +1,212 @@
+import { execFile } from 'node:child_process'
+import { stat } from 'node:fs/promises'
+import { basename, dirname } from 'node:path'
+import { promisify } from 'node:util'
+
+import { DEFAULT_MAX_TURNS, MAX_CONCURRENT } from './types.js'
+
+export const MAX_DELAY_MS = 2_147_483_647
+
+export const MIN_TIMEOUT_MS = 30 * 60_000
+
+export async function abortableDelay(ms: number, signal: AbortSignal | undefined): Promise<void> {
+    if (signal?.aborted) throw new Error('Subagent aborted.')
+    ms = Math.min(ms, MAX_DELAY_MS)
+    await new Promise<void>((resolve, reject) => {
+        const cleanup = () => signal?.removeEventListener('abort', onAbort)
+        const timer = setTimeout(() => {
+            cleanup()
+            resolve()
+        }, ms)
+        const onAbort = () => {
+            clearTimeout(timer)
+            cleanup()
+            reject(new Error('Subagent aborted.'))
+        }
+        signal?.addEventListener('abort', onAbort, { once: true })
+    })
+}
+
+export function resolveTimeoutMs(ms: number | undefined): number | undefined {
+    return ms !== undefined && Number.isFinite(ms) && ms > 0 ? Math.max(ms, MIN_TIMEOUT_MS) : undefined
+}
+
+export function resolveMaxTurns(requested: number | undefined, profile: number | undefined): number {
+    const valid = (value: number | undefined): value is number =>
+        value !== undefined && Number.isFinite(value) && value >= 1
+    const fallback = valid(profile) ? profile : DEFAULT_MAX_TURNS
+    return Math.floor(valid(requested) ? requested : fallback)
+}
+
+export function wrapUpMessage(hasSchema: boolean): string {
+    const close = hasSchema
+        ? 'call `structured_output` now with what you already have'
+        : 'reply now with your final answer'
+    return `Turn budget spent: this is your last turn. Stop investigating and ${close}, naming what you could not finish.`
+}
+
+export function structuredRecoveryMessage(attempt: number): string {
+    const lead =
+        'You finished without calling the `structured_output` tool. Do not investigate further. Call `structured_output` now, exactly once, with the fields the task requires, using the findings you already have.'
+    return attempt <= 1 ? lead : `${lead} The parent cannot use a plain text answer for this task; this is reminder ${attempt}.`
+}
+
+export function isProviderSchemaError(error: Error | string): boolean {
+    const message = error instanceof Error ? error.message : error
+    return (
+        /tool[_ ]schema|schema.*invalid|invalid[_ ]schema|structured[_ ]output|json_schema|response[_ ]format|response_format/i.test(
+            message
+        ) || /invalid request parameters/i.test(message)
+    )
+}
+
+export function shouldRetryWithoutSchema(error: Error | string, hasSchema: boolean): boolean {
+    return hasSchema && isProviderSchemaError(error)
+}
+
+export interface RunOutcome {
+    hasAssistant: boolean
+    timedOut: boolean
+    duration: string | undefined
+    hitTurnLimit: boolean
+    maxTurns: number
+    aborted: boolean
+    hasSchema: boolean
+    hasStructured: boolean
+    output: string
+    stopReason: string | undefined
+    errorMessage: string | undefined
+}
+
+export function failureReason(outcome: RunOutcome): string | undefined {
+    if (outcome.timedOut) {
+        return `Timed out after ${outcome.duration ?? 'the deadline'}. Raise timeoutMs or narrow the task.`
+    }
+    if (outcome.aborted || (!outcome.hitTurnLimit && outcome.stopReason === 'aborted')) return 'Cancelled'
+    if (!outcome.hasAssistant) return 'Child produced no response.'
+    if (outcome.stopReason === 'error') return outcome.errorMessage ?? 'Child produced no response.'
+    if (outcome.hitTurnLimit && !outcome.output && !outcome.hasStructured) return 'Child produced no response.'
+    return undefined
+}
+
+export function salvageOutput(assistant: { content?: unknown } | undefined): string | undefined {
+    if (!assistant) return undefined
+    const content = assistant.content
+    if (!Array.isArray(content)) return undefined
+    const text = content
+        .filter((part): part is { type: 'text'; text: string } => {
+            if (!part) return false
+            const p = part as { type: unknown; text: unknown }
+            return p.type === 'text' && p.text != null
+        })
+        .map((part) => String(part.text))
+        .join('')
+        .trim()
+    return text || undefined
+}
+
+export function salvageFromMessages(messages: readonly unknown[] | undefined): string | undefined {
+    if (!messages) return undefined
+    for (let index = messages.length - 1; index >= 0; index--) {
+        const message = messages[index] as { role?: unknown; content?: unknown } | undefined
+        if (!message || message.role !== 'assistant') continue
+        const text = salvageOutput(message)
+        if (text) return text
+    }
+    return undefined
+}
+
+export function childPromptExtras(
+    model: { baseUrl?: string } | undefined,
+    parentPrompt: string,
+    schemaInstruction: string | undefined
+): string[] {
+    const inherited = model?.baseUrl === 'claude-bridge' ? parentPrompt.trim() : ''
+    return [inherited, schemaInstruction].filter((part): part is string => Boolean(part))
+}
+
+export async function validateCwd(cwd: string): Promise<void> {
+    let info
+    try {
+        info = await stat(cwd)
+    } catch {
+        throw new Error(`Subagent working directory does not exist: ${cwd}`)
+    }
+    if (!info.isDirectory()) throw new Error(`Subagent working directory is not a directory: ${cwd}`)
+}
+
+const execFileAsync = promisify(execFile)
+
+export async function createWorktree(repo: string, target: string): Promise<void> {
+    try {
+        await execFileAsync('git', ['-C', repo, 'worktree', 'add', '-b', worktreeBranch(target), target, 'HEAD'])
+    } catch (error) {
+        const reason = error instanceof Error ? error.message : String(error)
+        throw new Error(`Could not create a worktree under ${repo}: ${reason}`, { cause: error })
+    }
+}
+
+/** The branch a worktree at `target` commits to, named after the task directory holding it. */
+export function worktreeBranch(target: string): string {
+    return `pi-task-${basename(dirname(target))}`
+}
+
+export function gitStatus(repo: string): Promise<string> {
+    return execFileAsync('git', ['-C', repo, 'status', '--porcelain']).then(
+        (result) => result.stdout,
+        () => ''
+    )
+}
+
+export function changedPaths(status: string): string[] {
+    return status
+        .split('\n')
+        .filter((line) => line.trim())
+        .map((line) => {
+            const arrow = line.indexOf(' -> ')
+            const raw = arrow >= 0 ? line.slice(arrow + 4) : line.slice(3)
+            return raw.trim().replace(/^"|"$/g, '')
+        })
+}
+
+let permitsInUse = 0
+const permitWaiters: Array<() => void> = []
+
+export async function acquirePermit(signal: AbortSignal | undefined): Promise<void> {
+    if (signal?.aborted) throw new Error('Subagent aborted while queued.')
+    if (permitsInUse < MAX_CONCURRENT) {
+        permitsInUse++
+        return
+    }
+    await new Promise<void>((resolve, reject) => {
+        const waiter = () => {
+            signal?.removeEventListener('abort', onAbort)
+            permitsInUse++
+            resolve()
+        }
+        const onAbort = () => {
+            const index = permitWaiters.indexOf(waiter)
+            if (index >= 0) permitWaiters.splice(index, 1)
+            reject(new Error('Subagent aborted while queued.'))
+        }
+        permitWaiters.push(waiter)
+        signal?.addEventListener('abort', onAbort, { once: true })
+    })
+}
+
+export function releasePermit(): void {
+    permitsInUse--
+    permitWaiters.shift()?.()
+}
+
+export function findDuplicateTask(tasks: readonly string[]): { first: number; second: number } | undefined {
+    const seen = new Map<string, number>()
+    for (let index = 0; index < tasks.length; index++) {
+        const key = (tasks[index] ?? '').trim().replace(/\s+/g, ' ').toLowerCase()
+        if (!key) continue
+        const first = seen.get(key)
+        if (first !== undefined) return { first, second: index }
+        seen.set(key, index)
+    }
+    return undefined
+}