세션 & 메모리 도구

서브에이전트, 할 일 목록, 체크포인트, Hindsight 메모리 계층 — task, todo_write, checkpoint, rewind, recall, retain, reflect.

이 도구들은 에이전트가 서브에이전트 분산, 계획 추적, 탐색 컨텍스트 정리, 지속 메모리 읽기·쓰기를 할 수 있게 해줍니다. 이름은 업스트림 docs/tools/ 레퍼런스와 동일합니다.

`task`

병렬, 그리고 선택적으로 격리된 작업을 위해 서브에이전트를 띄웁니다. 부모가 이름으로 에이전트를 고르고, 작고 독립적인 항목 묶음을 함께 넘겨줍니다.

입력

정확한 필드 구성은 task.simple 모드에 따라 달라집니다.

필드	타입	필수	설명
`agent`	`string`	예	배치에 사용할 정확한 에이전트 이름. 실행 시점에 해석됩니다.
`tasks`	`Array<{ id; description; assignment }>`	예	작고 독립적인 항목들. `id`는 최대 48자이며 대소문자 무시 중복은 거부됩니다. `description`은 UI 전용이고, `assignment`가 실제 작업 지시입니다.
`context`	`string`	아니오	모든 서브에이전트 프롬프트 앞에 붙는 공통 배경. `independent` 모드에서는 거부됩니다.
`schema`	`string`	아니오	JSON으로 인코딩한 JTD 출력 스키마. `schema-free`와 `independent` 모드에서는 거부됩니다.
`isolated`	`boolean`	아니오	격리가 활성화된 경우에만 존재합니다. 배치를 격리된 워크스페이스에서 실행합니다.

심플 모드

모드	`context`	`schema`
`default`	허용	허용
`schema-free`	허용	거부
`independent`	거부 — 각 `assignment`가 독립적이어야 함	거부

번들 에이전트

Gajae-Code는 소수의 서브에이전트 타입을 함께 제공합니다.

에이전트	역할
`explore`	구조화된 핸드오프 출력을 내는 읽기 전용 정찰.
`plan`	아키텍처/계획 에이전트. `explore`를 띄울 수 있습니다.
`designer`	UI/UX 전문가.
`reviewer`	`report_finding` 추출을 지원하는 리뷰 에이전트.
`task`	모든 기능을 갖춘 범용 워커.
`quick_task`	추론이 적은 기계적 워커.
`librarian`	소스 기반 외부 API/라이브러리 리서처.

프로젝트 agents/ 디렉터리의 커스텀 에이전트 프론트매터는 같은 이름의 번들 에이전트를 덮어쓸 수 있습니다.

실행 모델

동기는 인라인으로 실행됩니다. 기본값이며, 선택한 에이전트가 blocking으로 표시되었거나 작업이 없으면 강제됩니다.
비동기는 async.enabled가 켜져 있고 에이전트가 blocking이 아닐 때 작업마다 백그라운드 잡 하나를 예약합니다. 잡이 실행되는 동안 진행 스냅샷이 스트리밍됩니다.

각 서브에이전트는 숨겨진 yield 도구로 종료합니다. 그렇지 않으면 런타임이 최대 3번까지 리마인더 프롬프트를 보냅니다. 아티팩트 디렉터리가 있는 서브에이전트는 모두 <id>.md를 씁니다. agent://<id>가 그 파일로 해석됩니다. JSON 출력은 agent://<id>/<path> 및 agent://<id>?q=<query> 추출도 지원합니다.

격리

isolated를 요청하면 배치가 캡처된 베이스라인을 기준으로 다음 중 하나에서 실행됩니다.

백엔드	플랫폼
`worktree`	분리된 git worktree와 베이스라인 재생.
`fuse-overlay`	Unix FUSE 오버레이 마운트.
`fuse-projfs`	Windows ProjFS 오버레이.

결과는 두 가지 전략으로 병합됩니다. patch 모드(작업별 패치를 합쳐 적용)와 branch 모드(각 작업을 gjc/task/<id> 브랜치에 커밋 후 부모로 cherry-pick). 격리 실행에는 git 저장소가 필요합니다.

한도와 상한

서브에이전트별 출력 절단: MAX_OUTPUT_BYTES = 500_000, MAX_OUTPUT_LINES = 5000. 원본 전체 출력은 그래도 <id>.md에 기록됩니다. 이 상한은 GJC_TASK_MAX_OUTPUT_BYTES와 GJC_TASK_MAX_OUTPUT_LINES로 재정의할 수 있습니다.
동시성은 task.maxConcurrency를 사용합니다(비동기는 세마포어, 동기는 동시성 제한 맵).
task 도구는 task.maxRecursionDepth 이상에서 숨겨지고, 최대 깊이에서는 자식의 task 접근도 제거됩니다.
작업 id 스키마 상한은 48자입니다(프롬프트는 ≤32를 권장).
GJC_BLOCKED_AGENT는 특정 서브에이전트 타입을 차단하며 자기 재귀 방지 검사의 일부입니다.

참고

자식 세션은 대화 기록을 상속하지 않습니다. 유일한 인계는 공통 context, 선택적 context.md, 워크스페이스 트리, 공유 local:// 루트뿐입니다.
서브에이전트는 todo_write를 받지 않습니다. 부모가 소유합니다.
await 타임아웃은 관찰 창일 뿐이며, 서브에이전트를 멈추거나 실패시키거나 만료시키지 않습니다. 실제로 실패했거나 길을 잃었을 때만 취소하세요.

`todo_write`

세션 할 일 목록에 순서가 있는 변경을 적용하고, 요약과 전체 단계/작업 상태를 반환합니다. 모델은 비어 있지 않은 ops 배열을 넘기며, 각 op가 작업 목록을 변경합니다.

연산

Op	필수	효과
`init`	`list`	목록 전체를 교체. 새 작업은 모두 `pending`으로 시작.
`start`	`task`	한 작업을 `in_progress`로. 다른 활성 작업은 `pending`으로 강등.
`done`	`task` / `phase` / 없음	대상 작업, 단계, 또는 전체를 `completed`로.
`drop`	`task` / `phase` / 없음	대상을 `abandoned`로.
`rm`	`task` / `phase` / 없음	대상 작업을 제거하거나 단계/전체를 비움.
`append`	`phase`, `items`	새 `pending` 작업 추가. 단계가 없으면 생성.
`note`	`task`, `text`	작업에 노트 하나 추가. 트림 후 빈 값은 거부.

작업은 단계 안에 들어 있습니다. 각 항목은 pending, in_progress, completed, abandoned 중 하나의 status와 선택적 notes를 가집니다.

단일 활성 작업 규칙

op 배치가 끝나면 정규화가 활성 작업을 하나로 강제합니다. 여러 개가 in_progress면 첫 번째만 활성으로 남습니다. 하나도 없으면 첫 pending 작업이 자동 승격됩니다. 한 번의 호출로 의도적으로 중간 상태를 만든 뒤 이 최종 단계에 맡길 수 있습니다.

참고

작업 조회는 정확한 문자열 일치입니다. 작업 내용과 단계 이름은 고유하게 유지하세요. append는 전역적으로 중복 작업 내용을 거부합니다.
일반적인 잘못된 페이로드는 예외를 던지지 않습니다. 오류는 Errors: 접두로 누적되며 변경된 상태는 그대로 반환됩니다.
자동 정리는 tasks.todoClearDelay(기본 60초, < 0이면 비활성화) 후 completed/abandoned 작업을 제거합니다.
재개 시 완료/중단 작업은 캐시 목록에서 제거됩니다. /todo 명령은 트랜스크립트에서 이를 복원합니다.

`checkpoint`

현재 최상위 대화 상태를 표시하여, 이후 rewind가 탐색 컨텍스트를 간결한 보고서로 접을 수 있게 합니다. 기본적으로 비활성화(checkpoint.enabled)이며, 서브에이전트에서는 절대 사용할 수 없습니다.

필드	타입	필수	설명
`goal`	`string`	예	조사 목표. 결과에 그대로 반영됩니다.

도구는 Checkpoint created., 목표, 그리고 "조사를 진행한 뒤 rewind를 호출하라"는 안내를 반환합니다. 캡처하는 것은 대화 메타데이터뿐입니다 — 메시지 수, 세션 항목 id, 타임스탬프. git을 호출하거나 작업 트리, 스테이지 변경, 아티팩트, 기록을 스냅샷하지 않습니다.

체크포인트가 활성인 동안 먼저 yield를 시도하면, 발견 내용을 담아 rewind를 호출하라는 시스템 경고로 차단됩니다. 세션당 활성 체크포인트는 하나만 허용됩니다(그 외에는 Checkpoint already active.).

`rewind`

탐색 메시지를 정리하고 그 자리에 간결한 보고서를 남겨 활성 체크포인트를 종료합니다.

필드	타입	필수	설명
`report`	`string`	예	조사 결과. 트림되며 빈 값은 거부됩니다.

도구는 즉시 반환하지만(Rewind requested.), 부수 효과는 턴 종료 시 순서대로 적용됩니다:

인메모리 기록이 체크포인트까지의 접두로 교체됩니다.
지속된 세션 리프가 branch_summary와 함께 체크포인트 항목으로 분기됩니다.
숨겨진 rewind-report 메시지가 재구성 컨텍스트로 보고서를 전달합니다.

rewind는 트랜스크립트/세션 상태만 복원합니다 — 파일, git 상태, 아티팩트, blob 페이로드는 절대 아닙니다. 지속 기록에 파괴적이지 않습니다. 버려진 경로는 세션 로그에 남고 활성 컨텍스트만 재배선됩니다. 체크포인트 목록이나 id는 없습니다. rewind는 항상 단일 활성 체크포인트를 대상으로 합니다.

메모리: `recall`, `retain`, `reflect`

이 세 도구는 Hindsight 메모리 백엔드의 전면부이며, memory.backend == "hindsight"일 때만 사용할 수 있습니다. 저장은 서버 측이며 세션 간 공유됩니다. 서브에이전트는 부모의 Hindsight 상태를 별칭으로 공유해 같은 뱅크에 씁니다.

뱅크 스코프는 세션별로 설정됩니다.

스코프	동작
`global`	공유 뱅크 하나, 태그 필터 없음.
`per-project`	cwd 베이스명마다 별도 뱅크 id.
`per-project-tagged`	공유 뱅크 + `project:<cwd basename>` 태그 필터(프로젝트 태그/무태그 메모리 모두 매칭).

`recall`

활성 뱅크를 검색해 일치하는 원본 메모리를 반환합니다.

필드	타입	필수	설명
`query`	`string`	예	자연어 검색 쿼리. 그대로 전달됩니다.

매치가 있으면 Found <n> relevant memories 헤더와 함께 불릿 목록(- <text> [<type>] (<mentioned_at>))을 반환합니다. 매치가 없으면 No relevant memories found.를 반환합니다. 원본 히트를 반환할 뿐 종합하지 않습니다 — 종합은 reflect를 쓰세요. 기본값: hindsight.recallBudget = "mid", hindsight.recallMaxTokens = 1024, hindsight.recallTypes = ["world", "experience"].

`retain`

지속 사실을 큐에 넣어 활성 뱅크에 비동기로 씁니다.

필드	타입	필수	설명
`items`	`Array<{ content; context? }>`	예	하나 이상의 독립적인 메모리(`minItems: 1`). `context`는 선택적 항목별 출처.

쓰기는 도구가 반환되기 전에 확정되지 않습니다 — 즉시 <count> memory queued.를 반환합니다. 큐는 이후 RETAIN_FLUSH_BATCH_SIZE = 16에 도달하거나, RETAIN_FLUSH_INTERVAL_MS = 5_000 디바운스, 또는 에이전트 종료 시 플러시됩니다. 플러시 실패는 세션 경고로 나타납니다. 도구 오류는 아닙니다. 로컬 파일은 쓰지 않습니다. 저장은 서버 측입니다.

멘탈 모델(user-preferences, project-conventions, project-decisions)은 이 도구와 별개로 공유 백엔드가 시드하고 갱신합니다.

`reflect`

Hindsight 서버에 뱅크 전체에 대한 답을 종합하도록 요청합니다.

필드	타입	필수	설명
`query`	`string`	예	장기 메모리에서 답할 질문.
`context`	`string`	아니오	reflect 엔드포인트로 보내는 추가 안내.

recall과 달리 원본 히트가 아니라 서버가 종합한 텍스트를 반환합니다(비어 있으면 No relevant information found to reflect on.).